numberformatter.h

Go to the documentation of this file.

// © 2017 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html

#include "unicode/utypes.h"

#if !UCONFIG_NO_FORMATTING
#ifndef __NUMBERFORMATTER_H__
#define __NUMBERFORMATTER_H__

#include "unicode/appendable.h"
#include "unicode/dcfmtsym.h"
#include "unicode/currunit.h"
#include "unicode/fieldpos.h"
#include "unicode/fpositer.h"
#include "unicode/measunit.h"
#include "unicode/nounit.h"
#include "unicode/plurrule.h"
#include "unicode/ucurr.h"
#include "unicode/unum.h"

#ifndef U_HIDE_DRAFT_API

typedef enum UNumberUnitWidth {
            UNUM_UNIT_WIDTH_NARROW,

            UNUM_UNIT_WIDTH_SHORT,

            UNUM_UNIT_WIDTH_FULL_NAME,

            UNUM_UNIT_WIDTH_ISO_CODE,

            UNUM_UNIT_WIDTH_HIDDEN,

            UNUM_UNIT_WIDTH_COUNT
} UNumberUnitWidth;

typedef enum UNumberSignDisplay {
            UNUM_SIGN_AUTO,

            UNUM_SIGN_ALWAYS,

            UNUM_SIGN_NEVER,

            UNUM_SIGN_ACCOUNTING,

            UNUM_SIGN_ACCOUNTING_ALWAYS,

            UNUM_SIGN_COUNT
} UNumberSignDisplay;

typedef enum UNumberDecimalSeparatorDisplay {
            UNUM_DECIMAL_SEPARATOR_AUTO,

            UNUM_DECIMAL_SEPARATOR_ALWAYS,

            UNUM_DECIMAL_SEPARATOR_COUNT
} UNumberDecimalMarkDisplay;

