NSDecimalNumber

NSDecimalNumber is a Foundation class that provides an immutable decimal-number object and supports precise base-10 arithmetic. It is a subclass of NSNumber and is designed to avoid the rounding errors associated with binary floating-point types, making it well suited for financial calculations and other domains requiring exact decimal results.

NSDecimalNumber uses an internal decimal representation with a fixed precision of up to 38 significant digits and a base-10 exponent. This enables accurate representation of many decimal values that are inexact in binary floating-point formats. Results of arithmetic operations may be exact or rounded, depending on the configured behavior.

To control rounding and error handling, NSDecimalNumber relies on an object that conforms to NSDecimalNumberBehaviors, typically an NSDecimalNumberHandler. The handler specifies the rounding mode, the scale (number of digits after the decimal point), and how to handle overflow, underflow, and inexact results. By supplying a behavior object, developers can tailor arithmetic to financial or regulatory requirements.

Creating NSDecimalNumber instances can be done via factory methods such as +decimalNumberWithString:, +decimalNumberWithDecimal:, and +decimalNumberWithMantissa:exponent:isNegative:. There are corresponding initializers, and the class provides convenient values such as notANumber and zero. NSDecimalNumber instances are immutable, allowing safe sharing across threads and contexts.

Arithmetic with NSDecimalNumber is provided through methods such as -adding:, -subtracting:, -multiplying:, and -dividing:, each returning a new NSDecimalNumber. The results are governed by the specified NSDecimalNumberHandler, enabling consistent rounding and overflow behavior. The class also supports conversion to other types (for example, string or double) and interoperation with Swift’s Decimal type, making it a common choice for precise decimal calculations in Apple platforms.