# NSDecimalNumber class reference

FredKiefer@gmx.de
2000 Free Software Foundation, Inc.
Software documentation for the NSDecimalNumber class
Foundation/NSDecimalNumber.h
NSDecimalNumberBehaviors

Class that implements a number of methods for performing decimal arithmetic to arbitrary precision. The behavior in terms of rounding choices and exception handling may be customized using the NSDecimalNumberHandlerclass, and defaults to [NSDecimalNumberHandler +defaultDecimalNumberHandler].

Equivalent functionality to the `NSDecimalNumber` class may be accessed through functions, mostly named `NSDecimalXXX`, e.g., NSDecimalMin() . Both the class and the functions use a structure called `NSDecimal`.

Note that instances of `NSDecimalNumber` are immutable.

Description forthcoming.
decimalNumberWithDecimal:
decimal
New instance with given value. Note an NSDecimal may be created using the function NSDecimalFromString() .
decimalNumberWithMantissa:
mantissa
exponent:
exponent
isNegative:
isNegative
New instance by component. Note that the precision of this initializer is limited.
decimalNumberWithString:
numericString
New instance from string. Arbitrary precision is preserved, though calling one of the `decimalNumberBy...` methods will return a result constrained by the current `scale`. Number format is parsed according to current default locale.
decimalNumberWithString:
numericString
locale:
locale
New instance from string. Arbitrary precision is preserved, though calling one of the `decimalNumberBy...` methods will return a result constrained by the current `scale`. Number format is parsed according to given locale.
defaultBehavior
Returns the default rounding/precision/exception handling behavior, which is same as [NSDecimalNumberHandler +defaultDecimalNumberHandler] unless it has been explicitly set otherwise.
maximumDecimalNumber
Return maximum positive value that can be represented.
minimumDecimalNumber
Return minimum negative value (not the smallest positive value) that can be represented.
notANumber
Return a fixed value representing an NaN.
one
Return a constant object with a value of one.
setDefaultBehavior:
behavior
Sets the default rounding/precision/exception handling behavior to the given behavior. If this is not called, behavior defaults to [NSDecimalNumberHandler +defaultDecimalNumberHandler].
zero
Return a constant object with a value of zero.
compare:
decimalNumber
Compares with other number, returning less, greater, or equal.
decimalNumberByAdding:
decimalNumber
Adds self to decimalNumber and returns new result, using +defaultBehavior for rounding/precision/error handling.
decimalNumberByAdding:
decimalNumber
withBehavior:
behavior
Adds self to decimalNumber and returns new result, using given behavior for rounding/precision/error handling.
decimalNumberByDividingBy:
decimalNumber
Divides self by decimalNumber and returns new result, using +defaultBehavior for rounding/precision/error handling.
decimalNumberByDividingBy:
decimalNumber
withBehavior:
behavior
Divides self by decimalNumber and returns new result, using given behavior for rounding/precision/error handling.
decimalNumberByMultiplyingBy:
decimalNumber
Multiplies self by decimalNumber and returns new result, using +defaultBehavior for rounding/precision/error handling.
decimalNumberByMultiplyingBy:
decimalNumber
withBehavior:
behavior
Multiplies self by decimalNumber and returns new result, using given behavior for rounding/precision/error handling.
decimalNumberByMultiplyingByPowerOf10:
power
Multiplies self by given power of 10 and returns new result, using +defaultBehavior for rounding/precision/error handling.
decimalNumberByMultiplyingByPowerOf10:
power
withBehavior:
behavior
Multiplies self by given power of 10 and returns new result, using given behavior for rounding/precision/error handling.
decimalNumberByRaisingToPower:
power
Raises self to given positive integer power and returns new result, using +defaultBehavior for rounding/precision/error handling.
decimalNumberByRaisingToPower:
power
withBehavior:
behavior
Raises self to given positive integer power and returns new result, using given behavior for rounding/precision/error handling.
decimalNumberByRoundingAccordingToBehavior:
behavior
Returns rounded version of underlying decimal.
decimalNumberBySubtracting:
decimalNumber
Subtracts decimalNumber from self and returns new result, using +defaultBehavior for rounding/precision/error handling.
decimalNumberBySubtracting:
decimalNumber
withBehavior:
behavior
Subtracts decimalNumber from self and returns new result, using given behavior for rounding/precision/error handling.
decimalValue
Return underlying value as an `NSDecimal` structure.
descriptionWithLocale:
locale
Returns string version of number formatted according to locale.
doubleValue
Returns underlying value as a `double`, which may be an approximation if precision greater than the default of 38.
initWithDecimal:
decimal
Initialize with given value. Note an NSDecimal may be created using the function NSDecimalFromString() .
initWithMantissa:
mantissa
exponent:
exponent
isNegative:
flag
Initialize by component. Note that the precision of this initializer is limited.
initWithString:
numberValue
Initialize from string. Arbitrary precision is preserved, though calling one of the `decimalNumberBy...` methods will return a result constrained by the current `scale`. Number format is parsed according to current default locale.
initWithString:
numberValue
locale:
locale
Initialize from string. Arbitrary precision is preserved, though calling one of the `decimalNumberBy...` methods will return a result constrained by the current `scale`. Number format is parsed according to given locale.
objCType
Returns the Objective-C type ( `@encode(...)` compatible) of the data contained `NSDecimalNumber`, which is by convention "d" (for double), even though this is not strictly accurate.
Software documentation for the NSDecimalNumberHandler class
Foundation/NSDecimalNumber.h
NSDecimalNumberBehaviors
A utility class adopting <NSDecimalNumberBehaviors> protocol. Can be used to control NSDecimalNumber rounding and exception-handling behavior, by passing an instance as an argument to any NSDecimalNumber method ending with `...Behavior:`.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
decimalNumberHandlerWithRoundingMode:
roundingMode
scale:
scale
raiseOnExactness:
raiseOnExactness
raiseOnOverflow:
raiseOnOverflow
raiseOnUnderflow:
raiseOnUnderflow
raiseOnDivideByZero:
raiseOnDivideByZero
Constructor setting all behavior. (For more precise control over error handling, create your own class implementing the <NSDecimalNumberBehaviors> protocol.)
defaultDecimalNumberHandler
Provides an instance implementing the default behavior for the NSDecimalNumber class. 38 decimal digits, rounded to closest return value (`NSRoundPlain`). Exceptions raised on overflow, underflow, and divide by zero.
initWithRoundingMode:
roundingMode
scale:
scale
raiseOnExactness:
raiseOnExactness
raiseOnOverflow:
raiseOnOverflow
raiseOnUnderflow:
raiseOnUnderflow
raiseOnDivideByZero:
raiseOnDivideByZero
Initializer setting all behavior. (For more precise control over error handling, create your own class implementing the <NSDecimalNumberBehaviors> protocol.)
Software documentation for the NSNumber(NSDecimalNumber) category
Foundation/NSDecimalNumber.h
Interface for obtaining an NSDecimalNumber value from an ordinary NSNumber.
decimalValue
Obtaining an NSDecimalNumber version of an ordinary NSNumber.
Returns an NSDecimal representation of the number. Float and double values may not be converted exactly
Software documentation for the NSDecimalNumberBehaviors protocol
Foundation/NSDecimalNumber.h
This protocol encapsulates information about how an NSDecimalNumber should round and process exceptions. Usually you can just create objects of the NSDecimalNumberHandler class, which implements this protocol, but if you don't want to use that class you can create your own implementing it.
exceptionDuringOperation:
method
error:
error
leftOperand:
leftOperand
rightOperand:
rightOperand

