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

ICU 76.1 76.1

Namespaces | Typedefs | Enumerations | Functions
unumberrangeformatter.h File Reference

C API: Localized number range formatting. More...

`#include "unicode/utypes.h"`
`#include "unicode/parseerr.h"`
`#include "unicode/ufieldpositer.h"`
`#include "unicode/umisc.h"`
`#include "unicode/uformattedvalue.h"`
`#include "unicode/uformattable.h"`

Go to the source code of this file.

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

## Typedefs
typedef enum UNumberRangeCollapse | UNumberRangeCollapse
| Defines how to merge fields that are identical across the range sign.
typedef enum UNumberRangeIdentityFallback | UNumberRangeIdentityFallback
| Defines the behavior when the two numbers in the range are identical after rounding.
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.
typedef struct UNumberRangeFormatter | UNumberRangeFormatter
| C-compatible version of icu::number::LocalizedNumberRangeFormatter.
typedef struct UFormattedNumberRange | UFormattedNumberRange
| C-compatible version of icu::number::FormattedNumberRange.

## 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...

## Functions
U_CAPI UNumberRangeFormatter * | unumrf_openForSkeletonWithCollapseAndIdentityFallback (const UChar *skeleton, int32_t skeletonLen, UNumberRangeCollapse collapse, UNumberRangeIdentityFallback identityFallback, const char *locale, UParseError *perror, UErrorCode *ec)
| Creates a new UNumberFormatter for the given skeleton string, collapse option, identity fallback option, and locale.
U_CAPI UFormattedNumberRange * | unumrf_openResult (UErrorCode *ec)
| Creates an object to hold the result of a UNumberRangeFormatter operation.
U_CAPI void | unumrf_formatDoubleRange (const UNumberRangeFormatter *uformatter, double first, double second, UFormattedNumberRange *uresult, UErrorCode *ec)
| Uses a UNumberRangeFormatter to format a range of doubles.
U_CAPI void | unumrf_formatDecimalRange (const UNumberRangeFormatter *uformatter, const char *first, int32_t firstLen, const char *second, int32_t secondLen, UFormattedNumberRange *uresult, UErrorCode *ec)
| Uses a UNumberRangeFormatter to format a range of decimal numbers.
U_CAPI const UFormattedValue * | unumrf_resultAsValue (const UFormattedNumberRange *uresult, UErrorCode *ec)
| Returns a representation of a UFormattedNumberRange as a UFormattedValue, which can be subsequently passed to any API requiring that type.
U_CAPI UNumberRangeIdentityResult | unumrf_resultGetIdentityResult (const UFormattedNumberRange *uresult, UErrorCode *ec)
| Extracts the identity result from a UFormattedNumberRange.
U_CAPI int32_t | unumrf_resultGetFirstDecimalNumber (const UFormattedNumberRange *uresult, char *dest, int32_t destCapacity, UErrorCode *ec)
| Extracts the first formatted number as a decimal number.
U_CAPI int32_t | unumrf_resultGetSecondDecimalNumber (const UFormattedNumberRange *uresult, char *dest, int32_t destCapacity, UErrorCode *ec)
| Extracts the second formatted number as a decimal number.
U_CAPI void | unumrf_close (UNumberRangeFormatter *uformatter)
| Releases the UNumberFormatter created by unumf_openForSkeletonAndLocale().
U_CAPI void | unumrf_closeResult (UFormattedNumberRange *uresult)
| Releases the UFormattedNumber created by unumf_openResult().

## Detailed Description

C API: Localized number range formatting.

This is the C-compatible version of the NumberRangeFormatter API. C++ users should include unicode/numberrangeformatter.h and use the proper C++ APIs.

First create a UNumberRangeFormatter, which is immutable, and then format to a UFormattedNumberRange.

Example code:

    // Setup:
    UErrorCode ec = U_ZERO_ERROR;
    UNumberRangeFormatter* uformatter = unumrf_openForSkeletonCollapseIdentityFallbackAndLocaleWithError(
        u"currency/USD precision-integer",
        -1,
        UNUM_RANGE_COLLAPSE_AUTO,
        UNUM_IDENTITY_FALLBACK_APPROXIMATELY,
        "en-US",
        NULL,
        &ec);
    UFormattedNumberRange* uresult = unumrf_openResult(&ec);
    if (U_FAILURE(ec)) { return; }

    // Format a double range:
    unumrf_formatDoubleRange(uformatter, 3.0, 5.0, uresult, &ec);
    if (U_FAILURE(ec)) { return; }

    // Get the result string:
    int32_t len;
    const UChar* str = ufmtval_getString(unumrf_resultAsValue(uresult, &ec), &len, &ec);
    if (U_FAILURE(ec)) { return; }
    // str should equal "$3 – $5"

    // Cleanup:
    unumf_close(uformatter);
    unumf_closeResult(uresult);

