ICU 70.1 70.1

unumberformatter.h
Go to the documentation of this file.
1// © 2018 and later: Unicode, Inc. and others.
2// License & terms of use: http://www.unicode.org/copyright.html
3
4#ifndef __UNUMBERFORMATTER_H__
5#define __UNUMBERFORMATTER_H__
6
7#include "unicode/utypes.h"
8
9#if !UCONFIG_NO_FORMATTING
10
11#include "unicode/parseerr.h"
12#include "unicode/ufieldpositer.h"
13#include "unicode/umisc.h"
14#include "unicode/uformattedvalue.h"
15
16
81#ifndef U_FORCE_HIDE_DRAFT_API
120 typedef enum UNumberRoundingPriority {
126 UNUM_ROUNDING_PRIORITY_RELAXED,
127
133 UNUM_ROUNDING_PRIORITY_STRICT,
134} UNumberRoundingPriority;
135#endif // U_FORCE_HIDE_DRAFT_API
136
155 typedef enum UNumberUnitWidth {
167 UNUM_UNIT_WIDTH_NARROW = 0,
168
183 UNUM_UNIT_WIDTH_SHORT = 1,
184
194 UNUM_UNIT_WIDTH_FULL_NAME = 2,
195
205 UNUM_UNIT_WIDTH_ISO_CODE = 3,
206
216 UNUM_UNIT_WIDTH_FORMAL = 4,
217
227 UNUM_UNIT_WIDTH_VARIANT = 5,
228
236 UNUM_UNIT_WIDTH_HIDDEN = 6,
237
238 // Do not conditionalize the following with #ifndef U_HIDE_INTERNAL_API,
239 // needed for unconditionalized struct MacroProps
245 UNUM_UNIT_WIDTH_COUNT = 7
246} UNumberUnitWidth;
247
274 typedef enum UNumberGroupingStrategy {
280 UNUM_GROUPING_OFF,
281
296 UNUM_GROUPING_MIN2,
297
311 UNUM_GROUPING_AUTO,
312
327 UNUM_GROUPING_ON_ALIGNED,
328
335 UNUM_GROUPING_THOUSANDS
336
337#ifndef U_HIDE_INTERNAL_API
338 ,
344 UNUM_GROUPING_COUNT
345#endif /* U_HIDE_INTERNAL_API */
346
347} UNumberGroupingStrategy;
348
368 typedef enum UNumberSignDisplay {
378 UNUM_SIGN_AUTO,
379
386 UNUM_SIGN_ALWAYS,
387
393 UNUM_SIGN_NEVER,
394
409 UNUM_SIGN_ACCOUNTING,
410
419 UNUM_SIGN_ACCOUNTING_ALWAYS,
420
427 UNUM_SIGN_EXCEPT_ZERO,
428
436 UNUM_SIGN_ACCOUNTING_EXCEPT_ZERO,
437
438#ifndef U_HIDE_DRAFT_API
444 UNUM_SIGN_NEGATIVE,
445
451 UNUM_SIGN_ACCOUNTING_NEGATIVE,
452#endif // U_HIDE_DRAFT_API
453
454 // Do not conditionalize the following with #ifndef U_HIDE_INTERNAL_API,
455 // needed for unconditionalized struct MacroProps
461 UNUM_SIGN_COUNT = 9,
462} UNumberSignDisplay;
463
475 typedef enum UNumberDecimalSeparatorDisplay {
482 UNUM_DECIMAL_SEPARATOR_AUTO,
483
489 UNUM_DECIMAL_SEPARATOR_ALWAYS,
490
491 // Do not conditionalize the following with #ifndef U_HIDE_INTERNAL_API,
492 // needed for unconditionalized struct MacroProps
498 UNUM_DECIMAL_SEPARATOR_COUNT
499} UNumberDecimalSeparatorDisplay;
500
501#ifndef U_FORCE_HIDE_DRAFT_API
510 typedef enum UNumberTrailingZeroDisplay {
516 UNUM_TRAILING_ZERO_AUTO,
517
523 UNUM_TRAILING_ZERO_HIDE_IF_WHOLE,
524} UNumberTrailingZeroDisplay;
525#endif // U_FORCE_HIDE_DRAFT_API
526
527 struct UNumberFormatter;
535 typedef struct UNumberFormatter UNumberFormatter;
536
537 struct UFormattedNumber;
545 typedef struct UFormattedNumber UFormattedNumber;
546
547
568 U_CAPI UNumberFormatter* U_EXPORT2
569 unumf_openForSkeletonAndLocale(const UChar* skeleton, int32_t skeletonLen, const char* locale,
570 UErrorCode* ec);
571
572
588 U_CAPI UNumberFormatter* U_EXPORT2
589 unumf_openForSkeletonAndLocaleWithError(
590 const UChar* skeleton, int32_t skeletonLen, const char* locale, UParseError* perror, UErrorCode* ec);
591
592
601 U_CAPI UFormattedNumber* U_EXPORT2
602 unumf_openResult(UErrorCode* ec);
603
604
620 U_CAPI void U_EXPORT2
621 unumf_formatInt(const UNumberFormatter* uformatter, int64_t value, UFormattedNumber* uresult,
622 UErrorCode* ec);
623
624
640 U_CAPI void U_EXPORT2
641 unumf_formatDouble(const UNumberFormatter* uformatter, double value, UFormattedNumber* uresult,
642 UErrorCode* ec);
643
644
664 U_CAPI void U_EXPORT2
665 unumf_formatDecimal(const UNumberFormatter* uformatter, const char* value, int32_t valueLen,
666 UFormattedNumber* uresult, UErrorCode* ec);
667
682 U_CAPI const UFormattedValue* U_EXPORT2
683 unumf_resultAsValue(const UFormattedNumber* uresult, UErrorCode* ec);
684
685
705 U_CAPI int32_t U_EXPORT2
706 unumf_resultToString(const UFormattedNumber* uresult, UChar* buffer, int32_t bufferCapacity,
707 UErrorCode* ec);
708
709
743 U_CAPI UBool U_EXPORT2
744 unumf_resultNextFieldPosition(const UFormattedNumber* uresult, UFieldPosition* ufpos, UErrorCode* ec);
745
746
768 U_CAPI void U_EXPORT2
769 unumf_resultGetAllFieldPositions(const UFormattedNumber* uresult, UFieldPositionIterator* ufpositer,
770 UErrorCode* ec);
771
772
791 U_CAPI int32_t U_EXPORT2
792 unumf_resultToDecimalNumber(
793 const UFormattedNumber* uresult,
794 char* dest,
795 int32_t destCapacity,
796 UErrorCode* ec);
797
798
805 U_CAPI void U_EXPORT2
806 unumf_close(UNumberFormatter* uformatter);
807
808
815 U_CAPI void U_EXPORT2
816 unumf_closeResult(UFormattedNumber* uresult);
817
818
819#if U_SHOW_CPLUSPLUS_API
820U_NAMESPACE_BEGIN
821
837 U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberFormatterPointer, UNumberFormatter, unumf_close);
838
854 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedNumberPointer, UFormattedNumber, unumf_closeResult);
855
856U_NAMESPACE_END
857#endif // U_SHOW_CPLUSPLUS_API
858
859#endif /* #if !UCONFIG_NO_FORMATTING */
860#endif //__UNUMBERFORMATTER_H__
LocalUFormattedNumberPointer
"Smart pointer" class; closes a UFormattedNumber via unumf_closeResult().
Definition: unumberrangeformatter.h:448
LocalUNumberFormatterPointer
"Smart pointer" class; closes a UNumberFormatter via unumf_close().
U_DEFINE_LOCAL_OPEN_POINTER
#define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction)
"Smart pointer" definition macro, deletes objects via the closeFunction.
Definition: localpointer.h:550
parseerr.h
C API: Parse Error Information.
UFieldPosition
A struct representing a range of text containing a specific field.
Definition: umisc.h:34
UParseError
A UParseError struct is used to returned detailed information about parsing errors.
Definition: parseerr.h:58
ufieldpositer.h
C API: UFieldPositionIterator for use with format APIs.
UFieldPositionIterator
struct UFieldPositionIterator UFieldPositionIterator
C typedef for struct UFieldPositionIterator.
Definition: ufieldpositer.h:46
uformattedvalue.h
C API: Abstract operations for localized strings.
UFormattedValue
struct UFormattedValue UFormattedValue
An abstract formatted value: a string with associated field attributes.
Definition: uformattedvalue.h:370
UBool
int8_t UBool
The ICU boolean type, a signed-byte integer.
Definition: umachine.h:269
U_CAPI
#define U_CAPI
This is used to declare a function as a public ICU C API.
Definition: umachine.h:110
UChar
char16_t UChar
The base type for UTF-16 code units and pointers.
Definition: umachine.h:418
umisc.h
C API:misc definitions.
UNumberRoundingPriority
UNumberRoundingPriority
An enum declaring how to resolve conflicts between maximum fraction digits and maximum significant di...
Definition: unumberformatter.h:120
UNUM_ROUNDING_PRIORITY_RELAXED
@ UNUM_ROUNDING_PRIORITY_RELAXED
Favor greater precision by relaxing one of the rounding constraints.
Definition: unumberformatter.h:126
UNUM_ROUNDING_PRIORITY_STRICT
@ UNUM_ROUNDING_PRIORITY_STRICT
Favor adherence to all rounding constraints by producing lower precision.
Definition: unumberformatter.h:133
UNumberSignDisplay
UNumberSignDisplay
An enum declaring how to denote positive and negative numbers.
Definition: unumberformatter.h:368
UNUM_SIGN_ALWAYS
@ UNUM_SIGN_ALWAYS
Show the minus sign on negative numbers and the plus sign on positive numbers, including zero.
Definition: unumberformatter.h:386
UNUM_SIGN_ACCOUNTING_EXCEPT_ZERO
@ UNUM_SIGN_ACCOUNTING_EXCEPT_ZERO
Use the locale-dependent accounting format on negative numbers, and show the plus sign on positive nu...
Definition: unumberformatter.h:436
UNUM_SIGN_ACCOUNTING_NEGATIVE
@ UNUM_SIGN_ACCOUNTING_NEGATIVE
Same as ACCOUNTING, but do not show the sign on negative zero.
Definition: unumberformatter.h:451
UNUM_SIGN_AUTO
@ UNUM_SIGN_AUTO
Show the minus sign on negative numbers, and do not show the sign on positive numbers.
Definition: unumberformatter.h:378
UNUM_SIGN_ACCOUNTING
@ UNUM_SIGN_ACCOUNTING
Use the locale-dependent accounting format on negative numbers, and do not show the sign on positive ...
Definition: unumberformatter.h:409
UNUM_SIGN_NEVER
@ UNUM_SIGN_NEVER
Do not show the sign on positive or negative numbers.
Definition: unumberformatter.h:393
UNUM_SIGN_ACCOUNTING_ALWAYS
@ UNUM_SIGN_ACCOUNTING_ALWAYS
Use the locale-dependent accounting format on negative numbers, and show the plus sign on positive nu...
Definition: unumberformatter.h:419
UNUM_SIGN_EXCEPT_ZERO
@ UNUM_SIGN_EXCEPT_ZERO
Show the minus sign on negative numbers and the plus sign on positive numbers.
Definition: unumberformatter.h:427
UNUM_SIGN_NEGATIVE
@ UNUM_SIGN_NEGATIVE
Same as AUTO, but do not show the sign on negative zero.
Definition: unumberformatter.h:444
UNUM_SIGN_COUNT
@ UNUM_SIGN_COUNT
One more than the highest UNumberSignDisplay value.
Definition: unumberformatter.h:461
UNumberDecimalSeparatorDisplay
UNumberDecimalSeparatorDisplay
An enum declaring how to render the decimal separator.
Definition: unumberformatter.h:475
UNUM_DECIMAL_SEPARATOR_COUNT
@ UNUM_DECIMAL_SEPARATOR_COUNT
One more than the highest UNumberDecimalSeparatorDisplay value.
Definition: unumberformatter.h:498
UNUM_DECIMAL_SEPARATOR_AUTO
@ UNUM_DECIMAL_SEPARATOR_AUTO
Show the decimal separator when there are one or more digits to display after the separator,...
Definition: unumberformatter.h:482
UNUM_DECIMAL_SEPARATOR_ALWAYS
@ UNUM_DECIMAL_SEPARATOR_ALWAYS
Always show the decimal separator, even if there are no digits to display after the separator.
Definition: unumberformatter.h:489
UNumberTrailingZeroDisplay
UNumberTrailingZeroDisplay
An enum declaring how to render trailing zeros.
Definition: unumberformatter.h:510
UNUM_TRAILING_ZERO_AUTO
@ UNUM_TRAILING_ZERO_AUTO
Display trailing zeros according to the settings for minimum fraction and significant digits.
Definition: unumberformatter.h:516
UNUM_TRAILING_ZERO_HIDE_IF_WHOLE
@ UNUM_TRAILING_ZERO_HIDE_IF_WHOLE
Same as AUTO, but hide trailing zeros after the decimal separator if they are all zero.
Definition: unumberformatter.h:523
unumf_closeResult
U_CAPI void unumf_closeResult(UFormattedNumber *uresult)
Releases the UFormattedNumber created by unumf_openResult().
unumf_openForSkeletonAndLocale
U_CAPI UNumberFormatter * unumf_openForSkeletonAndLocale(const UChar *skeleton, int32_t skeletonLen, const char *locale, UErrorCode *ec)
Creates a new UNumberFormatter for the given skeleton string and locale.
unumf_formatDouble
U_CAPI void unumf_formatDouble(const UNumberFormatter *uformatter, double value, UFormattedNumber *uresult, UErrorCode *ec)
Uses a UNumberFormatter to format a double to a UFormattedNumber.
UNumberUnitWidth
UNumberUnitWidth
An enum declaring how to render units, including currencies.
Definition: unumberformatter.h:155
UNUM_UNIT_WIDTH_HIDDEN
@ UNUM_UNIT_WIDTH_HIDDEN
Format the number according to the specified unit, but do not display the unit.
Definition: unumberformatter.h:236
UNUM_UNIT_WIDTH_FULL_NAME
@ UNUM_UNIT_WIDTH_FULL_NAME
Print the full name of the unit, without any abbreviations.
Definition: unumberformatter.h:194
UNUM_UNIT_WIDTH_FORMAL
@ UNUM_UNIT_WIDTH_FORMAL
Use the formal variant of the currency symbol; for example, "NT$" for the New Taiwan dollar in zh-TW.
Definition: unumberformatter.h:216
UNUM_UNIT_WIDTH_NARROW
@ UNUM_UNIT_WIDTH_NARROW
Print an abbreviated version of the unit name.
Definition: unumberformatter.h:167
UNUM_UNIT_WIDTH_VARIANT
@ UNUM_UNIT_WIDTH_VARIANT
Use the alternate variant of the currency symbol; for example, "TL" for the Turkish lira (TRY).
Definition: unumberformatter.h:227
UNUM_UNIT_WIDTH_ISO_CODE
@ UNUM_UNIT_WIDTH_ISO_CODE
Use the three-digit ISO XXX code in place of the symbol for displaying currencies.
Definition: unumberformatter.h:205
UNUM_UNIT_WIDTH_SHORT
@ UNUM_UNIT_WIDTH_SHORT
Print an abbreviated version of the unit name.
Definition: unumberformatter.h:183
UNUM_UNIT_WIDTH_COUNT
@ UNUM_UNIT_WIDTH_COUNT
One more than the highest UNumberUnitWidth value.
Definition: unumberformatter.h:245
unumf_formatDecimal
U_CAPI void unumf_formatDecimal(const UNumberFormatter *uformatter, const char *value, int32_t valueLen, UFormattedNumber *uresult, UErrorCode *ec)
Uses a UNumberFormatter to format a decimal number to a UFormattedNumber.
unumf_formatInt
U_CAPI void unumf_formatInt(const UNumberFormatter *uformatter, int64_t value, UFormattedNumber *uresult, UErrorCode *ec)
Uses a UNumberFormatter to format an integer to a UFormattedNumber.
UNumberFormatter
struct UNumberFormatter UNumberFormatter
C-compatible version of icu::number::LocalizedNumberFormatter.
Definition: unumberformatter.h:535
unumf_close
U_CAPI void unumf_close(UNumberFormatter *uformatter)
Releases the UNumberFormatter created by unumf_openForSkeletonAndLocale().
UFormattedNumber
struct UFormattedNumber UFormattedNumber
C-compatible version of icu::number::FormattedNumber.
Definition: unumberformatter.h:545
unumf_openForSkeletonAndLocaleWithError
U_CAPI UNumberFormatter * unumf_openForSkeletonAndLocaleWithError(const UChar *skeleton, int32_t skeletonLen, const char *locale, UParseError *perror, UErrorCode *ec)
Like unumf_openForSkeletonAndLocale, but accepts a UParseError, which will be populated with the loca...
unumf_resultAsValue
U_CAPI const UFormattedValue * unumf_resultAsValue(const UFormattedNumber *uresult, UErrorCode *ec)
Returns a representation of a UFormattedNumber as a UFormattedValue, which can be subsequently passed...
unumf_resultToDecimalNumber
U_CAPI int32_t unumf_resultToDecimalNumber(const UFormattedNumber *uresult, char *dest, int32_t destCapacity, UErrorCode *ec)
Extracts the formatted number as a "numeric string" conforming to the syntax defined in the Decimal A...
unumf_resultToString
U_CAPI int32_t unumf_resultToString(const UFormattedNumber *uresult, UChar *buffer, int32_t bufferCapacity, UErrorCode *ec)
Extracts the result number string out of a UFormattedNumber to a UChar buffer if possible.
unumf_openResult
U_CAPI UFormattedNumber * unumf_openResult(UErrorCode *ec)
Creates an object to hold the result of a UNumberFormatter operation.
unumf_resultNextFieldPosition
U_CAPI UBool unumf_resultNextFieldPosition(const UFormattedNumber *uresult, UFieldPosition *ufpos, UErrorCode *ec)
Determines the start and end indices of the next occurrence of the given field in the output string.
UNumberGroupingStrategy
UNumberGroupingStrategy
An enum declaring the strategy for when and how to display grouping separators (i....
Definition: unumberformatter.h:274
UNUM_GROUPING_THOUSANDS
@ UNUM_GROUPING_THOUSANDS
Use the Western defaults: groups of 3 and enabled for all numbers 1000 or greater.
Definition: unumberformatter.h:335
UNUM_GROUPING_MIN2
@ UNUM_GROUPING_MIN2
Display grouping using locale defaults, except do not show grouping on values smaller than 10000 (suc...
Definition: unumberformatter.h:296
UNUM_GROUPING_ON_ALIGNED
@ UNUM_GROUPING_ON_ALIGNED
Always display the grouping separator on values of at least 1000.
Definition: unumberformatter.h:327
UNUM_GROUPING_AUTO
@ UNUM_GROUPING_AUTO
Display grouping using the default strategy for all locales.
Definition: unumberformatter.h:311
UNUM_GROUPING_OFF
@ UNUM_GROUPING_OFF
Do not display grouping separators in any locale.
Definition: unumberformatter.h:280
UNUM_GROUPING_COUNT
@ UNUM_GROUPING_COUNT
One more than the highest UNumberGroupingStrategy value.
Definition: unumberformatter.h:344
unumf_resultGetAllFieldPositions
U_CAPI void unumf_resultGetAllFieldPositions(const UFormattedNumber *uresult, UFieldPositionIterator *ufpositer, UErrorCode *ec)
Populates the given iterator with all fields in the formatted output string.
utypes.h
Basic definitions for ICU, for both C and C++ APIs.
UErrorCode
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415