NSDecimalNumber

Inherits From

NSObject
NSValue
NSNumber
NSDecimalNumber

NSObject
NSValue
NSNumber
NSDecimalNumber

Conforms To

Import Statement

Objective-C

@import Foundation;

Swift

import Foundation

Availability

Available in OS X v10.0 and later

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 10^exponent where mantissa is a decimal integer up to 38 digits long, and exponent is an integer from –128 through 127.

Creating a Decimal Number

+ decimalNumberWithDecimal:

Creates and returns an NSDecimalNumber object equivalent to a given NSDecimal structure.

Declaration

Objective-C

+ (NSDecimalNumber *)decimalNumberWithDecimal:(NSDecimal)decimal

Parameters

decimal

An NSDecimal structure that specifies the value for the new decimal number object.

Return Value

An NSDecimalNumber object equivalent to decimal.

Discussion

You can initialize decimal programmatically or generate it using the NSScanner method, scanDecimal:

Availability

Available in OS X v10.0 and later.


    
      
           + decimalNumberWithMantissa:exponent:isNegative:

Creates and returns an NSDecimalNumber object equivalent to the number specified by the arguments.

Declaration

Objective-C

+ (NSDecimalNumber *)decimalNumberWithMantissa:(unsigned long long)mantissa exponent:(short)exponent isNegative:(BOOL)isNegative

Parameters

`mantissa`	The mantissa for the new decimal number object.
`exponent`	The exponent for the new decimal number object.
`isNegative`	A Boolean value that specifies whether the sign of the number is negative.

Discussion

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 –12.345, it is expressed as 12345x10^–3—mantissa is 12345; exponent is –3; and isNegative is YEStrue, as illustrated by the following example.

        NSDecimalNumber *number = [NSDecimalNumber decimalNumberWithMantissa:12345
                                           exponent:-3
                                           isNegative:YES];

      

Availability

Available in OS X v10.0 and later.


    
      
           + decimalNumberWithString:

Creates and returns an NSDecimalNumber object whose value is equivalent to that in a given numeric string.

Declaration

Objective-C

+ (NSDecimalNumber *)decimalNumberWithString:(NSString *)numericString

Parameters


  numericString

A numeric string.

Besides digits, numericString can include an initial “+” or “–”; a single “E” or “e”, to indicate the exponent of a number in scientific notation; and a single NSLocaleDecimalSeparator to divide the fractional from the integral part of the number.

Return Value

An NSDecimalNumber object whose value is equivalent to numericString.

Discussion

Whether the NSLocaleDecimalSeparator is a period (as is used, for example, in the United States) or a comma (as is used, for example, in France) depends on the default locale.

Availability

Available in OS X v10.0 and later.

Declaration

Objective-C

+ (NSDecimalNumber *)decimalNumberWithString:(NSString *)numericString locale:(id)locale

Parameters

`numericString`	A numeric string. Besides digits, `numericString` can include an initial “+” or “–”; a single “E” or “e”, to indicate the exponent of a number in scientific notation; and a single `NSLocaleDecimalSeparator` to divide the fractional from the integral part of the number.
`locale`	A dictionary that defines the locale (specifically the `NSLocaleDecimalSeparator`) to use to interpret the number in `numericString`.

Return Value

An NSDecimalNumber object whose value is equivalent to numericString.

Discussion

The locale parameter determines whether the NSLocaleDecimalSeparator is a period (as is used, for example, in the United States) or a comma (as is used, for example, in France).

The following strings show examples of acceptable values for numericString:

“2500.6” (or “2500,6”, depending on locale)
“–2500.6” (or “–2500.6”)
“–2.5006e3” (or “–2,5006e3”)
“–2.5006E3” (or “–2,5006E3”)

The following strings are unacceptable:

“2,500.6”
“2500 3/5”
“2.5006x10e3”
“two thousand five hundred and six tenths”

Availability

Available in OS X v10.0 and later.

Initializing a Decimal Number

init(decimal:) - initWithDecimal: Designated Initializer

Returns an NSDecimalNumber object initialized to represent a given decimal.

Declaration

Swift

init(decimal dcm: NSDecimal)

Objective-C

- (instancetype)initWithDecimal:(NSDecimal)decimal

Parameters

decimal

The value of the new object.

Return Value

An NSDecimalNumber object initialized to represent decimal.

Discussion

This method is the designated initializer for NSDecimalNumber.

Availability

Available in OS X v10.0 and later.


    
      
           init(mantissa:exponent:isNegative:)
      
      
           - initWithMantissa:exponent:isNegative:

Returns an NSDecimalNumber object initialized using the given mantissa, exponent, and sign.

