Up
Authors
- Fred Kiefer (
FredKiefer@gmx.de
)
-
Version: 37003
Date: 2013-08-22 09:44:54 -0600 (Thu, 22 Aug 2013)
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*)
decimalNumberWithDecimal: (NSDecimal)decimal;
Availability: MacOS-X 10.0.0
New instance with given value. Note an NSDecimal may be
created using the function
NSDecimalFromString()
.
+ (
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: (
NSUInteger)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: (
NSUInteger)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: (id)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;
Availability: MacOS-X 10.0.0
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;
Availability: MacOS-X 10.0.0
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;
Availability: MacOS-X 10.0.0
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;
Availability: MacOS-X 10.0.0
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;
Availability: MacOS-X 10.0.0
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;
Availability: MacOS-X 10.0.0
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;
Availability: MacOS-X 10.0.0
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