NSDecimalNumber

Inherits From:
NSNumber : NSValue : NSObject

Conforms To:
NSDecimalNumberBehavior
NSObject (NSObject)

Declared In:
Foundation/NSDecimalNumber.h

Class Description

In the course of doing arithmetic, a method may produce calculation errors, such as division by zero. It may also meet circumstances where it has a choice of ways to round a number off. The way the method acts on such occasions is called its "behavior."

Behavior is set by methods in the NSDecimalNumberBehaviors protocol. Every NSDecimalNumber argument called behavior requires an object that conforms to this protocol. For more on behaviors, see the specifications for the NSDecimalNumberBehaviors protocol and the NSDecimalNumberHandler class. Also see the defaultBehavior method description, below.

C Interface to Decimal Numbers

You might also consider the C interface if you need maximum efficiency. The C interface is faster and uses less memory than the NSDecimalNumber class.

If you need mutability, you can combine the two interfaces. Use functions from the C interface and convert their results to NSDecimalNumbers.

The C functions-NSDecimalCompact(), NSDecimalCompare(), NSDecimalRound(), NSDecimalNormalize(), NSDecimalAdd(), NSDecimalSubtract(), NSDecimalMultiply(), NSDecimalDivide(), NSDecimalPower(), NSDecimalMultiplyByPowerOf10(), NSDecimalString()-are all documented in the "Functions" chapter of the Foundation Framework Reference.

Creating an NSDecimalNumber

+ decimalNumberWithDecimal:

+ decimalNumberWithMantissa:exponent:isNegative:

+ decimalNumberWithString:

+ decimalNumberWithString:locale:

+ one

+ zero

+ notANumber

Initializing an NSDecimalNumber

- initWithDecimal:

- initWithMantissa:exponent:isNegative:

- initWithString:

- initWithString:locale:

Doing arithmetic

- decimalNumberByAdding:

- decimalNumberBySubtracting:

- decimalNumberByMultiplyingBy:

- decimalNumberByDividingBy:

- decimalNumberByRaisingToPower:

- decimalNumberByMultiplyingByPowerOf10:

- decimalNumberByAdding:withBehavior:

- decimalNumberBySubtracting:withBehavior:

- decimalNumberByMultiplyingBy:withBehavior:

- decimalNumberByDividingBy:withBehavior:

- decimalNumberByRaisingToPower:withBehavior:

- decimalNumberByMultiplyingByPowerOf10:withBehavior:

Rounding off

- decimalNumberByRoundingAccordingToBehavior:

Accessing data

- decimalValue

- doubleValue

- descriptionWithLocale:

- objCType

Modifying behavior

+ defaultBehavior

+ setDefaultBehavior:

Comparing NSDecimalNumbers

- compare:

Getting the highest and lowest possible NSDecimalNumbers

+ maximumDecimalNumber

+ minimumDecimalNumber

Class Methods

decimalNumberWithDecimal:

Creates and returns an NSDecimalNumber equivalent to decimal.

decimal is an NSDecimal structure, which you can initialize by hand, or generate using the scanDecimal: method from the NSDecimalNumberScanning category of NSScanner, defined in NSDecimalNumber.h.

decimalNumberWithMantissa:exponent:isNegative:

Creates and returns an NSDecimalNumber equivalent to the number specified by the arguments.

The arguments express a number in a kind of scientific notation that requires the mantissa to be an integer. So, for example, if the number to be represented is 1.23, it is expressed as 123x10-2-mantissa is 123, exponent is -2, and isNegative, which refers to the sign of the mantissa, is NO.

decimalNumberWithString:

Creates and returns an NSDecimalNumber equivalent to numericString. Besides digits, numericString can include an initial "+" or "-," a single "E" or "e", to indicate the exponent of a number in scientific notation, and a single NSDecimalSeparator to divide the fractional from the integral part of the number.

Whether the NSDecimalSeparator is a period (as in the United States) or a comma (as in France) depends on the default locale.

See also: + decimalNumberWithString:locale:

decimalNumberWithString:locale:

Creates and returns an NSDecimalNumber equivalent to numericString. Besides digits, numericString can include an initial "+" or "-," a single "E" or "e", to indicate the exponent of a number in scientific notation, and a single NSDecimalSeparator to divide the fractional from the integral part of the number.

locale determines whether the NSDecimalSeparator is a period (as in the United States) or a comma (as in France).

The following strings show examples of acceptable values for numericString:

• "2500.6" (or "2500,6", depending on locale)
  
• "-2500.6" (or "-2500.6")
  
• "-2.5006e3" (or "-2,5006e3")
  
• "-2.5006E3" (or "-2,5006E3")
  

• "2,500.6"
  
• "2500 3/5"
  
• "2.5006x10e3"
  
• "two thousand five hundred and six tenths"
  

defaultBehavior

Returns the way that arithmetic methods, like decimalNumberByAdding:, round off and handle error conditions.

By default, the arithmetic methods do not round numbers off. They assume that your need for precision does not exceed 38 significant digits. And they raise exceptions when they try to divide by zero, or when they produce a number that is too big or small to be represented.

If this default behavior doesn't suit your application, you should use methods that let you specify the behavior, like decimalNumberByAdding:withBehavior. If you find yourself using a particular behavior consistently, you can specify a different default behavior with setDefaultBehavior:.

maximumDecimalNumber

Returns the largest possible NSDecimalNumber.

See also: + minimumDecimalNumber

minimumDecimalNumber