Declaration

Swift

convenience init(mantissa mantissa: UInt64, exponent exponent: Int16, isNegative flag: Bool)

Objective-C

- (instancetype)initWithMantissa:(unsigned long long)mantissa exponent:(short)exponent isNegative:(BOOL)flag

Parameters

`mantissa`	The mantissa for the new decimal number object.
`exponent`	The exponent for the new decimal number object.
`flag`	A Boolean value that specifies whether the sign of the number is negative.

Return Value

An NSDecimalNumber object initialized using the given mantissa, exponent, and sign.

Discussion

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 NOfalse.

Availability

Available in OS X v10.0 and later.

Declaration

Swift

convenience init(string numberValue: String?)

Objective-C

- (instancetype)initWithString:(NSString *)numericString

Parameters


  numericString

A numeric string.

Return Value

An NSDecimalNumber object initialized so that its value is equivalent to that in numericString.

Availability

Available in OS X v10.0 and later.


    
      
           init(string:locale:)
      
      
           - initWithString:locale:

Returns an NSDecimalNumber object initialized so that its value is equivalent to that in a given numeric string, interpreted using a given locale.

Declaration

Swift

convenience init(string numberValue: String?, locale locale: AnyObject?)

Objective-C

- (instancetype)initWithString:(NSString *)numericString locale:(id)locale

Parameters

`numericString`	A numeric string. Besides digits, `numericString` can include an initial “+” or “–”; a single “E” or “e”, to indicate the exponent of a number in scientific notation; and a single `NSLocaleDecimalSeparator` to divide the fractional from the integral part of the number.
`locale`	A dictionary that defines the locale (specifically the `NSLocaleDecimalSeparator`) to use to interpret the number in `numericString`.

Return Value

An NSDecimalNumber object initialized so that its value is equivalent to that in numericString, interpreted using locale.

Availability

Available in OS X v10.0 and later.

Performing Arithmetic

decimalNumberByAdding(_:) - decimalNumberByAdding:

Returns a new NSDecimalNumber object whose value is the sum of the receiver and another given NSDecimalNumber object.

Declaration

Swift

func decimalNumberByAdding(_ decimalNumber: NSDecimalNumber) -> NSDecimalNumber

Objective-C

- (NSDecimalNumber *)decimalNumberByAdding:(NSDecimalNumber *)decimalNumber

Parameters

decimalNumber

The number to add to the receiver.

Return Value

A new NSDecimalNumber object whose value is the sum of the receiver and decimalNumber.

Discussion

This method uses the default behavior when handling calculation errors and rounding.

Availability

Available in OS X v10.0 and later.

See Also

– decimalNumberByAdding:withBehavior:
+ defaultBehavior
decimalNumberBySubtracting(_:) - decimalNumberBySubtracting:

Returns a new NSDecimalNumber object whose value is that of another given NSDecimalNumber object subtracted from the value of the receiver.

Declaration

Swift

func decimalNumberBySubtracting(_ decimalNumber: NSDecimalNumber) -> NSDecimalNumber

Objective-C

- (NSDecimalNumber *)decimalNumberBySubtracting:(NSDecimalNumber *)decimalNumber

Parameters

decimalNumber

The number to subtract from the receiver.

Return Value

A new NSDecimalNumber object whose value is decimalNumber subtracted from the receiver.

Discussion

This method uses the default behavior when handling calculation errors and when rounding.

Availability

Available in OS X v10.0 and later.

See Also

– decimalNumberBySubtracting:withBehavior:
+ defaultBehavior
decimalNumberByMultiplyingBy(_:) - decimalNumberByMultiplyingBy:

Returns a new NSDecimalNumber object whose value is the value of the receiver multiplied by that of another given NSDecimalNumber object.

Declaration

Swift

func decimalNumberByMultiplyingBy(_ decimalNumber: NSDecimalNumber) -> NSDecimalNumber

Objective-C

- (NSDecimalNumber *)decimalNumberByMultiplyingBy:(NSDecimalNumber *)decimalNumber

Parameters

decimalNumber

The number by which to multiply the receiver.

Return Value

A new NSDecimalNumber object whose value is decimalNumber multiplied by the receiver.

Discussion

This method uses the default behavior when handling calculation errors and when rounding.

Availability

Available in OS X v10.0 and later.

See Also

– decimalNumberByMultiplyingBy:withBehavior:
+ defaultBehavior
decimalNumberByDividingBy(_:) - decimalNumberByDividingBy:

Returns a new NSDecimalNumber object whose value is the value of the receiver divided by that of another given NSDecimalNumber object.

Declaration

