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