/* Interface of NSDecimalNumber class Copyright (C) 1998 Free Software Foundation, Inc. Written by: Richard Frith-Macdonald Created: November 1998 This file is part of the GNUstep Base Library. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111 USA. */ #ifndef __NSDecimalNumber_h_GNUSTEP_BASE_INCLUDE #define __NSDecimalNumber_h_GNUSTEP_BASE_INCLUDE #import #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) #import #import #import #if defined(__cplusplus) extern "C" { #endif @class NSDecimalNumber; /** * 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. */ @protocol NSDecimalNumberBehaviors /** *

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. * */ - (NSDecimalNumber*) exceptionDuringOperation: (SEL)method error: (NSCalculationError)error leftOperand: (NSDecimalNumber*)leftOperand rightOperand: (NSDecimalNumber*)rightOperand; /** * 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. * */ - (NSRoundingMode) roundingMode; /** * 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. */ - (short) scale; @end /** * A utility class adopting [(NSDecimalNumberBehaviors)] protocol. Can be used * to control [NSDecimalNumber] rounding and exception-handling behavior, by * passing an instance as an argument to any [NSDecimalNumber] method ending * with ...Behavior:. */ @interface NSDecimalNumberHandler : NSObject { #if GS_EXPOSE(NSDecimalNumberHandler) NSRoundingMode _roundingMode; short _scale; BOOL _raiseOnExactness; BOOL _raiseOnOverflow; BOOL _raiseOnUnderflow; BOOL _raiseOnDivideByZero; void *_unused; #endif } /** * 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)defaultDecimalNumberHandler; /** * Constructor setting all behavior. (For more precise control over error * handling, create your own class implementing the [(NSDecimalNumberBehaviors)] * protocol.) */ + (id)decimalNumberHandlerWithRoundingMode:(NSRoundingMode)roundingMode scale:(short)scale raiseOnExactness:(BOOL)raiseOnExactness raiseOnOverflow:(BOOL)raiseOnOverflow raiseOnUnderflow:(BOOL)raiseOnUnderflow raiseOnDivideByZero:(BOOL)raiseOnDivideByZero; /** * Initializer setting all behavior. (For more precise control over error * handling, create your own class implementing the [(NSDecimalNumberBehaviors)] * protocol.) */ - (id)initWithRoundingMode:(NSRoundingMode)roundingMode scale:(short)scale raiseOnExactness:(BOOL)raiseOnExactness raiseOnOverflow:(BOOL)raiseOnOverflow raiseOnUnderflow:(BOOL)raiseOnUnderflow raiseOnDivideByZero:(BOOL)raiseOnDivideByZero; @end /** *

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.

*/ @interface NSDecimalNumber : NSNumber { #if GS_EXPOSE(NSDecimalNumber) NSDecimal data; #endif } /** * Returns the default rounding/precision/exception handling behavior, which * is same as [NSDecimalNumberHandler+defaultDecimalNumberHandler] unless it * has been explicitly set otherwise. */ + (id )defaultBehavior; /** * Sets the default rounding/precision/exception handling behavior to the * given behavior. If this is not called, behavior defaults to * [NSDecimalNumberHandler+defaultDecimalNumberHandler]. */ + (void)setDefaultBehavior:(id )behavior; /** * Return maximum positive value that can be represented. */ + (NSDecimalNumber *)maximumDecimalNumber; /** * Return minimum negative value (not the smallest positive value) * that can be represented. */ + (NSDecimalNumber *)minimumDecimalNumber; /** * Return a fixed value representing an NaN. */ + (NSDecimalNumber *)notANumber; /** * Return a constant object with a value of one. */ + (NSDecimalNumber *)one; /** * Return a constant object with a value of zero. */ + (NSDecimalNumber *)zero; /** * New instance with given value. Note an NSDecimal may be created using the * function NSDecimalFromString(). */ + (NSDecimalNumber *)decimalNumberWithDecimal:(NSDecimal)decimal; /** * New instance by component. Note that the precision of this initializer is * limited. */ + (NSDecimalNumber *)decimalNumberWithMantissa:(unsigned long long)mantissa exponent:(short)exponent isNegative:(BOOL)isNegative; /** * 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; /** * 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 *)decimalNumberWithString:(NSString *)numericString locale:(NSDictionary *)locale; /** * Initialize with given value. Note an NSDecimal may be created using the * function NSDecimalFromString(). */ - (id)initWithDecimal:(NSDecimal)decimal; /** * Initialize by component. Note that the precision of this initializer is * limited. */ - (id)initWithMantissa:(unsigned long long)mantissa exponent:(short)exponent isNegative:(BOOL)flag; /** * 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; /** * 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. */ - (id)initWithString:(NSString *)numberValue locale:(NSDictionary *)locale; /** * 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. */ - (const char *)objCType; /** * Return underlying value as an NSDecimal structure. */ - (NSDecimal)decimalValue; /** * Returns string version of number formatted according to locale. */ - (NSString *)descriptionWithLocale:(NSDictionary *)locale; /** * Returns underlying value as a double, which may be an * approximation if precision greater than the default of 38. */ - (double)doubleValue; /** * Compares with other number, returning less, greater, or equal. */ - (NSComparisonResult)compare:(NSNumber *)decimalNumber; /** * Adds self to decimalNumber and returns new result, using +defaultBehavior * for rounding/precision/error handling. */ - (NSDecimalNumber *)decimalNumberByAdding:(NSDecimalNumber *)decimalNumber; /** * Adds self to decimalNumber and returns new result, using given behavior * for rounding/precision/error handling. */ - (NSDecimalNumber *)decimalNumberByAdding:(NSDecimalNumber *)decimalNumber withBehavior:(id)behavior; /** * Divides self by decimalNumber and returns new result, using +defaultBehavior * for rounding/precision/error handling. */ - (NSDecimalNumber *)decimalNumberByDividingBy:(NSDecimalNumber *)decimalNumber; /** * Divides self by decimalNumber and returns new result, using given behavior * for rounding/precision/error handling. */ - (NSDecimalNumber *)decimalNumberByDividingBy:(NSDecimalNumber *)decimalNumber withBehavior:(id )behavior; /** * Multiplies self by decimalNumber and returns new result, using * +defaultBehavior for rounding/precision/error handling. */ - (NSDecimalNumber *)decimalNumberByMultiplyingBy:(NSDecimalNumber *)decimalNumber; /** * Multiplies self by decimalNumber and returns new result, using given * behavior for rounding/precision/error handling. */ - (NSDecimalNumber *)decimalNumberByMultiplyingBy:(NSDecimalNumber *)decimalNumber withBehavior:(id )behavior; /** * Multiplies self by given power of 10 and returns new result, using * +defaultBehavior for rounding/precision/error handling. */ - (NSDecimalNumber *)decimalNumberByMultiplyingByPowerOf10:(short)power; /** * Multiplies self by given power of 10 and returns new result, using given * behavior for rounding/precision/error handling. */ - (NSDecimalNumber *)decimalNumberByMultiplyingByPowerOf10:(short)power withBehavior:(id )behavior; /** * Raises self to given positive integer power and returns new result, using * +defaultBehavior for rounding/precision/error handling. */ - (NSDecimalNumber *)decimalNumberByRaisingToPower:(NSUInteger)power; /** * Raises self to given positive integer power and returns new result, using * given behavior for rounding/precision/error handling. */ - (NSDecimalNumber *)decimalNumberByRaisingToPower:(NSUInteger)power withBehavior:(id )behavior; /** * Subtracts decimalNumber from self and returns new result, using * +defaultBehavior for rounding/precision/error handling. */ - (NSDecimalNumber *)decimalNumberBySubtracting: (NSDecimalNumber *)decimalNumber; /** * Subtracts decimalNumber from self and returns new result, using given * behavior for rounding/precision/error handling. */ - (NSDecimalNumber *)decimalNumberBySubtracting: (NSDecimalNumber *)decimalNumber withBehavior:(id )behavior; /** * Returns rounded version of underlying decimal. */ - (NSDecimalNumber *)decimalNumberByRoundingAccordingToBehavior:(id )behavior; @end /** * Interface for obtaining an NSDecimalNumber value from an ordinary * NSNumber. */ @interface NSNumber (NSDecimalNumber) /** * Obtaining an NSDecimalNumber version of an ordinary NSNumber. */ - (NSDecimal) decimalValue; @end #if defined(__cplusplus) } #endif #endif #endif