ICU 74.1 74.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. 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...
 
typedef struct UNumberRangeFormatter UNumberRangeFormatter
 C-compatible version of icu::number::LocalizedNumberRangeFormatter. More...
 
typedef struct UFormattedNumberRange UFormattedNumberRange
 C-compatible version of icu::number::FormattedNumberRange. 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...
 

Functions

U_CAPI UNumberRangeFormatterunumrf_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. More...
 
U_CAPI UFormattedNumberRangeunumrf_openResult (UErrorCode *ec)
 Creates an object to hold the result of a UNumberRangeFormatter operation. More...
 
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. More...
 
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. More...
 
U_CAPI const UFormattedValueunumrf_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. More...
 
U_CAPI UNumberRangeIdentityResult unumrf_resultGetIdentityResult (const UFormattedNumberRange *uresult, UErrorCode *ec)
 Extracts the identity result from a UFormattedNumberRange. More...
 
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. More...
 
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. More...
 
U_CAPI void unumrf_close (UNumberRangeFormatter *uformatter)
 Releases the UNumberFormatter created by unumf_openForSkeletonAndLocale(). More...
 
U_CAPI void unumrf_closeResult (UFormattedNumberRange *uresult)
 Releases the UFormattedNumber created by unumf_openResult(). More...
 

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

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

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

Stable:
ICU 63

◆ 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

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

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

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

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

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
uformatterAn 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
uresultAn 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
uformatterA formatter object; see unumberrangeformatter.h.
firstThe first (usually smaller) number in the range.
firstLenThe length of the first decimal number string.
secondThe second (usually larger) number in the range.
secondLenThe length of the second decimal number string.
uresultThe object that will be mutated to store the result; see unumrf_openResult.
ecSet 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
uformatterA formatter object; see unumberrangeformatter.h.
firstThe first (usually smaller) number in the range.
secondThe second (usually larger) number in the range.
uresultThe object that will be mutated to store the result; see unumrf_openResult.
ecSet 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
skeletonThe skeleton string, like u"percent precision-integer"
skeletonLenThe number of UChars in the skeleton string, or -1 if it is NUL-terminated.
collapseOption for how to merge affixes (if unsure, use UNUM_RANGE_COLLAPSE_AUTO)
identityFallbackOption for resolving when both sides of the range are equal.
localeThe NUL-terminated locale ID.
perrorA parse error struct populated if an error occurs when parsing. Can be NULL. If no error occurs, perror->offset will be set to -1.
ecSet 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
ecSet 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
uresultThe object containing the formatted number range.
ecSet 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
uresultThe input object containing the formatted number range.
destthe 8-bit char buffer into which the decimal number is placed
destCapacityThe size, in chars, of the destination buffer. May be zero for precomputing the required size.
ecreceives 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
uresultThe object containing the formatted number range.
ecSet 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
uresultThe input object containing the formatted number range.
destthe 8-bit char buffer into which the decimal number is placed
destCapacityThe size, in chars, of the destination buffer. May be zero for precomputing the required size.
ecreceives 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