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"

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

U_CAPI UFormattedNumberRange *	unumrf_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 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. 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

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

Namespaces

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ UFormattedNumberRange

◆ UNumberRangeCollapse

◆ UNumberRangeFormatter

◆ UNumberRangeIdentityFallback

◆ UNumberRangeIdentityResult

Enumeration Type Documentation

◆ UNumberRangeCollapse

◆ UNumberRangeIdentityFallback

◆ UNumberRangeIdentityResult

Function Documentation

◆ unumrf_close()

◆ unumrf_closeResult()

◆ unumrf_formatDecimalRange()

◆ unumrf_formatDoubleRange()

◆ unumrf_openForSkeletonWithCollapseAndIdentityFallback()

◆ unumrf_openResult()

◆ unumrf_resultAsValue()

◆ unumrf_resultGetFirstDecimalNumber()

◆ unumrf_resultGetIdentityResult()

◆ unumrf_resultGetSecondDecimalNumber()