- 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 NSRoundPlain
,
that is, the method rounds to the closest possible return value.
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
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.- (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
- (id)initWithDecimal:(NSDecimal)decimal
- (id)initWithMantissa:(unsigned
long long)mantissa
exponent:(short)exponent
isNegative:(BOOL)flag
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.
- (id)initWithString:(NSString
*)numberValue
- (id)initWithString:(NSString
*)numberValue
locale:(NSDictionary *)locale
See Also: + decimalNumberWithString:locale:
- (const char *)objCType