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.

Parameters

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.

Declaration

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.

Declaration

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:

Parameters

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.

Declaration

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.

Declaration

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.

Declaration

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.