icuSources/i18n/precision.h

   1 /*
   2 *******************************************************************************
   3 * Copyright (C) 2015, International Business Machines
   4 * Corporation and others.  All Rights Reserved.
   5 *******************************************************************************
   6 * precision.h
   7 *
   8 * created on: 2015jan06
   9 * created by: Travis Keep
  10 */
  11
  12 #ifndef __PRECISION_H__
  13 #define __PRECISION_H__
  14
  15 #include "unicode/uobject.h"
  16
  17 #if !UCONFIG_NO_FORMATTING
  18 #include "unicode/utypes.h"
  19
  20 #include "digitinterval.h"
  21 #include "digitlst.h"
  22 #include "significantdigitinterval.h"
  23
  24 U_NAMESPACE_BEGIN
  25
  26 class VisibleDigits;
  27 class VisibleDigitsWithExponent;
  28
  29
  30 /**
  31  * A precision manager for values to be formatted as fixed point.
  32  * Handles rounding of number to prepare it for formatting.
  33  */
  34 class U_I18N_API FixedPrecision : public UMemory {
  35 public:
  36
  37     /**
  38      * The smallest format interval allowed. Default is 1 integer digit and no
  39      * fraction digits.
  40      */
  41     DigitInterval fMin;
  42
  43     /**
  44      * The largest format interval allowed. Must contain fMin.
  45      *  Default is all digits.
  46      */
  47     DigitInterval fMax;
  48
  49     /**
  50      * Min and max significant digits allowed. The default is no constraints.
  51      */
  52     SignificantDigitInterval fSignificant;
  53
  54     /**
  55      * The rounding increment or zero if there is no rounding increment.
  56      * Default is zero.
  57      */
  58     DigitList fRoundingIncrement;
  59
  60     /**
  61      * If set, causes round() to set status to U_FORMAT_INEXACT_ERROR if
  62      * any rounding is done. Default is FALSE.
  63      */
  64     UBool fExactOnly;
  65
  66     /**
  67      * If set, causes round() to set status to U_ILLEGAL_ARGUMENT_ERROR if
  68      * rounded number has more than maximum integer digits. Default is FALSE.
  69      */
  70     UBool fFailIfOverMax;
  71
  72     /**
  73      * Controls the rounding mode that initVisibleDigits uses.
  74      * Default is DecimalFormat::kRoundHalfEven
  75      */
  76     DecimalFormat::ERoundingMode fRoundingMode;
  77
  78     FixedPrecision();
  79
  80     /**
  81      * Returns TRUE if this object equals rhs.
  82      */
  83     UBool equals(const FixedPrecision &rhs) const {
  84         return (fMin.equals(rhs.fMin) &&
  85                 fMax.equals(rhs.fMax) &&
  86                 fSignificant.equals(rhs.fSignificant) &&
  87                 (fRoundingIncrement == rhs.fRoundingIncrement) &&
  88                 fExactOnly == rhs.fExactOnly &&
  89                 fFailIfOverMax == rhs.fFailIfOverMax &&
  90                 fRoundingMode == rhs.fRoundingMode);
  91     }
  92
  93     /**
  94      * Rounds value in place to prepare it for formatting.
  95      * @param value The value to be rounded. It is rounded in place.
  96      * @param exponent Always pass 0 for fixed decimal formatting. scientific
  97      *  precision passes the exponent value.  Essentially, it divides value by
  98      *  10^exponent, rounds and then multiplies by 10^exponent.
  99      * @param status error returned here.
 100      * @return reference to value.
 101      */
 102     DigitList &round(DigitList &value, int32_t exponent, UErrorCode &status) const;
 103
 104     /**
 105      * Returns the interval to use to format the rounded value.
 106      * @param roundedValue the already rounded value to format.
 107      * @param interval modified in place to be the interval to use to format
 108      *   the rounded value.
 109      * @return a reference to interval.
 110      */
 111     DigitInterval &getInterval(
 112             const DigitList &roundedValue, DigitInterval &interval) const;
 113
 114     /**
 115      * Returns TRUE if this instance allows for fast formatting of integers.
 116      */
 117     UBool isFastFormattable() const;
 118
 119     /**
 120      * Initializes a VisibleDigits.
 121      * @param value value for VisibleDigits
 122      *    Caller must not assume that the value of this parameter will remain
 123      *    unchanged.
 124      * @param digits This is the value that is initialized.
 125      * @param status any error returned here.
 126      * @return digits
 127      */
 128     VisibleDigits &initVisibleDigits(
 129             DigitList &value,
 130             VisibleDigits &digits,
 131             UErrorCode &status) const;
 132
 133     /**
 134      * Initializes a VisibleDigits.
 135      * @param value value for VisibleDigits
 136      * @param digits This is the value that is initialized.
 137      * @param status any error returned here.
 138      * @return digits
 139      */
 140     VisibleDigits &initVisibleDigits(
 141             double value,
 142             VisibleDigits &digits,
 143             UErrorCode &status) const;
 144
 145     /**
 146      * Initializes a VisibleDigits.
 147      * @param value value for VisibleDigits
 148      * @param digits This is the value that is initialized.
 149      * @param status any error returned here.
 150      * @return digits
 151      */
 152     VisibleDigits &initVisibleDigits(
 153             int64_t value,
 154             VisibleDigits &digits,
 155             UErrorCode &status) const;
 156
 157     /**
 158      * Initializes a VisibleDigitsWithExponent.
 159      * @param value value for VisibleDigits
 160      *    Caller must not assume that the value of this parameter will remain
 161      *    unchanged.
 162      * @param digits This is the value that is initialized.
 163      * @param status any error returned here.
 164      * @return digits
 165      */
 166     VisibleDigitsWithExponent &initVisibleDigitsWithExponent(
 167             DigitList &value,
 168             VisibleDigitsWithExponent &digits,
 169             UErrorCode &status) const;
 170
 171     /**
 172      * Initializes a VisibleDigitsWithExponent.
 173      * @param value value for VisibleDigits
 174      * @param digits This is the value that is initialized.
 175      * @param status any error returned here.
 176      * @return digits
 177      */
 178     VisibleDigitsWithExponent &initVisibleDigitsWithExponent(
 179             double value,
 180             VisibleDigitsWithExponent &digits,
 181             UErrorCode &status) const;
 182
 183     /**
 184      * Initializes a VisibleDigitsWithExponent.
 185      * @param value value for VisibleDigits
 186      * @param digits This is the value that is initialized.
 187      * @param status any error returned here.
 188      * @return digits
 189      */
 190     VisibleDigitsWithExponent &initVisibleDigitsWithExponent(
 191             int64_t value,
 192             VisibleDigitsWithExponent &digits,
 193             UErrorCode &status) const;
 194
 195 private:
 196     /**
 197      * Attempts to initialize 'digits' using simple mod 10 arithmetic.
 198      * Returns FALSE if this is not possible such as when rounding
 199      * would change the value. Otherwise returns TRUE.
 200      *
 201      * If the method returns FALSE, caller should create a DigitList
 202      * and use it to initialize 'digits'. If this method returns TRUE,
 203      * caller should accept the value stored in 'digits'. If this
 204      * method returns TRUE along with a non zero error, caller must accept
 205      * the error and not try again with a DigitList.
 206      *
 207      * Before calling this method, caller must verify that this object
 208      * has no rounding increment set.
 209      *
 210      * The value that 'digits' is initialized to is mantissa * 10^exponent.
 211      * For example mantissa = 54700 and exponent = -3 means 54.7. The
 212      * properties of this object (such as min and max fraction digits),
 213      * not the number of trailing zeros in the mantissa, determine whether or
 214      * not the result contains any trailing 0's after the decimal point.
 215      *
 216      * @param mantissa the digits. May be positive or negative. May contain
 217      *  trailing zeros.
 218      * @param exponent must always be zero or negative. An exponent > 0
 219      *  yields undefined results!
 220      * @param digits result stored here.
 221      * @param status any error returned here.
 222      */
 223     UBool
 224     initVisibleDigits(
 225             int64_t mantissa,
 226             int32_t exponent,
 227             VisibleDigits &digits,
 228             UErrorCode &status) const;
 229     UBool isRoundingRequired(
 230             int32_t upperExponent, int32_t lowerExponent) const;
 231     DigitInterval &getIntervalForZero(DigitInterval &interval) const;
 232     DigitInterval &getInterval(
 233             int32_t upperExponent, DigitInterval &interval) const;
 234     static UBool handleNonNumeric(DigitList &value, VisibleDigits &digits);
 235
 236     friend class ScientificPrecision;
 237 };
 238
 239 /**
 240  * A precision manager for values to be expressed as scientific notation.
 241  */
 242 class U_I18N_API ScientificPrecision : public UMemory {
 243 public:
 244     FixedPrecision fMantissa;
 245     int32_t fMinExponentDigits;
 246
 247     ScientificPrecision();
 248
 249     /**
 250      * rounds value in place to prepare it for formatting.
 251      * @param value The value to be rounded. It is rounded in place.
 252      * @param status error returned here.
 253      * @return reference to value.
 254      */
 255     DigitList &round(DigitList &value, UErrorCode &status) const;
 256
 257     /**
 258      * Converts value to a mantissa and exponent.
 259      *
 260      * @param value modified in place to be the mantissa. Depending on
 261      *   the precision settings, the resulting mantissa may not fall
 262      *   between 1.0 and 10.0.
 263      * @return the exponent of value.
 264      */
 265     int32_t toScientific(DigitList &value) const;
 266
 267     /**
 268      * Returns TRUE if this object equals rhs.
 269      */
 270     UBool equals(const ScientificPrecision &rhs) const {
 271         return fMantissa.equals(rhs.fMantissa) && fMinExponentDigits == rhs.fMinExponentDigits;
 272     }
 273
 274     /**
 275      * Initializes a VisibleDigitsWithExponent.
 276      * @param value the value
 277      *    Caller must not assume that the value of this parameter will remain
 278      *    unchanged.
 279      * @param digits This is the value that is initialized.
 280      * @param status any error returned here.
 281      * @return digits
 282      */
 283     VisibleDigitsWithExponent &initVisibleDigitsWithExponent(
 284             DigitList &value,
 285             VisibleDigitsWithExponent &digits,
 286             UErrorCode &status) const;
 287
 288     /**
 289      * Initializes a VisibleDigitsWithExponent.
 290      * @param value the value
 291      * @param digits This is the value that is initialized.
 292      * @param status any error returned here.
 293      * @return digits
 294      */
 295     VisibleDigitsWithExponent &initVisibleDigitsWithExponent(
 296             double value,
 297             VisibleDigitsWithExponent &digits,
 298             UErrorCode &status) const;
 299
 300     /**
 301      * Initializes a VisibleDigitsWithExponent.
 302      * @param value the value
 303      * @param digits This is the value that is initialized.
 304      * @param status any error returned here.
 305      * @return digits
 306      */
 307     VisibleDigitsWithExponent &initVisibleDigitsWithExponent(
 308             int64_t value,
 309             VisibleDigitsWithExponent &digits,
 310             UErrorCode &status) const;
 311
 312 private:
 313     int32_t getMultiplier() const;
 314
 315 };
 316
 317
 318
 319 U_NAMESPACE_END
 320 #endif // #if !UCONFIG_NO_FORMATTING
 321 #endif  // __PRECISION_H__