Up

# NSDecimalNumber class reference

### Authors

Fred Kiefer (`FredKiefer@gmx.de`)

Copyright: (C) 2000 Free Software Foundation, Inc.

### Contents -

1. Software documentation for the NSDecimalNumber class
2. Software documentation for the NSDecimalNumberHandler class
3. Software documentation for the NSNumber(NSDecimalNumber) category
4. Software documentation for the NSDecimalNumberBehaviors protocol

# Software documentation for the NSDecimalNumber class

## NSDecimalNumber : NSNumber

> Declared in:
>   Foundation/NSDecimalNumber.h

> Conforms to:
>   NSDecimalNumberBehaviors

Availability: MacOS-X 10.0.0

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 NSDecimalNumberHandler class, 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.

Instance Variables
Method summary

- +decimalNumberWithDecimal:
- +decimalNumberWithMantissa:exponent:isNegative:
- +decimalNumberWithString:
- +decimalNumberWithString:locale:
- +defaultBehavior
- +maximumDecimalNumber
- +minimumDecimalNumber
- +notANumber
- +one
- +setDefaultBehavior:
- +zero
- -compare:
- -decimalNumberByAdding:
- -decimalNumberByAdding:withBehavior:
- -decimalNumberByDividingBy:
- -decimalNumberByDividingBy:withBehavior:
- -decimalNumberByMultiplyingBy:
- -decimalNumberByMultiplyingBy:withBehavior:
- -decimalNumberByMultiplyingByPowerOf10:
- -decimalNumberByMultiplyingByPowerOf10:withBehavior:
- -decimalNumberByRaisingToPower:
- -decimalNumberByRaisingToPower:withBehavior:
- -decimalNumberByRoundingAccordingToBehavior:
- -decimalNumberBySubtracting:
- -decimalNumberBySubtracting:withBehavior:
- -decimalValue
- -descriptionWithLocale:
- -doubleValue
- -initWithDecimal:
- -initWithMantissa:exponent:isNegative:
- -initWithString:
- -initWithString:locale:
- -objCType

### decimalNumberWithDecimal:

+ (NSDecimalNumber*) decimalNumberWithDecimal: (NSDecimal)decimal;
Availability: MacOS-X 10.0.0
New instance with given value. Note an NSDecimal may be created using the function NSDecimalFromString() .

### decimalNumberWithMantissa: exponent: isNegative:

+ (NSDecimalNumber*) decimalNumberWithMantissa: (unsigned long long)mantissa exponent: (short)exponent isNegative: (BOOL)isNegative;
Availability: MacOS-X 10.0.0
New instance by component. Note that the precision of this initializer is limited.

### decimalNumberWithString:

+ (NSDecimalNumber*) decimalNumberWithString: (NSString*)numericString;
Availability: MacOS-X 10.0.0
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: locale:

+ (NSDecimalNumber*) decimalNumberWithString: (NSString*)numericString locale: (NSDictionary*)locale;
Availability: MacOS-X 10.0.0
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

+ (id<NSDecimalNumberBehaviors>) defaultBehavior;
Availability: MacOS-X 10.0.0
Returns the default rounding/precision/exception handling behavior, which is same as [NSDecimalNumberHandler +defaultDecimalNumberHandler] unless it has been explicitly set otherwise.

### maximumDecimalNumber

+ (NSDecimalNumber*) maximumDecimalNumber;
Availability: MacOS-X 10.0.0
Return maximum positive value that can be represented.

### minimumDecimalNumber

+ (NSDecimalNumber*) minimumDecimalNumber;
Availability: MacOS-X 10.0.0
Return minimum negative value (not the smallest positive value) that can be represented.

### notANumber

+ (NSDecimalNumber*) notANumber;
Availability: MacOS-X 10.0.0
Return a fixed value representing an NaN.

### one

+ (NSDecimalNumber*) one;
Availability: MacOS-X 10.0.0
Return a constant object with a value of one.

### setDefaultBehavior:

+ (void) setDefaultBehavior: (id<NSDecimalNumberBehaviors>)behavior;
Availability: MacOS-X 10.0.0
Sets the default rounding/precision/exception handling behavior to the given behavior. If this is not called, behavior defaults to [NSDecimalNumberHandler +defaultDecimalNumberHandler] .

### zero

+ (NSDecimalNumber*) zero;
Availability: MacOS-X 10.0.0
Return a constant object with a value of zero.

### compare:

- (NSComparisonResult) compare: (NSNumber*)decimalNumber;
Availability: MacOS-X 10.0.0
Compares with other number, returning less, greater, or equal.

### decimalNumberByAdding:

- (NSDecimalNumber*) decimalNumberByAdding: (NSDecimalNumber*)decimalNumber;
Availability: MacOS-X 10.0.0
Adds self to decimalNumber and returns new result, using +defaultBehavior for rounding/precision/error handling.