Swift

func decimalNumberByDividingBy(_ decimalNumber: NSDecimalNumber) -> NSDecimalNumber

Objective-C

- (NSDecimalNumber *)decimalNumberByDividingBy:(NSDecimalNumber *)decimalNumber

Parameters

decimalNumber

The number by which to divide the receiver.

Return Value

A new NSDecimalNumber object whose value is the value of the receiver divided by decimalNumber.

Discussion

This method uses the default behavior when handling calculation errors and rounding.

Availability

Available in OS X v10.0 and later.

See Also

– decimalNumberByDividingBy:withBehavior:
+ defaultBehavior
decimalNumberByRaisingToPower(_:) - decimalNumberByRaisingToPower:

Returns a new NSDecimalNumber object whose value is the value of the receiver raised to a given power.

Declaration

Swift

func decimalNumberByRaisingToPower(_ power: Int) -> NSDecimalNumber

Objective-C

- (NSDecimalNumber *)decimalNumberByRaisingToPower:(NSUInteger)power

Parameters

power

The power to which to raise the receiver.

Return Value

A new NSDecimalNumber object whose value is the value of the receiver raised to the power power.

Discussion

This method uses the default behavior when handling calculation errors and when rounding.

Availability

Available in OS X v10.0 and later.

See Also

– decimalNumberByRaisingToPower:withBehavior:
+ defaultBehavior
decimalNumberByMultiplyingByPowerOf10(_:) - decimalNumberByMultiplyingByPowerOf10:

Multiplies the receiver by 10^power and returns the product, a newly created NSDecimalNumber object.

Declaration

Swift

func decimalNumberByMultiplyingByPowerOf10(_ power: Int16) -> NSDecimalNumber

Objective-C

- (NSDecimalNumber *)decimalNumberByMultiplyingByPowerOf10:(short)power

Discussion

This method uses the default behavior when handling calculation errors and when rounding.

Availability

Available in OS X v10.0 and later.

See Also

– decimalNumberByMultiplyingByPowerOf10:withBehavior:
+ defaultBehavior
decimalNumberByAdding(_:withBehavior:) - decimalNumberByAdding:withBehavior:

Adds decimalNumber to the receiver and returns the sum, a newly created NSDecimalNumber object.

Declaration

Swift

func decimalNumberByAdding(_ decimalNumber: NSDecimalNumber, withBehavior behavior: NSDecimalNumberBehaviors?) -> NSDecimalNumber

Objective-C

- (NSDecimalNumber *)decimalNumberByAdding:(NSDecimalNumber *)decimalNumber withBehavior:(id<NSDecimalNumberBehaviors>)behavior

Discussion

behavior specifies the handling of calculation errors and rounding.

Availability

Available in OS X v10.0 and later.
decimalNumberBySubtracting(_:withBehavior:) - decimalNumberBySubtracting:withBehavior:

Subtracts decimalNumber from the receiver and returns the difference, a newly created NSDecimalNumber object.

Declaration

Swift

func decimalNumberBySubtracting(_ decimalNumber: NSDecimalNumber, withBehavior behavior: NSDecimalNumberBehaviors?) -> NSDecimalNumber

Objective-C

- (NSDecimalNumber *)decimalNumberBySubtracting:(NSDecimalNumber *)decimalNumber withBehavior:(id<NSDecimalNumberBehaviors>)behavior

Discussion

behavior specifies the handling of calculation errors and rounding.

Availability

Available in OS X v10.0 and later.
decimalNumberByMultiplyingBy(_:withBehavior:) - decimalNumberByMultiplyingBy:withBehavior:

Multiplies the receiver by decimalNumber and returns the product, a newly created NSDecimalNumber object.

Declaration

Swift

func decimalNumberByMultiplyingBy(_ decimalNumber: NSDecimalNumber, withBehavior behavior: NSDecimalNumberBehaviors?) -> NSDecimalNumber

Objective-C

- (NSDecimalNumber *)decimalNumberByMultiplyingBy:(NSDecimalNumber *)decimalNumber withBehavior:(id<NSDecimalNumberBehaviors>)behavior

Discussion

behavior specifies the handling of calculation errors and rounding.

Availability

Available in OS X v10.0 and later.
decimalNumberByDividingBy(_:withBehavior:) - decimalNumberByDividingBy:withBehavior:

Divides the receiver by decimalNumber and returns the quotient, a newly created NSDecimalNumber object.

Declaration

Swift

func decimalNumberByDividingBy(_ decimalNumber: NSDecimalNumber, withBehavior behavior: NSDecimalNumberBehaviors?) -> NSDecimalNumber

