---

NSDecimalNumberHandler Class Reference

Overview

NSDecimalNumberHandler is a class that adopts the NSDecimalNumberBehaviors protocol. This class allows you to set the way an NSDecimalNumber object rounds off and handles errors, without having to create a custom class.

You can use an instance of this class as an argument to any of the NSDecimalNumber methods that end with ...Behavior:. If you don’t think you need special behavior, you probably don’t need this class—it is likely that NSDecimalNumber's default behavior will suit your needs.

For more information, see the NSDecimalNumberBehaviors protocol specification.

Adopted Protocols

• – roundingMode

• – scale

• – exceptionDuringOperation:error:leftOperand:rightOperand:

• – encodeWithCoder:

• – initWithCoder:

Tasks

Creating a Decimal Number Handler

• + defaultDecimalNumberHandler
• + decimalNumberHandlerWithRoundingMode:scale:raiseOnExactness:raiseOnOverflow:raiseOnUnderflow:raiseOnDivideByZero:

Initializing a Decimal Number Handler

• – initWithRoundingMode:scale:raiseOnExactness:raiseOnOverflow:raiseOnUnderflow:raiseOnDivideByZero:

Class Methods

decimalNumberHandlerWithRoundingMode:scale:raiseOnExactness:raiseOnOverflow:raiseOnUnderflow:raiseOnDivideByZero:

Returns an NSDecimalNumberHandler object with customized behavior.

+ (id)decimalNumberHandlerWithRoundingMode:(NSRoundingMode)roundingMode scale:(short)scale raiseOnExactness:(BOOL)raiseOnExactness raiseOnOverflow:(BOOL)raiseOnOverflow raiseOnUnderflow:(BOOL)raiseOnUnderflow raiseOnDivideByZero:(BOOL)raiseOnDivideByZero

Parameters

roundingMode

The rounding mode to use. There are four possible values: NSRoundUp, NSRoundDown, NSRoundPlain, and NSRoundBankers.

scale

The number of digits a rounded value should have after its decimal point.

raiseOnExactness

If YES, in the event of an exactness error the handler will raise an exception, otherwise it will ignore the error and return control to the calling method.

raiseOnOverflow

If YES, in the event of an overflow error the handler will raise an exception, otherwise it will ignore the error and return control to the calling method

raiseOnUnderflow

If YES, in the event of an underflow error the handler will raise an exception, otherwise it will ignore the error and return control to the calling method

raiseOnDivideByZero

If YES, in the event of a divide by zero error the handler will raise an exception, otherwise it will ignore the error and return control to the calling method

Return Value

An NSDecimalNumberHandler object with customized behavior.

Discussion

See the NSDecimalNumberBehaviors protocol specification for a complete explanation of the possible behaviors.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDecimalNumber.h

defaultDecimalNumberHandler

Returns the default instance of NSDecimalNumberHandler.

+ (id)defaultDecimalNumberHandler

Return Value

The default instance of NSDecimalNumberHandler.

Discussion

This default decimal number handler rounds to the closest possible return value. It assumes your need for precision does not exceed 38 significant digits, and it raises an exception when its NSDecimalNumber object tries to divide by 0 or when its NSDecimalNumber object produces a number too big or too small to be represented.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDecimalNumber.h

Instance Methods

initWithRoundingMode:scale:raiseOnExactness:raiseOnOverflow:raiseOnUnderflow:raiseOnDivideByZero:

Returns an NSDecimalNumberHandler object initialized so it behaves as specified by the method’s arguments.

- (id)initWithRoundingMode:(NSRoundingMode)roundingMode scale:(short)scale raiseOnExactness:(BOOL)raiseOnExactness raiseOnOverflow:(BOOL)raiseOnOverflow raiseOnUnderflow:(BOOL)raiseOnUnderflow raiseOnDivideByZero:(BOOL)raiseOnDivideByZero

Parameters

roundingMode

The rounding mode to use. There are four possible values: NSRoundUp, NSRoundDown, NSRoundPlain, and NSRoundBankers.

scale

The number of digits a rounded value should have after its decimal point.

raiseOnExactness

If YES, in the event of an exactness error the handler will raise an exception, otherwise it will ignore the error and return control to the calling method.

raiseOnOverflow

If YES, in the event of an overflow error the handler will raise an exception, otherwise it will ignore the error and return control to the calling method

raiseOnUnderflow

If YES, in the event of an underflow error the handler will raise an exception, otherwise it will ignore the error and return control to the calling method

raiseOnDivideByZero

If YES, in the event of a divide by zero error the handler will raise an exception, otherwise it will ignore the error and return control to the calling method

Return Value

An initialized NSDecimalNumberHandler object initialized with customized behavior. The returned object might be different than the original receiver.

Discussion

See the NSDecimalNumberBehaviors protocol specification for a complete explanation of the possible behaviors.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDecimalNumber.h

---