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

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

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

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

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

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

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.