U_NAMESPACE_BEGIN namespace number {  // icu::number

// Forward declarations:
class UnlocalizedNumberFormatter;
class LocalizedNumberFormatter;
class FormattedNumber;
class Notation;
class ScientificNotation;
class Rounder;
class FractionRounder;
class CurrencyRounder;
class IncrementRounder;
class Grouper;
class IntegerWidth;

namespace impl {

// Forward declarations:
class Padder;
struct MacroProps;
struct MicroProps;
class DecimalQuantity;
struct NumberFormatterResults;
class NumberFormatterImpl;
struct ParsedPatternInfo;
class ScientificModifier;
class MultiplierProducer;
class MutablePatternModifier;
class LongNameHandler;
class ScientificHandler;
class CompactHandler;
class Modifier;
class NumberStringBuilder;

} // namespace impl

// Reserve extra names in case they are added as classes in the future:
typedef Notation CompactNotation;
typedef Notation SimpleNotation;

class U_I18N_API Notation : public UMemory {
  public:
    static ScientificNotation scientific();

    static ScientificNotation engineering();

    static CompactNotation compactShort();

    static CompactNotation compactLong();

    static SimpleNotation simple();

  private:
    enum NotationType {
        NTN_SCIENTIFIC, NTN_COMPACT, NTN_SIMPLE, NTN_ERROR
    } fType;

    union NotationUnion {
        // For NTN_SCIENTIFIC
        struct ScientificSettings {
            int8_t fEngineeringInterval;
            bool fRequireMinInt;
            int8_t fMinExponentDigits;
            UNumberSignDisplay fExponentSignDisplay;
        } scientific;

        // For NTN_COMPACT
        UNumberCompactStyle compactStyle;

        // For NTN_ERROR
        UErrorCode errorCode;
    } fUnion;

    typedef NotationUnion::ScientificSettings ScientificSettings;

    Notation(const NotationType &type, const NotationUnion &union_) : fType(type), fUnion(union_) {}

    Notation(UErrorCode errorCode) : fType(NTN_ERROR) {
        fUnion.errorCode = errorCode;
    }

    Notation() : fType(NTN_SIMPLE), fUnion() {}

    UBool copyErrorTo(UErrorCode &status) const {
        if (fType == NTN_ERROR) {
            status = fUnion.errorCode;
            return TRUE;
        }
        return FALSE;
    }

    // To allow MacroProps to initialize empty instances:
    friend struct impl::MacroProps;
    friend class ScientificNotation;

    // To allow implementation to access internal types:
    friend class impl::NumberFormatterImpl;
    friend class impl::ScientificModifier;
    friend class impl::ScientificHandler;
};

class U_I18N_API ScientificNotation : public Notation {
  public:
    ScientificNotation withMinExponentDigits(int32_t minExponentDigits) const;

    ScientificNotation withExponentSignDisplay(UNumberSignDisplay exponentSignDisplay) const;

  private:
    // Inherit constructor
    using Notation::Notation;

    friend class Notation;
};

// Reserve extra names in case they are added as classes in the future:
typedef Rounder DigitRounder;

class U_I18N_API Rounder : public UMemory {

  public:
    static Rounder unlimited();

    static FractionRounder integer();

    static FractionRounder fixedFraction(int32_t minMaxFractionPlaces);

    static FractionRounder minFraction(int32_t minFractionPlaces);

    static FractionRounder maxFraction(int32_t maxFractionPlaces);

    static FractionRounder minMaxFraction(int32_t minFractionPlaces, int32_t maxFractionPlaces);

    static DigitRounder fixedDigits(int32_t minMaxSignificantDigits);

    static DigitRounder minDigits(int32_t minSignificantDigits);

    static DigitRounder maxDigits(int32_t maxSignificantDigits);

    static DigitRounder minMaxDigits(int32_t minSignificantDigits, int32_t maxSignificantDigits);

    static IncrementRounder increment(double roundingIncrement);

    static CurrencyRounder currency(UCurrencyUsage currencyUsage);

    Rounder withMode(UNumberFormatRoundingMode roundingMode) const;

  private:
    enum RounderType {
        RND_BOGUS,
        RND_NONE,
        RND_FRACTION,
        RND_SIGNIFICANT,
        RND_FRACTION_SIGNIFICANT,
        RND_INCREMENT,
        RND_CURRENCY,
        RND_PASS_THROUGH,
        RND_ERROR
    } fType;

    union RounderUnion {
        struct FractionSignificantSettings {
            // For RND_FRACTION, RND_SIGNIFICANT, and RND_FRACTION_SIGNIFICANT
            int8_t fMinFrac;
            int8_t fMaxFrac;
            int8_t fMinSig;
            int8_t fMaxSig;
        } fracSig;
        struct IncrementSettings {
            double fIncrement;
            int32_t fMinFrac;
        } increment; // For RND_INCREMENT
        UCurrencyUsage currencyUsage; // For RND_CURRENCY
        UErrorCode errorCode; // For RND_ERROR
    } fUnion;

    typedef RounderUnion::FractionSignificantSettings FractionSignificantSettings;
    typedef RounderUnion::IncrementSettings IncrementSettings;

    UNumberFormatRoundingMode fRoundingMode;

    Rounder(const RounderType &type, const RounderUnion &union_, UNumberFormatRoundingMode roundingMode)
            : fType(type), fUnion(union_), fRoundingMode(roundingMode) {}

    Rounder(UErrorCode errorCode) : fType(RND_ERROR) {
        fUnion.errorCode = errorCode;
    }

    Rounder() : fType(RND_BOGUS) {}

    bool isBogus() const {
        return fType == RND_BOGUS;
    }

    UBool copyErrorTo(UErrorCode &status) const {
        if (fType == RND_ERROR) {
            status = fUnion.errorCode;
            return TRUE;
        }
        return FALSE;
    }

    // On the parent type so that this method can be called internally on Rounder instances.
    Rounder withCurrency(const CurrencyUnit &currency, UErrorCode &status) const;

    void setLocaleData(const CurrencyUnit &currency, UErrorCode &status);

    void apply(impl::DecimalQuantity &value, UErrorCode &status) const;

    void apply(impl::DecimalQuantity &value, int32_t minInt, UErrorCode status);

    int32_t
    chooseMultiplierAndApply(impl::DecimalQuantity &input, const impl::MultiplierProducer &producer,
                             UErrorCode &status);

    static FractionRounder constructFraction(int32_t minFrac, int32_t maxFrac);

    static Rounder constructSignificant(int32_t minSig, int32_t maxSig);

    static Rounder
    constructFractionSignificant(const FractionRounder &base, int32_t minSig, int32_t maxSig);

    static IncrementRounder constructIncrement(double increment, int32_t minFrac);

    static CurrencyRounder constructCurrency(UCurrencyUsage usage);

    static Rounder constructPassThrough();

    // To allow MacroProps/MicroProps to initialize bogus instances:
    friend struct impl::MacroProps;
    friend struct impl::MicroProps;

    // To allow NumberFormatterImpl to access isBogus() and other internal methods:
    friend class impl::NumberFormatterImpl;

    // To give access to apply() and chooseMultiplierAndApply():
    friend class impl::MutablePatternModifier;
    friend class impl::LongNameHandler;
    friend class impl::ScientificHandler;
    friend class impl::CompactHandler;

    // To allow child classes to call private methods:
    friend class FractionRounder;
    friend class CurrencyRounder;
    friend class IncrementRounder;
};

class U_I18N_API FractionRounder : public Rounder {
  public:
    Rounder withMinDigits(int32_t minSignificantDigits) const;

    Rounder withMaxDigits(int32_t maxSignificantDigits) const;

  private:
    // Inherit constructor
    using Rounder::Rounder;

    // To allow parent class to call this class's constructor:
    friend class Rounder;
};

class U_I18N_API CurrencyRounder : public Rounder {
  public:
    Rounder withCurrency(const CurrencyUnit &currency) const;

  private:
    // Inherit constructor
    using Rounder::Rounder;

    // To allow parent class to call this class's constructor:
    friend class Rounder;
};

class U_I18N_API IncrementRounder : public Rounder {
  public:
    Rounder withMinFraction(int32_t minFrac) const;

  private:
    // Inherit constructor
    using Rounder::Rounder;

    // To allow parent class to call this class's constructor:
    friend class Rounder;
};

class U_I18N_API Grouper : public UMemory {
  public:
    static Grouper defaults();

    static Grouper minTwoDigits();

    static Grouper none();

  private:
    int8_t fGrouping1; // -3 means "bogus"; -2 means "needs locale data"; -1 means "no grouping"
    int8_t fGrouping2;
    bool fMin2;

    Grouper(int8_t grouping1, int8_t grouping2, bool min2)
            : fGrouping1(grouping1), fGrouping2(grouping2), fMin2(min2) {}

    Grouper() : fGrouping1(-3) {};

    bool isBogus() const {
        return fGrouping1 == -3;
    }

    void setLocaleData(const impl::ParsedPatternInfo &patternInfo);

    bool groupAtPosition(int32_t position, const impl::DecimalQuantity &value) const;

    // To allow MacroProps/MicroProps to initialize empty instances:
    friend struct impl::MacroProps;
    friend struct impl::MicroProps;

    // To allow NumberFormatterImpl to access isBogus() and perform other operations:
    friend class impl::NumberFormatterImpl;
};

class U_I18N_API IntegerWidth : public UMemory {
  public:
    static IntegerWidth zeroFillTo(int32_t minInt);

    IntegerWidth truncateAt(int32_t maxInt);

  private:
    union {
        struct {
            int8_t fMinInt;
            int8_t fMaxInt;
        } minMaxInt;
        UErrorCode errorCode;
    } fUnion;
    bool fHasError = false;

    IntegerWidth(int8_t minInt, int8_t maxInt);

    IntegerWidth(UErrorCode errorCode) { // NOLINT
        fUnion.errorCode = errorCode;
        fHasError = true;
    }

    IntegerWidth() { // NOLINT
        fUnion.minMaxInt.fMinInt = -1;
    }

    bool isBogus() const {
        return !fHasError && fUnion.minMaxInt.fMinInt == -1;
    }

    UBool copyErrorTo(UErrorCode &status) const {
        if (fHasError) {
            status = fUnion.errorCode;
            return TRUE;
        }
        return FALSE;
    }

    void apply(impl::DecimalQuantity &quantity, UErrorCode &status) const;

    // To allow MacroProps/MicroProps to initialize empty instances:
    friend struct impl::MacroProps;
    friend struct impl::MicroProps;

    // To allow NumberFormatterImpl to access isBogus() and perform other operations:
    friend class impl::NumberFormatterImpl;
};

namespace impl {

static constexpr int32_t DEFAULT_THRESHOLD = 3;

class U_I18N_API SymbolsWrapper : public UMemory {
  public:
    SymbolsWrapper() : fType(SYMPTR_NONE), fPtr{nullptr} {}

    SymbolsWrapper(const SymbolsWrapper &other);

    ~SymbolsWrapper();

    SymbolsWrapper &operator=(const SymbolsWrapper &other);

    void setTo(const DecimalFormatSymbols &dfs);

    void setTo(const NumberingSystem *ns);

    bool isDecimalFormatSymbols() const;

    bool isNumberingSystem() const;

    const DecimalFormatSymbols *getDecimalFormatSymbols() const;

    const NumberingSystem *getNumberingSystem() const;

    UBool copyErrorTo(UErrorCode &status) const {
        if (fType == SYMPTR_DFS && fPtr.dfs == nullptr) {
            status = U_MEMORY_ALLOCATION_ERROR;
            return TRUE;
        } else if (fType == SYMPTR_NS && fPtr.ns == nullptr) {
            status = U_MEMORY_ALLOCATION_ERROR;
            return TRUE;
        }
        return FALSE;
    }

  private:
    enum SymbolsPointerType {
        SYMPTR_NONE, SYMPTR_DFS, SYMPTR_NS
    } fType;

    union {
        const DecimalFormatSymbols *dfs;
        const NumberingSystem *ns;
    } fPtr;

    void doCopyFrom(const SymbolsWrapper &other);

    void doCleanup();
};

class U_I18N_API Padder : public UMemory {
  public:
    static Padder none();

    static Padder codePoints(UChar32 cp, int32_t targetWidth, UNumberFormatPadPosition position);

  private:
    UChar32 fWidth;  // -3 = error; -2 = bogus; -1 = no padding
    union {
        struct {
            int32_t fCp;
            UNumberFormatPadPosition fPosition;
        } padding;
        UErrorCode errorCode;
    } fUnion;

    Padder(UChar32 cp, int32_t width, UNumberFormatPadPosition position);

    Padder(int32_t width);

    Padder(UErrorCode errorCode) : fWidth(-3) { // NOLINT
        fUnion.errorCode = errorCode;
    }

    Padder() : fWidth(-2) {} // NOLINT

    bool isBogus() const {
        return fWidth == -2;
    }

    UBool copyErrorTo(UErrorCode &status) const {
        if (fWidth == -3) {
            status = fUnion.errorCode;
            return TRUE;
        }
        return FALSE;
    }

    bool isValid() const {
        return fWidth > 0;
    }

    int32_t padAndApply(const impl::Modifier &mod1, const impl::Modifier &mod2,
                        impl::NumberStringBuilder &string, int32_t leftIndex, int32_t rightIndex,
                        UErrorCode &status) const;

    // To allow MacroProps/MicroProps to initialize empty instances:
    friend struct MacroProps;
    friend struct MicroProps;

    // To allow NumberFormatterImpl to access isBogus() and perform other operations:
    friend class impl::NumberFormatterImpl;
};

struct U_I18N_API MacroProps : public UMemory {
    Notation notation;

    MeasureUnit unit; // = NoUnit::base();

    Rounder rounder;  // = Rounder();  (bogus)

    Grouper grouper;  // = Grouper();  (bogus)

    Padder padder;    // = Padder();   (bogus)

    IntegerWidth integerWidth; // = IntegerWidth(); (bogus)

    SymbolsWrapper symbols;

    // UNUM_XYZ_COUNT denotes null (bogus) values.

    UNumberUnitWidth unitWidth = UNUM_UNIT_WIDTH_COUNT;

    UNumberSignDisplay sign = UNUM_SIGN_COUNT;

    UNumberDecimalSeparatorDisplay decimal = UNUM_DECIMAL_SEPARATOR_COUNT;

    PluralRules *rules = nullptr;  // no ownership

    int32_t threshold = DEFAULT_THRESHOLD;
    Locale locale;

    bool copyErrorTo(UErrorCode &status) const {
        return notation.copyErrorTo(status) || rounder.copyErrorTo(status) ||
               padder.copyErrorTo(status) || integerWidth.copyErrorTo(status) ||
               symbols.copyErrorTo(status);
    }
};

} // namespace impl

template<typename Derived>
class U_I18N_API NumberFormatterSettings {
  public:
    Derived notation(const Notation &notation) const;

    Derived unit(const icu::MeasureUnit &unit) const;

    Derived adoptUnit(const icu::MeasureUnit *unit) const;

    Derived rounding(const Rounder &rounder) const;

#ifndef U_HIDE_INTERNAL_API

    Derived grouping(const Grouper &grouper) const;

#endif  /* U_HIDE_INTERNAL_API */

    Derived integerWidth(const IntegerWidth &style) const;

    Derived symbols(const DecimalFormatSymbols &symbols) const;

    Derived adoptSymbols(const NumberingSystem *symbols) const;

    Derived unitWidth(const UNumberUnitWidth &width) const;

    Derived sign(const UNumberSignDisplay &width) const;

    Derived decimal(const UNumberDecimalSeparatorDisplay &width) const;

#ifndef U_HIDE_INTERNAL_API

    Derived padding(const impl::Padder &padder) const;

    Derived threshold(int32_t threshold) const;

#endif  /* U_HIDE_INTERNAL_API */

    UBool copyErrorTo(UErrorCode &outErrorCode) const {
        if (U_FAILURE(outErrorCode)) {
            // Do not overwrite the older error code
            return TRUE;
        }
        fMacros.copyErrorTo(outErrorCode);
        return U_FAILURE(outErrorCode);
    }

  protected:
    impl::MacroProps fMacros;

  private:
    // Don't construct me directly!  Use (Un)LocalizedNumberFormatter.
    NumberFormatterSettings() = default;

    friend class LocalizedNumberFormatter;
    friend class UnlocalizedNumberFormatter;
};

class U_I18N_API UnlocalizedNumberFormatter
        : public NumberFormatterSettings<UnlocalizedNumberFormatter>, public UMemory {

  public:
    LocalizedNumberFormatter locale(const icu::Locale &locale) const;

    // Make default copy constructor call the NumberFormatterSettings copy constructor.
    UnlocalizedNumberFormatter(const UnlocalizedNumberFormatter &other) : UnlocalizedNumberFormatter(
            static_cast<const NumberFormatterSettings<UnlocalizedNumberFormatter> &>(other)) {}

  private:
    UnlocalizedNumberFormatter() = default;

    explicit UnlocalizedNumberFormatter(
            const NumberFormatterSettings<UnlocalizedNumberFormatter> &other);

    // To give the fluent setters access to this class's constructor:
    friend class NumberFormatterSettings<UnlocalizedNumberFormatter>;

    // To give NumberFormatter::with() access to this class's constructor:
    friend class NumberFormatter;
};

class U_I18N_API LocalizedNumberFormatter
        : public NumberFormatterSettings<LocalizedNumberFormatter>, public UMemory {
  public:
    FormattedNumber formatInt(int64_t value, UErrorCode &status) const;

    FormattedNumber formatDouble(double value, UErrorCode &status) const;

    FormattedNumber formatDecimal(StringPiece value, UErrorCode &status) const;

    // Make default copy constructor call the NumberFormatterSettings copy constructor.
    LocalizedNumberFormatter(const LocalizedNumberFormatter &other) : LocalizedNumberFormatter(
            static_cast<const NumberFormatterSettings<LocalizedNumberFormatter> &>(other)) {}

    ~LocalizedNumberFormatter();

  private:
    const impl::NumberFormatterImpl* fCompiled {nullptr};
    char fUnsafeCallCount[8] {};  // internally cast to u_atomic_int32_t

    LocalizedNumberFormatter() = default;

    explicit LocalizedNumberFormatter(const NumberFormatterSettings<LocalizedNumberFormatter> &other);

    LocalizedNumberFormatter(const impl::MacroProps &macros, const Locale &locale);

    FormattedNumber formatImpl(impl::NumberFormatterResults *results, UErrorCode &status) const;

    // To give the fluent setters access to this class's constructor:
    friend class NumberFormatterSettings<UnlocalizedNumberFormatter>;
    friend class NumberFormatterSettings<LocalizedNumberFormatter>;

    // To give UnlocalizedNumberFormatter::locale() access to this class's constructor:
    friend class UnlocalizedNumberFormatter;
};

class U_I18N_API FormattedNumber : public UMemory {
  public:
    UnicodeString toString() const;

    Appendable &appendTo(Appendable &appendable);

    void populateFieldPosition(FieldPosition &fieldPosition, UErrorCode &status);

    void populateFieldPositionIterator(FieldPositionIterator &iterator, UErrorCode &status);

    ~FormattedNumber();

  private:
    // Can't use LocalPointer because NumberFormatterResults is forward-declared
    const impl::NumberFormatterResults *fResults;

    // Error code for the terminal methods
    UErrorCode fErrorCode;

    explicit FormattedNumber(impl::NumberFormatterResults *results)
        : fResults(results), fErrorCode(U_ZERO_ERROR) {};

    explicit FormattedNumber(UErrorCode errorCode)
        : fResults(nullptr), fErrorCode(errorCode) {};

    // To give LocalizedNumberFormatter format methods access to this class's constructor:
    friend class LocalizedNumberFormatter;
};

class U_I18N_API NumberFormatter final {
  public:
    static UnlocalizedNumberFormatter with();

    static LocalizedNumberFormatter withLocale(const Locale &locale);

    NumberFormatter() = delete;
};

}  // namespace number
U_NAMESPACE_END

#endif  // U_HIDE_DRAFT_API

#endif // __NUMBERFORMATTER_H__

#endif /* #if !UCONFIG_NO_FORMATTING */

---