Up
Authors
- Fred Kiefer (
FredKiefer@gmx.de
)
-
Version: 1.13
Date: 2005/05/22 03:32:13
Copyright: (C) 2000 Free Software Foundation, Inc.
- Declared in:
- Foundation/NSDecimalNumber.h
- Conforms to:
- NSDecimalNumberBehaviors
Availability: MacOS-X 10.0.0
Class that implements a number of methods for performing decimal arithmetic to arbitrary precision. The behavior in terms of rounding choices and exception handling may be customized using the NSDecimalNumberHandler
class, and defaults to [NSDecimalNumberHandler +defaultDecimalNumberHandler]
.
Equivalent functionality to the NSDecimalNumber
class may be accessed through functions, mostly named NSDecimalXXX
, e.g., NSDecimalMin()
. Both the class and the functions use a structure called NSDecimal
.
Note that instances of NSDecimalNumber
are immutable.
Instance Variables
Method summary
+ (
NSDecimalNumber*)
decimalNumberWithMantissa: (unsigned long long)mantissa
exponent: (short)exponent
isNegative: (BOOL)isNegative;
Availability: MacOS-X 10.0.0
New instance by component. Note that the precision of this initializer is limited.
+ (
NSDecimalNumber*)
decimalNumberWithString: (
NSString*)numericString;
Availability: MacOS-X 10.0.0
New instance from string. Arbitrary precision is preserved, though calling one of the decimalNumberBy...
methods will return a result constrained by the current scale
. Number format is parsed according to current default locale.
+ (
NSDecimalNumber*)
decimalNumberWithString: (
NSString*)numericString
locale: (
NSDictionary*)locale;
Availability: MacOS-X 10.0.0
New instance from string. Arbitrary precision is preserved, though calling one of the decimalNumberBy...
methods will return a result constrained by the current scale
. Number format is parsed according to given locale.
+ (
NSDecimalNumber*)
maximumDecimalNumber;
Availability: MacOS-X 10.0.0
Return maximum positive value that can be represented.
+ (
NSDecimalNumber*)
minimumDecimalNumber;
Availability: MacOS-X 10.0.0
Return minimum negative value (not the smallest positive value) that can be represented.
+ (
NSDecimalNumber*)
notANumber;
Availability: MacOS-X 10.0.0
Return a fixed value representing an NaN.
+ (
NSDecimalNumber*)
one;
Availability: MacOS-X 10.0.0
Return a constant object with a value of one.
+ (
NSDecimalNumber*)
zero;
Availability: MacOS-X 10.0.0
Return a constant object with a value of zero.
- (
NSComparisonResult)
compare: (
NSNumber*)decimalNumber;
Availability: MacOS-X 10.0.0
Compares with other number, returning less, greater, or equal.
- (
NSDecimalNumber*)
decimalNumberByDividingBy: (
NSDecimalNumber*)decimalNumber
withBehavior: (id<
NSDecimalNumberBehaviors>)behavior;
Availability: MacOS-X 10.0.0
Divides self by decimalNumber and returns new result, using given behavior for rounding/precision/error handling.
- (
NSDecimalNumber*)
decimalNumberByMultiplyingBy: (
NSDecimalNumber*)decimalNumber;
Availability: MacOS-X 10.0.0
Multiplies self by
decimalNumber and returns new result, using
+defaultBehavior
for rounding/precision/error handling.
- (
NSDecimalNumber*)
decimalNumberByMultiplyingBy: (
NSDecimalNumber*)decimalNumber
withBehavior: (id<
NSDecimalNumberBehaviors>)behavior;
Availability: MacOS-X 10.0.0
Multiplies self by decimalNumber and returns new result, using given behavior for rounding/precision/error handling.
- (
NSDecimalNumber*)
decimalNumberByMultiplyingByPowerOf10: (short)power;
Availability: MacOS-X 10.0.0
Multiplies self by given
power of 10 and returns new result, using
+defaultBehavior
for rounding/precision/error handling.
- (
NSDecimalNumber*)
decimalNumberByMultiplyingByPowerOf10: (short)power
withBehavior: (id<
NSDecimalNumberBehaviors>)behavior;
Availability: MacOS-X 10.0.0
Multiplies self by given power of 10 and returns new result, using given behavior for rounding/precision/error handling.
- (
NSDecimalNumber*)
decimalNumberByRaisingToPower: (unsigned)power;
Availability: MacOS-X 10.0.0
Raises self to given positive integer
power and returns new result, using
+defaultBehavior
for rounding/precision/error handling.
- (
NSDecimalNumber*)
decimalNumberByRaisingToPower: (unsigned)power
withBehavior: (id<
NSDecimalNumberBehaviors>)behavior;
Availability: MacOS-X 10.0.0
Raises self to given positive integer power and returns new result, using given behavior for rounding/precision/error handling.
- (
NSDecimalNumber*)
decimalNumberBySubtracting: (
NSDecimalNumber*)decimalNumber;
Availability: MacOS-X 10.0.0
Subtracts
decimalNumber from self and returns new result, using
+defaultBehavior
for rounding/precision/error handling.
- (
NSDecimalNumber*)
decimalNumberBySubtracting: (
NSDecimalNumber*)decimalNumber
withBehavior: (id<
NSDecimalNumberBehaviors>)behavior;
Availability: MacOS-X 10.0.0
Subtracts decimalNumber from self and returns new result, using given behavior for rounding/precision/error handling.
- (
NSDecimal)
decimalValue;
Availability: MacOS-X 10.0.0
Return underlying value as an NSDecimal
structure.
- (
NSString*)
descriptionWithLocale: (
NSDictionary*)locale;
Availability: MacOS-X 10.0.0
Returns string version of number formatted according to locale.
- (double)
doubleValue;
Availability: MacOS-X 10.0.0
Returns underlying value as a double
, which may be an approximation if precision greater than the default of 38.
- (id)
initWithDecimal: (
NSDecimal)decimal;
Availability: MacOS-X 10.0.0
- (id)
initWithMantissa: (unsigned long long)mantissa
exponent: (short)exponent
isNegative: (BOOL)flag;
Availability: MacOS-X 10.0.0
Initialize by component. Note that the precision of this initializer is limited.
- (id)
initWithString: (
NSString*)numberValue;
Availability: MacOS-X 10.0.0
Initialize from string. Arbitrary precision is preserved, though calling one of the decimalNumberBy...
methods will return a result constrained by the current scale
. Number format is parsed according to current default locale.
- (id)
initWithString: (
NSString*)numberValue
locale: (
NSDictionary*)locale;
Availability: MacOS-X 10.0.0
Initialize from string. Arbitrary precision is preserved, though calling one of the decimalNumberBy...
methods will return a result constrained by the current scale
. Number format is parsed according to given locale.
- (const char*)
objCType;
Availability: MacOS-X 10.0.0
Returns the Objective-C type ( @encode(...)
compatible) of the data contained NSDecimalNumber
, which is by convention "d" (for double), even though this is not strictly accurate.
Instance Variables for NSDecimalNumber Class
@protected NSDecimal data;
Description forthcoming.
- Declared in:
- Foundation/NSDecimalNumber.h
- Conforms to:
- NSDecimalNumberBehaviors
Availability: MacOS-X 10.0.0
Instance Variables
Method summary
+ (id)
decimalNumberHandlerWithRoundingMode: (
NSRoundingMode)roundingMode
scale: (short)scale
raiseOnExactness: (BOOL)raiseOnExactness
raiseOnOverflow: (BOOL)raiseOnOverflow
raiseOnUnderflow: (BOOL)raiseOnUnderflow
raiseOnDivideByZero: (BOOL)raiseOnDivideByZero;
Availability: MacOS-X 10.0.0
Constructor setting all behavior. (For more precise control over error handling, create your own class implementing the
<NSDecimalNumberBehaviors>
protocol.)
+ (id)
defaultDecimalNumberHandler;
Availability: MacOS-X 10.0.0
Provides an instance implementing the default behavior for the
NSDecimalNumber
class. 38 decimal digits, rounded to closest return value (
NSRoundPlain
). Exceptions raised on overflow, underflow, and divide by zero.
- (id)
initWithRoundingMode: (
NSRoundingMode)roundingMode
scale: (short)scale
raiseOnExactness: (BOOL)raiseOnExactness
raiseOnOverflow: (BOOL)raiseOnOverflow
raiseOnUnderflow: (BOOL)raiseOnUnderflow
raiseOnDivideByZero: (BOOL)raiseOnDivideByZero;
Availability: MacOS-X 10.0.0
Initializer setting all behavior. (For more precise control over error handling, create your own class implementing the
<NSDecimalNumberBehaviors>
protocol.)
Instance Variables for NSDecimalNumberHandler Class
@protected BOOL _raiseOnDivideByZero;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
@protected BOOL _raiseOnExactness;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
@protected BOOL _raiseOnOverflow;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
@protected BOOL _raiseOnUnderflow;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
@protected NSRoundingMode _roundingMode;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
@protected short int _scale;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
- Declared in:
- Foundation/NSDecimalNumber.h
Availability: MacOS-X 10.0.0
Interface for obtaining an NSDecimalNumber value from an ordinary NSNumber.
Method summary
- (
NSDecimal)
decimalValue;
Availability: MacOS-X 10.0.0
Obtaining an NSDecimalNumber version of an ordinary NSNumber.
Returns an NSDecimal representation of the number. Float and double values may not be converted exactly
- Declared in:
- Foundation/NSDecimalNumber.h
Availability: MacOS-X 10.0.0
This protocol encapsulates information about how an
NSDecimalNumber
should round and process exceptions. Usually you can just create objects of the
NSDecimalNumberHandler
class, which implements this protocol, but if you don't want to use that class you can create your own implementing it.
Method summary
- (
NSDecimalNumber*)
exceptionDuringOperation: (SEL)method
error: (
NSCalculationError)error
leftOperand: (
NSDecimalNumber*)leftOperand
rightOperand: (
NSDecimalNumber*)rightOperand;
Availability: MacOS-X 10.0.0
Specifies behavior when, in the course of applying method to leftOperand and rightOperand, an NSDecimalNumber
instance encounters given error.
error has four possible constant values:
NSCalculationLossOfPrecision
-
The number can't be represented in 38 significant digits.
NSCalculationOverflow
-
The number is too large to represent.
NSCalculationUnderflow
-
The number is too small to represent.
NSCalculationDivideByZero
-
The caller tried to divide by 0.
Behavior on error can be one of the following:
-
Raise an exception.
-
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, 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
. The calling method will use this as its own return value.
- (
NSRoundingMode)
roundingMode;
Availability: MacOS-X 10.0.0
Specifies how
NSDecimalNumber
's
decimalNumberBy...
methods round their return values. This should be set to one of the following constants:
NSRoundDown
-
Always round down.
NSRoundUp
-
Always round up.
NSRoundPlain
-
Round to the closest possible return value. Halfway (e.g..5) rounds up for positive numbers, down for negative (towards larger absolute value).
NSRoundBankers
-
Round to the closest possible return value, but halfway (e.g..5) rounds towards possibility whose last digit is even.
- (short)
scale;
Availability: MacOS-X 10.0.0
Specifies the precision of the values returned by
NSDecimalNumber
's
decimalNumberBy...
methods, in terms of the number of digits allowed after the decimal point. This can be negative, implying that the precision should be, e.g., 100's, 1000's, etc.. For unlimited precision, set to
NSDecimalNoScale
.
Up