If you are a C++ user linking against the C libraries, you can use the LocalPointer versions of these APIs. The following example uses LocalPointer with the decimal number and field position APIs:

    // Setup:
    LocalUNumberRangeFormatterPointer uformatter(
        unumrf_openForSkeletonCollapseIdentityFallbackAndLocaleWithError(...));
    LocalUFormattedNumberRangePointer uresult(unumrf_openResult(&ec));
    if (U_FAILURE(ec)) { return; }

    // Format a double number range:
    unumrf_formatDoubleRange(uformatter.getAlias(), 3.0, 5.0, uresult.getAlias(), &ec);
    if (U_FAILURE(ec)) { return; }

    // No need to do any cleanup since we are using LocalPointer.

You can also get field positions. For more information, see uformattedvalue.h.

Definition in file unumberrangeformatter.h.

## Typedef Documentation

## ◆ UFormattedNumberRange

typedef struct UFormattedNumberRange UFormattedNumberRange

C-compatible version of icu::number::FormattedNumberRange.

NOTE: This is a C-compatible API; C++ users should build against numberrangeformatter.h instead.

Stable
  ICU 68

Definition at line 220 of file unumberrangeformatter.h.

## ◆ UNumberRangeCollapse

typedef enum UNumberRangeCollapse UNumberRangeCollapse

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

Stable
  ICU 63

## ◆ UNumberRangeFormatter

typedef struct UNumberRangeFormatter UNumberRangeFormatter

C-compatible version of icu::number::LocalizedNumberRangeFormatter.

NOTE: This is a C-compatible API; C++ users should build against numberrangeformatter.h instead.

Stable
  ICU 68

Definition at line 209 of file unumberrangeformatter.h.

## ◆ 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.

Stable
  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.

Stable
  ICU 63

See also
  NumberRangeFormatter

## Enumeration Type Documentation

## ◆ UNumberRangeCollapse

enum UNumberRangeCollapse

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

Stable
  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. Stable ICU 63
UNUM_RANGE_COLLAPSE_NONE | Do not collapse any part of the number. Example: "3.2 thousand kilograms – 5.3 thousand kilograms" Stable 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" Stable 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" Stable ICU 63

Definition at line 83 of file unumberrangeformatter.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.

Stable
  ICU 63

See also
  NumberRangeFormatter

Enumerator
UNUM_IDENTITY_FALLBACK_SINGLE_VALUE | Show the number as a single value rather than a range. Example: "$5" Stable 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" Stable 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" Stable 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" Stable ICU 63

Definition at line 125 of file unumberrangeformatter.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.

Stable
  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. Stable 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. Stable 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. Stable 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 165 of file unumberrangeformatter.h.

## Function Documentation

## ◆ unumrf_close()

U_CAPI void unumrf_close | ( | UNumberRangeFormatter * | uformatter | ) |

Releases the UNumberFormatter created by unumf_openForSkeletonAndLocale().

Parameters

  uformatter | An object created by unumf_openForSkeletonAndLocale().

Stable
  ICU 68

## ◆ unumrf_closeResult()

U_CAPI void unumrf_closeResult | ( | UFormattedNumberRange * | uresult | ) |

Releases the UFormattedNumber created by unumf_openResult().

Parameters

  uresult | An object created by unumf_openResult().

Stable
  ICU 68

## ◆ unumrf_formatDecimalRange()

U_CAPI void unumrf_formatDecimalRange | ( | const UNumberRangeFormatter * | uformatter,
|  | const char * | first,
|  | int32_t | firstLen,
|  | const char * | second,
|  | int32_t | secondLen,
|  | UFormattedNumberRange * | uresult,
|  | UErrorCode * | ec )

Uses a UNumberRangeFormatter to format a range of decimal numbers.

With a decimal number string, you can specify an input with arbitrary precision.

The UNumberRangeFormatter can be shared between threads. Each thread should have its own local UFormattedNumberRange, however, for storing the result of the formatting operation.

NOTE: This is a C-compatible API; C++ users should build against numberrangeformatter.h instead.

Parameters

  uformatter | A formatter object; see unumberrangeformatter.h.
  first | The first (usually smaller) number in the range.
  firstLen | The length of the first decimal number string.
  second | The second (usually larger) number in the range.
  secondLen | The length of the second decimal number string.
  uresult | The object that will be mutated to store the result; see unumrf_openResult.
  ec | Set if an error occurs.

Stable
  ICU 68

## ◆ unumrf_formatDoubleRange()

U_CAPI void unumrf_formatDoubleRange | ( | const UNumberRangeFormatter * | uformatter,
|  | double | first,
|  | double | second,
|  | UFormattedNumberRange * | uresult,
|  | UErrorCode * | ec )

Uses a UNumberRangeFormatter to format a range of doubles.

The UNumberRangeFormatter can be shared between threads. Each thread should have its own local UFormattedNumberRange, however, for storing the result of the formatting operation.

NOTE: This is a C-compatible API; C++ users should build against numberrangeformatter.h instead.

Parameters

  uformatter | A formatter object; see unumberrangeformatter.h.
  first | The first (usually smaller) number in the range.
  second | The second (usually larger) number in the range.
  uresult | The object that will be mutated to store the result; see unumrf_openResult.
  ec | Set if an error occurs.

Stable
  ICU 68

