# NSDecimalNumberBehaviors Protocol Reference

 Adopted by Framework /System/Library/Frameworks/Foundation.framework Availability Available in OS X v10.0 and later. Companion guide Declared in NSDecimal.hNSDecimalNumber.h

## Overview

The `NSDecimalBehaviors` protocol declares three methods that control the discretionary aspects of working with `NSDecimalNumber` objects.

The `scale` and `roundingMode` methods determine the precision of `NSDecimalNumber`’s return values and the way in which those values should be rounded to fit that precision. The `exceptionDuringOperation:error:leftOperand:rightOperand:` method determines the way in which an `NSDecimalNumber` object should handle different calculation errors.

For an example of a class that adopts the `NSDecimalBehaviors` protocol, see the specification for NSDecimalNumberHandler.

## Instance Methods

### exceptionDuringOperation:error:leftOperand:rightOperand:

Specifies what an `NSDecimalNumber` object will do when it encounters an error. (required)

- (NSDecimalNumber *)exceptionDuringOperation:(SEL)method error:(NSCalculationError)error leftOperand:(NSDecimalNumber *)leftOperand rightOperand:(NSDecimalNumber *)rightOperand
##### Parameters
method

The method that was being executed when the error occurred.

error

The type of error that was generated.

leftOperand

The left operand.

rightOperand

The right operand.

##### Discussion

There are four possible values for error, described in NSCalculationError. The first three have to do with limits on the ability of `NSDecimalNumber` to represent decimal numbers. An `NSDecimalNumber` object 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 between –256 and 256. The fourth results from the caller trying to divide by `0`.

In implementing `exceptionDuringOperation:error:leftOperand:rightOperand:`, you can handle each of these errors in several ways:

• Raise an exception. For an explanation of exceptions, see Exception Programming Topics.

• Return `nil`. The calling method will return its value as though no error had occurred. If error is `NSCalculationLossOfPrecision`, method will return an imprecise value—that is, one constrained to 38 significant digits. If error is `NSCalculationUnderflow` or `NSCalculationOverflow`, method will return `NSDecimalNumber`'s `notANumber`. You shouldn’t return `nil` if error is `NSDivideByZero`.

• Correct the error and return a valid `NSDecimalNumber` object. The calling method will use this as its own return value.

##### Availability
• Available in OS X v10.0 and later.
##### Declared In
`NSDecimalNumber.h`

### roundingMode

Returns the way that `NSDecimalNumber`'s `decimalNumberBy...` methods round their return values. (required)

- (NSRoundingMode)roundingMode
##### Return Value

Returns the current rounding mode. See “NSRoundingMode” for possible values.

##### Availability
• Available in OS X v10.0 and later.
##### Declared In
`NSDecimalNumber.h`

### scale

Returns the number of digits allowed after the decimal separator. (required)

- (short)scale
##### Return Value

The number of digits allowed after the decimal separator.

##### Discussion

This method limits the precision of the values returned by `NSDecimalNumber`’s `decimalNumberBy...` methods. If `scale` returns a negative value, it affects the digits before the decimal separator as well. If `scale` returns `NSDecimalNoScale`, the number of digits is unlimited.

Assuming that `roundingMode` returns `NSRoundPlain`, different values of `scale` have the following effects on the number 123.456:

Scale

Return Value

`NSDecimalNoScale`

123.456

2

123.45

0

123

–2

100

##### Availability
• Available in OS X v10.0 and later.
##### Declared In
`NSDecimalNumber.h`

## Constants

### NSRoundingMode

These constants specify rounding behaviors.

```enum {
NSRoundPlain,
NSRoundDown,
NSRoundUp,
NSRoundBankers
};
typedef NSUInteger NSRoundingMode;
```
##### Constants
`NSRoundPlain`

Round to the closest possible return value; when caught halfway between two positive numbers, round up; when caught between two negative numbers, round down.

Available in OS X v10.0 and later.

Declared in `NSDecimal.h`.

`NSRoundDown`

Round return values down.

Available in OS X v10.0 and later.

Declared in `NSDecimal.h`.

`NSRoundUp`

Round return values up.

Available in OS X v10.0 and later.

Declared in `NSDecimal.h`.

`NSRoundBankers`

Round to the closest possible return value; when halfway between two possibilities, return the possibility whose last digit is even.

In practice, this means that, over the long run, numbers will be rounded up as often as they are rounded down; there will be no systematic bias.

Available in OS X v10.0 and later.

Declared in `NSDecimal.h`.

##### Discussion

The rounding mode matters only if the `scale` method sets a limit on the precision of `NSDecimalNumber` return values. It has no effect if `scale` returns `NSDecimalNoScale`. Assuming that `scale` returns 1, the rounding mode has the following effects on various original values:

Original Value

NSRoundPlain

NSRoundDown

NSRoundUp

NSRoundBankers

1.24

1.2

1.2

1.3

1.2

1.26

1.3

1.2

1.3

1.3

1.25

1.3

1.2

1.3

1.2

1.35

1.4

1.3

1.4

1.4

–1.35

–1.4

–1.4

–1.3

–1.4

### NSCalculationError

Calculation error constants used to describe an error in `exceptionDuringOperation:error:leftOperand:rightOperand:`.

```enum {
NSCalculationNoError = 0,
NSCalculationLossOfPrecision,
NSCalculationUnderflow,
NSCalculationOverflow,
NSCalculationDivideByZero
};
typedef NSUInteger NSCalculationError;
```
##### Constants
`NSCalculationNoError`

No error occurred.

Available in OS X v10.0 and later.

Declared in `NSDecimal.h`.

`NSCalculationLossOfPrecision`

The number can’t be represented in 38 significant digits.

Available in OS X v10.0 and later.

Declared in `NSDecimal.h`.

`NSCalculationOverflow`

The number is too large to represent.

Available in OS X v10.0 and later.

Declared in `NSDecimal.h`.

`NSCalculationUnderflow`

The number is too small to represent.

Available in OS X v10.0 and later.

Declared in `NSDecimal.h`.

`NSCalculationDivideByZero`

The caller tried to divide by `0`.

Available in OS X v10.0 and later.

Declared in `NSDecimal.h`.