### decimalNumberByAdding: withBehavior:

- (NSDecimalNumber*) decimalNumberByAdding: (NSDecimalNumber*)decimalNumber withBehavior: (id<NSDecimalNumberBehaviors>)behavior;
Availability: MacOS-X 10.0.0
Adds self to decimalNumber and returns new result, using given behavior for rounding/precision/error handling.

### decimalNumberByDividingBy:

- (NSDecimalNumber*) decimalNumberByDividingBy: (NSDecimalNumber*)decimalNumber;
Availability: MacOS-X 10.0.0
Divides self by decimalNumber and returns new result, using +defaultBehavior for rounding/precision/error handling.

### decimalNumberByDividingBy: withBehavior:

- (NSDecimalNumber*) decimalNumberByDividingBy: (NSDecimalNumber*)decimalNumber withBehavior: (id<NSDecimalNumberBehaviors>)behavior;
Availability: MacOS-X 10.0.0
Divides self by decimalNumber and returns new result, using given behavior for rounding/precision/error handling.

### decimalNumberByMultiplyingBy:

- (NSDecimalNumber*) decimalNumberByMultiplyingBy: (NSDecimalNumber*)decimalNumber;
Availability: MacOS-X 10.0.0
Multiplies self by decimalNumber and returns new result, using +defaultBehavior for rounding/precision/error handling.

### decimalNumberByMultiplyingBy: withBehavior:

- (NSDecimalNumber*) decimalNumberByMultiplyingBy: (NSDecimalNumber*)decimalNumber withBehavior: (id<NSDecimalNumberBehaviors>)behavior;
Availability: MacOS-X 10.0.0
Multiplies self by decimalNumber and returns new result, using given behavior for rounding/precision/error handling.

### decimalNumberByMultiplyingByPowerOf10:

- (NSDecimalNumber*) decimalNumberByMultiplyingByPowerOf10: (short)power;
Availability: MacOS-X 10.0.0
Multiplies self by given power of 10 and returns new result, using +defaultBehavior for rounding/precision/error handling.

### decimalNumberByMultiplyingByPowerOf10: withBehavior:

- (NSDecimalNumber*) decimalNumberByMultiplyingByPowerOf10: (short)power withBehavior: (id<NSDecimalNumberBehaviors>)behavior;
Availability: MacOS-X 10.0.0
Multiplies self by given power of 10 and returns new result, using given behavior for rounding/precision/error handling.

### decimalNumberByRaisingToPower:

- (NSDecimalNumber*) decimalNumberByRaisingToPower: (NSUInteger)power;
Availability: MacOS-X 10.0.0
Raises self to given positive integer power and returns new result, using +defaultBehavior for rounding/precision/error handling.

### decimalNumberByRaisingToPower: withBehavior:

- (NSDecimalNumber*) decimalNumberByRaisingToPower: (NSUInteger)power withBehavior: (id<NSDecimalNumberBehaviors>)behavior;
Availability: MacOS-X 10.0.0
Raises self to given positive integer power and returns new result, using given behavior for rounding/precision/error handling.

### decimalNumberByRoundingAccordingToBehavior:

- (NSDecimalNumber*) decimalNumberByRoundingAccordingToBehavior: (id<NSDecimalNumberBehaviors>)behavior;
Availability: MacOS-X 10.0.0
Returns rounded version of underlying decimal.

### decimalNumberBySubtracting:

- (NSDecimalNumber*) decimalNumberBySubtracting: (NSDecimalNumber*)decimalNumber;
Availability: MacOS-X 10.0.0
Subtracts decimalNumber from self and returns new result, using +defaultBehavior for rounding/precision/error handling.

### decimalNumberBySubtracting: withBehavior:

- (NSDecimalNumber*) decimalNumberBySubtracting: (NSDecimalNumber*)decimalNumber withBehavior: (id<NSDecimalNumberBehaviors>)behavior;
Availability: MacOS-X 10.0.0
Subtracts decimalNumber from self and returns new result, using given behavior for rounding/precision/error handling.

### decimalValue

- (NSDecimal) decimalValue;
Availability: MacOS-X 10.0.0
Return underlying value as an `NSDecimal` structure.

### descriptionWithLocale:

- (NSString*) descriptionWithLocale: (id)locale;
Availability: MacOS-X 10.0.0
Returns string version of number formatted according to locale.

### doubleValue

- (double) doubleValue;
Availability: MacOS-X 10.0.0
Returns underlying value as a `double`, which may be an approximation if precision greater than the default of 38.

### initWithDecimal:

- (id) initWithDecimal: (NSDecimal)decimal;
Availability: MacOS-X 10.0.0
Initialize with given value. Note an NSDecimal may be created using the function NSDecimalFromString() .

### initWithMantissa: exponent: isNegative:

- (id) initWithMantissa: (unsigned long long)mantissa exponent: (short)exponent isNegative: (BOOL)flag;
Availability: MacOS-X 10.0.0
Initialize by component. Note that the precision of this initializer is limited.