## ◆ unumrf_openForSkeletonWithCollapseAndIdentityFallback()

U_CAPI UNumberRangeFormatter * unumrf_openForSkeletonWithCollapseAndIdentityFallback | ( | const UChar * | skeleton,
|  | int32_t | skeletonLen,
|  | UNumberRangeCollapse | collapse,
|  | UNumberRangeIdentityFallback | identityFallback,
|  | const char * | locale,
|  | UParseError * | perror,
|  | UErrorCode * | ec )

Creates a new UNumberFormatter for the given skeleton string, collapse option, identity fallback option, and locale.

This is currently the only method for creating a new UNumberRangeFormatter.

Objects of type UNumberRangeFormatter returned by this method are threadsafe.

For more details on skeleton strings, see the documentation in numberrangeformatter.h. For more details on the usage of this API, see the documentation at the top of unumberrangeformatter.h.

NOTE: This is a C-compatible API; C++ users should build against numberrangeformatter.h instead.

Parameters

  skeleton | The skeleton string, like u"percent precision-integer"
  skeletonLen | The number of UChars in the skeleton string, or -1 if it is NUL-terminated.
  collapse | Option for how to merge affixes (if unsure, use UNUM_RANGE_COLLAPSE_AUTO)
  identityFallback | Option for resolving when both sides of the range are equal.
  locale | The NUL-terminated locale ID.
  perror | A parse error struct populated if an error occurs when parsing. Can be NULL. If no error occurs, perror->offset will be set to -1.
  ec | Set if an error occurs.

Stable
  ICU 68

## ◆ unumrf_openResult()

U_CAPI UFormattedNumberRange * unumrf_openResult | ( | UErrorCode * | ec | ) |

Creates an object to hold the result of a UNumberRangeFormatter operation.

The object can be used repeatedly; it is cleared whenever passed to a format function.

Parameters

  ec | Set if an error occurs.

Stable
  ICU 68

## ◆ unumrf_resultAsValue()

U_CAPI const UFormattedValue * unumrf_resultAsValue | ( | const UFormattedNumberRange * | uresult,
|  | UErrorCode * | ec )

Returns a representation of a UFormattedNumberRange as a UFormattedValue, which can be subsequently passed to any API requiring that type.

The returned object is owned by the UFormattedNumberRange and is valid only as long as the UFormattedNumber is present and unchanged in memory.

You can think of this method as a cast between types.

Parameters

  uresult | The object containing the formatted number range.
  ec | Set if an error occurs.

Returns
  A UFormattedValue owned by the input object.

Stable
  ICU 68

## ◆ unumrf_resultGetFirstDecimalNumber()

U_CAPI int32_t unumrf_resultGetFirstDecimalNumber | ( | const UFormattedNumberRange * | uresult,
|  | char * | dest,
|  | int32_t | destCapacity,
|  | UErrorCode * | ec )

Extracts the first formatted number as a decimal number.

This endpoint is useful for obtaining the exact number being printed after scaling and rounding have been applied by the number range formatting pipeline.

The syntax of the unformatted number is a "numeric string" as defined in the Decimal Arithmetic Specification, available at http://speleotrove.com/decimal

Parameters

  uresult | The input object containing the formatted number range.
  dest | the 8-bit char buffer into which the decimal number is placed
  destCapacity | The size, in chars, of the destination buffer. May be zero for precomputing the required size.
  ec | receives any error status. If U_BUFFER_OVERFLOW_ERROR: Returns number of chars for preflighting.

Returns
  Number of chars in the data. Does not include a trailing NUL.

Stable
  ICU 68

## ◆ unumrf_resultGetIdentityResult()

U_CAPI UNumberRangeIdentityResult unumrf_resultGetIdentityResult | ( | const UFormattedNumberRange * | uresult,
|  | UErrorCode * | ec )

Extracts the identity result from a UFormattedNumberRange.

NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead.

Parameters

  uresult | The object containing the formatted number range.
  ec | Set if an error occurs.

Returns
  The identity result; see UNumberRangeIdentityResult.

Stable
  ICU 68

## ◆ unumrf_resultGetSecondDecimalNumber()

U_CAPI int32_t unumrf_resultGetSecondDecimalNumber | ( | const UFormattedNumberRange * | uresult,
|  | char * | dest,
|  | int32_t | destCapacity,
|  | UErrorCode * | ec )

Extracts the second formatted number as a decimal number.

This endpoint is useful for obtaining the exact number being printed after scaling and rounding have been applied by the number range formatting pipeline.

The syntax of the unformatted number is a "numeric string" as defined in the Decimal Arithmetic Specification, available at http://speleotrove.com/decimal

Parameters

  uresult | The input object containing the formatted number range.
  dest | the 8-bit char buffer into which the decimal number is placed
  destCapacity | The size, in chars, of the destination buffer. May be zero for precomputing the required size.
  ec | receives any error status. If U_BUFFER_OVERFLOW_ERROR: Returns number of chars for preflighting.

Returns
  Number of chars in the data. Does not include a trailing NUL.

Stable
  ICU 68