ICU 63.1 63.1

Data Structures | Namespaces | Typedefs | Enumerations
numberrangeformatter.h File Reference

C++ API: Library for localized formatting of number, currency, and unit ranges. More...

`#include <atomic>`
`#include "unicode/appendable.h"`
`#include "unicode/fieldpos.h"`
`#include "unicode/fpositer.h"`
`#include "unicode/numberformatter.h"`

Go to the source code of this file.

## Data Structures
struct | icu::number::impl::RangeMacroProps
class | icu::number::NumberRangeFormatterSettings< Derived >
| An abstract base class for specifying settings related to number formatting. More...
class | icu::number::UnlocalizedNumberRangeFormatter
| A NumberRangeFormatter that does not yet have a locale. More...
class | icu::number::LocalizedNumberRangeFormatter
| A NumberRangeFormatter that has a locale associated with it; this means .formatRange() methods are available. More...
class | icu::number::FormattedNumberRange
| The result of a number range formatting operation. More...
class | icu::number::NumberRangeFormatter
| See the main description in numberrangeformatter.h for documentation and examples. More...

## Namespaces
| icu
| File coll.h.

## Typedefs
typedef enum UNumberRangeCollapse | UNumberRangeCollapse
| Defines how to merge fields that are identical across the range sign. More...
typedef enum UNumberRangeIdentityFallback | UNumberRangeIdentityFallback
| Defines the behavior when the two numbers in the range are identical after rounding. More...
typedef enum UNumberRangeIdentityResult | UNumberRangeIdentityResult
| Used in the result class FormattedNumberRange to indicate to the user whether the numbers formatted in the range were equal or not, and whether or not the identity fallback was applied. More...

## Enumerations
enum | UNumberRangeCollapse { UNUM_RANGE_COLLAPSE_AUTO, UNUM_RANGE_COLLAPSE_NONE, UNUM_RANGE_COLLAPSE_UNIT, UNUM_RANGE_COLLAPSE_ALL }
| Defines how to merge fields that are identical across the range sign. More...
enum | UNumberRangeIdentityFallback { UNUM_IDENTITY_FALLBACK_SINGLE_VALUE, UNUM_IDENTITY_FALLBACK_APPROXIMATELY_OR_SINGLE_VALUE, UNUM_IDENTITY_FALLBACK_APPROXIMATELY, UNUM_IDENTITY_FALLBACK_RANGE }
| Defines the behavior when the two numbers in the range are identical after rounding. More...
enum | UNumberRangeIdentityResult { UNUM_IDENTITY_RESULT_EQUAL_BEFORE_ROUNDING, UNUM_IDENTITY_RESULT_EQUAL_AFTER_ROUNDING, UNUM_IDENTITY_RESULT_NOT_EQUAL, UNUM_IDENTITY_RESULT_COUNT }
| Used in the result class FormattedNumberRange to indicate to the user whether the numbers formatted in the range were equal or not, and whether or not the identity fallback was applied. More...

## Detailed Description

C++ API: Library for localized formatting of number, currency, and unit ranges.

The main entrypoint to the formatting of ranges of numbers, including currencies and other units of measurement.

Usage example:

    NumberRangeFormatter::with()
        .identityFallback(UNUM_IDENTITY_FALLBACK_APPROXIMATELY_OR_SINGLE_VALUE)
        .numberFormatterFirst(NumberFormatter::with().adoptUnit(MeasureUnit::createMeter()))
        .numberFormatterSecond(NumberFormatter::with().adoptUnit(MeasureUnit::createKilometer()))
        .locale("en-GB")
        .formatRange(750, 1.2, status)
        .toString(status);
    // => "750 m - 1.2 km"

Like NumberFormatter, NumberRangeFormatter instances are immutable and thread-safe. This API is based on the fluent design pattern popularized by libraries such as Google's Guava.

Author
  Shane Carr

Definition in file numberrangeformatter.h.

## Typedef Documentation

## ◆ UNumberRangeCollapse

typedef enum UNumberRangeCollapse UNumberRangeCollapse

Defines how to merge fields that are identical across the range sign.

Draft:
  This API may be changed in the future versions and was introduced in ICU 63

## ◆ UNumberRangeIdentityFallback

typedef enum UNumberRangeIdentityFallback UNumberRangeIdentityFallback

Defines the behavior when the two numbers in the range are identical after rounding.

To programmatically detect when the identity fallback is used, compare the lower and upper BigDecimals via FormattedNumber.

Draft:
  This API may be changed in the future versions and was introduced in ICU 63

