• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 // © 2017 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 
4 #include "unicode/utypes.h"
5 
6 #if !UCONFIG_NO_FORMATTING
7 #ifndef __NUMBER_DECIMALQUANTITY_H__
8 #define __NUMBER_DECIMALQUANTITY_H__
9 
10 #include <cstdint>
11 #include "unicode/umachine.h"
12 #include "standardplural.h"
13 #include "plurrule_impl.h"
14 #include "number_types.h"
15 
16 U_NAMESPACE_BEGIN namespace number {
17 namespace impl {
18 
19 // Forward-declare (maybe don't want number_utils.h included here):
20 class DecNum;
21 
22 /**
23  * An class for representing a number to be processed by the decimal formatting pipeline. Includes
24  * methods for rounding, plural rules, and decimal digit extraction.
25  *
26  * <p>By design, this is NOT IMMUTABLE and NOT THREAD SAFE. It is intended to be an intermediate
27  * object holding state during a pass through the decimal formatting pipeline.
28  *
29  * <p>Represents numbers and digit display properties using Binary Coded Decimal (BCD).
30  *
31  * <p>Java has multiple implementations for testing, but C++ has only one implementation.
32  */
33 class U_I18N_API DecimalQuantity : public IFixedDecimal, public UMemory {
34   public:
35     /** Copy constructor. */
36     DecimalQuantity(const DecimalQuantity &other);
37 
38     /** Move constructor. */
39     DecimalQuantity(DecimalQuantity &&src) U_NOEXCEPT;
40 
41     DecimalQuantity();
42 
43     ~DecimalQuantity() override;
44 
45     /**
46      * Sets this instance to be equal to another instance.
47      *
48      * @param other The instance to copy from.
49      */
50     DecimalQuantity &operator=(const DecimalQuantity &other);
51 
52     /** Move assignment */
53     DecimalQuantity &operator=(DecimalQuantity&& src) U_NOEXCEPT;
54 
55     /**
56      * Sets the minimum and maximum integer digits that this {@link DecimalQuantity} should generate.
57      * This method does not perform rounding.
58      *
59      * @param minInt The minimum number of integer digits.
60      * @param maxInt The maximum number of integer digits.
61      */
62     void setIntegerLength(int32_t minInt, int32_t maxInt);
63 
64     /**
65      * Sets the minimum and maximum fraction digits that this {@link DecimalQuantity} should generate.
66      * This method does not perform rounding.
67      *
68      * @param minFrac The minimum number of fraction digits.
69      * @param maxFrac The maximum number of fraction digits.
70      */
71     void setFractionLength(int32_t minFrac, int32_t maxFrac);
72 
73     /**
74      * Rounds the number to a specified interval, such as 0.05.
75      *
76      * <p>If rounding to a power of ten, use the more efficient {@link #roundToMagnitude} instead.
77      *
78      * @param roundingIncrement The increment to which to round.
79      * @param mathContext The {@link RoundingMode} to use if rounding is necessary.
80      */
81     void roundToIncrement(double roundingIncrement, RoundingMode roundingMode,
82                           int32_t maxFrac, UErrorCode& status);
83 
84     /** Removes all fraction digits. */
85     void truncate();
86 
87     /**
88      * Rounds the number to a specified magnitude (power of ten).
89      *
90      * @param roundingMagnitude The power of ten to which to round. For example, a value of -2 will
91      *     round to 2 decimal places.
92      * @param mathContext The {@link RoundingMode} to use if rounding is necessary.
93      */
94     void roundToMagnitude(int32_t magnitude, RoundingMode roundingMode, UErrorCode& status);
95 
96     /**
97      * Rounds the number to an infinite number of decimal points. This has no effect except for
98      * forcing the double in {@link DecimalQuantity_AbstractBCD} to adopt its exact representation.
99      */
100     void roundToInfinity();
101 
102     /**
103      * Multiply the internal value. Uses decNumber.
104      *
105      * @param multiplicand The value by which to multiply.
106      */
107     void multiplyBy(const DecNum& multiplicand, UErrorCode& status);
108 
109     /**
110      * Divide the internal value. Uses decNumber.
111      *
112      * @param multiplicand The value by which to multiply.
113      */
114     void divideBy(const DecNum& divisor, UErrorCode& status);
115 
116     /** Flips the sign from positive to negative and back. */
117     void negate();
118 
119     /**
120      * Scales the number by a power of ten. For example, if the value is currently "1234.56", calling
121      * this method with delta=-3 will change the value to "1.23456".
122      *
123      * @param delta The number of magnitudes of ten to change by.
124      * @return true if integer overflow occured; false otherwise.
125      */
126     bool adjustMagnitude(int32_t delta);
127 
128     /**
129      * @return The power of ten corresponding to the most significant nonzero digit.
130      * The number must not be zero.
131      */
132     int32_t getMagnitude() const;
133 
134     /** @return Whether the value represented by this {@link DecimalQuantity} is zero. */
135     bool isZero() const;
136 
137     /** @return Whether the value represented by this {@link DecimalQuantity} is less than zero. */
138     bool isNegative() const;
139 
140     /** @return -1 if the value is negative; 1 if positive; or 0 if zero. */
141     int8_t signum() const;
142 
143     /** @return Whether the value represented by this {@link DecimalQuantity} is infinite. */
144     bool isInfinite() const U_OVERRIDE;
145 
146     /** @return Whether the value represented by this {@link DecimalQuantity} is not a number. */
147     bool isNaN() const U_OVERRIDE;
148 
149     /** @param truncateIfOverflow if false and the number does NOT fit, fails with an assertion error. */
150     int64_t toLong(bool truncateIfOverflow = false) const;
151 
152     uint64_t toFractionLong(bool includeTrailingZeros) const;
153 
154     /**
155      * Returns whether or not a Long can fully represent the value stored in this DecimalQuantity.
156      * @param ignoreFraction if true, silently ignore digits after the decimal place.
157      */
158     bool fitsInLong(bool ignoreFraction = false) const;
159 
160     /** @return The value contained in this {@link DecimalQuantity} approximated as a double. */
161     double toDouble() const;
162 
163     /** Computes a DecNum representation of this DecimalQuantity, saving it to the output parameter. */
164     void toDecNum(DecNum& output, UErrorCode& status) const;
165 
166     DecimalQuantity &setToInt(int32_t n);
167 
168     DecimalQuantity &setToLong(int64_t n);
169 
170     DecimalQuantity &setToDouble(double n);
171 
172     /** decNumber is similar to BigDecimal in Java. */
173     DecimalQuantity &setToDecNumber(StringPiece n, UErrorCode& status);
174 
175     /** Internal method if the caller already has a DecNum. */
176     DecimalQuantity &setToDecNum(const DecNum& n, UErrorCode& status);
177 
178     /**
179      * Appends a digit, optionally with one or more leading zeros, to the end of the value represented
180      * by this DecimalQuantity.
181      *
182      * <p>The primary use of this method is to construct numbers during a parsing loop. It allows
183      * parsing to take advantage of the digit list infrastructure primarily designed for formatting.
184      *
185      * @param value The digit to append.
186      * @param leadingZeros The number of zeros to append before the digit. For example, if the value
187      *     in this instance starts as 12.3, and you append a 4 with 1 leading zero, the value becomes
188      *     12.304.
189      * @param appendAsInteger If true, increase the magnitude of existing digits to make room for the
190      *     new digit. If false, append to the end like a fraction digit. If true, there must not be
191      *     any fraction digits already in the number.
192      * @internal
193      * @deprecated This API is ICU internal only.
194      */
195     void appendDigit(int8_t value, int32_t leadingZeros, bool appendAsInteger);
196 
197     double getPluralOperand(PluralOperand operand) const U_OVERRIDE;
198 
199     bool hasIntegerValue() const U_OVERRIDE;
200 
201     /**
202      * Gets the digit at the specified magnitude. For example, if the represented number is 12.3,
203      * getDigit(-1) returns 3, since 3 is the digit corresponding to 10^-1.
204      *
205      * @param magnitude The magnitude of the digit.
206      * @return The digit at the specified magnitude.
207      */
208     int8_t getDigit(int32_t magnitude) const;
209 
210     /**
211      * Gets the largest power of ten that needs to be displayed. The value returned by this function
212      * will be bounded between minInt and maxInt.
213      *
214      * @return The highest-magnitude digit to be displayed.
215      */
216     int32_t getUpperDisplayMagnitude() const;
217 
218     /**
219      * Gets the smallest power of ten that needs to be displayed. The value returned by this function
220      * will be bounded between -minFrac and -maxFrac.
221      *
222      * @return The lowest-magnitude digit to be displayed.
223      */
224     int32_t getLowerDisplayMagnitude() const;
225 
226     int32_t fractionCount() const;
227 
228     int32_t fractionCountWithoutTrailingZeros() const;
229 
230     void clear();
231 
232     /** This method is for internal testing only. */
233     uint64_t getPositionFingerprint() const;
234 
235 //    /**
236 //     * If the given {@link FieldPosition} is a {@link UFieldPosition}, populates it with the fraction
237 //     * length and fraction long value. If the argument is not a {@link UFieldPosition}, nothing
238 //     * happens.
239 //     *
240 //     * @param fp The {@link UFieldPosition} to populate.
241 //     */
242 //    void populateUFieldPosition(FieldPosition fp);
243 
244     /**
245      * Checks whether the bytes stored in this instance are all valid. For internal unit testing only.
246      *
247      * @return An error message if this instance is invalid, or null if this instance is healthy.
248      */
249     const char16_t* checkHealth() const;
250 
251     UnicodeString toString() const;
252 
253     /** Returns the string in standard exponential notation. */
254     UnicodeString toScientificString() const;
255 
256     /** Returns the string without exponential notation. Slightly slower than toScientificString(). */
257     UnicodeString toPlainString() const;
258 
259     /** Visible for testing */
isUsingBytes()260     inline bool isUsingBytes() { return usingBytes; }
261 
262     /** Visible for testing */
isExplicitExactDouble()263     inline bool isExplicitExactDouble() { return explicitExactDouble; };
264 
265     bool operator==(const DecimalQuantity& other) const;
266 
267     inline bool operator!=(const DecimalQuantity& other) const {
268         return !(*this == other);
269     }
270 
271     /**
272      * Bogus flag for when a DecimalQuantity is stored on the stack.
273      */
274     bool bogus = false;
275 
276   private:
277     /**
278      * The power of ten corresponding to the least significant digit in the BCD. For example, if this
279      * object represents the number "3.14", the BCD will be "0x314" and the scale will be -2.
280      *
281      * <p>Note that in {@link java.math.BigDecimal}, the scale is defined differently: the number of
282      * digits after the decimal place, which is the negative of our definition of scale.
283      */
284     int32_t scale;
285 
286     /**
287      * The number of digits in the BCD. For example, "1007" has BCD "0x1007" and precision 4. The
288      * maximum precision is 16 since a long can hold only 16 digits.
289      *
290      * <p>This value must be re-calculated whenever the value in bcd changes by using {@link
291      * #computePrecisionAndCompact()}.
292      */
293     int32_t precision;
294 
295     /**
296      * A bitmask of properties relating to the number represented by this object.
297      *
298      * @see #NEGATIVE_FLAG
299      * @see #INFINITY_FLAG
300      * @see #NAN_FLAG
301      */
302     int8_t flags;
303 
304     // The following three fields relate to the double-to-ascii fast path algorithm.
305     // When a double is given to DecimalQuantityBCD, it is converted to using a fast algorithm. The
306     // fast algorithm guarantees correctness to only the first ~12 digits of the double. The process
307     // of rounding the number ensures that the converted digits are correct, falling back to a slow-
308     // path algorithm if required.  Therefore, if a DecimalQuantity is constructed from a double, it
309     // is *required* that roundToMagnitude(), roundToIncrement(), or roundToInfinity() is called. If
310     // you don't round, assertions will fail in certain other methods if you try calling them.
311 
312     /**
313      * Whether the value in the BCD comes from the double fast path without having been rounded to
314      * ensure correctness
315      */
316     UBool isApproximate;
317 
318     /**
319      * The original number provided by the user and which is represented in BCD. Used when we need to
320      * re-compute the BCD for an exact double representation.
321      */
322     double origDouble;
323 
324     /**
325      * The change in magnitude relative to the original double. Used when we need to re-compute the
326      * BCD for an exact double representation.
327      */
328     int32_t origDelta;
329 
330     // Four positions: left optional '(', left required '[', right required ']', right optional ')'.
331     // These four positions determine which digits are displayed in the output string.  They do NOT
332     // affect rounding.  These positions are internal-only and can be specified only by the public
333     // endpoints like setFractionLength, setIntegerLength, and setSignificantDigits, among others.
334     //
335     //   * Digits between lReqPos and rReqPos are in the "required zone" and are always displayed.
336     //   * Digits between lOptPos and rOptPos but outside the required zone are in the "optional zone"
337     //     and are displayed unless they are trailing off the left or right edge of the number and
338     //     have a numerical value of zero.  In order to be "trailing", the digits need to be beyond
339     //     the decimal point in their respective directions.
340     //   * Digits outside of the "optional zone" are never displayed.
341     //
342     // See the table below for illustrative examples.
343     //
344     // +---------+---------+---------+---------+------------+------------------------+--------------+
345     // | lOptPos | lReqPos | rReqPos | rOptPos |   number   |        positions       | en-US string |
346     // +---------+---------+---------+---------+------------+------------------------+--------------+
347     // |    5    |    2    |   -1    |   -5    |   1234.567 |     ( 12[34.5]67  )    |   1,234.567  |
348     // |    3    |    2    |   -1    |   -5    |   1234.567 |      1(2[34.5]67  )    |     234.567  |
349     // |    3    |    2    |   -1    |   -2    |   1234.567 |      1(2[34.5]6)7      |     234.56   |
350     // |    6    |    4    |    2    |   -5    | 123456789. |  123(45[67]89.     )   | 456,789.     |
351     // |    6    |    4    |    2    |    1    | 123456789. |     123(45[67]8)9.     | 456,780.     |
352     // |   -1    |   -1    |   -3    |   -4    | 0.123456   |     0.1([23]4)56       |        .0234 |
353     // |    6    |    4    |   -2    |   -2    |     12.3   |     (  [  12.3 ])      |    0012.30   |
354     // +---------+---------+---------+---------+------------+------------------------+--------------+
355     //
356     int32_t lOptPos = INT32_MAX;
357     int32_t lReqPos = 0;
358     int32_t rReqPos = 0;
359     int32_t rOptPos = INT32_MIN;
360 
361     /**
362      * The BCD of the 16 digits of the number represented by this object. Every 4 bits of the long map
363      * to one digit. For example, the number "12345" in BCD is "0x12345".
364      *
365      * <p>Whenever bcd changes internally, {@link #compact()} must be called, except in special cases
366      * like setting the digit to zero.
367      */
368     union {
369         struct {
370             int8_t *ptr;
371             int32_t len;
372         } bcdBytes;
373         uint64_t bcdLong;
374     } fBCD;
375 
376     bool usingBytes = false;
377 
378     /**
379      * Whether this {@link DecimalQuantity} has been explicitly converted to an exact double. true if
380      * backed by a double that was explicitly converted via convertToAccurateDouble; false otherwise.
381      * Used for testing.
382      */
383     bool explicitExactDouble = false;
384 
385     /**
386      * Returns a single digit from the BCD list. No internal state is changed by calling this method.
387      *
388      * @param position The position of the digit to pop, counted in BCD units from the least
389      *     significant digit. If outside the range supported by the implementation, zero is returned.
390      * @return The digit at the specified location.
391      */
392     int8_t getDigitPos(int32_t position) const;
393 
394     /**
395      * Sets the digit in the BCD list. This method only sets the digit; it is the caller's
396      * responsibility to call {@link #compact} after setting the digit.
397      *
398      * @param position The position of the digit to pop, counted in BCD units from the least
399      *     significant digit. If outside the range supported by the implementation, an AssertionError
400      *     is thrown.
401      * @param value The digit to set at the specified location.
402      */
403     void setDigitPos(int32_t position, int8_t value);
404 
405     /**
406      * Adds zeros to the end of the BCD list. This will result in an invalid BCD representation; it is
407      * the caller's responsibility to do further manipulation and then call {@link #compact}.
408      *
409      * @param numDigits The number of zeros to add.
410      */
411     void shiftLeft(int32_t numDigits);
412 
413     void shiftRight(int32_t numDigits);
414 
415     /**
416      * Sets the internal representation to zero. Clears any values stored in scale, precision,
417      * hasDouble, origDouble, origDelta, and BCD data.
418      */
419     void setBcdToZero();
420 
421     /**
422      * Sets the internal BCD state to represent the value in the given int. The int is guaranteed to
423      * be either positive. The internal state is guaranteed to be empty when this method is called.
424      *
425      * @param n The value to consume.
426      */
427     void readIntToBcd(int32_t n);
428 
429     /**
430      * Sets the internal BCD state to represent the value in the given long. The long is guaranteed to
431      * be either positive. The internal state is guaranteed to be empty when this method is called.
432      *
433      * @param n The value to consume.
434      */
435     void readLongToBcd(int64_t n);
436 
437     void readDecNumberToBcd(const DecNum& dn);
438 
439     void readDoubleConversionToBcd(const char* buffer, int32_t length, int32_t point);
440 
441     void copyFieldsFrom(const DecimalQuantity& other);
442 
443     void copyBcdFrom(const DecimalQuantity &other);
444 
445     void moveBcdFrom(DecimalQuantity& src);
446 
447     /**
448      * Removes trailing zeros from the BCD (adjusting the scale as required) and then computes the
449      * precision. The precision is the number of digits in the number up through the greatest nonzero
450      * digit.
451      *
452      * <p>This method must always be called when bcd changes in order for assumptions to be correct in
453      * methods like {@link #fractionCount()}.
454      */
455     void compact();
456 
457     void _setToInt(int32_t n);
458 
459     void _setToLong(int64_t n);
460 
461     void _setToDoubleFast(double n);
462 
463     void _setToDecNum(const DecNum& dn, UErrorCode& status);
464 
465     void convertToAccurateDouble();
466 
467     /** Ensure that a byte array of at least 40 digits is allocated. */
468     void ensureCapacity();
469 
470     void ensureCapacity(int32_t capacity);
471 
472     /** Switches the internal storage mechanism between the 64-bit long and the byte array. */
473     void switchStorage();
474 };
475 
476 } // namespace impl
477 } // namespace number
478 U_NAMESPACE_END
479 
480 
481 #endif //__NUMBER_DECIMALQUANTITY_H__
482 
483 #endif /* #if !UCONFIG_NO_FORMATTING */
484