ICU 76.1: i18n/unicode/numberformatter.h File Reference

ICU 76.1 76.1

Data Structures | Namespaces | Typedefs | Functions
numberformatter.h File Reference

C++ API: All-in-one formatter for localized numbers, currencies, and units. More...

`#include "unicode/utypes.h"`
`#include "unicode/appendable.h"`
`#include "unicode/bytestream.h"`
`#include "unicode/currunit.h"`
`#include "unicode/dcfmtsym.h"`
`#include "unicode/displayoptions.h"`
`#include "unicode/fieldpos.h"`
`#include "unicode/fpositer.h"`
`#include "unicode/measunit.h"`
`#include "unicode/nounit.h"`
`#include "unicode/parseerr.h"`
`#include "unicode/plurrule.h"`
`#include "unicode/ucurr.h"`
`#include "unicode/unum.h"`
`#include "unicode/unumberformatter.h"`
`#include "unicode/uobject.h"`
`#include "unicode/unumberoptions.h"`
`#include "unicode/formattednumber.h"`

Go to the source code of this file.

## Data Structures
class | icu::number::Notation
| A class that defines the notation style to be used when formatting numbers in NumberFormatter. More...
struct | icu::number::Notation::NotationUnion::ScientificSettings
class | icu::number::ScientificNotation
| A class that defines the scientific notation style to be used when formatting numbers in NumberFormatter. More...
class | icu::number::Precision
| A class that defines the rounding precision to be used when formatting numbers in NumberFormatter. More...
struct | icu::number::Precision::PrecisionUnion::FractionSignificantSettings
struct | icu::number::Precision::PrecisionUnion::IncrementSettings
class | icu::number::FractionPrecision
| A class that defines a rounding precision based on a number of fraction places and optionally significant digits to be used when formatting numbers in NumberFormatter. More...
class | icu::number::CurrencyPrecision
| A class that defines a rounding precision parameterized by a currency to be used when formatting numbers in NumberFormatter. More...
class | icu::number::IncrementPrecision
| A class that defines a rounding precision parameterized by a rounding increment to be used when formatting numbers in NumberFormatter. More...
class | icu::number::IntegerWidth
| A class that defines the strategy for padding and truncating integers before the decimal separator. More...
class | icu::number::Scale
| A class that defines a quantity by which a number should be multiplied when formatting. More...
class | icu::number::impl::StringProp
| Manages NumberFormatterSettings::usage()'s char* instance on the heap. More...
class | icu::number::impl::SymbolsWrapper
class | icu::number::impl::Grouper
class | icu::number::impl::Padder
struct | icu::number::impl::MacroProps
class | icu::number::NumberFormatterSettings< Derived >
| An abstract base class for specifying settings related to number formatting. More...
class | icu::number::UnlocalizedNumberFormatter
| A NumberFormatter that does not yet have a locale. More...
class | icu::number::LocalizedNumberFormatter
| A NumberFormatter that has a locale associated with it; this means .format() methods are available. More...
class | icu::number::NumberFormatter
| See the main description in numberformatter.h for documentation and examples. More...

## Namespaces
namespace | icu
| File coll.h.

## Typedefs
typedef int16_t | icu::number::impl::digits_t
| Datatype for minimum/maximum fraction digits.
typedef Notation | icu::number::CompactNotation
| Extra name reserved in case it is needed in the future.
typedef Notation | icu::number::SimpleNotation
| Extra name reserved in case it is needed in the future.
typedef Precision | icu::number::SignificantDigitsPrecision
| Extra name reserved in case it is needed in the future.

## Functions
void | icu::number::impl::touchRangeLocales (impl::RangeMacroProps &macros)
| Used for NumberRangeFormatter and implemented in numrange_fluent.cpp.

## Detailed Description

C++ API: All-in-one formatter for localized numbers, currencies, and units.

For a full list of options, see icu::number::NumberFormatterSettings.

    // Most basic usage:
    NumberFormatter::withLocale(...).format(123).toString();  // 1,234 in en-US

    // Custom notation, unit, and rounding precision:
    NumberFormatter::with()
        .notation(Notation::compactShort())
        .unit(CurrencyUnit("EUR", status))
        .precision(Precision::maxDigits(2))
        .locale(...)
        .format(1234)
        .toString();  // €1.2K in en-US

    // Create a formatter in a singleton by value for use later:
    static const LocalizedNumberFormatter formatter = NumberFormatter::withLocale(...)
        .unit(NoUnit::percent())
        .precision(Precision::fixedFraction(3));
    formatter.format(5.9831).toString();  // 5.983% in en-US

    // Create a "template" in a singleton unique_ptr but without setting a locale until the call site:
    std::unique_ptr<UnlocalizedNumberFormatter> template = NumberFormatter::with()
        .sign(UNumberSignDisplay::UNUM_SIGN_ALWAYS)
        .unit(MeasureUnit::getMeter())
        .unitWidth(UNumberUnitWidth::UNUM_UNIT_WIDTH_FULL_NAME)
        .clone();
    template->locale(...).format(1234).toString();  // +1,234 meters in en-US

This API offers more features than DecimalFormat and is geared toward new users of ICU.

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

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

This API is based on the fluent design pattern popularized by libraries such as Google's Guava. For extensive details on the design of this API, read the design doc.

Note: To format monetary/currency values, specify the currency in the `.unit()` function.

Author
  Shane Carr

Definition in file numberformatter.h.

## Typedef Documentation

## ◆ CompactNotation

typedef Notation icu::number::CompactNotation

Extra name reserved in case it is needed in the future.

Stable
  ICU 63

Definition at line 189 of file numberformatter.h.

## ◆ digits_t

typedef int16_t icu::number::impl::digits_t

Datatype for minimum/maximum fraction digits.

Must be able to hold kMaxIntFracSig.

Internal
  Do not use. This API is for internal use only.

Definition at line 134 of file numberformatter.h.

## ◆ SignificantDigitsPrecision

typedef Precision icu::number::SignificantDigitsPrecision

Extra name reserved in case it is needed in the future.

Stable
  ICU 63

Definition at line 464 of file numberformatter.h.

## ◆ SimpleNotation

typedef Notation icu::number::SimpleNotation

Extra name reserved in case it is needed in the future.

Stable
  ICU 63

Definition at line 196 of file numberformatter.h.

## Function Documentation

## ◆ touchRangeLocales()

void icu::number::impl::touchRangeLocales | ( | impl::RangeMacroProps & | macros | ) |

Used for NumberRangeFormatter and implemented in numrange_fluent.cpp.

Declared here so it can be friended.

Internal
  Do not use. This API is for internal use only.

References icu::number::impl::touchRangeLocales().

Referenced by icu::number::impl::touchRangeLocales().