Up

NSDecimalNumber class reference

Authors

Fred Kiefer (FredKiefer@gmx.de)

Date: Generated at 2023-12-20 19:35:39 -0500

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: 

+ (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: 

+ (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 

- (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: 

- (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