Specifies behavior when, in the course of applying method to leftOperand and rightOperand, an NSDecimalNumberinstance encounters given error.

error has four possible constant values:

`NSCalculationLossOfPrecision`
The number can't be represented in 38 significant digits.
`NSCalculationOverflow`
The number is too large to represent.
`NSCalculationUnderflow`
The number is too small to represent.
`NSCalculationDivideByZero`
The caller tried to divide by 0.

Behavior on error can be one of the following:

Raise an exception.
Return `nil`. The calling method will return its value as though no error had occurred. If error is `NSCalculationLossOfPrecision`, method will return an imprecise value, constrained to 38 significant digits. If error is `NSCalculationUnderflow` or `NSCalculationOverflow`, method will return `NSDecimalNumber` 's `notANumber`. You shouldn't return `nil` if error is `NSDivideByZero`.
Correct the error and return a valid `NSDecimalNumber`. The calling method will use this as its own return value.
roundingMode
Specifies how NSDecimalNumber 's `decimalNumberBy...` methods round their return values. This should be set to one of the following constants:
`NSRoundDown`
Always round down.
`NSRoundUp`
Always round up.
`NSRoundPlain`
Round to the closest possible return value. Halfway (e.g..5) rounds up for positive numbers, down for negative (towards larger absolute value).
`NSRoundBankers`
Round to the closest possible return value, but halfway (e.g..5) rounds towards possibility whose last digit is even.
scale
Specifies the precision of the values returned by NSDecimalNumber 's `decimalNumberBy...` methods, in terms of the number of digits allowed after the decimal point. This can be negative, implying that the precision should be, e.g., 100's, 1000's, etc.. For unlimited precision, set to `NSDecimalNoScale`.