Returns the smallest possible NSDecimalNumber.

See also: + maximumDecimalNumber

notANumber

Creates and returns an NSDecimalNumber that specifies no number. Any arithmetic method receiving notANumber as an argument returns notANumber.

This value can be a useful way of handling non-numeric data in an input file. It can also be a useful response to calculation errors. For more information on calculation errors, see the exceptionDuringOperation:error:leftOperand:rightOperand: method description in the NSDecimalNumberBehaviors protocol specification.

one

Creates and returns an NSDecimalNumber equivalent to the number 1.0.

See also: + zero

setDefaultBehavior:

Specifies the way that arithmetic methods, like decimalNumberByAdding:, round off and handle error conditions. behavior must conform to the NSDecimalNumberBehaviors protocol.

zero

Returns a newly allocated NSDecimalNumber equivalent to the number 0.0.

See also: + one

Instance Methods

compare:

Compares decimalNumber with the receiver. Returns NSOrderedAscending if decimalNumber's value is greater than the receiver's, NSOrderedSame if they're equal, and NSOrderedDescending if decimalNumber's value is less than the receiver's.

decimalNumberByAdding:

Adds decimalNumber to the receiver, and returns the sum, a newly created NSDecimalNumber. This method uses the default behavior when handling calculation errors and rounding.

See also: - decimalNumberByAdding:withBehavior:, + defaultBehavior

decimalNumberByAdding:withBehavior:

Adds decimalNumber to the receiver, and returns the sum, a newly created NSDecimalNumber. behavior specifies the handling of calculation errors and rounding.

decimalNumberByDividingBy:

Divides the receiver by decimalNumber, and returns the quotient, a newly created NSDecimalNumber. This method uses the default behavior when handling calculation errors and rounding.

See also: - decimalNumberByDividingBy:withBehavior:, + defaultBehavior

decimalNumberByDividingBy:withBehavior:

Divides the receiver by decimalNumber, and returns the quotient, a newly created NSDecimalNumber. behavior specifies the handling of calculation errors and rounding.

decimalNumberByMultiplyingBy:

Multiplies the receiver by decimalNumber, and returns the product, a newly created NSDecimalNumber. This method uses the default behavior when handling calculation errors and when rounding.

See also: - decimalNumberByMultiplyingBy:withBehavior:, + defaultBehavior

decimalNumberByMultiplyingBy:withBehavior:

Multiplies the receiver by decimalNumber, and returns the product, a newly created NSDecimalNumber. behavior specifies the handling of calculation errors and rounding.

decimalNumberByMultiplyingByPowerOf10:

Multiplies the receiver by 10power, and returns the product, a newly created NSDecimalNumber. This method uses the default behavior when handling calculation errors and when rounding.

See also: - decimalNumberByMultiplyingByPowerOf10:withBehavior:, + defaultBehavior

decimalNumberByMultiplyingByPowerOf10:withBehavior:

Multiplies the receiver by 10power, and returns the product, a newly created NSDecimalNumber. behavior specifies the handling of calculation errors and rounding.

decimalNumberByRaisingToPower:

Raises the receiver to power, and returns the result, a newly created NSDecimalNumber. This method uses the default behavior when handling calculation errors and when rounding.

See also: - decimalNumberByRaisingToPower:withBehavior:, + defaultBehavior

decimalNumberByRaisingToPower:withBehavior:

Raises the receiver to power, and returns the result, a newly created NSDecimalNumber. behavior specifies the handling of calculation errors and rounding.

decimalNumberByRoundingAccordingToBehavior:

Rounds the receiver off in the way specified by behavior, and returns the result, a newly created NSDecimalNumber. For a description of the different ways of rounding, see the roundingMode method in the NSDecimalNumberHandler class specification.

decimalNumberBySubtracting:

Subtracts decimalNumber from the receiver, and returns the difference, a newly created NSDecimalNumber. This method uses the default behavior when handling calculation errors and when rounding.

See also: - decimalNumberBySubtracting:withBehavior:, + defaultBehavior

decimalNumberBySubtracting:withBehavior:

Subtracts decimalNumber from the receiver, and returns the difference, a newly created NSDecimalNumber. behavior specifies the handling of calculation errors and rounding.

decimalValue

Returns the receiver's value, expressed as an NSDecimal structure.

descriptionWithLocale:

Returns an NSString that represents the contents of the receiver. Whether the separator is a period or a comma depends on locale.

doubleValue

Returns the approximate double value of the receiver.

initWithDecimal:

Returns an NSDecimalNumber initialized to represent decimal. This method is NSDecimalNumber's designated initializer.

initWithMantissa:exponent:isNegative:

Creates and returns an NSDecimalNumber equivalent to the number specified by the arguments.

The arguments express a number in a type of scientific notation that requires the mantissa to be an integer. So, for example, if the number to be represented is 1.23, it is expressed as 123x10-2-mantissa is 123, exponent is -2, and isNegative, which refers to the sign of the mantissa, is NO.

initWithString:

Returns an NSDecimalNumber equivalent to numericString. numericString must be a simple string of digits, possibly including a decimal separator. For a listing of acceptable and unacceptable strings, see the class method decimalNumberWithString:locale:.

initWithString:locale:

Returns a newly created NSDecimalNumber equivalent to numericString. The interpretation of numericString depends on locale.

See also: + decimalNumberWithString:locale:

objCType

Returns a C string containing the Objective-C type of the data contained in the receiver, which for an NSDecimalNumber is always "d" (for double).