See also
  NumberRangeFormatter

## ◆ UNumberRangeIdentityResult

typedef enum UNumberRangeIdentityResult UNumberRangeIdentityResult

Used in the result class FormattedNumberRange to indicate to the user whether the numbers formatted in the range were equal or not, and whether or not the identity fallback was applied.

Draft:
  This API may be changed in the future versions and was introduced in ICU 63

See also
  NumberRangeFormatter

## Enumeration Type Documentation

## ◆ UNumberRangeCollapse

enum UNumberRangeCollapse

Defines how to merge fields that are identical across the range sign.

Draft:
  This API may be changed in the future versions and was introduced in ICU 63

Enumerator
UNUM_RANGE_COLLAPSE_AUTO | Use locale data and heuristics to determine how much of the string to collapse. Could end up collapsing none, some, or all repeated pieces in a locale-sensitive way. The heuristics used for this option are subject to change over time. Draft: This API may be changed in the future versions and was introduced in ICU 63
UNUM_RANGE_COLLAPSE_NONE | Do not collapse any part of the number. Example: "3.2 thousand kilograms – 5.3 thousand kilograms" Draft: This API may be changed in the future versions and was introduced in ICU 63
UNUM_RANGE_COLLAPSE_UNIT | Collapse the unit part of the number, but not the notation, if present. Example: "3.2 thousand – 5.3 thousand kilograms" Draft: This API may be changed in the future versions and was introduced in ICU 63
UNUM_RANGE_COLLAPSE_ALL | Collapse any field that is equal across the range sign. May introduce ambiguity on the magnitude of the number. Example: "3.2 – 5.3 thousand kilograms" Draft: This API may be changed in the future versions and was introduced in ICU 63

Definition at line 47 of file numberrangeformatter.h.

## ◆ UNumberRangeIdentityFallback

enum UNumberRangeIdentityFallback

Defines the behavior when the two numbers in the range are identical after rounding.

To programmatically detect when the identity fallback is used, compare the lower and upper BigDecimals via FormattedNumber.

Draft:
  This API may be changed in the future versions and was introduced in ICU 63

See also
  NumberRangeFormatter

Enumerator
UNUM_IDENTITY_FALLBACK_SINGLE_VALUE | Show the number as a single value rather than a range. Example: "$5" Draft: This API may be changed in the future versions and was introduced in ICU 63
UNUM_IDENTITY_FALLBACK_APPROXIMATELY_OR_SINGLE_VALUE | Show the number using a locale-sensitive approximation pattern. If the numbers were the same before rounding, show the single value. Example: "~$5" or "$5" Draft: This API may be changed in the future versions and was introduced in ICU 63
UNUM_IDENTITY_FALLBACK_APPROXIMATELY | Show the number using a locale-sensitive approximation pattern. Use the range pattern always, even if the inputs are the same. Example: "~$5" Draft: This API may be changed in the future versions and was introduced in ICU 63
UNUM_IDENTITY_FALLBACK_RANGE | Show the number as the range of two equal values. Use the range pattern always, even if the inputs are the same. Example (with RangeCollapse.NONE): "$5 – $5" Draft: This API may be changed in the future versions and was introduced in ICU 63

Definition at line 89 of file numberrangeformatter.h.

## ◆ UNumberRangeIdentityResult

enum UNumberRangeIdentityResult

Used in the result class FormattedNumberRange to indicate to the user whether the numbers formatted in the range were equal or not, and whether or not the identity fallback was applied.

Draft:
  This API may be changed in the future versions and was introduced in ICU 63

See also
  NumberRangeFormatter

Enumerator
UNUM_IDENTITY_RESULT_EQUAL_BEFORE_ROUNDING | Used to indicate that the two numbers in the range were equal, even before any rounding rules were applied. Draft: This API may be changed in the future versions and was introduced in ICU 63 See also NumberRangeFormatter
UNUM_IDENTITY_RESULT_EQUAL_AFTER_ROUNDING | Used to indicate that the two numbers in the range were equal, but only after rounding rules were applied. Draft: This API may be changed in the future versions and was introduced in ICU 63 See also NumberRangeFormatter
UNUM_IDENTITY_RESULT_NOT_EQUAL | Used to indicate that the two numbers in the range were not equal, even after rounding rules were applied. Draft: This API may be changed in the future versions and was introduced in ICU 63 See also NumberRangeFormatter
UNUM_IDENTITY_RESULT_COUNT | The number of entries in this enum. Internal: Do not use. This API is for internal use only.

Definition at line 129 of file numberrangeformatter.h.