1
/* NSDecimal types and functions
2
Copyright (C) 1998 Free Software Foundation, Inc.
4
Written by: Richard Frith-Macdonald <richard@brainstorm.co.uk>
7
This file is part of the GNUstep Base Library.
9
This library is free software; you can redistribute it and/or
10
modify it under the terms of the GNU Library General Public
11
License as published by the Free Software Foundation; either
12
version 2 of the License, or (at your option) any later version.
14
This library is distributed in the hope that it will be useful,
15
but WITHOUT ANY WARRANTY; without even the implied warranty of
16
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17
Library General Public License for more details.
19
You should have received a copy of the GNU Library General Public
20
License along with this library; if not, write to the Free
21
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA.
25
#ifndef __NSDecimal_h_GNUSTEP_BASE_INCLUDE
26
#define __NSDecimal_h_GNUSTEP_BASE_INCLUDE
28
#ifndef STRICT_OPENSTEP
36
#include <Foundation/NSObject.h>
39
* Enumerated type for specifying decimal rounding behavior. Can be one of
40
* <code>NSRoundDown</code> (always round down), <code>NSRoundUp</code>
41
* (always round up), <code>NSRoundPlain</code> ("normal" rounding (up from
42
* .5 or above, down otherwise), <code>NSRoundBankers</code> (as "Plain" but
43
* .5 rounds to make last remaining digit even). See the
44
* [(NSDecimalNumberBehaviors)] protocol.
49
NSRoundPlain, /* Round .5 up */
50
NSRoundBankers /* Make last digit even */
54
* Enumerated type for specifying a decimal calculation error. Can be one of
57
* <term><code>NSCalculationNoError</code></term>
58
* <desc>No error occurred.</desc>
59
* <term><code>NSCalculationLossOfPrecision</code></term>
60
* <desc>The number can't be represented in 38 significant digits.</desc>
61
* <term><code>NSCalculationOverflow</code></term>
62
* <desc>The number is too large to represent.</desc>
63
* <term><code>NSCalculationUnderflow</code></term>
64
* <desc>The number is too small to represent.</desc>
65
* <term><code>NSCalculationDivideByZero</code></term>
66
* <desc>The caller tried to divide by 0.</desc>
70
NSCalculationNoError = 0,
71
NSCalculationUnderflow, /* result became zero */
72
NSCalculationOverflow,
73
NSCalculationLossOfPrecision,
74
NSCalculationDivideByZero
78
* Give a precision of at least 38 decimal digits
81
#define NSDecimalMaxSize (16/sizeof(mp_limb_t))
83
#define NSDecimalMaxDigit 38
84
#define NSDecimalNoScale 128
87
* <p>Structure providing equivalent functionality, in conjunction with a set
88
* of functions, to the [NSDecimalNumber] class.</p>
91
signed char exponent; // Signed exponent - -128 to 127
92
BOOL isNegative; // Is this negative?
93
BOOL validNumber; // Is this a valid number?
94
unsigned char length; // digits in mantissa.
95
unsigned char cMantissa[2*NSDecimalMaxDigit];
98
* <p>Instances can be initialized using the NSDecimalFromString(NSString *)
102
signed char exponent; /* Signed exponent - -128 to 127 */
103
BOOL isNegative; /* Is this negative? */
104
BOOL validNumber; /* Is this a valid number? */
107
mp_limb_t lMantissa[NSDecimalMaxSize];
109
unsigned char length; /* digits in mantissa. */
110
unsigned char cMantissa[NSDecimalMaxDigit];
114
/** Returns whether decimal represents an invalid number (i.e., an "NaN" as
115
might result from an overflow or a division by zero). */
117
NSDecimalIsNotANumber(const NSDecimal *decimal)
119
return (decimal->validNumber == NO);
122
/** Copies value of decimal number to preallocated destination. */
124
NSDecimalCopy(NSDecimal *destination, const NSDecimal *source);
126
/** Tries to reduce memory used to store number internally. */
128
NSDecimalCompact(NSDecimal *number);
131
* Returns <code>NSOrderedDescending</code>, <code>NSOrderedSame</code>, or
132
* <code>NSOrderedAscending</code> depending on whether leftOperand is
133
* greater than, equal to, or less than rightOperand.
135
GS_EXPORT NSComparisonResult
136
NSDecimalCompare(const NSDecimal *leftOperand, const NSDecimal *rightOperand);
139
* Rounds number to result such that it has at most scale digits to the right
140
* of its decimal point, according to mode (see the
141
* [(NSDecimalNumberBehaviors)] protocol). The result should be preallocated
142
* but can be the same as number.
145
NSDecimalRound(NSDecimal *result, const NSDecimal *number, int scale, NSRoundingMode mode);
148
* Sets the exponents of n1 and n2 equal to one another, adjusting mantissas
149
* as necessary to preserve values. This makes certain operations quicker.
151
GS_EXPORT NSCalculationError
152
NSDecimalNormalize(NSDecimal *n1, NSDecimal *n2, NSRoundingMode mode);
155
* Adds two decimals and returns result to 38-digit precision. See the
156
* [(NSDecimalNumberBehaviors)] protocol for a description of mode and the
157
* return value. The result should be preallocated but can be the same as
160
GS_EXPORT NSCalculationError
161
NSDecimalAdd(NSDecimal *result, const NSDecimal *left, const NSDecimal *right, NSRoundingMode mode);
164
* Subtracts two decimals and returns result to 38-digit precision. See the
165
* [(NSDecimalNumberBehaviors)] protocol for a description of mode and the
166
* return value. The result should be preallocated but can be the same as
169
GS_EXPORT NSCalculationError
170
NSDecimalSubtract(NSDecimal *result, const NSDecimal *left, const NSDecimal *right, NSRoundingMode mode);
173
* Multiplies two decimals and returns result to 38-digit precision. See the
174
* [(NSDecimalNumberBehaviors)] protocol for a description of mode and the
175
* return value. The result should be preallocated but can be the same as
178
GS_EXPORT NSCalculationError
179
NSDecimalMultiply(NSDecimal *result, const NSDecimal *l, const NSDecimal *r, NSRoundingMode mode);
182
* Divides l by rr and returns result to 38-digit precision. See the
183
* [(NSDecimalNumberBehaviors)] protocol for a description of mode and the
184
* return value. The result should be preallocated but can be the same as
187
GS_EXPORT NSCalculationError
188
NSDecimalDivide(NSDecimal *result, const NSDecimal *l, const NSDecimal *rr, NSRoundingMode mode);
191
* Raises n to power and returns result to 38-digit precision. See the
192
* [(NSDecimalNumberBehaviors)] protocol for a description of mode and the
193
* return value. The result should be preallocated but can be the same as
196
GS_EXPORT NSCalculationError
197
NSDecimalPower(NSDecimal *result, const NSDecimal *n, unsigned power, NSRoundingMode mode);
200
* Multiplies n by 10^power and returns result to 38-digit precision. See the
201
* [(NSDecimalNumberBehaviors)] protocol for a description of mode and the
202
* return value. The result should be preallocated but can be the same as
205
GS_EXPORT NSCalculationError
206
NSDecimalMultiplyByPowerOf10(NSDecimal *result, const NSDecimal *n, short power, NSRoundingMode mode);
209
* Returns a string representing the full decimal value, formatted according
210
* to locale (send nil here for default locale).
213
NSDecimalString(const NSDecimal *decimal, NSDictionary *locale);
216
// GNUstep extensions to make the implementation of NSDecimalNumber totaly
217
// independent for NSDecimals internal representation
219
/** Give back the biggest NSDecimal in (preallocated) result. */
221
NSDecimalMax(NSDecimal *result);
223
/** Give back the smallest NSDecimal in (preallocated) result. */
225
NSDecimalMin(NSDecimal *result);
227
/** Give back the value of a NSDecimal as a double in (preallocated) result. */
229
NSDecimalDouble(NSDecimal *number);
232
* Create a NSDecimal with a mantissa, exponent and a negative flag in
233
* (preallocated) result.
236
NSDecimalFromComponents(NSDecimal *result, unsigned long long mantissa,
237
short exponent, BOOL negative);
240
* Create a NSDecimal from a string using the locale, in (preallocated)
244
NSDecimalFromString(NSDecimal *result, NSString *numberValue,
245
NSDictionary *locale);