# Using Decimal Numbers

`NSDecimalNumber`

is an immutable subclass of `NSNumber`

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

## C Interface to Decimal Numbers

You can access the arithmetic and rounding methods of `NSDecimalNumber`

through group of C functions:

`NSDecimalAdd` | Adds two decimal values. |

`NSDecimalCompact` | Compacts the decimal structure for efficiency. |

`NSDecimalCompare` | Compares two decimal values. |

`NSDecimalCopy` | Copies the value of a decimal number. |

`NSDecimalDivide` | Divides one decimal value by another. |

`NSDecimalIsNotANumber` | Returns a Boolean that indicates whether a given decimal contains a valid number. |

`NSDecimalMultiply` | Multiplies two decimal numbers together. |

`NSDecimalMultiplyByPowerOf10` | Multiplies a decimal by the specified power of 10. |

`NSDecimalNormalize` | Normalizes the internal format of two decimal numbers to simplify later operations. |

`NSDecimalPower` | Raises the decimal value to the specified power. |

`NSDecimalRound` | Rounds off the decimal value. |

`NSDecimalString` | Returns a string representation of the decimal value. |

`NSDecimalSubtract` | Subtracts one decimal value from another. |

You might consider the C interface if you don’t need to treat decimal numbers as objects—that is, if you don’t need to store them in an object-oriented collection like an instance of `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 instances of `NSDecimalNumber`

.

Copyright © 2008 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2008-02-08