Class: NSDecimalNumber
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.
Class Method Summary (collapse)
-
+ decimalNumberWithDecimal:
Creates and returns an NSDecimalNumber object equivalent to a given NSDecimal structure.
-
+ decimalNumberWithMantissa:exponent:isNegative:
Creates and returns an NSDecimalNumber object equivalent to the number specified by the arguments.
-
+ decimalNumberWithString:
Creates and returns an NSDecimalNumber object whose value is equivalent to that in a given numeric string.
-
+ decimalNumberWithString:locale:
Creates and returns an NSDecimalNumber object whose value is equivalent to that in a given numeric string, interpreted using a given locale.
-
+ defaultBehavior
Returns the way arithmetic methods, like decimalNumberByAdding:, round off and handle error conditions.
-
+ maximumDecimalNumber
Returns the largest possible value of an NSDecimalNumber object.
-
+ minimumDecimalNumber
Returns the smallest possible value of an NSDecimalNumber object.
-
+ notANumber
Returns an NSDecimalNumber object that specifies no number.
-
+ one
Returns an NSDecimalNumber object equivalent to the number 1.0.
-
+ setDefaultBehavior:
Specifies the way that arithmetic methods, like decimalNumberByAdding:, round off and handle error conditions.
-
+ zero
Returns an NSDecimalNumber object equivalent to the number 0.0.
Instance Method Summary (collapse)
-
- compare:
Returns an NSComparisonResult value that indicates the numerical ordering of the receiver and another given NSDecimalNumber object.
-
- decimalNumberByAdding:
Returns a new NSDecimalNumber object whose value is the sum of the receiver and another given NSDecimalNumber object.
-
- decimalNumberByAdding:withBehavior:
Adds decimalNumber to the receiver and returns the sum, a newly created NSDecimalNumber object.
-
- decimalNumberByDividingBy:
Returns a new NSDecimalNumber object whose value is the value of the receiver divided by that of another given NSDecimalNumber object.
-
- decimalNumberByDividingBy:withBehavior:
Divides the receiver by decimalNumber and returns the quotient, a newly created NSDecimalNumber object.
-
- decimalNumberByMultiplyingBy:
Returns a new NSDecimalNumber object whose value is the value of the receiver multiplied by that of another given NSDecimalNumber object.
-
- decimalNumberByMultiplyingBy:withBehavior:
Multiplies the receiver by decimalNumber and returns the product, a newly created NSDecimalNumber object.
-
- decimalNumberByMultiplyingByPowerOf10:
Multiplies the receiver by 10^power and returns the product, a newly created NSDecimalNumber object.
-
- decimalNumberByMultiplyingByPowerOf10:withBehavior:
Multiplies the receiver by 10^power and returns the product, a newly created NSDecimalNumber object.
-
- decimalNumberByRaisingToPower:
Returns a new NSDecimalNumber object whose value is the value of the receiver raised to a given power.
-
- decimalNumberByRaisingToPower:withBehavior:
Raises the receiver to power and returns the result, a newly created NSDecimalNumber object.
-
- decimalNumberByRoundingAccordingToBehavior:
Rounds the receiver off in the way specified by behavior and returns the result, a newly created NSDecimalNumber object.
-
- decimalNumberBySubtracting:
Returns a new NSDecimalNumber object whose value is that of another given NSDecimalNumber object subtracted from the value of the receiver.
-
- decimalNumberBySubtracting:withBehavior:
Subtracts decimalNumber from the receiver and returns the difference, a newly created NSDecimalNumber object.
-
- decimalValue
Returns the receiver’s value, expressed as an NSDecimal structure.
-
- descriptionWithLocale:
Returns a string, specified according to a given locale, that represents the contents of the receiver.
-
- doubleValue
Returns the approximate value of the receiver as a double.
-
- initWithDecimal:
Returns an NSDecimalNumber object initialized to represent a given decimal.
-
- initWithMantissa:exponent:isNegative:
Returns an NSDecimalNumber object initialized using the given mantissa, exponent, and sign.
-
- initWithString:
Returns an NSDecimalNumber object initialized so that its value is equivalent to that in a given numeric string.
-
- initWithString:locale:
Returns an NSDecimalNumber object initialized so that its value is equivalent to that in a given numeric string, interpreted using a given locale.
-
- objCType
Returns a C string containing the Objective-C type of the data contained in the receiver, which for an NSDecimalNumber object is always “d” (for double).
Methods inherited from NSNumber
#boolValue, #charValue, #floatValue, #initWithBool:, #initWithChar:, #initWithDouble:, #initWithFloat:, #initWithInt:, #initWithInteger:, #initWithLong:, #initWithLongLong:, #initWithShort:, #initWithUnsignedChar:, #initWithUnsignedInt:, #initWithUnsignedInteger:, #initWithUnsignedLong:, #initWithUnsignedLongLong:, #initWithUnsignedShort:, #intValue, #integerValue, #isEqualToNumber:, #longLongValue, #longValue, numberWithBool:, numberWithChar:, numberWithDouble:, numberWithFloat:, numberWithInt:, numberWithInteger:, numberWithLong:, numberWithLongLong:, numberWithShort:, numberWithUnsignedChar:, numberWithUnsignedInt:, numberWithUnsignedInteger:, numberWithUnsignedLong:, numberWithUnsignedLongLong:, numberWithUnsignedShort:, #shortValue, #stringValue, #unsignedCharValue, #unsignedIntValue, #unsignedIntegerValue, #unsignedLongLongValue, #unsignedLongValue, #unsignedShortValue
Methods inherited from NSValue
#getValue:, #initWithBytes:objCType:, #isEqualToValue:, #nonretainedObjectValue, #pointerValue, #rangeValue, value:withObjCType:, valueWithBytes:objCType:, valueWithNonretainedObject:, valueWithPointer:, valueWithRange:
Methods inherited from NSObject
#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version
Constructor Details
This class inherits a constructor from NSObject
Dynamic Method Handling
This class handles dynamic methods through the method_missing method in the class NSObject
Class Method Details
+ (NSDecimalNumber) decimalNumberWithDecimal(decimal)
Creates and returns an NSDecimalNumber object equivalent to a given NSDecimal structure. You can initialize decimal programmatically or generate it using the NSScanner method, scanDecimal:
+ (NSDecimalNumber) decimalNumberWithMantissa(mantissa, exponent:exponent, isNegative:isNegative)
Creates and returns an NSDecimalNumber object equivalent to the number specified by the arguments. 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) decimalNumberWithString(numericString)
Creates and returns an NSDecimalNumber object whose value is equivalent to that in a given numeric string. 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.
+ (NSDecimalNumber) decimalNumberWithString(numericString, locale:locale)
Creates and returns an NSDecimalNumber object whose value is equivalent to that in a given numeric string, interpreted using a given locale. 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”
+ (Object) defaultBehavior
Returns the way arithmetic methods, like decimalNumberByAdding:, round off and handle error conditions. 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:.
+ (NSDecimalNumber) maximumDecimalNumber
Returns the largest possible value of an NSDecimalNumber object.
+ (NSDecimalNumber) minimumDecimalNumber
Returns the smallest possible value of an NSDecimalNumber object.
+ (NSDecimalNumber) notANumber
Returns an NSDecimalNumber object that specifies no number. 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.
+ (NSDecimalNumber) one
Returns an NSDecimalNumber object equivalent to the number 1.0.
+ (Object) setDefaultBehavior(behavior)
Specifies the way that arithmetic methods, like decimalNumberByAdding:, round off and handle error conditions.
behavior must conform to the NSDecimalNumberBehaviors protocol.+ (NSDecimalNumber) zero
Returns an NSDecimalNumber object equivalent to the number 0.0.
Instance Method Details
- (NSComparisonResult) compare(decimalNumber)
Returns an NSComparisonResult value that indicates the numerical ordering of the receiver and another given NSDecimalNumber object.
- (NSDecimalNumber) decimalNumberByAdding(decimalNumber)
Returns a new NSDecimalNumber object whose value is the sum of the receiver and another given NSDecimalNumber object. This method uses the default behavior when handling calculation errors and rounding.
- (NSDecimalNumber) decimalNumberByAdding(decimalNumber, withBehavior:behavior)
Adds decimalNumber to the receiver and returns the sum, a newly created NSDecimalNumber object.
behavior specifies the handling of calculation errors and rounding.- (NSDecimalNumber) decimalNumberByDividingBy(decimalNumber)
Returns a new NSDecimalNumber object whose value is the value of the receiver divided by that of another given NSDecimalNumber object. This method uses the default behavior when handling calculation errors and rounding.
- (NSDecimalNumber) decimalNumberByDividingBy(decimalNumber, withBehavior:behavior)
Divides the receiver by decimalNumber and returns the quotient, a newly created NSDecimalNumber object.
behavior specifies the handling of calculation errors and rounding.- (NSDecimalNumber) decimalNumberByMultiplyingBy(decimalNumber)
Returns a new NSDecimalNumber object whose value is the value of the receiver multiplied by that of another given NSDecimalNumber object. This method uses the default behavior when handling calculation errors and when rounding.
- (NSDecimalNumber) decimalNumberByMultiplyingBy(decimalNumber, withBehavior:behavior)
Multiplies the receiver by decimalNumber and returns the product, a newly created NSDecimalNumber object.
behavior specifies the handling of calculation errors and rounding.- (NSDecimalNumber) decimalNumberByMultiplyingByPowerOf10(power)
Multiplies the receiver by 10^power and returns the product, a newly created NSDecimalNumber object.
This method uses the default behavior when handling calculation errors and when rounding.- (NSDecimalNumber) decimalNumberByMultiplyingByPowerOf10(power, withBehavior:behavior)
Multiplies the receiver by 10^power and returns the product, a newly created NSDecimalNumber object.
behavior specifies the handling of calculation errors and rounding.- (NSDecimalNumber) decimalNumberByRaisingToPower(power)
Returns a new NSDecimalNumber object whose value is the value of the receiver raised to a given power. This method uses the default behavior when handling calculation errors and when rounding.
- (NSDecimalNumber) decimalNumberByRaisingToPower(power, withBehavior:behavior)
Raises the receiver to power and returns the result, a newly created NSDecimalNumber object.
behavior specifies the handling of calculation errors and rounding.- (NSDecimalNumber) decimalNumberByRoundingAccordingToBehavior(behavior)
Rounds the receiver off in the way specified by behavior and returns the result, a newly created NSDecimalNumber object. For a description of the different ways of rounding, see the roundingMode method in the NSDecimalNumberBehaviors protocol specification.
- (NSDecimalNumber) decimalNumberBySubtracting(decimalNumber)
Returns a new NSDecimalNumber object whose value is that of another given NSDecimalNumber object subtracted from the value of the receiver. This method uses the default behavior when handling calculation errors and when rounding.
- (NSDecimalNumber) decimalNumberBySubtracting(decimalNumber, withBehavior:behavior)
Subtracts decimalNumber from the receiver and returns the difference, a newly created NSDecimalNumber object.
behavior specifies the handling of calculation errors and rounding.- (String) descriptionWithLocale(locale)
Returns a string, specified according to a given locale, that represents the contents of the receiver.
- (Float) doubleValue
Returns the approximate value of the receiver as a double.
- (Object) initWithDecimal(decimal)
Returns an NSDecimalNumber object initialized to represent a given decimal. This method is the designated initializer for NSDecimalNumber.
- (Object) initWithMantissa(mantissa, exponent:exponent, isNegative:flag)
Returns an NSDecimalNumber object initialized using the given mantissa, exponent, and sign. 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.
- (Object) initWithString(numericString)
Returns an NSDecimalNumber object initialized so that its value is equivalent to that in a given numeric string.
- (Object) initWithString(numericString, locale:locale)
Returns an NSDecimalNumber object initialized so that its value is equivalent to that in a given numeric string, interpreted using a given locale.
- (const char) objCType
Returns a C string containing the Objective-C type of the data contained in the receiver, which for an NSDecimalNumber object is always “d” (for double).