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

roundingMode()  roundingMode
RequiredReturns the way that
NSDecimalNumber
'sdecimalNumberBy...
methods round their return values.Return Value
Returns the current rounding mode. See NSRoundingMode for possible values.
Availability
Available in OS X v10.0 and later.

Returns the number of digits allowed after the decimal separator.
Return Value
The number of digits allowed after the decimal separator.
Discussion
This method limits the precision of the values returned by
NSDecimalNumber
’sdecimalNumberBy...
methods. Ifscale
returns a negative value, it affects the digits before the decimal separator as well. Ifscale
returnsNSDecimalNoScale
, the number of digits is unlimited.Assuming that
roundingMode
returnsNSRoundPlain
, different values ofscale
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.

exceptionDuringOperation(_:error:leftOperand:rightOperand:)  exceptionDuringOperation:error:leftOperand:rightOperand:
RequiredSpecifies what an
NSDecimalNumber
object will do when it encounters an error.Declaration
Swift
func exceptionDuringOperation(_
operation
: Selector, errorerror
: NSCalculationError, leftOperandleftOperand
: NSDecimalNumber, rightOperandrightOperand
: NSDecimalNumber?) > NSDecimalNumber?ObjectiveC
 (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 ofNSDecimalNumber
to represent decimal numbers. AnNSDecimalNumber
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 by0
.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. Iferror
isNSCalculationLossOfPrecision
,method
will return an imprecise value—that is, one constrained to 38 significant digits. Iferror
isNSCalculationUnderflow
orNSCalculationOverflow
,method
will returnNSDecimalNumber
'snotANumber
. You shouldn’t returnnil
iferror
isNSDivideByZero
.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.

These constants specify rounding behaviors.
Declaration
Swift
enum NSRoundingMode : UInt { case RoundPlain case RoundDown case RoundUp case RoundBankers }
ObjectiveC
enum { NSRoundPlain, NSRoundDown, NSRoundUp, NSRoundBankers }; typedef NSUInteger NSRoundingMode;
Constants

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

RoundDown
NSRoundDown
Round return values down.
Available in OS X v10.0 and later.

RoundUp
NSRoundUp
Round return values up.
Available in OS X v10.0 and later.

RoundBankers
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.
Discussion
The rounding mode matters only if the
scale
method sets a limit on the precision ofNSDecimalNumber
return values. It has no effect ifscale
returnsNSDecimalNoScale
. Assuming thatscale
returns 1, the rounding mode has the following effects on various original values:Original Value
NSRoundPlain
NSRoundDown & NS RoundUp
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
Import Statement
ObjectiveC
@import Foundation;
Swift
import Foundation
Availability
Available in OS X v10.0 and later.


Calculation error constants used to describe an error in
exceptionDuringOperation:error:leftOperand:rightOperand:
.Declaration
Swift
enum NSCalculationError : UInt { case NoError case LossOfPrecision case Underflow case Overflow case DivideByZero }
ObjectiveC
enum { NSCalculationNoError = 0, NSCalculationLossOfPrecision, NSCalculationUnderflow, NSCalculationOverflow, NSCalculationDivideByZero }; typedef NSUInteger NSCalculationError;
Constants

NoError
NSCalculationNoError
No error occurred.
Available in OS X v10.0 and later.

LossOfPrecision
NSCalculationLossOfPrecision
The number can’t be represented in 38 significant digits.
Available in OS X v10.0 and later.

Overflow
NSCalculationOverflow
The number is too large to represent.
Available in OS X v10.0 and later.

Underflow
NSCalculationUnderflow
The number is too small to represent.
Available in OS X v10.0 and later.

DivideByZero
NSCalculationDivideByZero
The caller tried to divide by
0
.Available in OS X v10.0 and later.
Import Statement
ObjectiveC
@import Foundation;
Swift
import Foundation
Availability
Available in OS X v10.0 and later.

Copyright © 2016 Apple Inc. All rights reserved. Terms of Use  Privacy Policy  Updated: 20091117