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 | |
| icu | |
| Filecoll.h. | |
Typedefs | |
| typedef enumUNumberRangeCollapse | UNumberRangeCollapse |
| Defines how to merge fields that are identical across the range sign.More... | |
| typedef enumUNumberRangeIdentityFallback | UNumberRangeIdentityFallback |
| Defines the behavior when the two numbers in the range are identical after rounding.More... | |
| typedef enumUNumberRangeIdentityResult | 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 structUNumberRangeFormatter | UNumberRangeFormatter |
| C-compatible version oficu::number::LocalizedNumberRangeFormatter.More... | |
| typedef structUFormattedNumberRange | UFormattedNumberRange |
| C-compatible version oficu::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_CAPIUNumberRangeFormatter * | unumrf_openForSkeletonWithCollapseAndIdentityFallback (constUChar *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_CAPIUFormattedNumberRange * | unumrf_openResult (UErrorCode *ec) |
| Creates an object to hold the result of a UNumberRangeFormatter operation.More... | |
| U_CAPI void | unumrf_formatDoubleRange (constUNumberRangeFormatter *uformatter, double first, double second,UFormattedNumberRange *uresult,UErrorCode *ec) |
| Uses a UNumberRangeFormatter to format a range of doubles.More... | |
| U_CAPI void | unumrf_formatDecimalRange (constUNumberRangeFormatter *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 constUFormattedValue * | unumrf_resultAsValue (constUFormattedNumberRange *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_CAPIUNumberRangeIdentityResult | unumrf_resultGetIdentityResult (constUFormattedNumberRange *uresult,UErrorCode *ec) |
| Extracts the identity result from a UFormattedNumberRange.More... | |
| U_CAPI int32_t | unumrf_resultGetFirstDecimalNumber (constUFormattedNumberRange *uresult, char *dest, int32_t destCapacity,UErrorCode *ec) |
| Extracts the first formatted number as a decimal number.More... | |
| U_CAPI int32_t | unumrf_resultGetSecondDecimalNumber (constUFormattedNumberRange *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 byunumf_openForSkeletonAndLocale().More... | |
| U_CAPI void | unumrf_closeResult (UFormattedNumberRange *uresult) |
| Releases the UFormattedNumber created byunumf_openResult().More... | |
C API: Localized number range formatting.
This is the C-compatible version of the NumberRangeFormatter API. C++ users should includeunicode/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, seeuformattedvalue.h.
Definition in fileunumberrangeformatter.h.
| typedef structUFormattedNumberRangeUFormattedNumberRange |
C-compatible version oficu::number::FormattedNumberRange.
NOTE: This is a C-compatible API; C++ users should build againstnumberrangeformatter.h instead.
Definition at line1 of fileunumberrangeformatter.h.
| typedef enumUNumberRangeCollapseUNumberRangeCollapse |
Defines how to merge fields that are identical across the range sign.
| typedef structUNumberRangeFormatterUNumberRangeFormatter |
C-compatible version oficu::number::LocalizedNumberRangeFormatter.
NOTE: This is a C-compatible API; C++ users should build againstnumberrangeformatter.h instead.
Definition at line1 of fileunumberrangeformatter.h.
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.
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.
Defines how to merge fields that are identical across the range sign.
| 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.
|
| UNUM_RANGE_COLLAPSE_NONE | Do not collapse any part of the number. Example: "3.2 thousand kilograms – 5.3 thousand kilograms"
|
| UNUM_RANGE_COLLAPSE_UNIT | Collapse the unit part of the number, but not the notation, if present. Example: "3.2 thousand – 5.3 thousandkilograms"
|
| 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"
|
Definition at line83 of fileunumberrangeformatter.h.
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.
| Enumerator | |
|---|---|
| UNUM_IDENTITY_FALLBACK_SINGLE_VALUE | Show the number as a single value rather than a range. Example: "$5"
|
| 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"
|
| 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"
|
| 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"
|
Definition at line125 of fileunumberrangeformatter.h.
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.
| 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.
|
| 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.
|
| UNUM_IDENTITY_RESULT_NOT_EQUAL | Used to indicate that the two numbers in the range were not equal, even after rounding rules were applied.
|
| UNUM_IDENTITY_RESULT_COUNT | The number of entries in this enum.
|
Definition at line165 of fileunumberrangeformatter.h.
| U_CAPI void unumrf_close | ( | UNumberRangeFormatter * | uformatter | ) |
Releases the UNumberFormatter created byunumf_openForSkeletonAndLocale().
| uformatter | An object created byunumf_openForSkeletonAndLocale(). |
| U_CAPI void unumrf_closeResult | ( | UFormattedNumberRange * | uresult | ) |
Releases the UFormattedNumber created byunumf_openResult().
| uresult | An object created byunumf_openResult(). |
| U_CAPI void unumrf_formatDecimalRange | ( | constUNumberRangeFormatter * | 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 againstnumberrangeformatter.h instead.
| uformatter | A formatter object; seeunumberrangeformatter.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. |
| U_CAPI void unumrf_formatDoubleRange | ( | constUNumberRangeFormatter * | 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 againstnumberrangeformatter.h instead.
| uformatter | A formatter object; seeunumberrangeformatter.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. |
| U_CAPIUNumberRangeFormatter* unumrf_openForSkeletonWithCollapseAndIdentityFallback | ( | constUChar * | 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 innumberrangeformatter.h. For more details on the usage of this API, see the documentation at the top ofunumberrangeformatter.h.
NOTE: This is a C-compatible API; C++ users should build againstnumberrangeformatter.h instead.
| 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. |
| U_CAPIUFormattedNumberRange* 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.
| ec | Set if an error occurs. |
| U_CAPI constUFormattedValue* unumrf_resultAsValue | ( | constUFormattedNumberRange * | 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.
| uresult | The object containing the formatted number range. |
| ec | Set if an error occurs. |
| U_CAPI int32_t unumrf_resultGetFirstDecimalNumber | ( | constUFormattedNumberRange * | 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 athttp://speleotrove.com/decimal
| 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. |
| U_CAPIUNumberRangeIdentityResult unumrf_resultGetIdentityResult | ( | constUFormattedNumberRange * | uresult, |
| UErrorCode * | ec | ||
| ) |
Extracts the identity result from a UFormattedNumberRange.
NOTE: This is a C-compatible API; C++ users should build againstnumberformatter.h instead.
| uresult | The object containing the formatted number range. |
| ec | Set if an error occurs. |
| U_CAPI int32_t unumrf_resultGetSecondDecimalNumber | ( | constUFormattedNumberRange * | 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 athttp://speleotrove.com/decimal
| 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. |
1.9.1