jpayne@69: // © 2017 and later: Unicode, Inc. and others. jpayne@69: // License & terms of use: http://www.unicode.org/copyright.html jpayne@69: jpayne@69: #ifndef __NUMBERFORMATTER_H__ jpayne@69: #define __NUMBERFORMATTER_H__ jpayne@69: jpayne@69: #include "unicode/utypes.h" jpayne@69: jpayne@69: #if U_SHOW_CPLUSPLUS_API jpayne@69: jpayne@69: #if !UCONFIG_NO_FORMATTING jpayne@69: jpayne@69: #include "unicode/appendable.h" jpayne@69: #include "unicode/bytestream.h" jpayne@69: #include "unicode/currunit.h" jpayne@69: #include "unicode/dcfmtsym.h" jpayne@69: #include "unicode/fieldpos.h" jpayne@69: #include "unicode/formattedvalue.h" jpayne@69: #include "unicode/fpositer.h" jpayne@69: #include "unicode/measunit.h" jpayne@69: #include "unicode/nounit.h" jpayne@69: #include "unicode/parseerr.h" jpayne@69: #include "unicode/plurrule.h" jpayne@69: #include "unicode/ucurr.h" jpayne@69: #include "unicode/unum.h" jpayne@69: #include "unicode/unumberformatter.h" jpayne@69: #include "unicode/uobject.h" jpayne@69: jpayne@69: /** jpayne@69: * \file jpayne@69: * \brief C++ API: Library for localized number formatting introduced in ICU 60. jpayne@69: * jpayne@69: * This library was introduced in ICU 60 to simplify the process of formatting localized number strings. jpayne@69: * Basic usage examples: jpayne@69: * jpayne@69: * 
jpayne@69:  * // Most basic usage:
jpayne@69:  * NumberFormatter::withLocale(...).format(123).toString();  // 1,234 in en-US
jpayne@69:  *
jpayne@69:  * // Custom notation, unit, and rounding precision:
jpayne@69:  * NumberFormatter::with()
jpayne@69:  *     .notation(Notation::compactShort())
jpayne@69:  *     .unit(CurrencyUnit("EUR", status))
jpayne@69:  *     .precision(Precision::maxDigits(2))
jpayne@69:  *     .locale(...)
jpayne@69:  *     .format(1234)
jpayne@69:  *     .toString();  // €1.2K in en-US
jpayne@69:  *
jpayne@69:  * // Create a formatter in a singleton by value for use later:
jpayne@69:  * static const LocalizedNumberFormatter formatter = NumberFormatter::withLocale(...)
jpayne@69:  *     .unit(NoUnit::percent())
jpayne@69:  *     .precision(Precision::fixedFraction(3));
jpayne@69:  * formatter.format(5.9831).toString();  // 5.983% in en-US
jpayne@69:  *
jpayne@69:  * // Create a "template" in a singleton unique_ptr but without setting a locale until the call site:
jpayne@69:  * std::unique_ptr template = NumberFormatter::with()
jpayne@69:  *     .sign(UNumberSignDisplay::UNUM_SIGN_ALWAYS)
jpayne@69:  *     .unit(MeasureUnit::getMeter())
jpayne@69:  *     .unitWidth(UNumberUnitWidth::UNUM_UNIT_WIDTH_FULL_NAME)
jpayne@69:  *     .clone();
jpayne@69:  * template->locale(...).format(1234).toString();  // +1,234 meters in en-US
jpayne@69:  *
jpayne@69: * jpayne@69: *

jpayne@69: * This API offers more features than DecimalFormat and is geared toward new users of ICU. jpayne@69: * jpayne@69: *

jpayne@69: * NumberFormatter instances (i.e., LocalizedNumberFormatter and UnlocalizedNumberFormatter) jpayne@69: * are immutable and thread safe. This means that invoking a configuration method has no jpayne@69: * effect on the receiving instance; you must store and use the new number formatter instance it returns instead. jpayne@69: * jpayne@69: * 

jpayne@69:  * UnlocalizedNumberFormatter formatter = UnlocalizedNumberFormatter::with().notation(Notation::scientific());
jpayne@69:  * formatter.precision(Precision.maxFraction(2)); // does nothing!
jpayne@69:  * formatter.locale(Locale.getEnglish()).format(9.8765).toString(); // prints "9.8765E0", not "9.88E0"
jpayne@69:  *
jpayne@69: * jpayne@69: *

jpayne@69: * This API is based on the fluent design pattern popularized by libraries such as Google's Guava. For jpayne@69: * extensive details on the design of this API, read the design doc. jpayne@69: * jpayne@69: * @author Shane Carr jpayne@69: */ jpayne@69: jpayne@69: U_NAMESPACE_BEGIN jpayne@69: jpayne@69: // Forward declarations: jpayne@69: class IFixedDecimal; jpayne@69: class FieldPositionIteratorHandler; jpayne@69: class FormattedStringBuilder; jpayne@69: jpayne@69: namespace numparse { jpayne@69: namespace impl { jpayne@69: jpayne@69: // Forward declarations: jpayne@69: class NumberParserImpl; jpayne@69: class MultiplierParseHandler; jpayne@69: jpayne@69: } jpayne@69: } jpayne@69: jpayne@69: namespace number { // icu::number jpayne@69: jpayne@69: // Forward declarations: jpayne@69: class UnlocalizedNumberFormatter; jpayne@69: class LocalizedNumberFormatter; jpayne@69: class FormattedNumber; jpayne@69: class Notation; jpayne@69: class ScientificNotation; jpayne@69: class Precision; jpayne@69: class FractionPrecision; jpayne@69: class CurrencyPrecision; jpayne@69: class IncrementPrecision; jpayne@69: class IntegerWidth; jpayne@69: jpayne@69: namespace impl { jpayne@69: jpayne@69: // can't be #ifndef U_HIDE_INTERNAL_API; referenced throughout this file in public classes jpayne@69: /** jpayne@69: * Datatype for minimum/maximum fraction digits. Must be able to hold kMaxIntFracSig. jpayne@69: * jpayne@69: * @internal jpayne@69: */ jpayne@69: typedef int16_t digits_t; jpayne@69: jpayne@69: // can't be #ifndef U_HIDE_INTERNAL_API; needed for struct initialization jpayne@69: /** jpayne@69: * Use a default threshold of 3. This means that the third time .format() is called, the data structures get built jpayne@69: * using the "safe" code path. The first two calls to .format() will trigger the unsafe code path. jpayne@69: * jpayne@69: * @internal jpayne@69: */ jpayne@69: static constexpr int32_t kInternalDefaultThreshold = 3; jpayne@69: jpayne@69: // Forward declarations: jpayne@69: class Padder; jpayne@69: struct MacroProps; jpayne@69: struct MicroProps; jpayne@69: class DecimalQuantity; jpayne@69: class UFormattedNumberData; jpayne@69: class NumberFormatterImpl; jpayne@69: struct ParsedPatternInfo; jpayne@69: class ScientificModifier; jpayne@69: class MultiplierProducer; jpayne@69: class RoundingImpl; jpayne@69: class ScientificHandler; jpayne@69: class Modifier; jpayne@69: class AffixPatternProvider; jpayne@69: class NumberPropertyMapper; jpayne@69: struct DecimalFormatProperties; jpayne@69: class MultiplierFormatHandler; jpayne@69: class CurrencySymbols; jpayne@69: class GeneratorHelpers; jpayne@69: class DecNum; jpayne@69: class NumberRangeFormatterImpl; jpayne@69: struct RangeMacroProps; jpayne@69: struct UFormattedNumberImpl; jpayne@69: class MutablePatternModifier; jpayne@69: class ImmutablePatternModifier; jpayne@69: jpayne@69: /** jpayne@69: * Used for NumberRangeFormatter and implemented in numrange_fluent.cpp. jpayne@69: * Declared here so it can be friended. jpayne@69: * jpayne@69: * @internal jpayne@69: */ jpayne@69: void touchRangeLocales(impl::RangeMacroProps& macros); jpayne@69: jpayne@69: } // namespace impl jpayne@69: jpayne@69: /** jpayne@69: * Extra name reserved in case it is needed in the future. jpayne@69: * jpayne@69: * @stable ICU 63 jpayne@69: */ jpayne@69: typedef Notation CompactNotation; jpayne@69: jpayne@69: /** jpayne@69: * Extra name reserved in case it is needed in the future. jpayne@69: * jpayne@69: * @stable ICU 63 jpayne@69: */ jpayne@69: typedef Notation SimpleNotation; jpayne@69: jpayne@69: /** jpayne@69: * A class that defines the notation style to be used when formatting numbers in NumberFormatter. jpayne@69: * jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: class U_I18N_API Notation : public UMemory { jpayne@69: public: jpayne@69: /** jpayne@69: * Print the number using scientific notation (also known as scientific form, standard index form, or standard form jpayne@69: * in the UK). The format for scientific notation varies by locale; for example, many Western locales display the jpayne@69: * number in the form "#E0", where the number is displayed with one digit before the decimal separator, zero or more jpayne@69: * digits after the decimal separator, and the corresponding power of 10 displayed after the "E". jpayne@69: * jpayne@69: *

jpayne@69: * Example outputs in en-US when printing 8.765E4 through 8.765E-3: jpayne@69: * jpayne@69: * 

jpayne@69:      * 8.765E4
jpayne@69:      * 8.765E3
jpayne@69:      * 8.765E2
jpayne@69:      * 8.765E1
jpayne@69:      * 8.765E0
jpayne@69:      * 8.765E-1
jpayne@69:      * 8.765E-2
jpayne@69:      * 8.765E-3
jpayne@69:      * 0E0
jpayne@69:      *
jpayne@69: * jpayne@69: * @return A ScientificNotation for chaining or passing to the NumberFormatter notation() setter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: static ScientificNotation scientific(); jpayne@69: jpayne@69: /** jpayne@69: * Print the number using engineering notation, a variant of scientific notation in which the exponent must be jpayne@69: * divisible by 3. jpayne@69: * jpayne@69: *

jpayne@69: * Example outputs in en-US when printing 8.765E4 through 8.765E-3: jpayne@69: * jpayne@69: * 

jpayne@69:      * 87.65E3
jpayne@69:      * 8.765E3
jpayne@69:      * 876.5E0
jpayne@69:      * 87.65E0
jpayne@69:      * 8.765E0
jpayne@69:      * 876.5E-3
jpayne@69:      * 87.65E-3
jpayne@69:      * 8.765E-3
jpayne@69:      * 0E0
jpayne@69:      *
jpayne@69: * jpayne@69: * @return A ScientificNotation for chaining or passing to the NumberFormatter notation() setter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: static ScientificNotation engineering(); jpayne@69: jpayne@69: /** jpayne@69: * Print the number using short-form compact notation. jpayne@69: * jpayne@69: *

jpayne@69: * Compact notation, defined in Unicode Technical Standard #35 Part 3 Section 2.4.1, prints numbers with jpayne@69: * localized prefixes or suffixes corresponding to different powers of ten. Compact notation is similar to jpayne@69: * engineering notation in how it scales numbers. jpayne@69: * jpayne@69: *

jpayne@69: * Compact notation is ideal for displaying large numbers (over ~1000) to humans while at the same time minimizing jpayne@69: * screen real estate. jpayne@69: * jpayne@69: *

jpayne@69: * In short form, the powers of ten are abbreviated. In en-US, the abbreviations are "K" for thousands, "M" jpayne@69: * for millions, "B" for billions, and "T" for trillions. Example outputs in en-US when printing 8.765E7 jpayne@69: * through 8.765E0: jpayne@69: * jpayne@69: * 

jpayne@69:      * 88M
jpayne@69:      * 8.8M
jpayne@69:      * 876K
jpayne@69:      * 88K
jpayne@69:      * 8.8K
jpayne@69:      * 876
jpayne@69:      * 88
jpayne@69:      * 8.8
jpayne@69:      *
jpayne@69: * jpayne@69: *

jpayne@69: * When compact notation is specified without an explicit rounding precision, numbers are rounded off to the closest jpayne@69: * integer after scaling the number by the corresponding power of 10, but with a digit shown after the decimal jpayne@69: * separator if there is only one digit before the decimal separator. The default compact notation rounding precision jpayne@69: * is equivalent to: jpayne@69: * jpayne@69: * 

jpayne@69:      * Precision::integer().withMinDigits(2)
jpayne@69:      *
jpayne@69: * jpayne@69: * @return A CompactNotation for passing to the NumberFormatter notation() setter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: static CompactNotation compactShort(); jpayne@69: jpayne@69: /** jpayne@69: * Print the number using long-form compact notation. For more information on compact notation, see jpayne@69: * {@link #compactShort}. jpayne@69: * jpayne@69: *

jpayne@69: * In long form, the powers of ten are spelled out fully. Example outputs in en-US when printing 8.765E7 jpayne@69: * through 8.765E0: jpayne@69: * jpayne@69: * 

jpayne@69:      * 88 million
jpayne@69:      * 8.8 million
jpayne@69:      * 876 thousand
jpayne@69:      * 88 thousand
jpayne@69:      * 8.8 thousand
jpayne@69:      * 876
jpayne@69:      * 88
jpayne@69:      * 8.8
jpayne@69:      *
jpayne@69: * jpayne@69: * @return A CompactNotation for passing to the NumberFormatter notation() setter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: static CompactNotation compactLong(); jpayne@69: jpayne@69: /** jpayne@69: * Print the number using simple notation without any scaling by powers of ten. This is the default behavior. jpayne@69: * jpayne@69: *

jpayne@69: * Since this is the default behavior, this method needs to be called only when it is necessary to override a jpayne@69: * previous setting. jpayne@69: * jpayne@69: *

jpayne@69: * Example outputs in en-US when printing 8.765E7 through 8.765E0: jpayne@69: * jpayne@69: * 

jpayne@69:      * 87,650,000
jpayne@69:      * 8,765,000
jpayne@69:      * 876,500
jpayne@69:      * 87,650
jpayne@69:      * 8,765
jpayne@69:      * 876.5
jpayne@69:      * 87.65
jpayne@69:      * 8.765
jpayne@69:      *
jpayne@69: * jpayne@69: * @return A SimpleNotation for passing to the NumberFormatter notation() setter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: static SimpleNotation simple(); jpayne@69: jpayne@69: private: jpayne@69: enum NotationType { jpayne@69: NTN_SCIENTIFIC, NTN_COMPACT, NTN_SIMPLE, NTN_ERROR jpayne@69: } fType; jpayne@69: jpayne@69: union NotationUnion { jpayne@69: // For NTN_SCIENTIFIC jpayne@69: /** @internal */ jpayne@69: struct ScientificSettings { jpayne@69: /** @internal */ jpayne@69: int8_t fEngineeringInterval; jpayne@69: /** @internal */ jpayne@69: bool fRequireMinInt; jpayne@69: /** @internal */ jpayne@69: impl::digits_t fMinExponentDigits; jpayne@69: /** @internal */ jpayne@69: UNumberSignDisplay fExponentSignDisplay; jpayne@69: } scientific; jpayne@69: jpayne@69: // For NTN_COMPACT jpayne@69: UNumberCompactStyle compactStyle; jpayne@69: jpayne@69: // For NTN_ERROR jpayne@69: UErrorCode errorCode; jpayne@69: } fUnion; jpayne@69: jpayne@69: typedef NotationUnion::ScientificSettings ScientificSettings; jpayne@69: jpayne@69: Notation(const NotationType &type, const NotationUnion &union_) : fType(type), fUnion(union_) {} jpayne@69: jpayne@69: Notation(UErrorCode errorCode) : fType(NTN_ERROR) { jpayne@69: fUnion.errorCode = errorCode; jpayne@69: } jpayne@69: jpayne@69: Notation() : fType(NTN_SIMPLE), fUnion() {} jpayne@69: jpayne@69: UBool copyErrorTo(UErrorCode &status) const { jpayne@69: if (fType == NTN_ERROR) { jpayne@69: status = fUnion.errorCode; jpayne@69: return TRUE; jpayne@69: } jpayne@69: return FALSE; jpayne@69: } jpayne@69: jpayne@69: // To allow MacroProps to initialize empty instances: jpayne@69: friend struct impl::MacroProps; jpayne@69: friend class ScientificNotation; jpayne@69: jpayne@69: // To allow implementation to access internal types: jpayne@69: friend class impl::NumberFormatterImpl; jpayne@69: friend class impl::ScientificModifier; jpayne@69: friend class impl::ScientificHandler; jpayne@69: jpayne@69: // To allow access to the skeleton generation code: jpayne@69: friend class impl::GeneratorHelpers; jpayne@69: }; jpayne@69: jpayne@69: /** jpayne@69: * A class that defines the scientific notation style to be used when formatting numbers in NumberFormatter. jpayne@69: * jpayne@69: *