Objective-C

- (NSDecimalNumber *)decimalNumberByDividingBy:(NSDecimalNumber *)decimalNumber withBehavior:(id<NSDecimalNumberBehaviors>)behavior

Discussion

behavior specifies the handling of calculation errors and rounding.

Availability

Available in OS X v10.0 and later.
decimalNumberByRaisingToPower(_:withBehavior:) - decimalNumberByRaisingToPower:withBehavior:

Raises the receiver to power and returns the result, a newly created NSDecimalNumber object.

Declaration

Swift

func decimalNumberByRaisingToPower(_ power: Int, withBehavior behavior: NSDecimalNumberBehaviors?) -> NSDecimalNumber

Objective-C

- (NSDecimalNumber *)decimalNumberByRaisingToPower:(NSUInteger)power withBehavior:(id<NSDecimalNumberBehaviors>)behavior

Discussion

behavior specifies the handling of calculation errors and rounding.

Availability

Available in OS X v10.0 and later.
decimalNumberByMultiplyingByPowerOf10(_:withBehavior:) - decimalNumberByMultiplyingByPowerOf10:withBehavior:

Multiplies the receiver by 10^power and returns the product, a newly created NSDecimalNumber object.

Declaration

Swift

func decimalNumberByMultiplyingByPowerOf10(_ power: Int16, withBehavior behavior: NSDecimalNumberBehaviors?) -> NSDecimalNumber

Objective-C

- (NSDecimalNumber *)decimalNumberByMultiplyingByPowerOf10:(short)power withBehavior:(id<NSDecimalNumberBehaviors>)behavior

Discussion

behavior specifies the handling of calculation errors and rounding.

Availability

Available in OS X v10.0 and later.

Rounding Off

decimalNumberByRoundingAccordingToBehavior(_:) - decimalNumberByRoundingAccordingToBehavior:

Rounds the receiver off in the way specified by behavior and returns the result, a newly created NSDecimalNumber object.

Declaration

Swift

func decimalNumberByRoundingAccordingToBehavior(_ behavior: NSDecimalNumberBehaviors?) -> NSDecimalNumber

Objective-C

- (NSDecimalNumber *)decimalNumberByRoundingAccordingToBehavior:(id<NSDecimalNumberBehaviors>)behavior

Discussion

For a description of the different ways of rounding, see the roundingMode method in the NSDecimalNumberBehaviors protocol specification.

Availability

Available in OS X v10.0 and later.

Accessing the Value

decimalValue decimalValue Property

The decimal number’s value, expressed as an NSDecimal structure. (read-only)

Declaration

Swift

var decimalValue: NSDecimal { get }

Objective-C

@property(readonly) NSDecimal decimalValue

Availability

Available in OS X v10.0 and later.
doubleValue doubleValue Property

The decimal number’s closest approximate double value. (read-only)

Declaration

Swift

var doubleValue: Double { get }

Objective-C

@property(readonly) double doubleValue

Discussion

Not all decimal numbers can be accurately represented using a double value.

Availability

Available in OS X v10.0 and later.
descriptionWithLocale(_:) - descriptionWithLocale:

Returns a string, specified according to a given locale, that represents the contents of the receiver.

Declaration

Swift

func descriptionWithLocale(_ locale: AnyObject?) -> String

Objective-C

- (NSString *)descriptionWithLocale:(id)locale

Parameters

locale

A dictionary that defines the locale (specifically the NSLocaleDecimalSeparator) to use to generate the returned string.

Return Value

A string that represents the contents of the receiver, according to locale.

Availability

Available in OS X v10.0 and later.
objCType objCType Property

A C string containing the Objective-C type for the data contained in the decimal number object. (read-only)

Declaration

Swift

var objCType: UnsafePointer<Int8> { get }

Objective-C

@property(readonly) const char *objCType

Discussion

For a decimal number object, this property always contains “d” (for double).

Availability

Available in OS X v10.0 and later.

Managing Behavior

defaultBehavior() + defaultBehavior

Returns the way arithmetic methods, like decimalNumberByAdding:, round off and handle error conditions.

Declaration

Swift

class func defaultBehavior() -> NSDecimalNumberBehaviors

Objective-C

+ (id<NSDecimalNumberBehaviors>)defaultBehavior

Discussion

By default, the arithmetic methods use the NSRoundPlain behavior; that is, the methods round to the closest possible return value. The methods assume your need for precision does not exceed 38 significant digits and raise exceptions when they try to divide by 0 or 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:.

The default behavior is maintained separately for each thread in your app.

Availability

Available in OS X v10.0 and later.
setDefaultBehavior(_:) + setDefaultBehavior:

