NSDecimalNumber Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in OS X v10.0 and later. |
| Companion guide | |
| Declared in | NSDecimalNumber.h |
Overview
NSDecimalNumber, an immutable subclass of NSNumber, provides an object-oriented wrapper for doing base-10 arithmetic. An instance 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 an integer from –128 through 127.
Tasks
Creating a Decimal Number
-
+ decimalNumberWithDecimal: -
+ decimalNumberWithMantissa:exponent:isNegative: -
+ decimalNumberWithString: -
+ decimalNumberWithString:locale: -
+ one -
+ zero -
+ notANumber
Initializing a Decimal Number
-
– initWithDecimal: -
– initWithMantissa:exponent:isNegative: -
– initWithString: -
– initWithString:locale:
Performing Arithmetic
-
– decimalNumberByAdding: -
– decimalNumberBySubtracting: -
– decimalNumberByMultiplyingBy: -
– decimalNumberByDividingBy: -
– decimalNumberByRaisingToPower: -
– decimalNumberByMultiplyingByPowerOf10: -
– decimalNumberByAdding:withBehavior: -
– decimalNumberBySubtracting:withBehavior: -
– decimalNumberByMultiplyingBy:withBehavior: -
– decimalNumberByDividingBy:withBehavior: -
– decimalNumberByRaisingToPower:withBehavior: -
– decimalNumberByMultiplyingByPowerOf10:withBehavior:
Rounding Off
Accessing the Value
Managing Behavior
Comparing Decimal Numbers
Getting Maximum and Minimum Possible Values
Class Methods
decimalNumberWithDecimal:
Creates and returns an NSDecimalNumber object equivalent to a given NSDecimal structure.
Parameters
- decimal
An
NSDecimalstructure that specifies the value for the new decimal number object.
Return Value
An NSDecimalNumber object equivalent to decimal.
Discussion
You can initialize decimal programmatically or generate it using the NSScanner method, scanDecimal:
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hdecimalNumberWithMantissa:exponent:isNegative:
Creates and returns an NSDecimalNumber object equivalent to the number specified by the arguments.
Parameters
- mantissa
The mantissa for the new decimal number object.
- exponent
The exponent for the new decimal number object.
- isNegative
A Boolean value that specifies whether the sign of the number is negative.
Discussion
The arguments express a number in a kind of scientific notation that requires the mantissa to be an integer. So, for example, if the number to be represented is –12.345, it is expressed as 12345x10^–3—mantissa is 12345; exponent is –3; and isNegative is YES, as illustrated by the following example.
NSDecimalNumber *number = [NSDecimalNumber decimalNumberWithMantissa:12345 |
exponent:-3 |
isNegative:YES]; |
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hdecimalNumberWithString:
Creates and returns an NSDecimalNumber object whose value is equivalent to that in a given numeric string.
Parameters
- numericString
A numeric string.
Besides digits, numericString can include an initial “+” or “–”; a single “E” or “e”, to indicate the exponent of a number in scientific notation; and a single
NSDecimalSeparatorto divide the fractional from the integral part of the number.
Return Value
An NSDecimalNumber object whose value is equivalent to numericString.
Discussion
Whether the NSDecimalSeparator is a period (as is used, for example, in the United States) or a comma (as is used, for example, in France) depends on the default locale.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSDecimalNumber.hdecimalNumberWithString:locale:
Creates and returns an NSDecimalNumber object whose value is equivalent to that in a given numeric string, interpreted using a given locale.
Parameters
- numericString
A numeric string.
Besides digits, numericString can include an initial “+” or “–”; a single “E” or “e”, to indicate the exponent of a number in scientific notation; and a single
NSDecimalSeparatorto divide the fractional from the integral part of the number.- locale
A dictionary that defines the locale (specifically the
NSDecimalSeparator) to use to interpret the number in numericString.
Return Value
An NSDecimalNumber object whose value is equivalent to numericString.
Discussion
The locale parameter determines whether the NSDecimalSeparator is a period (as is used, for example, in the United States) or a comma (as is used, for example, in France).
The following strings show examples of acceptable values for numericString:
“2500.6” (or “2500,6”, depending on locale)
“–2500.6” (or “–2500.6”)
“–2.5006e3” (or “–2,5006e3”)
“–2.5006E3” (or “–2,5006E3”)
The following strings are unacceptable:
“2,500.6”
“2500 3/5”
“2.5006x10e3”
“two thousand five hundred and six tenths”
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSDecimalNumber.hdefaultBehavior
Returns the way arithmetic methods, like decimalNumberByAdding:, round off and handle error conditions.
Discussion
By default, the arithmetic methods use the NSRoundPlain behavior; that is, the methods round to the closest possible return value. The methods assume your need for precision does not exceed 38 significant digits and raise exceptions when they try to divide by 0 or produce a number too big or too small to be represented.
If this default behavior doesn’t suit your application, you should use methods that let you specify the behavior, like decimalNumberByAdding:withBehavior:. If you find yourself using a particular behavior consistently, you can specify a different default behavior with setDefaultBehavior:.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hmaximumDecimalNumber
Returns the largest possible value of an NSDecimalNumber object.
Return Value
The largest possible value of an NSDecimalNumber object.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSDecimalNumber.hminimumDecimalNumber
Returns the smallest possible value of an NSDecimalNumber object.
Return Value
The smallest possible value of an NSDecimalNumber object.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSDecimalNumber.hnotANumber
Returns an NSDecimalNumber object that specifies no number.
Return Value
An NSDecimalNumber object that specifies no number.
Discussion
Any arithmetic method receiving notANumber as an argument returns notANumber.
This value can be a useful way of handling non-numeric data in an input file. This method can also be a useful response to calculation errors. For more information on calculation errors, see the exceptionDuringOperation:error:leftOperand:rightOperand: method description in the NSDecimalNumberBehaviors protocol specification.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hone
Returns an NSDecimalNumber object equivalent to the number 1.0.
Return Value
An NSDecimalNumber object equivalent to the number 1.0.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSDecimalNumber.hsetDefaultBehavior:
Specifies the way that arithmetic methods, like decimalNumberByAdding:, round off and handle error conditions.
Discussion
behavior must conform to the NSDecimalNumberBehaviors protocol.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hzero
Returns an NSDecimalNumber object equivalent to the number 0.0.
Return Value
An NSDecimalNumber object equivalent to the number 0.0.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSDecimalNumber.hInstance Methods
compare:
Returns an NSComparisonResult value that indicates the numerical ordering of the receiver and another given NSDecimalNumber object.
Parameters
- decimalNumber
The number with which to compare the receiver.
This value must not be
nil. If this value isnil, the behavior is undefined and may change in future versions of OS X.
Return Value
NSOrderedAscending if the value of decimalNumber is greater than the receiver; NSOrderedSame if they’re equal; and NSOrderedDescending if the value of decimalNumber is less than the receiver.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hdecimalNumberByAdding:
Returns a new NSDecimalNumber object whose value is the sum of the receiver and another given NSDecimalNumber object.
Parameters
- decimalNumber
The number to add to the receiver.
Return Value
A new NSDecimalNumber object whose value is the sum of the receiver and decimalNumber.
Discussion
This method uses the default behavior when handling calculation errors and rounding.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hdecimalNumberByAdding:withBehavior:
Adds decimalNumber to the receiver and returns the sum, a newly created NSDecimalNumber object.
Discussion
behavior specifies the handling of calculation errors and rounding.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hdecimalNumberByDividingBy:
Returns a new NSDecimalNumber object whose value is the value of the receiver divided by that of another given NSDecimalNumber object.
Parameters
- decimalNumber
The number by which to divide the receiver.
Return Value
A new NSDecimalNumber object whose value is the value of the receiver divided by decimalNumber.
Discussion
This method uses the default behavior when handling calculation errors and rounding.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hdecimalNumberByDividingBy:withBehavior:
Divides the receiver by decimalNumber and returns the quotient, a newly created NSDecimalNumber object.
Discussion
behavior specifies the handling of calculation errors and rounding.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hdecimalNumberByMultiplyingBy:
Returns a new NSDecimalNumber object whose value is the value of the receiver multiplied by that of another given NSDecimalNumber object.
Parameters
- decimalNumber
The number by which to multiply the receiver.
Return Value
A new NSDecimalNumber object whose value is decimalNumber multiplied by the receiver.
Discussion
This method uses the default behavior when handling calculation errors and when rounding.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hdecimalNumberByMultiplyingBy:withBehavior:
Multiplies the receiver by decimalNumber and returns the product, a newly created NSDecimalNumber object.
Discussion
behavior specifies the handling of calculation errors and rounding.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hdecimalNumberByMultiplyingByPowerOf10:
Multiplies the receiver by 10^power and returns the product, a newly created NSDecimalNumber object.
Discussion
This method uses the default behavior when handling calculation errors and when rounding.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hdecimalNumberByMultiplyingByPowerOf10:withBehavior:
Multiplies the receiver by 10^power and returns the product, a newly created NSDecimalNumber object.
Discussion
behavior specifies the handling of calculation errors and rounding.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hdecimalNumberByRaisingToPower:
Returns a new NSDecimalNumber object whose value is the value of the receiver raised to a given power.
Parameters
- power
The power to which to raise the receiver.
Return Value
A new NSDecimalNumber object whose value is the value of the receiver raised to the power power.
Discussion
This method uses the default behavior when handling calculation errors and when rounding.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hdecimalNumberByRaisingToPower:withBehavior:
Raises the receiver to power and returns the result, a newly created NSDecimalNumber object.
Discussion
behavior specifies the handling of calculation errors and rounding.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hdecimalNumberByRoundingAccordingToBehavior:
Rounds the receiver off in the way specified by behavior and returns the result, a newly created NSDecimalNumber object.
Discussion
For a description of the different ways of rounding, see the roundingMode method in the NSDecimalNumberBehaviors protocol specification.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hdecimalNumberBySubtracting:
Returns a new NSDecimalNumber object whose value is that of another given NSDecimalNumber object subtracted from the value of the receiver.
Parameters
- decimalNumber
The number to subtract from the receiver.
Return Value
A new NSDecimalNumber object whose value is decimalNumber subtracted from the receiver.
Discussion
This method uses the default behavior when handling calculation errors and when rounding.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hdecimalNumberBySubtracting:withBehavior:
Subtracts decimalNumber from the receiver and returns the difference, a newly created NSDecimalNumber object.
Discussion
behavior specifies the handling of calculation errors and rounding.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hdecimalValue
Returns the receiver’s value, expressed as an NSDecimal structure.
Return Value
The receiver’s value, expressed as an NSDecimal structure.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hdescriptionWithLocale:
Returns a string, specified according to a given locale, that represents the contents of the receiver.
Parameters
- locale
A dictionary that defines the locale (specifically the
NSDecimalSeparator) to use to generate the returned string.
Return Value
A string that represents the contents of the receiver, according to locale.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hdoubleValue
Returns the approximate value of the receiver as a double.
Return Value
The approximate value of the receiver as a double.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hinitWithDecimal:
Returns an NSDecimalNumber object initialized to represent a given decimal.
Parameters
- decimal
The value of the new object.
Return Value
An NSDecimalNumber object initialized to represent decimal.
Discussion
This method is the designated initializer for NSDecimalNumber.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hinitWithMantissa:exponent:isNegative:
Returns an NSDecimalNumber object initialized using the given mantissa, exponent, and sign.
Parameters
- mantissa
The mantissa for the new decimal number object.
- exponent
The exponent for the new decimal number object.
- flag
A Boolean value that specifies whether the sign of the number is negative.
Return Value
An NSDecimalNumber object initialized using the given mantissa, exponent, and sign.
Discussion
The arguments express a number in a type of scientific notation that requires the mantissa to be an integer. So, for example, if the number to be represented is 1.23, it is expressed as 123x10^–2—mantissa is 123; exponent is –2; and isNegative, which refers to the sign of the mantissa, is NO.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hinitWithString:
Returns an NSDecimalNumber object initialized so that its value is equivalent to that in a given numeric string.
Parameters
- numericString
A numeric string.
Besides digits, numericString can include an initial “+” or “–”; a single “E” or “e”, to indicate the exponent of a number in scientific notation; and a single
NSDecimalSeparatorto divide the fractional from the integral part of the number. For a listing of acceptable and unacceptable strings, see the class methoddecimalNumberWithString:locale:.
Return Value
An NSDecimalNumber object initialized so that its value is equivalent to that in numericString.
Availability
- Available in OS X v10.0 and later.
Declared In
NSDecimalNumber.hinitWithString:locale:
Returns an NSDecimalNumber object initialized so that its value is equivalent to that in a given numeric string, interpreted using a given locale.
Parameters
- numericString
A numeric string.
Besides digits, numericString can include an initial “+” or “–”; a single “E” or “e”, to indicate the exponent of a number in scientific notation; and a single
NSDecimalSeparatorto divide the fractional from the integral part of the number.- locale
A dictionary that defines the locale (specifically the
NSDecimalSeparator) to use to interpret the number in numericString.
Return Value
An NSDecimalNumber object initialized so that its value is equivalent to that in numericString, interpreted using locale.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSDecimalNumber.hConstants
NSDecimalNumber Exception Names
Names of the various exceptions raised by NSDecimalNumber to indicate computational errors.
extern NSString *NSDecimalNumberExactnessException; extern NSString *NSDecimalNumberOverflowException; extern NSString *NSDecimalNumberUnderflowException; extern NSString *NSDecimalNumberDivideByZeroException;
Constants
NSDecimalNumberExactnessExceptionThe name of the exception raised if there is an exactness error.
Available in OS X v10.0 and later.
Declared in
NSDecimalNumber.h.NSDecimalNumberOverflowExceptionThe name of the exception raised on overflow.
Available in OS X v10.0 and later.
Declared in
NSDecimalNumber.h.NSDecimalNumberUnderflowExceptionThe name of the exception raised on underflow.
Available in OS X v10.0 and later.
Declared in
NSDecimalNumber.h.NSDecimalNumberDivideByZeroExceptionThe name of the exception raised on divide by zero.
Available in OS X v10.0 and later.
Declared in
NSDecimalNumber.h.
Declared In
NSDecimalNumber.h© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-10-31)