iOS Developer Library

Developer

Foundation Framework Reference NSDecimalNumber Class Reference

Options
Deployment Target:

On This Page
Language:

NSDecimalNumber

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.

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 2.0 and later.
  • 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:

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an NSDecimalNumber object whose value is equivalent to that in a given numeric string, interpreted using a given locale.

    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”

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Returns an NSDecimalNumber object equivalent to the number 1.0.

    Declaration

    Swift

    class func one() -> NSDecimalNumber

    Objective-C

    + (NSDecimalNumber *)one

    Return Value

    An NSDecimalNumber object equivalent to the number 1.0.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    + zero

  • Returns an NSDecimalNumber object equivalent to the number 0.0.

    Declaration

    Swift

    class func zero() -> NSDecimalNumber

    Objective-C

    + (NSDecimalNumber *)zero

    Return Value

    An NSDecimalNumber object equivalent to the number 0.0.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    + one

  • Returns an NSDecimalNumber object that specifies no number.

    Declaration

    Swift

    class func notANumber() -> NSDecimalNumber

    Objective-C

    + (NSDecimalNumber *)notANumber

    Return Value

    An NSDecimalNumber object that specifies no number.

    Discussion

    Any arithmetic method receiving notANumber as an argument returns notANumber.

    This value can be a useful way of handling non-numeric data in an input file. This method 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • initWithDecimal: - initWithDecimal: Designated Initializer

    Returns an NSDecimalNumber object initialized to represent a given decimal.

    Declaration

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns an NSDecimalNumber object initialized so that its value is equivalent to that in a given numeric string.

    Declaration

    Swift

    convenience init(string numericString: String?)

    Objective-C

    - (instancetype)initWithString:(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. For a listing of acceptable and unacceptable strings, see the class method decimalNumberWithString:locale:.

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • 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 numericString: 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

    @property(readonly) NSDecimal decimalValue

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.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).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    let NSDecimalNumberExactnessException: NSString! let NSDecimalNumberOverflowException: NSString! let NSDecimalNumberUnderflowException: NSString! let NSDecimalNumberDivideByZeroException: NSString!

    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 iOS 2.0 and later.

    • NSDecimalNumberOverflowException

      NSDecimalNumberOverflowException

      The name of the exception raised on overflow.

      Available in iOS 2.0 and later.

    • NSDecimalNumberUnderflowException

      NSDecimalNumberUnderflowException

      The name of the exception raised on underflow.

      Available in iOS 2.0 and later.

    • NSDecimalNumberDivideByZeroException

      NSDecimalNumberDivideByZeroException

      The name of the exception raised on divide by zero.

      Available in iOS 2.0 and later.