### initWithString:

- (id) initWithString: (NSString*)numberValue;
Availability: MacOS-X 10.0.0
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: locale:

- (id) initWithString: (NSString*)numberValue locale: (NSDictionary*)locale;
Availability: MacOS-X 10.0.0
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

- (const char*) objCType;
Availability: MacOS-X 10.0.0
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.

## Instance Variables for NSDecimalNumber Class

### data

@protected NSDecimal data;
Availability: MacOS-X 10.0.0
Description forthcoming.

# Software documentation for the NSDecimalNumberHandler class

## NSDecimalNumberHandler : NSObject

> Declared in:
>   Foundation/NSDecimalNumber.h

> Conforms to:
>   NSDecimalNumberBehaviors

Availability: MacOS-X 10.0.0
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:`.

Instance Variables
Method summary

- +decimalNumberHandlerWithRoundingMode:scale:raiseOnExactness:raiseOnOverflow:raiseOnUnderflow:raiseOnDivideByZero:
- +defaultDecimalNumberHandler
- -initWithRoundingMode:scale:raiseOnExactness:raiseOnOverflow:raiseOnUnderflow:raiseOnDivideByZero:

### decimalNumberHandlerWithRoundingMode: scale: raiseOnExactness: raiseOnOverflow: raiseOnUnderflow: raiseOnDivideByZero:

+ (id) decimalNumberHandlerWithRoundingMode: (NSRoundingMode)roundingMode scale: (short)scale raiseOnExactness: (BOOL)raiseOnExactness raiseOnOverflow: (BOOL)raiseOnOverflow raiseOnUnderflow: (BOOL)raiseOnUnderflow raiseOnDivideByZero: (BOOL)raiseOnDivideByZero;
Availability: MacOS-X 10.0.0
Constructor setting all behavior. (For more precise control over error handling, create your own class implementing the <NSDecimalNumberBehaviors> protocol.)

### defaultDecimalNumberHandler

+ (id) defaultDecimalNumberHandler;
Availability: MacOS-X 10.0.0
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: scale: raiseOnExactness: raiseOnOverflow: raiseOnUnderflow: raiseOnDivideByZero:

- (id) initWithRoundingMode: (NSRoundingMode)roundingMode scale: (short)scale raiseOnExactness: (BOOL)raiseOnExactness raiseOnOverflow: (BOOL)raiseOnOverflow raiseOnUnderflow: (BOOL)raiseOnUnderflow raiseOnDivideByZero: (BOOL)raiseOnDivideByZero;
Availability: MacOS-X 10.0.0
Initializer setting all behavior. (For more precise control over error handling, create your own class implementing the <NSDecimalNumberBehaviors> protocol.)

## Instance Variables for NSDecimalNumberHandler Class

### _raiseOnDivideByZero

@protected BOOL _raiseOnDivideByZero;
Availability: MacOS-X 10.0.0
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.

### _raiseOnExactness

@protected BOOL _raiseOnExactness;
Availability: MacOS-X 10.0.0
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.

### _raiseOnOverflow

@protected BOOL _raiseOnOverflow;
Availability: MacOS-X 10.0.0
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.

### _raiseOnUnderflow

@protected BOOL _raiseOnUnderflow;
Availability: MacOS-X 10.0.0
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.

### _roundingMode

@protected NSRoundingMode _roundingMode;
Availability: MacOS-X 10.0.0
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.

### _scale

@protected short int _scale;
Availability: MacOS-X 10.0.0
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.

# Software documentation for the NSNumber(NSDecimalNumber) category

## NSNumber(NSDecimalNumber)

> Declared in:
>   Foundation/NSDecimalNumber.h

Availability: MacOS-X 10.0.0
Interface for obtaining an NSDecimalNumber value from an ordinary NSNumber.
Method summary

- -decimalValue

### decimalValue

- (NSDecimal) decimalValue;
Availability: MacOS-X 10.0.0
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

## NSDecimalNumberBehaviors

> Declared in:
>   Foundation/NSDecimalNumber.h

Availability: MacOS-X 10.0.0
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.
Method summary

- -exceptionDuringOperation:error:leftOperand:rightOperand:
- -roundingMode
- -scale

### exceptionDuringOperation: error: leftOperand: rightOperand:

- (NSDecimalNumber*) exceptionDuringOperation: (SEL)method error: (NSCalculationError)error leftOperand: (NSDecimalNumber*)leftOperand rightOperand: (NSDecimalNumber*)rightOperand;
Availability: MacOS-X 10.0.0

Specifies behavior when, in the course of applying method to leftOperand and rightOperand, an NSDecimalNumber instance 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

- (NSRoundingMode) roundingMode;
Availability: MacOS-X 10.0.0
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

- (short) scale;
Availability: MacOS-X 10.0.0
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`.

Up