NSDecimalNumberBehaviors Protocol Reference
| Adopted by | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in iOS 2.0 and later. |
| Companion guide | |
| Declared in | NSDecimal.h NSDecimalNumber.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.
Tasks
Rounding
-
– roundingModerequired method -
– scalerequired method
Handling Errors
-
– exceptionDuringOperation:error:leftOperand:rightOperand:required method
Instance Methods
exceptionDuringOperation:error:leftOperand:rightOperand:
Specifies what an NSDecimalNumber object will do when it encounters an error. (required)
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 isNSCalculationLossOfPrecision, method will return an imprecise value—that is, one constrained to 38 significant digits. If error isNSCalculationUnderfloworNSCalculationOverflow, method will returnNSDecimalNumber'snotANumber. You shouldn’t returnnilif error isNSDivideByZero.Correct the error and return a valid
NSDecimalNumberobject. The calling method will use this as its own return value.
Availability
- Available in iOS 2.0 and later.
Declared In
NSDecimalNumber.hroundingMode
Returns the way that NSDecimalNumber's decimalNumberBy... methods round their return values. (required)
Return Value
Returns the current rounding mode. See “NSRoundingMode” for possible values.
Availability
- Available in iOS 2.0 and later.
Declared In
NSDecimalNumber.hscale
Returns the number of digits allowed after the decimal separator. (required)
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 |
|---|---|
123.456 | |
2 | 123.45 |
0 | 123 |
–2 | 100 |
Availability
- Available in iOS 2.0 and later.
Declared In
NSDecimalNumber.hConstants
NSRoundingMode
These constants specify rounding behaviors.
enum {
NSRoundPlain,
NSRoundDown,
NSRoundUp,
NSRoundBankers
};
typedef NSUInteger NSRoundingMode;
Constants
NSRoundPlainRound 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 iOS 2.0 and later.
Declared in
NSDecimal.h.NSRoundDownRound return values down.
Available in iOS 2.0 and later.
Declared in
NSDecimal.h.NSRoundUpRound return values up.
Available in iOS 2.0 and later.
Declared in
NSDecimal.h.NSRoundBankersRound 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 iOS 2.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
NSCalculationNoErrorNo error occurred.
Available in iOS 2.0 and later.
Declared in
NSDecimal.h.NSCalculationLossOfPrecisionThe number can’t be represented in 38 significant digits.
Available in iOS 2.0 and later.
Declared in
NSDecimal.h.NSCalculationOverflowThe number is too large to represent.
Available in iOS 2.0 and later.
Declared in
NSDecimal.h.NSCalculationUnderflowThe number is too small to represent.
Available in iOS 2.0 and later.
Declared in
NSDecimal.h.NSCalculationDivideByZeroThe caller tried to divide by
0.Available in iOS 2.0 and later.
Declared in
NSDecimal.h.
© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-11-12)