Specifies the way that arithmetic methods, like decimalNumberByAdding:, round off and handle error conditions.

Declaration

Swift

class func setDefaultBehavior(_ behavior: NSDecimalNumberBehaviors)

Objective-C

+ (void)setDefaultBehavior:(id<NSDecimalNumberBehaviors>)behavior

Discussion

behavior must conform to the NSDecimalNumberBehaviors protocol.

The default behavior is maintained separately for each thread in your app. setDefaultBehavior: sets the default behavior for the thread on which it’s executed.

Availability

Available in OS X v10.0 and later.

Comparing Decimal Numbers


    
      
           compare(_:)
      
      
           - compare:

Returns an NSComparisonResult value that indicates the numerical ordering of the receiver and another given NSDecimalNumber object.

Declaration

Swift

func compare(_ decimalNumber: NSNumber) -> NSComparisonResult

Objective-C

- (NSComparisonResult)compare:(NSNumber *)decimalNumber

Parameters


  decimalNumber

The number with which to compare the receiver.

This value must not be nil. If this value is nil, the behavior is undefined and may change in future versions of OS X.

Return Value

NSOrderedAscending if the value of decimalNumber is greater than the receiver; NSOrderedSame if they’re equal; and NSOrderedDescending if the value of decimalNumber is less than the receiver.

Availability

Available in OS X v10.0 and later.

Getting Maximum and Minimum Possible Values

maximumDecimalNumber() + maximumDecimalNumber

Returns the largest possible value of an NSDecimalNumber object.

Declaration

Swift

class func maximumDecimalNumber() -> NSDecimalNumber

Objective-C

+ (NSDecimalNumber *)maximumDecimalNumber

Return Value

The largest possible value of an NSDecimalNumber object.

Availability

Available in OS X v10.0 and later.

See Also

+ minimumDecimalNumber
minimumDecimalNumber() + minimumDecimalNumber

Returns the smallest possible value of an NSDecimalNumber object.

Declaration

Swift

class func minimumDecimalNumber() -> NSDecimalNumber

Objective-C

+ (NSDecimalNumber *)minimumDecimalNumber

Return Value

The smallest possible value of an NSDecimalNumber object.

Availability

Available in OS X v10.0 and later.

See Also

+ maximumDecimalNumber

Constants

NSDecimalNumber Exception Names
Names of the various exceptions raised by NSDecimalNumber to indicate computational errors.

Declaration

Swift

let NSDecimalNumberExactnessException: String let NSDecimalNumberOverflowException: String let NSDecimalNumberUnderflowException: String let NSDecimalNumberDivideByZeroException: String

Objective-C

extern NSString *NSDecimalNumberExactnessException; extern NSString *NSDecimalNumberOverflowException; extern NSString *NSDecimalNumberUnderflowException; extern NSString *NSDecimalNumberDivideByZeroException;

Constants
- NSDecimalNumberExactnessException
  
  NSDecimalNumberExactnessException
  
  The name of the exception raised if there is an exactness error.
  
  Available in OS X v10.0 and later.
- NSDecimalNumberOverflowException
  
  NSDecimalNumberOverflowException
  
  The name of the exception raised on overflow.
  
  Available in OS X v10.0 and later.
- NSDecimalNumberUnderflowException
  
  NSDecimalNumberUnderflowException
  
  The name of the exception raised on underflow.
  
  Available in OS X v10.0 and later.
- NSDecimalNumberDivideByZeroException
  
  NSDecimalNumberDivideByZeroException
  
  The name of the exception raised on divide by zero.
  
  Available in OS X v10.0 and later.

NSDecimalNumber

Creating a Decimal Number

Declaration

Parameters

Return Value

Discussion

Availability

Declaration

Parameters

Discussion

Availability

Declaration

Parameters

Return Value

Discussion

Availability

See Also

Declaration

Parameters

Return Value

Discussion

Availability

See Also

Declaration

Return Value

Availability

See Also

Declaration

Return Value

Availability

See Also

Declaration

Return Value

Discussion

Availability

Initializing a Decimal Number

Declaration

Parameters

Return Value

Discussion

Availability

Declaration

Parameters

Return Value

Discussion

Availability

See Also

Declaration

Parameters

Return Value

Availability

Declaration

Parameters

Return Value

Availability

See Also

Performing Arithmetic

Declaration

Parameters

Return Value

Discussion

Availability

See Also

Declaration

Parameters

Return Value

Discussion

Availability

See Also

Declaration

Parameters

Return Value

Discussion

Availability

See Also

Declaration

Parameters

Return Value

Discussion

Availability