Class

# NSDecimalNumber

An object for representing and performing arithmetic on base-10 numbers.

## Overview

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

## Topics

### Creating a Decimal Number

`+ decimalNumberWithDecimal:`

Creates and returns a decimal number equivalent to a given decimal structure.

`+ decimalNumberWithMantissa:exponent:isNegative:`

Creates and returns a decimal number equivalent to the number specified by the arguments.

`+ decimalNumberWithString:`

Creates a decimal number whose value is equivalent to that in a given numeric string.

`+ decimalNumberWithString:locale:`

Creates a decimal number whose value is equivalent to that in a given numeric string, interpreted using a given locale.

`one`

A decimal number equivalent to the number 1.0.

`zero`

A decimal number equivalent to the number 0.0.

`notANumber`

A decimal number that specifies no number.

### Initializing a Decimal Number

`- initWithDecimal:`

Initializes a decimal number to represent a given decimal.

`- initWithMantissa:exponent:isNegative:`

Initializes a decimal number using the given mantissa, exponent, and sign.

`- initWithString:`

Initializes a decimal number so that its value is equivalent to that in a given numeric string.

`- initWithString:locale:`

Initializes a decimal number so that its value is equivalent to that in a given numeric string, interpreted using a given locale.

### Performing Arithmetic

`- decimalNumberByAdding:`

Adds this number to another given number.

`- decimalNumberBySubtracting:`

Subtracts another given number from this one.

`- decimalNumberByMultiplyingBy:`

Multiplies the number by another given number.

`- decimalNumberByDividingBy:`

Divides the number by another given number.

`- decimalNumberByRaisingToPower:`

Raises the number to a given power.

`- decimalNumberByMultiplyingByPowerOf10:`

Multiplies the number by 10 raised to the given power.

`- decimalNumberByAdding:withBehavior:`

Adds this number to another given number using the specified behavior.

`- decimalNumberBySubtracting:withBehavior:`

Subtracts this a given number from this one using the specified behavior.

`- decimalNumberByMultiplyingBy:withBehavior:`

Multiplies this number by another given number using the specified behavior.

`- decimalNumberByDividingBy:withBehavior:`

Divides this number by another given number using the specified behavior.

`- decimalNumberByRaisingToPower:withBehavior:`

Raises the number to a given power using the specified behavior.

`- decimalNumberByMultiplyingByPowerOf10:withBehavior:`

Multiplies the number by 10 raised to the given power using the specified behavior.

### Rounding Off

`- decimalNumberByRoundingAccordingToBehavior:`

Returns a rounded version of the decimal number using the specified rounding behavior.

### Managing Behavior

`defaultBehavior`

The way arithmetic methods round off and handle error conditions.

`NSDecimalNumberBehaviors`

A protocol that declares three methods that control the discretionary aspects of working with decimal numbers.

`NSDecimalNumberHandler`

A class that adopts the decimal number behaviors protocol.

### Accessing the Value

`decimalValue`

The decimal number’s value, expressed as an `NSDecimal` structure.

`doubleValue`

The decimal number’s closest approximate `double` value.

`- descriptionWithLocale:`

Returns a string representation of the decimal number appropriate for the specified locale.

`objCType`

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

### Comparing Decimal Numbers

`- compare:`

Compares this decimal number and another.

### Getting Maximum and Minimum Possible Values

`maximumDecimalNumber`

Returns the largest possible value of a decimal number.

`minimumDecimalNumber`

Returns the smallest possible value of a decimal number.

### Recognizing Exceptions

Exceptions with these names may be raised to indicate computational errors with decimal numbers.

`NSDecimalNumberExactnessException`

The exception raised if there is an exactness error.

`NSDecimalNumberOverflowException`

The exception raised on overflow.

`NSDecimalNumberUnderflowException`

The exception raised on underflow.

`NSDecimalNumberDivideByZeroException`

The exception raised on divide by zero.

## Relationships

### Numbers

`NSInteger`

Describes an integer.

`NSUInteger`

Describes an unsigned integer.

`NSDecimal`

A structure representing a base-10 number.

`NSNumber`

An object wrapper for primitive scalar numeric values.

`NSNumberFormatter`

A formatter that converts between numeric values and their textual representations.