iOS Developer Library

Developer

Foundation Framework Reference NSDecimalNumberBehaviors Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSDecimalNumberBehaviors

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 2.0 and later.

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.

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

    Declaration

    Swift

    func roundingMode() -> NSRoundingMode

    Objective-C

    - (NSRoundingMode)roundingMode

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • scale() - scale Required

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

    Declaration

    Swift

    func scale() -> Int16

    Objective-C

    - (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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func exceptionDuringOperation(_ method: Selector, error error: NSCalculationError, leftOperand leftOperand: NSDecimalNumber, rightOperand rightOperand: NSDecimalNumber) -> NSDecimalNumber?

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • These constants specify rounding behaviors.

    Declaration

    Swift

    enum NSRoundingMode : UInt { case RoundPlain case RoundDown case RoundUp case RoundBankers }

    Objective-C

    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 iOS 2.0 and later.

    • RoundDown

      NSRoundDown

      Round return values down.

      Available in iOS 2.0 and later.

    • RoundUp

      NSRoundUp

      Round return values up.

      Available in iOS 2.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 iOS 2.0 and later.

    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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.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 }

    Objective-C

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

    Constants

    • NoError

      NSCalculationNoError

      No error occurred.

      Available in iOS 2.0 and later.

    • LossOfPrecision

      NSCalculationLossOfPrecision

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

      Available in iOS 2.0 and later.

    • Overflow

      NSCalculationOverflow

      The number is too large to represent.

      Available in iOS 2.0 and later.

    • Underflow

      NSCalculationUnderflow

      The number is too small to represent.

      Available in iOS 2.0 and later.

    • DivideByZero

      NSCalculationDivideByZero

      The caller tried to divide by 0.

      Available in iOS 2.0 and later.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.