Inherits from: NSNumber : NSValue : NSObject
Conforms to: NSDecimalNumberBehavior
NSObject (NSObject)
Declared in: Foundation/NSDecimalNumber.h
NSDecimalNumber, an immutable subclass of NSNumber, provides an object-oriented wrapper for doing base-10 arithmetic. An instance can represent any number that can be expressed as mantissa x 10exponent where mantissa is a decimal integer up to 38 digits long, and exponent is an integer between -128 and 127.
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.
The arithmetic and rounding methods of NSDecimalNumber are also accessible through group of ordinary C functions, defined in NSDecimal.h. You might consider the C interface if you don't need to treat NSDecimalNumbers as objects-that is, if you don't need to store them in an object-oriented collection like an NSArray or NSDictionary.
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
+ (NSDecimalNumber *)decimalNumberWithDecimal:(NSDecimal)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.
+ (NSDecimalNumber *)decimalNumberWithMantissa:(unsigned
long long)mantissa exponent:(short)exponent isNegative:(BOOL)isNegative
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.
+ (NSDecimalNumber *)decimalNumberWithString:(NSString
*)numericString
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:
+ (NSDecimalNumber *)decimalNumberWithString:(NSString
*)numericString locale:(NSDictionary *)locale
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:
The following are unacceptable:
See Also: + decimalNumberWithString:
+ (id <NSDecimalNumberBehaviors>)defaultBehavior
By default, the arithmetic methods do not round numbers off. They assume 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 too big or too 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:.
+ (NSDecimalNumber *)maximumDecimalNumber
See Also: + minimumDecimalNumber
+ (NSDecimalNumber *)minimumDecimalNumber
See Also: + maximumDecimalNumber
+ (NSDecimalNumber *)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.
+ (NSDecimalNumber *)one
See Also: + zero
+ (void)setDefaultBehavior:(id <NSDecimalNumberBehaviors>)behavior
+ (NSDecimalNumber *)zero
See Also: + one
- (NSComparisonResult)compare:(NSNumber *)decimalNumber
- (NSDecimalNumber *)decimalNumberByAdding:(NSDecimalNumber *)decimalNumber
See Also: - decimalNumberByAdding:withBehavior:, + defaultBehavior
- (NSDecimalNumber *)decimalNumberByAdding:(NSDecimalNumber *)decimalNumber
withBehavior:(id <NSDecimalNumberBehaviors>)behavior
- (NSDecimalNumber *)decimalNumberByDividingBy:(NSDecimalNumber *)decimalNumber
See Also: - decimalNumberByDividingBy:withBehavior:, + defaultBehavior
- (NSDecimalNumber *)decimalNumberByDividingBy:(NSDecimalNumber *)decimalNumber
withBehavior:(id <NSDecimalNumberBehaviors>)behavior
- (NSDecimalNumber *)decimalNumberByMultiplyingBy:(NSDecimalNumber *)decimalNumber
See Also: - decimalNumberByMultiplyingBy:withBehavior:, + defaultBehavior
- (NSDecimalNumber *)decimalNumberByMultiplyingBy:(NSDecimalNumber *)decimalNumber
withBehavior:(id <NSDecimalNumberBehaviors>)behavior
- (NSDecimalNumber *)decimalNumberByMultiplyingByPowerOf10:(short)power
See Also: - decimalNumberByMultiplyingByPowerOf10:withBehavior:, + defaultBehavior
- (NSDecimalNumber *)decimalNumberByMultiplyingByPowerOf10:(short)power withBehavior:(id
<NSDecimalNumberBehaviors>)behavior
- (NSDecimalNumber *)decimalNumberByRaisingToPower:(unsigned)power
See Also: - decimalNumberByRaisingToPower:withBehavior:, + defaultBehavior
- (NSDecimalNumber *)decimalNumberByRaisingToPower:(unsigned)power withBehavior:(id
<NSDecimalNumberBehaviors>)behavior
- (NSDecimalNumber *)decimalNumberByRoundingAccordingToBehavior:(id
<NSDecimalNumberBehaviors>)behavior
- (NSDecimalNumber *)decimalNumberBySubtracting:(NSDecimalNumber *)decimalNumber
See Also: - decimalNumberBySubtracting:withBehavior:, + defaultBehavior
- (NSDecimalNumber *)decimalNumberBySubtracting:(NSDecimalNumber *)decimalNumber
withBehavior:(id <NSDecimalNumberBehaviors>)behavior
- (NSDecimal)decimalValue
- (NSString *)descriptionWithLocale:(NSDictionary
*)locale
- (double)doubleValue
- (NSDecimalNumber *)initWithDecimal:(NSDecimal)decimal
- (NSDecimalNumber *)initWithMantissa:(unsigned
long long)mantissa exponent:(short)exponent isNegative:(BOOL)isNegative
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.
- (NSDecimalNumber *)initWithString:(NSString
*)numericString
- (NSDecimalNumber *)initWithString:(NSString
*)numericString locale:(NSDictionary *)locale
See Also: + decimalNumberWithString:locale:
- (const char *)objCType