jpayne@69: * To create a ScientificNotation, use one of the factory methods in {@link Notation}. jpayne@69: * jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: class U_I18N_API ScientificNotation : public Notation { jpayne@69: public: jpayne@69: /** jpayne@69: * Sets the minimum number of digits to show in the exponent of scientific notation, padding with zeros if jpayne@69: * necessary. Useful for fixed-width display. jpayne@69: * jpayne@69: *

jpayne@69: * For example, with minExponentDigits=2, the number 123 will be printed as "1.23E02" in en-US instead of jpayne@69: * the default "1.23E2". jpayne@69: * jpayne@69: * @param minExponentDigits jpayne@69: * The minimum number of digits to show in the exponent. jpayne@69: * @return A ScientificNotation, for chaining. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: ScientificNotation withMinExponentDigits(int32_t minExponentDigits) const; jpayne@69: jpayne@69: /** jpayne@69: * Sets whether to show the sign on positive and negative exponents in scientific notation. The default is AUTO, jpayne@69: * showing the minus sign but not the plus sign. jpayne@69: * jpayne@69: *

jpayne@69: * For example, with exponentSignDisplay=ALWAYS, the number 123 will be printed as "1.23E+2" in en-US jpayne@69: * instead of the default "1.23E2". jpayne@69: * jpayne@69: * @param exponentSignDisplay jpayne@69: * The strategy for displaying the sign in the exponent. jpayne@69: * @return A ScientificNotation, for chaining. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: ScientificNotation withExponentSignDisplay(UNumberSignDisplay exponentSignDisplay) const; jpayne@69: jpayne@69: private: jpayne@69: // Inherit constructor jpayne@69: using Notation::Notation; jpayne@69: jpayne@69: // Raw constructor for NumberPropertyMapper jpayne@69: ScientificNotation(int8_t fEngineeringInterval, bool fRequireMinInt, impl::digits_t fMinExponentDigits, jpayne@69: UNumberSignDisplay fExponentSignDisplay); jpayne@69: jpayne@69: friend class Notation; jpayne@69: jpayne@69: // So that NumberPropertyMapper can create instances jpayne@69: friend class impl::NumberPropertyMapper; jpayne@69: }; jpayne@69: jpayne@69: /** jpayne@69: * Extra name reserved in case it is needed in the future. jpayne@69: * jpayne@69: * @stable ICU 63 jpayne@69: */ jpayne@69: typedef Precision SignificantDigitsPrecision; jpayne@69: jpayne@69: /** jpayne@69: * A class that defines the rounding precision to be used when formatting numbers in NumberFormatter. jpayne@69: * jpayne@69: *

jpayne@69: * To create a Precision, use one of the factory methods. jpayne@69: * jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: class U_I18N_API Precision : public UMemory { jpayne@69: jpayne@69: public: jpayne@69: /** jpayne@69: * Show all available digits to full precision. jpayne@69: * jpayne@69: *

jpayne@69: * NOTE: When formatting a double, this method, along with {@link #minFraction} and jpayne@69: * {@link #minSignificantDigits}, will trigger complex algorithm similar to Dragon4 to determine the jpayne@69: * low-order digits and the number of digits to display based on the value of the double. jpayne@69: * If the number of fraction places or significant digits can be bounded, consider using {@link #maxFraction} jpayne@69: * or {@link #maxSignificantDigits} instead to maximize performance. jpayne@69: * For more information, read the following blog post. jpayne@69: * jpayne@69: *

jpayne@69: * http://www.serpentine.com/blog/2011/06/29/here-be-dragons-advances-in-problems-you-didnt-even-know-you-had/ jpayne@69: * jpayne@69: * @return A Precision for chaining or passing to the NumberFormatter precision() setter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: static Precision unlimited(); jpayne@69: jpayne@69: /** jpayne@69: * Show numbers rounded if necessary to the nearest integer. jpayne@69: * jpayne@69: * @return A FractionPrecision for chaining or passing to the NumberFormatter precision() setter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: static FractionPrecision integer(); jpayne@69: jpayne@69: /** jpayne@69: * Show numbers rounded if necessary to a certain number of fraction places (numerals after the decimal separator). jpayne@69: * Additionally, pad with zeros to ensure that this number of places are always shown. jpayne@69: * jpayne@69: *

jpayne@69: * Example output with minMaxFractionPlaces = 3: jpayne@69: * jpayne@69: *

jpayne@69: * 87,650.000
jpayne@69: * 8,765.000
jpayne@69: * 876.500
jpayne@69: * 87.650
jpayne@69: * 8.765
jpayne@69: * 0.876
jpayne@69: * 0.088
jpayne@69: * 0.009
jpayne@69: * 0.000 (zero) jpayne@69: * jpayne@69: *

jpayne@69: * This method is equivalent to {@link #minMaxFraction} with both arguments equal. jpayne@69: * jpayne@69: * @param minMaxFractionPlaces jpayne@69: * The minimum and maximum number of numerals to display after the decimal separator (rounding if too jpayne@69: * long or padding with zeros if too short). jpayne@69: * @return A FractionPrecision for chaining or passing to the NumberFormatter precision() setter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: static FractionPrecision fixedFraction(int32_t minMaxFractionPlaces); jpayne@69: jpayne@69: /** jpayne@69: * Always show at least a certain number of fraction places after the decimal separator, padding with zeros if jpayne@69: * necessary. Do not perform rounding (display numbers to their full precision). jpayne@69: * jpayne@69: *

jpayne@69: * NOTE: If you are formatting doubles, see the performance note in {@link #unlimited}. jpayne@69: * jpayne@69: * @param minFractionPlaces jpayne@69: * The minimum number of numerals to display after the decimal separator (padding with zeros if jpayne@69: * necessary). jpayne@69: * @return A FractionPrecision for chaining or passing to the NumberFormatter precision() setter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: static FractionPrecision minFraction(int32_t minFractionPlaces); jpayne@69: jpayne@69: /** jpayne@69: * Show numbers rounded if necessary to a certain number of fraction places (numerals after the decimal separator). jpayne@69: * Unlike the other fraction rounding strategies, this strategy does not pad zeros to the end of the jpayne@69: * number. jpayne@69: * jpayne@69: * @param maxFractionPlaces jpayne@69: * The maximum number of numerals to display after the decimal mark (rounding if necessary). jpayne@69: * @return A FractionPrecision for chaining or passing to the NumberFormatter precision() setter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: static FractionPrecision maxFraction(int32_t maxFractionPlaces); jpayne@69: jpayne@69: /** jpayne@69: * Show numbers rounded if necessary to a certain number of fraction places (numerals after the decimal separator); jpayne@69: * in addition, always show at least a certain number of places after the decimal separator, padding with zeros if jpayne@69: * necessary. jpayne@69: * jpayne@69: * @param minFractionPlaces jpayne@69: * The minimum number of numerals to display after the decimal separator (padding with zeros if jpayne@69: * necessary). jpayne@69: * @param maxFractionPlaces jpayne@69: * The maximum number of numerals to display after the decimal separator (rounding if necessary). jpayne@69: * @return A FractionPrecision for chaining or passing to the NumberFormatter precision() setter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: static FractionPrecision minMaxFraction(int32_t minFractionPlaces, int32_t maxFractionPlaces); jpayne@69: jpayne@69: /** jpayne@69: * Show numbers rounded if necessary to a certain number of significant digits or significant figures. Additionally, jpayne@69: * pad with zeros to ensure that this number of significant digits/figures are always shown. jpayne@69: * jpayne@69: *

jpayne@69: * This method is equivalent to {@link #minMaxSignificantDigits} with both arguments equal. jpayne@69: * jpayne@69: * @param minMaxSignificantDigits jpayne@69: * The minimum and maximum number of significant digits to display (rounding if too long or padding with jpayne@69: * zeros if too short). jpayne@69: * @return A precision for chaining or passing to the NumberFormatter precision() setter. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: static SignificantDigitsPrecision fixedSignificantDigits(int32_t minMaxSignificantDigits); jpayne@69: jpayne@69: /** jpayne@69: * Always show at least a certain number of significant digits/figures, padding with zeros if necessary. Do not jpayne@69: * perform rounding (display numbers to their full precision). jpayne@69: * jpayne@69: *

jpayne@69: * NOTE: If you are formatting doubles, see the performance note in {@link #unlimited}. jpayne@69: * jpayne@69: * @param minSignificantDigits jpayne@69: * The minimum number of significant digits to display (padding with zeros if too short). jpayne@69: * @return A precision for chaining or passing to the NumberFormatter precision() setter. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: static SignificantDigitsPrecision minSignificantDigits(int32_t minSignificantDigits); jpayne@69: jpayne@69: /** jpayne@69: * Show numbers rounded if necessary to a certain number of significant digits/figures. jpayne@69: * jpayne@69: * @param maxSignificantDigits jpayne@69: * The maximum number of significant digits to display (rounding if too long). jpayne@69: * @return A precision for chaining or passing to the NumberFormatter precision() setter. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: static SignificantDigitsPrecision maxSignificantDigits(int32_t maxSignificantDigits); jpayne@69: jpayne@69: /** jpayne@69: * Show numbers rounded if necessary to a certain number of significant digits/figures; in addition, always show at jpayne@69: * least a certain number of significant digits, padding with zeros if necessary. jpayne@69: * jpayne@69: * @param minSignificantDigits jpayne@69: * The minimum number of significant digits to display (padding with zeros if necessary). jpayne@69: * @param maxSignificantDigits jpayne@69: * The maximum number of significant digits to display (rounding if necessary). jpayne@69: * @return A precision for chaining or passing to the NumberFormatter precision() setter. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: static SignificantDigitsPrecision minMaxSignificantDigits(int32_t minSignificantDigits, jpayne@69: int32_t maxSignificantDigits); jpayne@69: jpayne@69: /** jpayne@69: * Show numbers rounded if necessary to the closest multiple of a certain rounding increment. For example, if the jpayne@69: * rounding increment is 0.5, then round 1.2 to 1 and round 1.3 to 1.5. jpayne@69: * jpayne@69: *

jpayne@69: * In order to ensure that numbers are padded to the appropriate number of fraction places, call jpayne@69: * withMinFraction() on the return value of this method. jpayne@69: * For example, to round to the nearest 0.5 and always display 2 numerals after the jpayne@69: * decimal separator (to display 1.2 as "1.00" and 1.3 as "1.50"), you can run: jpayne@69: * jpayne@69: * 

jpayne@69:      * Precision::increment(0.5).withMinFraction(2)
jpayne@69:      *
jpayne@69: * jpayne@69: * @param roundingIncrement jpayne@69: * The increment to which to round numbers. jpayne@69: * @return A precision for chaining or passing to the NumberFormatter precision() setter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: static IncrementPrecision increment(double roundingIncrement); jpayne@69: jpayne@69: /** jpayne@69: * Show numbers rounded and padded according to the rules for the currency unit. The most common jpayne@69: * rounding precision settings for currencies include Precision::fixedFraction(2), jpayne@69: * Precision::integer(), and Precision::increment(0.05) for cash transactions jpayne@69: * ("nickel rounding"). jpayne@69: * jpayne@69: *

jpayne@69: * The exact rounding details will be resolved at runtime based on the currency unit specified in the jpayne@69: * NumberFormatter chain. To round according to the rules for one currency while displaying the symbol for another jpayne@69: * currency, the withCurrency() method can be called on the return value of this method. jpayne@69: * jpayne@69: * @param currencyUsage jpayne@69: * Either STANDARD (for digital transactions) or CASH (for transactions where the rounding increment may jpayne@69: * be limited by the available denominations of cash or coins). jpayne@69: * @return A CurrencyPrecision for chaining or passing to the NumberFormatter precision() setter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: static CurrencyPrecision currency(UCurrencyUsage currencyUsage); jpayne@69: jpayne@69: private: jpayne@69: enum PrecisionType { jpayne@69: RND_BOGUS, jpayne@69: RND_NONE, jpayne@69: RND_FRACTION, jpayne@69: RND_SIGNIFICANT, jpayne@69: RND_FRACTION_SIGNIFICANT, jpayne@69: jpayne@69: // Used for strange increments like 3.14. jpayne@69: RND_INCREMENT, jpayne@69: jpayne@69: // Used for increments with 1 as the only digit. This is different than fraction jpayne@69: // rounding because it supports having additional trailing zeros. For example, this jpayne@69: // class is used to round with the increment 0.010. jpayne@69: RND_INCREMENT_ONE, jpayne@69: jpayne@69: // Used for increments with 5 as the only digit (nickel rounding). jpayne@69: RND_INCREMENT_FIVE, jpayne@69: jpayne@69: RND_CURRENCY, jpayne@69: RND_ERROR jpayne@69: } fType; jpayne@69: jpayne@69: union PrecisionUnion { jpayne@69: /** @internal */ jpayne@69: struct FractionSignificantSettings { jpayne@69: // For RND_FRACTION, RND_SIGNIFICANT, and RND_FRACTION_SIGNIFICANT jpayne@69: /** @internal */ jpayne@69: impl::digits_t fMinFrac; jpayne@69: /** @internal */ jpayne@69: impl::digits_t fMaxFrac; jpayne@69: /** @internal */ jpayne@69: impl::digits_t fMinSig; jpayne@69: /** @internal */ jpayne@69: impl::digits_t fMaxSig; jpayne@69: } fracSig; jpayne@69: /** @internal */ jpayne@69: struct IncrementSettings { jpayne@69: // For RND_INCREMENT, RND_INCREMENT_ONE, and RND_INCREMENT_FIVE jpayne@69: /** @internal */ jpayne@69: double fIncrement; jpayne@69: /** @internal */ jpayne@69: impl::digits_t fMinFrac; jpayne@69: /** @internal */ jpayne@69: impl::digits_t fMaxFrac; jpayne@69: } increment; jpayne@69: UCurrencyUsage currencyUsage; // For RND_CURRENCY jpayne@69: UErrorCode errorCode; // For RND_ERROR jpayne@69: } fUnion; jpayne@69: jpayne@69: typedef PrecisionUnion::FractionSignificantSettings FractionSignificantSettings; jpayne@69: typedef PrecisionUnion::IncrementSettings IncrementSettings; jpayne@69: jpayne@69: /** The Precision encapsulates the RoundingMode when used within the implementation. */ jpayne@69: UNumberFormatRoundingMode fRoundingMode; jpayne@69: jpayne@69: Precision(const PrecisionType& type, const PrecisionUnion& union_, jpayne@69: UNumberFormatRoundingMode roundingMode) jpayne@69: : fType(type), fUnion(union_), fRoundingMode(roundingMode) {} jpayne@69: jpayne@69: Precision(UErrorCode errorCode) : fType(RND_ERROR) { jpayne@69: fUnion.errorCode = errorCode; jpayne@69: } jpayne@69: jpayne@69: Precision() : fType(RND_BOGUS) {} jpayne@69: jpayne@69: bool isBogus() const { jpayne@69: return fType == RND_BOGUS; jpayne@69: } jpayne@69: jpayne@69: UBool copyErrorTo(UErrorCode &status) const { jpayne@69: if (fType == RND_ERROR) { jpayne@69: status = fUnion.errorCode; jpayne@69: return TRUE; jpayne@69: } jpayne@69: return FALSE; jpayne@69: } jpayne@69: jpayne@69: // On the parent type so that this method can be called internally on Precision instances. jpayne@69: Precision withCurrency(const CurrencyUnit ¤cy, UErrorCode &status) const; jpayne@69: jpayne@69: static FractionPrecision constructFraction(int32_t minFrac, int32_t maxFrac); jpayne@69: jpayne@69: static Precision constructSignificant(int32_t minSig, int32_t maxSig); jpayne@69: jpayne@69: static Precision jpayne@69: constructFractionSignificant(const FractionPrecision &base, int32_t minSig, int32_t maxSig); jpayne@69: jpayne@69: static IncrementPrecision constructIncrement(double increment, int32_t minFrac); jpayne@69: jpayne@69: static CurrencyPrecision constructCurrency(UCurrencyUsage usage); jpayne@69: jpayne@69: static Precision constructPassThrough(); jpayne@69: jpayne@69: // To allow MacroProps/MicroProps to initialize bogus instances: jpayne@69: friend struct impl::MacroProps; jpayne@69: friend struct impl::MicroProps; jpayne@69: jpayne@69: // To allow NumberFormatterImpl to access isBogus() and other internal methods: jpayne@69: friend class impl::NumberFormatterImpl; jpayne@69: jpayne@69: // To allow NumberPropertyMapper to create instances from DecimalFormatProperties: jpayne@69: friend class impl::NumberPropertyMapper; jpayne@69: jpayne@69: // To allow access to the main implementation class: jpayne@69: friend class impl::RoundingImpl; jpayne@69: jpayne@69: // To allow child classes to call private methods: jpayne@69: friend class FractionPrecision; jpayne@69: friend class CurrencyPrecision; jpayne@69: friend class IncrementPrecision; jpayne@69: jpayne@69: // To allow access to the skeleton generation code: jpayne@69: friend class impl::GeneratorHelpers; jpayne@69: }; jpayne@69: jpayne@69: /** jpayne@69: * A class that defines a rounding precision based on a number of fraction places and optionally significant digits to be jpayne@69: * used when formatting numbers in NumberFormatter. jpayne@69: * jpayne@69: *

jpayne@69: * To create a FractionPrecision, use one of the factory methods on Precision. jpayne@69: * jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: class U_I18N_API FractionPrecision : public Precision { jpayne@69: public: jpayne@69: /** jpayne@69: * Ensure that no less than this number of significant digits are retained when rounding according to fraction jpayne@69: * rules. jpayne@69: * jpayne@69: *

jpayne@69: * For example, with integer rounding, the number 3.141 becomes "3". However, with minimum figures set to 2, 3.141 jpayne@69: * becomes "3.1" instead. jpayne@69: * jpayne@69: *

jpayne@69: * This setting does not affect the number of trailing zeros. For example, 3.01 would print as "3", not "3.0". jpayne@69: * jpayne@69: * @param minSignificantDigits jpayne@69: * The number of significant figures to guarantee. jpayne@69: * @return A precision for chaining or passing to the NumberFormatter precision() setter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: Precision withMinDigits(int32_t minSignificantDigits) const; jpayne@69: jpayne@69: /** jpayne@69: * Ensure that no more than this number of significant digits are retained when rounding according to fraction jpayne@69: * rules. jpayne@69: * jpayne@69: *

jpayne@69: * For example, with integer rounding, the number 123.4 becomes "123". However, with maximum figures set to 2, 123.4 jpayne@69: * becomes "120" instead. jpayne@69: * jpayne@69: *

jpayne@69: * This setting does not affect the number of trailing zeros. For example, with fixed fraction of 2, 123.4 would jpayne@69: * become "120.00". jpayne@69: * jpayne@69: * @param maxSignificantDigits jpayne@69: * Round the number to no more than this number of significant figures. jpayne@69: * @return A precision for chaining or passing to the NumberFormatter precision() setter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: Precision withMaxDigits(int32_t maxSignificantDigits) const; jpayne@69: jpayne@69: private: jpayne@69: // Inherit constructor jpayne@69: using Precision::Precision; jpayne@69: jpayne@69: // To allow parent class to call this class's constructor: jpayne@69: friend class Precision; jpayne@69: }; jpayne@69: jpayne@69: /** jpayne@69: * A class that defines a rounding precision parameterized by a currency to be used when formatting numbers in jpayne@69: * NumberFormatter. jpayne@69: * jpayne@69: *

jpayne@69: * To create a CurrencyPrecision, use one of the factory methods on Precision. jpayne@69: * jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: class U_I18N_API CurrencyPrecision : public Precision { jpayne@69: public: jpayne@69: /** jpayne@69: * Associates a currency with this rounding precision. jpayne@69: * jpayne@69: *

jpayne@69: * Calling this method is not required, because the currency specified in unit() jpayne@69: * is automatically applied to currency rounding precisions. However, jpayne@69: * this method enables you to override that automatic association. jpayne@69: * jpayne@69: *

jpayne@69: * This method also enables numbers to be formatted using currency rounding rules without explicitly using a jpayne@69: * currency format. jpayne@69: * jpayne@69: * @param currency jpayne@69: * The currency to associate with this rounding precision. jpayne@69: * @return A precision for chaining or passing to the NumberFormatter precision() setter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: Precision withCurrency(const CurrencyUnit ¤cy) const; jpayne@69: jpayne@69: private: jpayne@69: // Inherit constructor jpayne@69: using Precision::Precision; jpayne@69: jpayne@69: // To allow parent class to call this class's constructor: jpayne@69: friend class Precision; jpayne@69: }; jpayne@69: jpayne@69: /** jpayne@69: * A class that defines a rounding precision parameterized by a rounding increment to be used when formatting numbers in jpayne@69: * NumberFormatter. jpayne@69: * jpayne@69: *

jpayne@69: * To create an IncrementPrecision, use one of the factory methods on Precision. jpayne@69: * jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: class U_I18N_API IncrementPrecision : public Precision { jpayne@69: public: jpayne@69: /** jpayne@69: * Specifies the minimum number of fraction digits to render after the decimal separator, padding with zeros if jpayne@69: * necessary. By default, no trailing zeros are added. jpayne@69: * jpayne@69: *

jpayne@69: * For example, if the rounding increment is 0.5 and minFrac is 2, then the resulting strings include "0.00", jpayne@69: * "0.50", "1.00", and "1.50". jpayne@69: * jpayne@69: *

jpayne@69: * Note: In ICU4J, this functionality is accomplished via the scale of the BigDecimal rounding increment. jpayne@69: * jpayne@69: * @param minFrac The minimum number of digits after the decimal separator. jpayne@69: * @return A precision for chaining or passing to the NumberFormatter precision() setter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: Precision withMinFraction(int32_t minFrac) const; jpayne@69: jpayne@69: private: jpayne@69: // Inherit constructor jpayne@69: using Precision::Precision; jpayne@69: jpayne@69: // To allow parent class to call this class's constructor: jpayne@69: friend class Precision; jpayne@69: }; jpayne@69: jpayne@69: /** jpayne@69: * A class that defines the strategy for padding and truncating integers before the decimal separator. jpayne@69: * jpayne@69: *

jpayne@69: * To create an IntegerWidth, use one of the factory methods. jpayne@69: * jpayne@69: * @stable ICU 60 jpayne@69: * @see NumberFormatter jpayne@69: */ jpayne@69: class U_I18N_API IntegerWidth : public UMemory { jpayne@69: public: jpayne@69: /** jpayne@69: * Pad numbers at the beginning with zeros to guarantee a certain number of numerals before the decimal separator. jpayne@69: * jpayne@69: *

jpayne@69: * For example, with minInt=3, the number 55 will get printed as "055". jpayne@69: * jpayne@69: * @param minInt jpayne@69: * The minimum number of places before the decimal separator. jpayne@69: * @return An IntegerWidth for chaining or passing to the NumberFormatter integerWidth() setter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: static IntegerWidth zeroFillTo(int32_t minInt); jpayne@69: jpayne@69: /** jpayne@69: * Truncate numbers exceeding a certain number of numerals before the decimal separator. jpayne@69: * jpayne@69: * For example, with maxInt=3, the number 1234 will get printed as "234". jpayne@69: * jpayne@69: * @param maxInt jpayne@69: * The maximum number of places before the decimal separator. maxInt == -1 means no jpayne@69: * truncation. jpayne@69: * @return An IntegerWidth for passing to the NumberFormatter integerWidth() setter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: IntegerWidth truncateAt(int32_t maxInt); jpayne@69: jpayne@69: private: jpayne@69: union { jpayne@69: struct { jpayne@69: impl::digits_t fMinInt; jpayne@69: impl::digits_t fMaxInt; jpayne@69: bool fFormatFailIfMoreThanMaxDigits; jpayne@69: } minMaxInt; jpayne@69: UErrorCode errorCode; jpayne@69: } fUnion; jpayne@69: bool fHasError = false; jpayne@69: jpayne@69: IntegerWidth(impl::digits_t minInt, impl::digits_t maxInt, bool formatFailIfMoreThanMaxDigits); jpayne@69: jpayne@69: IntegerWidth(UErrorCode errorCode) { // NOLINT jpayne@69: fUnion.errorCode = errorCode; jpayne@69: fHasError = true; jpayne@69: } jpayne@69: jpayne@69: IntegerWidth() { // NOLINT jpayne@69: fUnion.minMaxInt.fMinInt = -1; jpayne@69: } jpayne@69: jpayne@69: /** Returns the default instance. */ jpayne@69: static IntegerWidth standard() { jpayne@69: return IntegerWidth::zeroFillTo(1); jpayne@69: } jpayne@69: jpayne@69: bool isBogus() const { jpayne@69: return !fHasError && fUnion.minMaxInt.fMinInt == -1; jpayne@69: } jpayne@69: jpayne@69: UBool copyErrorTo(UErrorCode &status) const { jpayne@69: if (fHasError) { jpayne@69: status = fUnion.errorCode; jpayne@69: return TRUE; jpayne@69: } jpayne@69: return FALSE; jpayne@69: } jpayne@69: jpayne@69: void apply(impl::DecimalQuantity &quantity, UErrorCode &status) const; jpayne@69: jpayne@69: bool operator==(const IntegerWidth& other) const; jpayne@69: jpayne@69: // To allow MacroProps/MicroProps to initialize empty instances: jpayne@69: friend struct impl::MacroProps; jpayne@69: friend struct impl::MicroProps; jpayne@69: jpayne@69: // To allow NumberFormatterImpl to access isBogus(): jpayne@69: friend class impl::NumberFormatterImpl; jpayne@69: jpayne@69: // To allow the use of this class when formatting: jpayne@69: friend class impl::MutablePatternModifier; jpayne@69: friend class impl::ImmutablePatternModifier; jpayne@69: jpayne@69: // So that NumberPropertyMapper can create instances jpayne@69: friend class impl::NumberPropertyMapper; jpayne@69: jpayne@69: // To allow access to the skeleton generation code: jpayne@69: friend class impl::GeneratorHelpers; jpayne@69: }; jpayne@69: jpayne@69: /** jpayne@69: * A class that defines a quantity by which a number should be multiplied when formatting. jpayne@69: * jpayne@69: *

jpayne@69: * To create a Scale, use one of the factory methods. jpayne@69: * jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: class U_I18N_API Scale : public UMemory { jpayne@69: public: jpayne@69: /** jpayne@69: * Do not change the value of numbers when formatting or parsing. jpayne@69: * jpayne@69: * @return A Scale to prevent any multiplication. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: static Scale none(); jpayne@69: jpayne@69: /** jpayne@69: * Multiply numbers by a power of ten before formatting. Useful for combining with a percent unit: jpayne@69: * jpayne@69: * 

jpayne@69:      * NumberFormatter::with().unit(NoUnit::percent()).multiplier(Scale::powerOfTen(2))
jpayne@69:      *
jpayne@69: * jpayne@69: * @return A Scale for passing to the setter in NumberFormatter. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: static Scale powerOfTen(int32_t power); jpayne@69: jpayne@69: /** jpayne@69: * Multiply numbers by an arbitrary value before formatting. Useful for unit conversions. jpayne@69: * jpayne@69: * This method takes a string in a decimal number format with syntax jpayne@69: * as defined in the Decimal Arithmetic Specification, available at jpayne@69: * http://speleotrove.com/decimal jpayne@69: * jpayne@69: * Also see the version of this method that takes a double. jpayne@69: * jpayne@69: * @return A Scale for passing to the setter in NumberFormatter. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: static Scale byDecimal(StringPiece multiplicand); jpayne@69: jpayne@69: /** jpayne@69: * Multiply numbers by an arbitrary value before formatting. Useful for unit conversions. jpayne@69: * jpayne@69: * This method takes a double; also see the version of this method that takes an exact decimal. jpayne@69: * jpayne@69: * @return A Scale for passing to the setter in NumberFormatter. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: static Scale byDouble(double multiplicand); jpayne@69: jpayne@69: /** jpayne@69: * Multiply a number by both a power of ten and by an arbitrary double value. jpayne@69: * jpayne@69: * @return A Scale for passing to the setter in NumberFormatter. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: static Scale byDoubleAndPowerOfTen(double multiplicand, int32_t power); jpayne@69: jpayne@69: // We need a custom destructor for the DecNum, which means we need to declare jpayne@69: // the copy/move constructor/assignment quartet. jpayne@69: jpayne@69: /** @stable ICU 62 */ jpayne@69: Scale(const Scale& other); jpayne@69: jpayne@69: /** @stable ICU 62 */ jpayne@69: Scale& operator=(const Scale& other); jpayne@69: jpayne@69: /** @stable ICU 62 */ jpayne@69: Scale(Scale&& src) U_NOEXCEPT; jpayne@69: jpayne@69: /** @stable ICU 62 */ jpayne@69: Scale& operator=(Scale&& src) U_NOEXCEPT; jpayne@69: jpayne@69: /** @stable ICU 62 */ jpayne@69: ~Scale(); jpayne@69: jpayne@69: #ifndef U_HIDE_INTERNAL_API jpayne@69: /** @internal */ jpayne@69: Scale(int32_t magnitude, impl::DecNum* arbitraryToAdopt); jpayne@69: #endif /* U_HIDE_INTERNAL_API */ jpayne@69: jpayne@69: private: jpayne@69: int32_t fMagnitude; jpayne@69: impl::DecNum* fArbitrary; jpayne@69: UErrorCode fError; jpayne@69: jpayne@69: Scale(UErrorCode error) : fMagnitude(0), fArbitrary(nullptr), fError(error) {} jpayne@69: jpayne@69: Scale() : fMagnitude(0), fArbitrary(nullptr), fError(U_ZERO_ERROR) {} jpayne@69: jpayne@69: bool isValid() const { jpayne@69: return fMagnitude != 0 || fArbitrary != nullptr; jpayne@69: } jpayne@69: jpayne@69: UBool copyErrorTo(UErrorCode &status) const { jpayne@69: if (fError != U_ZERO_ERROR) { jpayne@69: status = fError; jpayne@69: return TRUE; jpayne@69: } jpayne@69: return FALSE; jpayne@69: } jpayne@69: jpayne@69: void applyTo(impl::DecimalQuantity& quantity) const; jpayne@69: jpayne@69: void applyReciprocalTo(impl::DecimalQuantity& quantity) const; jpayne@69: jpayne@69: // To allow MacroProps/MicroProps to initialize empty instances: jpayne@69: friend struct impl::MacroProps; jpayne@69: friend struct impl::MicroProps; jpayne@69: jpayne@69: // To allow NumberFormatterImpl to access isBogus() and perform other operations: jpayne@69: friend class impl::NumberFormatterImpl; jpayne@69: jpayne@69: // To allow the helper class MultiplierFormatHandler access to private fields: jpayne@69: friend class impl::MultiplierFormatHandler; jpayne@69: jpayne@69: // To allow access to the skeleton generation code: jpayne@69: friend class impl::GeneratorHelpers; jpayne@69: jpayne@69: // To allow access to parsing code: jpayne@69: friend class ::icu::numparse::impl::NumberParserImpl; jpayne@69: friend class ::icu::numparse::impl::MultiplierParseHandler; jpayne@69: }; jpayne@69: jpayne@69: namespace impl { jpayne@69: jpayne@69: // Do not enclose entire SymbolsWrapper with #ifndef U_HIDE_INTERNAL_API, needed for a protected field jpayne@69: /** @internal */ jpayne@69: class U_I18N_API SymbolsWrapper : public UMemory { jpayne@69: public: jpayne@69: /** @internal */ jpayne@69: SymbolsWrapper() : fType(SYMPTR_NONE), fPtr{nullptr} {} jpayne@69: jpayne@69: /** @internal */ jpayne@69: SymbolsWrapper(const SymbolsWrapper &other); jpayne@69: jpayne@69: /** @internal */ jpayne@69: SymbolsWrapper &operator=(const SymbolsWrapper &other); jpayne@69: jpayne@69: /** @internal */ jpayne@69: SymbolsWrapper(SymbolsWrapper&& src) U_NOEXCEPT; jpayne@69: jpayne@69: /** @internal */ jpayne@69: SymbolsWrapper &operator=(SymbolsWrapper&& src) U_NOEXCEPT; jpayne@69: jpayne@69: /** @internal */ jpayne@69: ~SymbolsWrapper(); jpayne@69: jpayne@69: #ifndef U_HIDE_INTERNAL_API jpayne@69: jpayne@69: /** jpayne@69: * The provided object is copied, but we do not adopt it. jpayne@69: * @internal jpayne@69: */ jpayne@69: void setTo(const DecimalFormatSymbols &dfs); jpayne@69: jpayne@69: /** jpayne@69: * Adopt the provided object. jpayne@69: * @internal jpayne@69: */ jpayne@69: void setTo(const NumberingSystem *ns); jpayne@69: jpayne@69: /** jpayne@69: * Whether the object is currently holding a DecimalFormatSymbols. jpayne@69: * @internal jpayne@69: */ jpayne@69: bool isDecimalFormatSymbols() const; jpayne@69: jpayne@69: /** jpayne@69: * Whether the object is currently holding a NumberingSystem. jpayne@69: * @internal jpayne@69: */ jpayne@69: bool isNumberingSystem() const; jpayne@69: jpayne@69: /** jpayne@69: * Get the DecimalFormatSymbols pointer. No ownership change. jpayne@69: * @internal jpayne@69: */ jpayne@69: const DecimalFormatSymbols *getDecimalFormatSymbols() const; jpayne@69: jpayne@69: /** jpayne@69: * Get the NumberingSystem pointer. No ownership change. jpayne@69: * @internal jpayne@69: */ jpayne@69: const NumberingSystem *getNumberingSystem() const; jpayne@69: jpayne@69: #endif // U_HIDE_INTERNAL_API jpayne@69: jpayne@69: /** @internal */ jpayne@69: UBool copyErrorTo(UErrorCode &status) const { jpayne@69: if (fType == SYMPTR_DFS && fPtr.dfs == nullptr) { jpayne@69: status = U_MEMORY_ALLOCATION_ERROR; jpayne@69: return TRUE; jpayne@69: } else if (fType == SYMPTR_NS && fPtr.ns == nullptr) { jpayne@69: status = U_MEMORY_ALLOCATION_ERROR; jpayne@69: return TRUE; jpayne@69: } jpayne@69: return FALSE; jpayne@69: } jpayne@69: jpayne@69: private: jpayne@69: enum SymbolsPointerType { jpayne@69: SYMPTR_NONE, SYMPTR_DFS, SYMPTR_NS jpayne@69: } fType; jpayne@69: jpayne@69: union { jpayne@69: const DecimalFormatSymbols *dfs; jpayne@69: const NumberingSystem *ns; jpayne@69: } fPtr; jpayne@69: jpayne@69: void doCopyFrom(const SymbolsWrapper &other); jpayne@69: jpayne@69: void doMoveFrom(SymbolsWrapper&& src); jpayne@69: jpayne@69: void doCleanup(); jpayne@69: }; jpayne@69: jpayne@69: // Do not enclose entire Grouper with #ifndef U_HIDE_INTERNAL_API, needed for a protected field jpayne@69: /** @internal */ jpayne@69: class U_I18N_API Grouper : public UMemory { jpayne@69: public: jpayne@69: #ifndef U_HIDE_INTERNAL_API jpayne@69: /** @internal */ jpayne@69: static Grouper forStrategy(UNumberGroupingStrategy grouping); jpayne@69: jpayne@69: /** jpayne@69: * Resolve the values in Properties to a Grouper object. jpayne@69: * @internal jpayne@69: */ jpayne@69: static Grouper forProperties(const DecimalFormatProperties& properties); jpayne@69: jpayne@69: // Future: static Grouper forProperties(DecimalFormatProperties& properties); jpayne@69: jpayne@69: /** @internal */ jpayne@69: Grouper(int16_t grouping1, int16_t grouping2, int16_t minGrouping, UNumberGroupingStrategy strategy) jpayne@69: : fGrouping1(grouping1), jpayne@69: fGrouping2(grouping2), jpayne@69: fMinGrouping(minGrouping), jpayne@69: fStrategy(strategy) {} jpayne@69: #endif // U_HIDE_INTERNAL_API jpayne@69: jpayne@69: /** @internal */ jpayne@69: int16_t getPrimary() const; jpayne@69: jpayne@69: /** @internal */ jpayne@69: int16_t getSecondary() const; jpayne@69: jpayne@69: private: jpayne@69: /** jpayne@69: * The grouping sizes, with the following special values: jpayne@69: * jpayne@69: */ jpayne@69: int16_t fGrouping1; jpayne@69: int16_t fGrouping2; jpayne@69: jpayne@69: /** jpayne@69: * The minimum grouping size, with the following special values: jpayne@69: * jpayne@69: */ jpayne@69: int16_t fMinGrouping; jpayne@69: jpayne@69: /** jpayne@69: * The UNumberGroupingStrategy that was used to create this Grouper, or UNUM_GROUPING_COUNT if this jpayne@69: * was not created from a UNumberGroupingStrategy. jpayne@69: */ jpayne@69: UNumberGroupingStrategy fStrategy; jpayne@69: jpayne@69: Grouper() : fGrouping1(-3) {} jpayne@69: jpayne@69: bool isBogus() const { jpayne@69: return fGrouping1 == -3; jpayne@69: } jpayne@69: jpayne@69: /** NON-CONST: mutates the current instance. */ jpayne@69: void setLocaleData(const impl::ParsedPatternInfo &patternInfo, const Locale& locale); jpayne@69: jpayne@69: bool groupAtPosition(int32_t position, const impl::DecimalQuantity &value) const; jpayne@69: jpayne@69: // To allow MacroProps/MicroProps to initialize empty instances: jpayne@69: friend struct MacroProps; jpayne@69: friend struct MicroProps; jpayne@69: jpayne@69: // To allow NumberFormatterImpl to access isBogus() and perform other operations: jpayne@69: friend class NumberFormatterImpl; jpayne@69: jpayne@69: // To allow NumberParserImpl to perform setLocaleData(): jpayne@69: friend class ::icu::numparse::impl::NumberParserImpl; jpayne@69: jpayne@69: // To allow access to the skeleton generation code: jpayne@69: friend class impl::GeneratorHelpers; jpayne@69: }; jpayne@69: jpayne@69: // Do not enclose entire Padder with #ifndef U_HIDE_INTERNAL_API, needed for a protected field jpayne@69: /** @internal */ jpayne@69: class U_I18N_API Padder : public UMemory { jpayne@69: public: jpayne@69: #ifndef U_HIDE_INTERNAL_API jpayne@69: /** @internal */ jpayne@69: static Padder none(); jpayne@69: jpayne@69: /** @internal */ jpayne@69: static Padder codePoints(UChar32 cp, int32_t targetWidth, UNumberFormatPadPosition position); jpayne@69: #endif // U_HIDE_INTERNAL_API jpayne@69: jpayne@69: /** @internal */ jpayne@69: static Padder forProperties(const DecimalFormatProperties& properties); jpayne@69: jpayne@69: private: jpayne@69: UChar32 fWidth; // -3 = error; -2 = bogus; -1 = no padding jpayne@69: union { jpayne@69: struct { jpayne@69: int32_t fCp; jpayne@69: UNumberFormatPadPosition fPosition; jpayne@69: } padding; jpayne@69: UErrorCode errorCode; jpayne@69: } fUnion; jpayne@69: jpayne@69: Padder(UChar32 cp, int32_t width, UNumberFormatPadPosition position); jpayne@69: jpayne@69: Padder(int32_t width); jpayne@69: jpayne@69: Padder(UErrorCode errorCode) : fWidth(-3) { // NOLINT jpayne@69: fUnion.errorCode = errorCode; jpayne@69: } jpayne@69: jpayne@69: Padder() : fWidth(-2) {} // NOLINT jpayne@69: jpayne@69: bool isBogus() const { jpayne@69: return fWidth == -2; jpayne@69: } jpayne@69: jpayne@69: UBool copyErrorTo(UErrorCode &status) const { jpayne@69: if (fWidth == -3) { jpayne@69: status = fUnion.errorCode; jpayne@69: return TRUE; jpayne@69: } jpayne@69: return FALSE; jpayne@69: } jpayne@69: jpayne@69: bool isValid() const { jpayne@69: return fWidth > 0; jpayne@69: } jpayne@69: jpayne@69: int32_t padAndApply(const impl::Modifier &mod1, const impl::Modifier &mod2, jpayne@69: FormattedStringBuilder &string, int32_t leftIndex, int32_t rightIndex, jpayne@69: UErrorCode &status) const; jpayne@69: jpayne@69: // To allow MacroProps/MicroProps to initialize empty instances: jpayne@69: friend struct MacroProps; jpayne@69: friend struct MicroProps; jpayne@69: jpayne@69: // To allow NumberFormatterImpl to access isBogus() and perform other operations: jpayne@69: friend class impl::NumberFormatterImpl; jpayne@69: jpayne@69: // To allow access to the skeleton generation code: jpayne@69: friend class impl::GeneratorHelpers; jpayne@69: }; jpayne@69: jpayne@69: // Do not enclose entire MacroProps with #ifndef U_HIDE_INTERNAL_API, needed for a protected field jpayne@69: /** @internal */ jpayne@69: struct U_I18N_API MacroProps : public UMemory { jpayne@69: /** @internal */ jpayne@69: Notation notation; jpayne@69: jpayne@69: /** @internal */ jpayne@69: MeasureUnit unit; // = NoUnit::base(); jpayne@69: jpayne@69: /** @internal */ jpayne@69: MeasureUnit perUnit; // = NoUnit::base(); jpayne@69: jpayne@69: /** @internal */ jpayne@69: Precision precision; // = Precision(); (bogus) jpayne@69: jpayne@69: /** @internal */ jpayne@69: UNumberFormatRoundingMode roundingMode = UNUM_ROUND_HALFEVEN; jpayne@69: jpayne@69: /** @internal */ jpayne@69: Grouper grouper; // = Grouper(); (bogus) jpayne@69: jpayne@69: /** @internal */ jpayne@69: Padder padder; // = Padder(); (bogus) jpayne@69: jpayne@69: /** @internal */ jpayne@69: IntegerWidth integerWidth; // = IntegerWidth(); (bogus) jpayne@69: jpayne@69: /** @internal */ jpayne@69: SymbolsWrapper symbols; jpayne@69: jpayne@69: // UNUM_XYZ_COUNT denotes null (bogus) values. jpayne@69: jpayne@69: /** @internal */ jpayne@69: UNumberUnitWidth unitWidth = UNUM_UNIT_WIDTH_COUNT; jpayne@69: jpayne@69: /** @internal */ jpayne@69: UNumberSignDisplay sign = UNUM_SIGN_COUNT; jpayne@69: jpayne@69: /** @internal */ jpayne@69: UNumberDecimalSeparatorDisplay decimal = UNUM_DECIMAL_SEPARATOR_COUNT; jpayne@69: jpayne@69: /** @internal */ jpayne@69: Scale scale; // = Scale(); (benign value) jpayne@69: jpayne@69: /** @internal */ jpayne@69: const AffixPatternProvider* affixProvider = nullptr; // no ownership jpayne@69: jpayne@69: /** @internal */ jpayne@69: const PluralRules* rules = nullptr; // no ownership jpayne@69: jpayne@69: /** @internal */ jpayne@69: int32_t threshold = kInternalDefaultThreshold; jpayne@69: jpayne@69: /** @internal */ jpayne@69: Locale locale; jpayne@69: jpayne@69: // NOTE: Uses default copy and move constructors. jpayne@69: jpayne@69: /** jpayne@69: * Check all members for errors. jpayne@69: * @internal jpayne@69: */ jpayne@69: bool copyErrorTo(UErrorCode &status) const { jpayne@69: return notation.copyErrorTo(status) || precision.copyErrorTo(status) || jpayne@69: padder.copyErrorTo(status) || integerWidth.copyErrorTo(status) || jpayne@69: symbols.copyErrorTo(status) || scale.copyErrorTo(status); jpayne@69: } jpayne@69: }; jpayne@69: jpayne@69: } // namespace impl jpayne@69: jpayne@69: #if (U_PF_WINDOWS <= U_PLATFORM && U_PLATFORM <= U_PF_CYGWIN) && defined(_MSC_VER) jpayne@69: // Ignore MSVC warning 4661. This is generated for NumberFormatterSettings<>::toSkeleton() as this method jpayne@69: // is defined elsewhere (in number_skeletons.cpp). The compiler is warning that the explicit template instantiation jpayne@69: // inside this single translation unit (CPP file) is incomplete, and thus it isn't sure if the template class is jpayne@69: // fully defined. However, since each translation unit explicitly instantiates all the necessary template classes, jpayne@69: // they will all be passed to the linker, and the linker will still find and export all the class members. jpayne@69: #pragma warning(push) jpayne@69: #pragma warning(disable: 4661) jpayne@69: #endif jpayne@69: jpayne@69: /** jpayne@69: * An abstract base class for specifying settings related to number formatting. This class is implemented by jpayne@69: * {@link UnlocalizedNumberFormatter} and {@link LocalizedNumberFormatter}. This class is not intended for jpayne@69: * public subclassing. jpayne@69: */ jpayne@69: template jpayne@69: class U_I18N_API NumberFormatterSettings { jpayne@69: public: jpayne@69: /** jpayne@69: * Specifies the notation style (simple, scientific, or compact) for rendering numbers. jpayne@69: * jpayne@69: * jpayne@69: * jpayne@69: *

jpayne@69: * All notation styles will be properly localized with locale data, and all notation styles are compatible with jpayne@69: * units, rounding precisions, and other number formatter settings. jpayne@69: * jpayne@69: *

jpayne@69: * Pass this method the return value of a {@link Notation} factory method. For example: jpayne@69: * jpayne@69: * 

jpayne@69:      * NumberFormatter::with().notation(Notation::compactShort())
jpayne@69:      *
jpayne@69: * jpayne@69: * The default is to use simple notation. jpayne@69: * jpayne@69: * @param notation jpayne@69: * The notation strategy to use. jpayne@69: * @return The fluent chain. jpayne@69: * @see Notation jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: Derived notation(const Notation ¬ation) const &; jpayne@69: jpayne@69: /** jpayne@69: * Overload of notation() for use on an rvalue reference. jpayne@69: * jpayne@69: * @param notation jpayne@69: * The notation strategy to use. jpayne@69: * @return The fluent chain. jpayne@69: * @see #notation jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Derived notation(const Notation ¬ation) &&; jpayne@69: jpayne@69: /** jpayne@69: * Specifies the unit (unit of measure, currency, or percent) to associate with rendered numbers. jpayne@69: * jpayne@69: * jpayne@69: * jpayne@69: * All units will be properly localized with locale data, and all units are compatible with notation styles, jpayne@69: * rounding precisions, and other number formatter settings. jpayne@69: * jpayne@69: * Pass this method any instance of {@link MeasureUnit}. For units of measure: jpayne@69: * jpayne@69: * 
jpayne@69:      * NumberFormatter::with().unit(MeasureUnit::getMeter())
jpayne@69:      *
jpayne@69: * jpayne@69: * Currency: jpayne@69: * jpayne@69: * 
jpayne@69:      * NumberFormatter::with().unit(CurrencyUnit(u"USD", status))
jpayne@69:      *
jpayne@69: * jpayne@69: * Percent: jpayne@69: * jpayne@69: * 
jpayne@69:      * NumberFormatter::with().unit(NoUnit.percent())
jpayne@69:      *
jpayne@69: * jpayne@69: * See {@link #perUnit} for information on how to format strings like "5 meters per second". jpayne@69: * jpayne@69: * The default is to render without units (equivalent to NoUnit.base()). jpayne@69: * jpayne@69: * @param unit jpayne@69: * The unit to render. jpayne@69: * @return The fluent chain. jpayne@69: * @see MeasureUnit jpayne@69: * @see Currency jpayne@69: * @see NoUnit jpayne@69: * @see #perUnit jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: Derived unit(const icu::MeasureUnit &unit) const &; jpayne@69: jpayne@69: /** jpayne@69: * Overload of unit() for use on an rvalue reference. jpayne@69: * jpayne@69: * @param unit jpayne@69: * The unit to render. jpayne@69: * @return The fluent chain. jpayne@69: * @see #unit jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Derived unit(const icu::MeasureUnit &unit) &&; jpayne@69: jpayne@69: /** jpayne@69: * Like unit(), but takes ownership of a pointer. Convenient for use with the MeasureFormat factory jpayne@69: * methods that return pointers that need ownership. jpayne@69: * jpayne@69: * Note: consider using the MeasureFormat factory methods that return by value. jpayne@69: * jpayne@69: * @param unit jpayne@69: * The unit to render. jpayne@69: * @return The fluent chain. jpayne@69: * @see #unit jpayne@69: * @see MeasureUnit jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: Derived adoptUnit(icu::MeasureUnit *unit) const &; jpayne@69: jpayne@69: /** jpayne@69: * Overload of adoptUnit() for use on an rvalue reference. jpayne@69: * jpayne@69: * @param unit jpayne@69: * The unit to render. jpayne@69: * @return The fluent chain. jpayne@69: * @see #adoptUnit jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Derived adoptUnit(icu::MeasureUnit *unit) &&; jpayne@69: jpayne@69: /** jpayne@69: * Sets a unit to be used in the denominator. For example, to format "3 m/s", pass METER to the unit and SECOND to jpayne@69: * the perUnit. jpayne@69: * jpayne@69: * Pass this method any instance of {@link MeasureUnit}. Example: jpayne@69: * jpayne@69: * 
jpayne@69:      * NumberFormatter::with()
jpayne@69:      *      .unit(MeasureUnit::getMeter())
jpayne@69:      *      .perUnit(MeasureUnit::getSecond())
jpayne@69:      *
jpayne@69: * jpayne@69: * The default is not to display any unit in the denominator. jpayne@69: * jpayne@69: * If a per-unit is specified without a primary unit via {@link #unit}, the behavior is undefined. jpayne@69: * jpayne@69: * @param perUnit jpayne@69: * The unit to render in the denominator. jpayne@69: * @return The fluent chain jpayne@69: * @see #unit jpayne@69: * @stable ICU 61 jpayne@69: */ jpayne@69: Derived perUnit(const icu::MeasureUnit &perUnit) const &; jpayne@69: jpayne@69: /** jpayne@69: * Overload of perUnit() for use on an rvalue reference. jpayne@69: * jpayne@69: * @param perUnit jpayne@69: * The unit to render in the denominator. jpayne@69: * @return The fluent chain. jpayne@69: * @see #perUnit jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Derived perUnit(const icu::MeasureUnit &perUnit) &&; jpayne@69: jpayne@69: /** jpayne@69: * Like perUnit(), but takes ownership of a pointer. Convenient for use with the MeasureFormat factory jpayne@69: * methods that return pointers that need ownership. jpayne@69: * jpayne@69: * Note: consider using the MeasureFormat factory methods that return by value. jpayne@69: * jpayne@69: * @param perUnit jpayne@69: * The unit to render in the denominator. jpayne@69: * @return The fluent chain. jpayne@69: * @see #perUnit jpayne@69: * @see MeasureUnit jpayne@69: * @stable ICU 61 jpayne@69: */ jpayne@69: Derived adoptPerUnit(icu::MeasureUnit *perUnit) const &; jpayne@69: jpayne@69: /** jpayne@69: * Overload of adoptPerUnit() for use on an rvalue reference. jpayne@69: * jpayne@69: * @param perUnit jpayne@69: * The unit to render in the denominator. jpayne@69: * @return The fluent chain. jpayne@69: * @see #adoptPerUnit jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Derived adoptPerUnit(icu::MeasureUnit *perUnit) &&; jpayne@69: jpayne@69: /** jpayne@69: * Specifies the rounding precision to use when formatting numbers. jpayne@69: * jpayne@69: * jpayne@69: * jpayne@69: *

jpayne@69: * Pass this method the return value of one of the factory methods on {@link Precision}. For example: jpayne@69: * jpayne@69: * 

jpayne@69:      * NumberFormatter::with().precision(Precision::fixedFraction(2))
jpayne@69:      *
jpayne@69: * jpayne@69: *

jpayne@69: * In most cases, the default rounding strategy is to round to 6 fraction places; i.e., jpayne@69: * Precision.maxFraction(6). The exceptions are if compact notation is being used, then the compact jpayne@69: * notation rounding strategy is used (see {@link Notation#compactShort} for details), or if the unit is a currency, jpayne@69: * then standard currency rounding is used, which varies from currency to currency (see {@link Precision#currency} for jpayne@69: * details). jpayne@69: * jpayne@69: * @param precision jpayne@69: * The rounding precision to use. jpayne@69: * @return The fluent chain. jpayne@69: * @see Precision jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Derived precision(const Precision& precision) const &; jpayne@69: jpayne@69: /** jpayne@69: * Overload of precision() for use on an rvalue reference. jpayne@69: * jpayne@69: * @param precision jpayne@69: * The rounding precision to use. jpayne@69: * @return The fluent chain. jpayne@69: * @see #precision jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Derived precision(const Precision& precision) &&; jpayne@69: jpayne@69: /** jpayne@69: * Specifies how to determine the direction to round a number when it has more digits than fit in the jpayne@69: * desired precision. When formatting 1.235: jpayne@69: * jpayne@69: *

jpayne@69: * jpayne@69: * The default is HALF_EVEN. For more information on rounding mode, see the ICU userguide here: jpayne@69: * jpayne@69: * http://userguide.icu-project.org/formatparse/numbers/rounding-modes jpayne@69: * jpayne@69: * @param roundingMode The rounding mode to use. jpayne@69: * @return The fluent chain. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Derived roundingMode(UNumberFormatRoundingMode roundingMode) const &; jpayne@69: jpayne@69: /** jpayne@69: * Overload of roundingMode() for use on an rvalue reference. jpayne@69: * jpayne@69: * @param roundingMode The rounding mode to use. jpayne@69: * @return The fluent chain. jpayne@69: * @see #roundingMode jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Derived roundingMode(UNumberFormatRoundingMode roundingMode) &&; jpayne@69: jpayne@69: /** jpayne@69: * Specifies the grouping strategy to use when formatting numbers. jpayne@69: * jpayne@69: * jpayne@69: * jpayne@69: *

jpayne@69: * The exact grouping widths will be chosen based on the locale. jpayne@69: * jpayne@69: *

jpayne@69: * Pass this method an element from the {@link UNumberGroupingStrategy} enum. For example: jpayne@69: * jpayne@69: * 

jpayne@69:      * NumberFormatter::with().grouping(UNUM_GROUPING_MIN2)
jpayne@69:      *
jpayne@69: * jpayne@69: * The default is to perform grouping according to locale data; most locales, but not all locales, jpayne@69: * enable it by default. jpayne@69: * jpayne@69: * @param strategy jpayne@69: * The grouping strategy to use. jpayne@69: * @return The fluent chain. jpayne@69: * @stable ICU 61 jpayne@69: */ jpayne@69: Derived grouping(UNumberGroupingStrategy strategy) const &; jpayne@69: jpayne@69: /** jpayne@69: * Overload of grouping() for use on an rvalue reference. jpayne@69: * jpayne@69: * @param strategy jpayne@69: * The grouping strategy to use. jpayne@69: * @return The fluent chain. jpayne@69: * @see #grouping jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Derived grouping(UNumberGroupingStrategy strategy) &&; jpayne@69: jpayne@69: /** jpayne@69: * Specifies the minimum and maximum number of digits to render before the decimal mark. jpayne@69: * jpayne@69: * jpayne@69: * jpayne@69: *

jpayne@69: * Pass this method the return value of {@link IntegerWidth#zeroFillTo}. For example: jpayne@69: * jpayne@69: * 

jpayne@69:      * NumberFormatter::with().integerWidth(IntegerWidth::zeroFillTo(2))
jpayne@69:      *
jpayne@69: * jpayne@69: * The default is to have one minimum integer digit. jpayne@69: * jpayne@69: * @param style jpayne@69: * The integer width to use. jpayne@69: * @return The fluent chain. jpayne@69: * @see IntegerWidth jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: Derived integerWidth(const IntegerWidth &style) const &; jpayne@69: jpayne@69: /** jpayne@69: * Overload of integerWidth() for use on an rvalue reference. jpayne@69: * jpayne@69: * @param style jpayne@69: * The integer width to use. jpayne@69: * @return The fluent chain. jpayne@69: * @see #integerWidth jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Derived integerWidth(const IntegerWidth &style) &&; jpayne@69: jpayne@69: /** jpayne@69: * Specifies the symbols (decimal separator, grouping separator, percent sign, numerals, etc.) to use when rendering jpayne@69: * numbers. jpayne@69: * jpayne@69: * jpayne@69: * jpayne@69: *

jpayne@69: * Pass this method an instance of {@link DecimalFormatSymbols}. For example: jpayne@69: * jpayne@69: * 

jpayne@69:      * NumberFormatter::with().symbols(DecimalFormatSymbols(Locale("de_CH"), status))
jpayne@69:      *
jpayne@69: * jpayne@69: *

jpayne@69: * Note: DecimalFormatSymbols automatically chooses the best numbering system based on the locale. jpayne@69: * In the examples above, the first three are using the Latin numbering system, and the fourth is using the Myanmar jpayne@69: * numbering system. jpayne@69: * jpayne@69: *

jpayne@69: * Note: The instance of DecimalFormatSymbols will be copied: changes made to the symbols object jpayne@69: * after passing it into the fluent chain will not be seen. jpayne@69: * jpayne@69: *

jpayne@69: * Note: Calling this method will override any previously specified DecimalFormatSymbols jpayne@69: * or NumberingSystem. jpayne@69: * jpayne@69: *

jpayne@69: * The default is to choose the symbols based on the locale specified in the fluent chain. jpayne@69: * jpayne@69: * @param symbols jpayne@69: * The DecimalFormatSymbols to use. jpayne@69: * @return The fluent chain. jpayne@69: * @see DecimalFormatSymbols jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: Derived symbols(const DecimalFormatSymbols &symbols) const &; jpayne@69: jpayne@69: /** jpayne@69: * Overload of symbols() for use on an rvalue reference. jpayne@69: * jpayne@69: * @param symbols jpayne@69: * The DecimalFormatSymbols to use. jpayne@69: * @return The fluent chain. jpayne@69: * @see #symbols jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Derived symbols(const DecimalFormatSymbols &symbols) &&; jpayne@69: jpayne@69: /** jpayne@69: * Specifies that the given numbering system should be used when fetching symbols. jpayne@69: * jpayne@69: *

jpayne@69: * jpayne@69: *

jpayne@69: * Pass this method an instance of {@link NumberingSystem}. For example, to force the locale to always use the Latin jpayne@69: * alphabet numbering system (ASCII digits): jpayne@69: * jpayne@69: * 

jpayne@69:      * NumberFormatter::with().adoptSymbols(NumberingSystem::createInstanceByName("latn", status))
jpayne@69:      *
jpayne@69: * jpayne@69: *

jpayne@69: * Note: Calling this method will override any previously specified DecimalFormatSymbols jpayne@69: * or NumberingSystem. jpayne@69: * jpayne@69: *

jpayne@69: * The default is to choose the best numbering system for the locale. jpayne@69: * jpayne@69: *

jpayne@69: * This method takes ownership of a pointer in order to work nicely with the NumberingSystem factory methods. jpayne@69: * jpayne@69: * @param symbols jpayne@69: * The NumberingSystem to use. jpayne@69: * @return The fluent chain. jpayne@69: * @see NumberingSystem jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: Derived adoptSymbols(NumberingSystem *symbols) const &; jpayne@69: jpayne@69: /** jpayne@69: * Overload of adoptSymbols() for use on an rvalue reference. jpayne@69: * jpayne@69: * @param symbols jpayne@69: * The NumberingSystem to use. jpayne@69: * @return The fluent chain. jpayne@69: * @see #adoptSymbols jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Derived adoptSymbols(NumberingSystem *symbols) &&; jpayne@69: jpayne@69: /** jpayne@69: * Sets the width of the unit (measure unit or currency). Most common values: jpayne@69: * jpayne@69: *

jpayne@69: * jpayne@69: *

jpayne@69: * Pass an element from the {@link UNumberUnitWidth} enum to this setter. For example: jpayne@69: * jpayne@69: * 

jpayne@69:      * NumberFormatter::with().unitWidth(UNumberUnitWidth::UNUM_UNIT_WIDTH_FULL_NAME)
jpayne@69:      *
jpayne@69: * jpayne@69: *

jpayne@69: * The default is the SHORT width. jpayne@69: * jpayne@69: * @param width jpayne@69: * The width to use when rendering numbers. jpayne@69: * @return The fluent chain jpayne@69: * @see UNumberUnitWidth jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: Derived unitWidth(UNumberUnitWidth width) const &; jpayne@69: jpayne@69: /** jpayne@69: * Overload of unitWidth() for use on an rvalue reference. jpayne@69: * jpayne@69: * @param width jpayne@69: * The width to use when rendering numbers. jpayne@69: * @return The fluent chain. jpayne@69: * @see #unitWidth jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Derived unitWidth(UNumberUnitWidth width) &&; jpayne@69: jpayne@69: /** jpayne@69: * Sets the plus/minus sign display strategy. Most common values: jpayne@69: * jpayne@69: *

jpayne@69: * jpayne@69: *

jpayne@69: * Pass an element from the {@link UNumberSignDisplay} enum to this setter. For example: jpayne@69: * jpayne@69: * 

jpayne@69:      * NumberFormatter::with().sign(UNumberSignDisplay::UNUM_SIGN_ALWAYS)
jpayne@69:      *
jpayne@69: * jpayne@69: *

jpayne@69: * The default is AUTO sign display. jpayne@69: * jpayne@69: * @param style jpayne@69: * The sign display strategy to use when rendering numbers. jpayne@69: * @return The fluent chain jpayne@69: * @see UNumberSignDisplay jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: Derived sign(UNumberSignDisplay style) const &; jpayne@69: jpayne@69: /** jpayne@69: * Overload of sign() for use on an rvalue reference. jpayne@69: * jpayne@69: * @param style jpayne@69: * The sign display strategy to use when rendering numbers. jpayne@69: * @return The fluent chain. jpayne@69: * @see #sign jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Derived sign(UNumberSignDisplay style) &&; jpayne@69: jpayne@69: /** jpayne@69: * Sets the decimal separator display strategy. This affects integer numbers with no fraction part. Most common jpayne@69: * values: jpayne@69: * jpayne@69: *

jpayne@69: * jpayne@69: *

jpayne@69: * Pass an element from the {@link UNumberDecimalSeparatorDisplay} enum to this setter. For example: jpayne@69: * jpayne@69: * 

jpayne@69:      * NumberFormatter::with().decimal(UNumberDecimalSeparatorDisplay::UNUM_DECIMAL_SEPARATOR_ALWAYS)
jpayne@69:      *
jpayne@69: * jpayne@69: *

jpayne@69: * The default is AUTO decimal separator display. jpayne@69: * jpayne@69: * @param style jpayne@69: * The decimal separator display strategy to use when rendering numbers. jpayne@69: * @return The fluent chain jpayne@69: * @see UNumberDecimalSeparatorDisplay jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: Derived decimal(UNumberDecimalSeparatorDisplay style) const &; jpayne@69: jpayne@69: /** jpayne@69: * Overload of decimal() for use on an rvalue reference. jpayne@69: * jpayne@69: * @param style jpayne@69: * The decimal separator display strategy to use when rendering numbers. jpayne@69: * @return The fluent chain. jpayne@69: * @see #decimal jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Derived decimal(UNumberDecimalSeparatorDisplay style) &&; jpayne@69: jpayne@69: /** jpayne@69: * Sets a scale (multiplier) to be used to scale the number by an arbitrary amount before formatting. jpayne@69: * Most common values: jpayne@69: * jpayne@69: *

jpayne@69: * jpayne@69: *

jpayne@69: * Pass an element from a {@link Scale} factory method to this setter. For example: jpayne@69: * jpayne@69: * 

jpayne@69:      * NumberFormatter::with().scale(Scale::powerOfTen(2))
jpayne@69:      *
jpayne@69: * jpayne@69: *

jpayne@69: * The default is to not apply any multiplier. jpayne@69: * jpayne@69: * @param scale jpayne@69: * The scale to apply when rendering numbers. jpayne@69: * @return The fluent chain jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Derived scale(const Scale &scale) const &; jpayne@69: jpayne@69: /** jpayne@69: * Overload of scale() for use on an rvalue reference. jpayne@69: * jpayne@69: * @param scale jpayne@69: * The scale to apply when rendering numbers. jpayne@69: * @return The fluent chain. jpayne@69: * @see #scale jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Derived scale(const Scale &scale) &&; jpayne@69: jpayne@69: #ifndef U_HIDE_INTERNAL_API jpayne@69: jpayne@69: /** jpayne@69: * Set the padding strategy. May be added in the future; see #13338. jpayne@69: * jpayne@69: * @internal ICU 60: This API is ICU internal only. jpayne@69: */ jpayne@69: Derived padding(const impl::Padder &padder) const &; jpayne@69: jpayne@69: /** @internal */ jpayne@69: Derived padding(const impl::Padder &padder) &&; jpayne@69: jpayne@69: /** jpayne@69: * Internal fluent setter to support a custom regulation threshold. A threshold of 1 causes the data structures to jpayne@69: * be built right away. A threshold of 0 prevents the data structures from being built. jpayne@69: * jpayne@69: * @internal ICU 60: This API is ICU internal only. jpayne@69: */ jpayne@69: Derived threshold(int32_t threshold) const &; jpayne@69: jpayne@69: /** @internal */ jpayne@69: Derived threshold(int32_t threshold) &&; jpayne@69: jpayne@69: /** jpayne@69: * Internal fluent setter to overwrite the entire macros object. jpayne@69: * jpayne@69: * @internal ICU 60: This API is ICU internal only. jpayne@69: */ jpayne@69: Derived macros(const impl::MacroProps& macros) const &; jpayne@69: jpayne@69: /** @internal */ jpayne@69: Derived macros(const impl::MacroProps& macros) &&; jpayne@69: jpayne@69: /** @internal */ jpayne@69: Derived macros(impl::MacroProps&& macros) const &; jpayne@69: jpayne@69: /** @internal */ jpayne@69: Derived macros(impl::MacroProps&& macros) &&; jpayne@69: jpayne@69: #endif /* U_HIDE_INTERNAL_API */ jpayne@69: jpayne@69: /** jpayne@69: * Creates a skeleton string representation of this number formatter. A skeleton string is a jpayne@69: * locale-agnostic serialized form of a number formatter. jpayne@69: * jpayne@69: * Not all options are capable of being represented in the skeleton string; for example, a jpayne@69: * DecimalFormatSymbols object. If any such option is encountered, the error code is set to jpayne@69: * U_UNSUPPORTED_ERROR. jpayne@69: * jpayne@69: * The returned skeleton is in normalized form, such that two number formatters with equivalent jpayne@69: * behavior should produce the same skeleton. jpayne@69: * jpayne@69: * @return A number skeleton string with behavior corresponding to this number formatter. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: UnicodeString toSkeleton(UErrorCode& status) const; jpayne@69: jpayne@69: /** jpayne@69: * Returns the current (Un)LocalizedNumberFormatter as a LocalPointer jpayne@69: * wrapping a heap-allocated copy of the current object. jpayne@69: * jpayne@69: * This is equivalent to new-ing the move constructor with a value object jpayne@69: * as the argument. jpayne@69: * jpayne@69: * @return A wrapped (Un)LocalizedNumberFormatter pointer, or a wrapped jpayne@69: * nullptr on failure. jpayne@69: * @stable ICU 64 jpayne@69: */ jpayne@69: LocalPointer clone() const &; jpayne@69: jpayne@69: /** jpayne@69: * Overload of clone for use on an rvalue reference. jpayne@69: * jpayne@69: * @return A wrapped (Un)LocalizedNumberFormatter pointer, or a wrapped jpayne@69: * nullptr on failure. jpayne@69: * @stable ICU 64 jpayne@69: */ jpayne@69: LocalPointer clone() &&; jpayne@69: jpayne@69: /** jpayne@69: * Sets the UErrorCode if an error occurred in the fluent chain. jpayne@69: * Preserves older error codes in the outErrorCode. jpayne@69: * @return TRUE if U_FAILURE(outErrorCode) jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: UBool copyErrorTo(UErrorCode &outErrorCode) const { jpayne@69: if (U_FAILURE(outErrorCode)) { jpayne@69: // Do not overwrite the older error code jpayne@69: return TRUE; jpayne@69: } jpayne@69: fMacros.copyErrorTo(outErrorCode); jpayne@69: return U_FAILURE(outErrorCode); jpayne@69: } jpayne@69: jpayne@69: // NOTE: Uses default copy and move constructors. jpayne@69: jpayne@69: private: jpayne@69: impl::MacroProps fMacros; jpayne@69: jpayne@69: // Don't construct me directly! Use (Un)LocalizedNumberFormatter. jpayne@69: NumberFormatterSettings() = default; jpayne@69: jpayne@69: friend class LocalizedNumberFormatter; jpayne@69: friend class UnlocalizedNumberFormatter; jpayne@69: jpayne@69: // Give NumberRangeFormatter access to the MacroProps jpayne@69: friend void impl::touchRangeLocales(impl::RangeMacroProps& macros); jpayne@69: friend class impl::NumberRangeFormatterImpl; jpayne@69: }; jpayne@69: jpayne@69: /** jpayne@69: * A NumberFormatter that does not yet have a locale. In order to format numbers, a locale must be specified. jpayne@69: * jpayne@69: * Instances of this class are immutable and thread-safe. jpayne@69: * jpayne@69: * @see NumberFormatter jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: class U_I18N_API UnlocalizedNumberFormatter jpayne@69: : public NumberFormatterSettings, public UMemory { jpayne@69: jpayne@69: public: jpayne@69: /** jpayne@69: * Associate the given locale with the number formatter. The locale is used for picking the appropriate symbols, jpayne@69: * formats, and other data for number display. jpayne@69: * jpayne@69: * @param locale jpayne@69: * The locale to use when loading data for number formatting. jpayne@69: * @return The fluent chain. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: LocalizedNumberFormatter locale(const icu::Locale &locale) const &; jpayne@69: jpayne@69: /** jpayne@69: * Overload of locale() for use on an rvalue reference. jpayne@69: * jpayne@69: * @param locale jpayne@69: * The locale to use when loading data for number formatting. jpayne@69: * @return The fluent chain. jpayne@69: * @see #locale jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: LocalizedNumberFormatter locale(const icu::Locale &locale) &&; jpayne@69: jpayne@69: /** jpayne@69: * Default constructor: puts the formatter into a valid but undefined state. jpayne@69: * jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: UnlocalizedNumberFormatter() = default; jpayne@69: jpayne@69: /** jpayne@69: * Returns a copy of this UnlocalizedNumberFormatter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: UnlocalizedNumberFormatter(const UnlocalizedNumberFormatter &other); jpayne@69: jpayne@69: /** jpayne@69: * Move constructor: jpayne@69: * The source UnlocalizedNumberFormatter will be left in a valid but undefined state. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: UnlocalizedNumberFormatter(UnlocalizedNumberFormatter&& src) U_NOEXCEPT; jpayne@69: jpayne@69: /** jpayne@69: * Copy assignment operator. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: UnlocalizedNumberFormatter& operator=(const UnlocalizedNumberFormatter& other); jpayne@69: jpayne@69: /** jpayne@69: * Move assignment operator: jpayne@69: * The source UnlocalizedNumberFormatter will be left in a valid but undefined state. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: UnlocalizedNumberFormatter& operator=(UnlocalizedNumberFormatter&& src) U_NOEXCEPT; jpayne@69: jpayne@69: private: jpayne@69: explicit UnlocalizedNumberFormatter(const NumberFormatterSettings& other); jpayne@69: jpayne@69: explicit UnlocalizedNumberFormatter( jpayne@69: NumberFormatterSettings&& src) U_NOEXCEPT; jpayne@69: jpayne@69: // To give the fluent setters access to this class's constructor: jpayne@69: friend class NumberFormatterSettings; jpayne@69: jpayne@69: // To give NumberFormatter::with() access to this class's constructor: jpayne@69: friend class NumberFormatter; jpayne@69: }; jpayne@69: jpayne@69: /** jpayne@69: * A NumberFormatter that has a locale associated with it; this means .format() methods are available. jpayne@69: * jpayne@69: * Instances of this class are immutable and thread-safe. jpayne@69: * jpayne@69: * @see NumberFormatter jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: class U_I18N_API LocalizedNumberFormatter jpayne@69: : public NumberFormatterSettings, public UMemory { jpayne@69: public: jpayne@69: /** jpayne@69: * Format the given integer number to a string using the settings specified in the NumberFormatter fluent jpayne@69: * setting chain. jpayne@69: * jpayne@69: * @param value jpayne@69: * The number to format. jpayne@69: * @param status jpayne@69: * Set to an ErrorCode if one occurred in the setter chain or during formatting. jpayne@69: * @return A FormattedNumber object; call .toString() to get the string. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: FormattedNumber formatInt(int64_t value, UErrorCode &status) const; jpayne@69: jpayne@69: /** jpayne@69: * Format the given float or double to a string using the settings specified in the NumberFormatter fluent setting jpayne@69: * chain. jpayne@69: * jpayne@69: * @param value jpayne@69: * The number to format. jpayne@69: * @param status jpayne@69: * Set to an ErrorCode if one occurred in the setter chain or during formatting. jpayne@69: * @return A FormattedNumber object; call .toString() to get the string. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: FormattedNumber formatDouble(double value, UErrorCode &status) const; jpayne@69: jpayne@69: /** jpayne@69: * Format the given decimal number to a string using the settings jpayne@69: * specified in the NumberFormatter fluent setting chain. jpayne@69: * The syntax of the unformatted number is a "numeric string" jpayne@69: * as defined in the Decimal Arithmetic Specification, available at jpayne@69: * http://speleotrove.com/decimal jpayne@69: * jpayne@69: * @param value jpayne@69: * The number to format. jpayne@69: * @param status jpayne@69: * Set to an ErrorCode if one occurred in the setter chain or during formatting. jpayne@69: * @return A FormattedNumber object; call .toString() to get the string. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: FormattedNumber formatDecimal(StringPiece value, UErrorCode& status) const; jpayne@69: jpayne@69: #ifndef U_HIDE_INTERNAL_API jpayne@69: jpayne@69: /** Internal method. jpayne@69: * @internal jpayne@69: */ jpayne@69: FormattedNumber formatDecimalQuantity(const impl::DecimalQuantity& dq, UErrorCode& status) const; jpayne@69: jpayne@69: /** Internal method for DecimalFormat compatibility. jpayne@69: * @internal jpayne@69: */ jpayne@69: void getAffixImpl(bool isPrefix, bool isNegative, UnicodeString& result, UErrorCode& status) const; jpayne@69: jpayne@69: /** jpayne@69: * Internal method for testing. jpayne@69: * @internal jpayne@69: */ jpayne@69: const impl::NumberFormatterImpl* getCompiled() const; jpayne@69: jpayne@69: /** jpayne@69: * Internal method for testing. jpayne@69: * @internal jpayne@69: */ jpayne@69: int32_t getCallCount() const; jpayne@69: jpayne@69: #endif /* U_HIDE_INTERNAL_API */ jpayne@69: jpayne@69: /** jpayne@69: * Creates a representation of this LocalizedNumberFormat as an icu::Format, enabling the use jpayne@69: * of this number formatter with APIs that need an object of that type, such as MessageFormat. jpayne@69: * jpayne@69: * This API is not intended to be used other than for enabling API compatibility. The formatDouble, jpayne@69: * formatInt, and formatDecimal methods should normally be used when formatting numbers, not the Format jpayne@69: * object returned by this method. jpayne@69: * jpayne@69: * The caller owns the returned object and must delete it when finished. jpayne@69: * jpayne@69: * @return A Format wrapping this LocalizedNumberFormatter. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Format* toFormat(UErrorCode& status) const; jpayne@69: jpayne@69: /** jpayne@69: * Default constructor: puts the formatter into a valid but undefined state. jpayne@69: * jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: LocalizedNumberFormatter() = default; jpayne@69: jpayne@69: /** jpayne@69: * Returns a copy of this LocalizedNumberFormatter. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: LocalizedNumberFormatter(const LocalizedNumberFormatter &other); jpayne@69: jpayne@69: /** jpayne@69: * Move constructor: jpayne@69: * The source LocalizedNumberFormatter will be left in a valid but undefined state. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: LocalizedNumberFormatter(LocalizedNumberFormatter&& src) U_NOEXCEPT; jpayne@69: jpayne@69: /** jpayne@69: * Copy assignment operator. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: LocalizedNumberFormatter& operator=(const LocalizedNumberFormatter& other); jpayne@69: jpayne@69: /** jpayne@69: * Move assignment operator: jpayne@69: * The source LocalizedNumberFormatter will be left in a valid but undefined state. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: LocalizedNumberFormatter& operator=(LocalizedNumberFormatter&& src) U_NOEXCEPT; jpayne@69: jpayne@69: #ifndef U_HIDE_INTERNAL_API jpayne@69: jpayne@69: /** jpayne@69: * This is the core entrypoint to the number formatting pipeline. It performs self-regulation: a static code path jpayne@69: * for the first few calls, and compiling a more efficient data structure if called repeatedly. jpayne@69: * jpayne@69: *

jpayne@69: * This function is very hot, being called in every call to the number formatting pipeline. jpayne@69: * jpayne@69: * @param results jpayne@69: * The results object. This method will mutate it to save the results. jpayne@69: * @param status jpayne@69: * @internal jpayne@69: */ jpayne@69: void formatImpl(impl::UFormattedNumberData *results, UErrorCode &status) const; jpayne@69: jpayne@69: #endif /* U_HIDE_INTERNAL_API */ jpayne@69: jpayne@69: /** jpayne@69: * Destruct this LocalizedNumberFormatter, cleaning up any memory it might own. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: ~LocalizedNumberFormatter(); jpayne@69: jpayne@69: private: jpayne@69: // Note: fCompiled can't be a LocalPointer because impl::NumberFormatterImpl is defined in an internal jpayne@69: // header, and LocalPointer needs the full class definition in order to delete the instance. jpayne@69: const impl::NumberFormatterImpl* fCompiled {nullptr}; jpayne@69: char fUnsafeCallCount[8] {}; // internally cast to u_atomic_int32_t jpayne@69: jpayne@69: explicit LocalizedNumberFormatter(const NumberFormatterSettings& other); jpayne@69: jpayne@69: explicit LocalizedNumberFormatter(NumberFormatterSettings&& src) U_NOEXCEPT; jpayne@69: jpayne@69: LocalizedNumberFormatter(const impl::MacroProps ¯os, const Locale &locale); jpayne@69: jpayne@69: LocalizedNumberFormatter(impl::MacroProps &¯os, const Locale &locale); jpayne@69: jpayne@69: void clear(); jpayne@69: jpayne@69: void lnfMoveHelper(LocalizedNumberFormatter&& src); jpayne@69: jpayne@69: /** jpayne@69: * @return true if the compiled formatter is available. jpayne@69: */ jpayne@69: bool computeCompiled(UErrorCode& status) const; jpayne@69: jpayne@69: // To give the fluent setters access to this class's constructor: jpayne@69: friend class NumberFormatterSettings; jpayne@69: friend class NumberFormatterSettings; jpayne@69: jpayne@69: // To give UnlocalizedNumberFormatter::locale() access to this class's constructor: jpayne@69: friend class UnlocalizedNumberFormatter; jpayne@69: }; jpayne@69: jpayne@69: #if (U_PF_WINDOWS <= U_PLATFORM && U_PLATFORM <= U_PF_CYGWIN) && defined(_MSC_VER) jpayne@69: // Warning 4661. jpayne@69: #pragma warning(pop) jpayne@69: #endif jpayne@69: jpayne@69: /** jpayne@69: * The result of a number formatting operation. This class allows the result to be exported in several data types, jpayne@69: * including a UnicodeString and a FieldPositionIterator. jpayne@69: * jpayne@69: * Instances of this class are immutable and thread-safe. jpayne@69: * jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: class U_I18N_API FormattedNumber : public UMemory, public FormattedValue { jpayne@69: public: jpayne@69: jpayne@69: /** jpayne@69: * Default constructor; makes an empty FormattedNumber. jpayne@69: * @stable ICU 64 jpayne@69: */ jpayne@69: FormattedNumber() jpayne@69: : fData(nullptr), fErrorCode(U_INVALID_STATE_ERROR) {} jpayne@69: jpayne@69: /** jpayne@69: * Move constructor: Leaves the source FormattedNumber in an undefined state. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: FormattedNumber(FormattedNumber&& src) U_NOEXCEPT; jpayne@69: jpayne@69: /** jpayne@69: * Destruct an instance of FormattedNumber. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: virtual ~FormattedNumber() U_OVERRIDE; jpayne@69: jpayne@69: /** Copying not supported; use move constructor instead. */ jpayne@69: FormattedNumber(const FormattedNumber&) = delete; jpayne@69: jpayne@69: /** Copying not supported; use move assignment instead. */ jpayne@69: FormattedNumber& operator=(const FormattedNumber&) = delete; jpayne@69: jpayne@69: /** jpayne@69: * Move assignment: Leaves the source FormattedNumber in an undefined state. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: FormattedNumber& operator=(FormattedNumber&& src) U_NOEXCEPT; jpayne@69: jpayne@69: // Copybrief: this method is older than the parent method jpayne@69: /** jpayne@69: * @copybrief FormattedValue::toString() jpayne@69: * jpayne@69: * For more information, see FormattedValue::toString() jpayne@69: * jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: UnicodeString toString(UErrorCode& status) const U_OVERRIDE; jpayne@69: jpayne@69: // Copydoc: this method is new in ICU 64 jpayne@69: /** @copydoc FormattedValue::toTempString() */ jpayne@69: UnicodeString toTempString(UErrorCode& status) const U_OVERRIDE; jpayne@69: jpayne@69: // Copybrief: this method is older than the parent method jpayne@69: /** jpayne@69: * @copybrief FormattedValue::appendTo() jpayne@69: * jpayne@69: * For more information, see FormattedValue::appendTo() jpayne@69: * jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: Appendable &appendTo(Appendable& appendable, UErrorCode& status) const U_OVERRIDE; jpayne@69: jpayne@69: // Copydoc: this method is new in ICU 64 jpayne@69: /** @copydoc FormattedValue::nextPosition() */ jpayne@69: UBool nextPosition(ConstrainedFieldPosition& cfpos, UErrorCode& status) const U_OVERRIDE; jpayne@69: jpayne@69: #ifndef U_HIDE_DRAFT_API jpayne@69: /** jpayne@69: * Export the formatted number as a "numeric string" conforming to the jpayne@69: * syntax defined in the Decimal Arithmetic Specification, available at jpayne@69: * http://speleotrove.com/decimal jpayne@69: * jpayne@69: * This endpoint is useful for obtaining the exact number being printed jpayne@69: * after scaling and rounding have been applied by the number formatter. jpayne@69: * jpayne@69: * Example call site: jpayne@69: * jpayne@69: * auto decimalNumber = fn.toDecimalNumber(status); jpayne@69: * jpayne@69: * @tparam StringClass A string class compatible with StringByteSink; jpayne@69: * for example, std::string. jpayne@69: * @param status Set if an error occurs. jpayne@69: * @return A StringClass containing the numeric string. jpayne@69: * @draft ICU 65 jpayne@69: */ jpayne@69: template jpayne@69: inline StringClass toDecimalNumber(UErrorCode& status) const; jpayne@69: #endif // U_HIDE_DRAFT_API jpayne@69: jpayne@69: #ifndef U_HIDE_INTERNAL_API jpayne@69: jpayne@69: /** jpayne@69: * Gets the raw DecimalQuantity for plural rule selection. jpayne@69: * @internal jpayne@69: */ jpayne@69: void getDecimalQuantity(impl::DecimalQuantity& output, UErrorCode& status) const; jpayne@69: jpayne@69: /** jpayne@69: * Populates the mutable builder type FieldPositionIteratorHandler. jpayne@69: * @internal jpayne@69: */ jpayne@69: void getAllFieldPositionsImpl(FieldPositionIteratorHandler& fpih, UErrorCode& status) const; jpayne@69: jpayne@69: #endif /* U_HIDE_INTERNAL_API */ jpayne@69: jpayne@69: private: jpayne@69: // Can't use LocalPointer because UFormattedNumberData is forward-declared jpayne@69: const impl::UFormattedNumberData *fData; jpayne@69: jpayne@69: // Error code for the terminal methods jpayne@69: UErrorCode fErrorCode; jpayne@69: jpayne@69: /** jpayne@69: * Internal constructor from data type. Adopts the data pointer. jpayne@69: * @internal jpayne@69: */ jpayne@69: explicit FormattedNumber(impl::UFormattedNumberData *results) jpayne@69: : fData(results), fErrorCode(U_ZERO_ERROR) {} jpayne@69: jpayne@69: explicit FormattedNumber(UErrorCode errorCode) jpayne@69: : fData(nullptr), fErrorCode(errorCode) {} jpayne@69: jpayne@69: // TODO(ICU-20775): Propose this as API. jpayne@69: void toDecimalNumber(ByteSink& sink, UErrorCode& status) const; jpayne@69: jpayne@69: // To give LocalizedNumberFormatter format methods access to this class's constructor: jpayne@69: friend class LocalizedNumberFormatter; jpayne@69: jpayne@69: // To give C API access to internals jpayne@69: friend struct impl::UFormattedNumberImpl; jpayne@69: }; jpayne@69: jpayne@69: #ifndef U_HIDE_DRAFT_API jpayne@69: // Note: This is draft ICU 65 jpayne@69: template jpayne@69: StringClass FormattedNumber::toDecimalNumber(UErrorCode& status) const { jpayne@69: StringClass result; jpayne@69: StringByteSink sink(&result); jpayne@69: toDecimalNumber(sink, status); jpayne@69: return result; jpayne@69: } jpayne@69: #endif // U_HIDE_DRAFT_API jpayne@69: jpayne@69: /** jpayne@69: * See the main description in numberformatter.h for documentation and examples. jpayne@69: * jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: class U_I18N_API NumberFormatter final { jpayne@69: public: jpayne@69: /** jpayne@69: * Call this method at the beginning of a NumberFormatter fluent chain in which the locale is not currently known at jpayne@69: * the call site. jpayne@69: * jpayne@69: * @return An {@link UnlocalizedNumberFormatter}, to be used for chaining. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: static UnlocalizedNumberFormatter with(); jpayne@69: jpayne@69: /** jpayne@69: * Call this method at the beginning of a NumberFormatter fluent chain in which the locale is known at the call jpayne@69: * site. jpayne@69: * jpayne@69: * @param locale jpayne@69: * The locale from which to load formats and symbols for number formatting. jpayne@69: * @return A {@link LocalizedNumberFormatter}, to be used for chaining. jpayne@69: * @stable ICU 60 jpayne@69: */ jpayne@69: static LocalizedNumberFormatter withLocale(const Locale &locale); jpayne@69: jpayne@69: /** jpayne@69: * Call this method at the beginning of a NumberFormatter fluent chain to create an instance based jpayne@69: * on a given number skeleton string. jpayne@69: * jpayne@69: * It is possible for an error to occur while parsing. See the overload of this method if you are jpayne@69: * interested in the location of a possible parse error. jpayne@69: * jpayne@69: * @param skeleton jpayne@69: * The skeleton string off of which to base this NumberFormatter. jpayne@69: * @param status jpayne@69: * Set to U_NUMBER_SKELETON_SYNTAX_ERROR if the skeleton was invalid. jpayne@69: * @return An UnlocalizedNumberFormatter, to be used for chaining. jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: static UnlocalizedNumberFormatter forSkeleton(const UnicodeString& skeleton, UErrorCode& status); jpayne@69: jpayne@69: /** jpayne@69: * Call this method at the beginning of a NumberFormatter fluent chain to create an instance based jpayne@69: * on a given number skeleton string. jpayne@69: * jpayne@69: * If an error occurs while parsing the skeleton string, the offset into the skeleton string at jpayne@69: * which the error occurred will be saved into the UParseError, if provided. jpayne@69: * jpayne@69: * @param skeleton jpayne@69: * The skeleton string off of which to base this NumberFormatter. jpayne@69: * @param perror jpayne@69: * A parse error struct populated if an error occurs when parsing. jpayne@69: * If no error occurs, perror.offset will be set to -1. jpayne@69: * @param status jpayne@69: * Set to U_NUMBER_SKELETON_SYNTAX_ERROR if the skeleton was invalid. jpayne@69: * @return An UnlocalizedNumberFormatter, to be used for chaining. jpayne@69: * @stable ICU 64 jpayne@69: */ jpayne@69: static UnlocalizedNumberFormatter forSkeleton(const UnicodeString& skeleton, jpayne@69: UParseError& perror, UErrorCode& status); jpayne@69: jpayne@69: /** jpayne@69: * Use factory methods instead of the constructor to create a NumberFormatter. jpayne@69: */ jpayne@69: NumberFormatter() = delete; jpayne@69: }; jpayne@69: jpayne@69: } // namespace number jpayne@69: U_NAMESPACE_END jpayne@69: jpayne@69: #endif /* #if !UCONFIG_NO_FORMATTING */ jpayne@69: jpayne@69: #endif /* U_SHOW_CPLUSPLUS_API */ jpayne@69: jpayne@69: #endif // __NUMBERFORMATTER_H__ jpayne@69: