ICU 69.1 69.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
82
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
207 #ifndef U_HIDE_DRAFT_API
208
217 UNUM_UNIT_WIDTH_FORMAL = 4,
218
228 UNUM_UNIT_WIDTH_VARIANT = 5,
229 #endif // U_HIDE_DRAFT_API
230
238 UNUM_UNIT_WIDTH_HIDDEN = 6,
239
240 // Do not conditionalize the following with #ifndef U_HIDE_INTERNAL_API,
241 // needed for unconditionalized struct MacroProps
247 UNUM_UNIT_WIDTH_COUNT = 7
248 } UNumberUnitWidth;
249
276 typedef enum UNumberGroupingStrategy {
282 UNUM_GROUPING_OFF,
283
298 UNUM_GROUPING_MIN2,
299
313 UNUM_GROUPING_AUTO,
314
329 UNUM_GROUPING_ON_ALIGNED,
330
337 UNUM_GROUPING_THOUSANDS
338
339 #ifndef U_HIDE_INTERNAL_API
340 ,
346 UNUM_GROUPING_COUNT
347 #endif /* U_HIDE_INTERNAL_API */
348
349 } UNumberGroupingStrategy;
350
370 typedef enum UNumberSignDisplay {
380 UNUM_SIGN_AUTO,
381
388 UNUM_SIGN_ALWAYS,
389
395 UNUM_SIGN_NEVER,
396
411 UNUM_SIGN_ACCOUNTING,
412
421 UNUM_SIGN_ACCOUNTING_ALWAYS,
422
429 UNUM_SIGN_EXCEPT_ZERO,
430
438 UNUM_SIGN_ACCOUNTING_EXCEPT_ZERO,
439
440 #ifndef U_HIDE_DRAFT_API
441
446 UNUM_SIGN_NEGATIVE,
447
453 UNUM_SIGN_ACCOUNTING_NEGATIVE,
454 #endif // U_HIDE_DRAFT_API
455
456 // Do not conditionalize the following with #ifndef U_HIDE_INTERNAL_API,
457 // needed for unconditionalized struct MacroProps
463 UNUM_SIGN_COUNT = 9,
464 } UNumberSignDisplay;
465
477 typedef enum UNumberDecimalSeparatorDisplay {
484 UNUM_DECIMAL_SEPARATOR_AUTO,
485
491 UNUM_DECIMAL_SEPARATOR_ALWAYS,
492
493 // Do not conditionalize the following with #ifndef U_HIDE_INTERNAL_API,
494 // needed for unconditionalized struct MacroProps
500 UNUM_DECIMAL_SEPARATOR_COUNT
501 } UNumberDecimalSeparatorDisplay;
502
503 #ifndef U_FORCE_HIDE_DRAFT_API
504
512 typedef enum UNumberTrailingZeroDisplay {
518 UNUM_TRAILING_ZERO_AUTO,
519
525 UNUM_TRAILING_ZERO_HIDE_IF_WHOLE,
526 } UNumberTrailingZeroDisplay;
527 #endif // U_FORCE_HIDE_DRAFT_API
528
529 struct UNumberFormatter;
537 typedef struct UNumberFormatter UNumberFormatter;
538
539 struct UFormattedNumber;
547 typedef struct UFormattedNumber UFormattedNumber;
548
549
570 U_CAPI UNumberFormatter* U_EXPORT2
571 unumf_openForSkeletonAndLocale(const UChar* skeleton, int32_t skeletonLen, const char* locale,
572 UErrorCode* ec);
573
574
590 U_CAPI UNumberFormatter* U_EXPORT2
591 unumf_openForSkeletonAndLocaleWithError(
592 const UChar* skeleton, int32_t skeletonLen, const char* locale, UParseError* perror, UErrorCode* ec);
593
594
603 U_CAPI UFormattedNumber* U_EXPORT2
604 unumf_openResult(UErrorCode* ec);
605
606
622 U_CAPI void U_EXPORT2
623 unumf_formatInt(const UNumberFormatter* uformatter, int64_t value, UFormattedNumber* uresult,
624 UErrorCode* ec);
625
626
642 U_CAPI void U_EXPORT2
643 unumf_formatDouble(const UNumberFormatter* uformatter, double value, UFormattedNumber* uresult,
644 UErrorCode* ec);
645
646
666 U_CAPI void U_EXPORT2
667 unumf_formatDecimal(const UNumberFormatter* uformatter, const char* value, int32_t valueLen,
668 UFormattedNumber* uresult, UErrorCode* ec);
669
684 U_CAPI const UFormattedValue* U_EXPORT2
685 unumf_resultAsValue(const UFormattedNumber* uresult, UErrorCode* ec);
686
687
707 U_CAPI int32_t U_EXPORT2
708 unumf_resultToString(const UFormattedNumber* uresult, UChar* buffer, int32_t bufferCapacity,
709 UErrorCode* ec);
710
711
745 U_CAPI UBool U_EXPORT2
746 unumf_resultNextFieldPosition(const UFormattedNumber* uresult, UFieldPosition* ufpos, UErrorCode* ec);
747
748
770 U_CAPI void U_EXPORT2
771 unumf_resultGetAllFieldPositions(const UFormattedNumber* uresult, UFieldPositionIterator* ufpositer,
772 UErrorCode* ec);
773
774
775 #ifndef U_HIDE_DRAFT_API
776
794 U_CAPI int32_t U_EXPORT2
795 unumf_resultToDecimalNumber(
796 const UFormattedNumber* uresult,
797 char* dest,
798 int32_t destCapacity,
799 UErrorCode* ec);
800 #endif // U_HIDE_DRAFT_API
801
802
809 U_CAPI void U_EXPORT2
810 unumf_close(UNumberFormatter* uformatter);
811
812
819 U_CAPI void U_EXPORT2
820 unumf_closeResult(UFormattedNumber* uresult);
821
822
823 #if U_SHOW_CPLUSPLUS_API
824 U_NAMESPACE_BEGIN
825
841 U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberFormatterPointer, UNumberFormatter, unumf_close);
842
858 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedNumberPointer, UFormattedNumber, unumf_closeResult);
859
860 U_NAMESPACE_END
861 #endif // U_SHOW_CPLUSPLUS_API
862
863 #endif /* #if !UCONFIG_NO_FORMATTING */
864 #endif //__UNUMBERFORMATTER_H__
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:228
UNUM_DECIMAL_SEPARATOR_COUNT
@ UNUM_DECIMAL_SEPARATOR_COUNT
One more than the highest UNumberDecimalSeparatorDisplay value.
Definition: unumberformatter.h:500
parseerr.h
C API: Parse Error Information.
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:438
UNUM_ROUNDING_PRIORITY_RELAXED
@ UNUM_ROUNDING_PRIORITY_RELAXED
Favor greater precision by relaxing one of the rounding constraints.
Definition: unumberformatter.h:126
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.
utypes.h
Basic definitions for ICU, for both C and C++ APIs.
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...
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_COUNT
@ UNUM_UNIT_WIDTH_COUNT
One more than the highest UNumberUnitWidth value.
Definition: unumberformatter.h:247
UBool
int8_t UBool
The ICU boolean type, a signed-byte integer.
Definition: umachine.h:269
UNumberSignDisplay
UNumberSignDisplay
An enum declaring how to denote positive and negative numbers.
Definition: unumberformatter.h:370
uformattedvalue.h
C API: Abstract operations for localized strings.
UNUM_SIGN_COUNT
@ UNUM_SIGN_COUNT
One more than the highest UNumberSignDisplay value.
Definition: unumberformatter.h:463
LocalUFormattedNumberPointer
Definition: unumberformatter.h:841
UFormattedNumber
struct UFormattedNumber UFormattedNumber
C-compatible version of icu::number::FormattedNumber.
Definition: unumberformatter.h:547
unumf_openResult
U_CAPI UFormattedNumber * unumf_openResult(UErrorCode *ec)
Creates an object to hold the result of a UNumberFormatter operation.
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:411
UNUM_ROUNDING_PRIORITY_STRICT
@ UNUM_ROUNDING_PRIORITY_STRICT
Favor adherence to all rounding constraints by producing lower precision.
Definition: unumberformatter.h:133
UFieldPositionIterator
struct UFieldPositionIterator UFieldPositionIterator
C typedef for struct UFieldPositionIterator.
Definition: ufieldpositer.h:46
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:238
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.
umisc.h
C API:misc definitions.
UParseError
A UParseError struct is used to returned detailed information about parsing errors.
Definition: parseerr.h:58
UNUM_GROUPING_COUNT
@ UNUM_GROUPING_COUNT
One more than the highest UNumberGroupingStrategy value.
Definition: unumberformatter.h:346
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.
UErrorCode
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415
UFormattedValue
struct UFormattedValue UFormattedValue
An abstract formatted value: a string with associated field attributes.
Definition: uformattedvalue.h:370
UNumberRoundingPriority
UNumberRoundingPriority
An enum declaring how to resolve conflicts between maximum fraction digits and maximum significant di...
Definition: unumberformatter.h:120
UNUM_SIGN_NEVER
@ UNUM_SIGN_NEVER
Do not show the sign on positive or negative numbers.
Definition: unumberformatter.h:395
LocalUNumberFormatterPointer
UNUM_UNIT_WIDTH_SHORT
@ UNUM_UNIT_WIDTH_SHORT
Print an abbreviated version of the unit name.
Definition: unumberformatter.h:183
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.
UNumberFormatter
struct UNumberFormatter UNumberFormatter
C-compatible version of icu::number::LocalizedNumberFormatter.
Definition: unumberformatter.h:537
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:380
UNUM_SIGN_ACCOUNTING_NEGATIVE
@ UNUM_SIGN_ACCOUNTING_NEGATIVE
Same as ACCOUNTING, but do not show the sign on negative zero.
Definition: unumberformatter.h:453
ufieldpositer.h
C API: UFieldPositionIterator for use with format APIs.
UNumberUnitWidth
UNumberUnitWidth
An enum declaring how to render units, including currencies.
Definition: unumberformatter.h:155
UNumberDecimalSeparatorDisplay
UNumberDecimalSeparatorDisplay
An enum declaring how to render the decimal separator.
Definition: unumberformatter.h:477
UNumberTrailingZeroDisplay
UNumberTrailingZeroDisplay
An enum declaring how to render trailing zeros.
Definition: unumberformatter.h:512
U_DEFINE_LOCAL_OPEN_POINTER
#define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction)
Definition: localpointer.h:550
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.
UFieldPosition
A struct representing a range of text containing a specific field.
Definition: umisc.h:34
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:388
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:484
unumf_closeResult
U_CAPI void unumf_closeResult(UFormattedNumber *uresult)
Releases the UFormattedNumber created by unumf_openResult().
UNUM_SIGN_NEGATIVE
@ UNUM_SIGN_NEGATIVE
Same as AUTO, but do not show the sign on negative zero.
Definition: unumberformatter.h:446
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:421
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:429
UNUM_GROUPING_THOUSANDS
@ UNUM_GROUPING_THOUSANDS
Use the Western defaults: groups of 3 and enabled for all numbers 1000 or greater.
Definition: unumberformatter.h:337
UNUM_UNIT_WIDTH_NARROW
@ UNUM_UNIT_WIDTH_NARROW
Print an abbreviated version of the unit name.
Definition: unumberformatter.h:167
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_GROUPING_ON_ALIGNED
@ UNUM_GROUPING_ON_ALIGNED
Always display the grouping separator on values of at least 1000.
Definition: unumberformatter.h:329
UNUM_GROUPING_OFF
@ UNUM_GROUPING_OFF
Do not display grouping separators in any locale.
Definition: unumberformatter.h:282
UNUM_TRAILING_ZERO_AUTO
@ UNUM_TRAILING_ZERO_AUTO
Display trailing zeros according to the settings for minimum fraction and significant digits.
Definition: unumberformatter.h:518
UChar
char16_t UChar
Definition: umachine.h:418
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:217
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:298
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.
UNumberGroupingStrategy
UNumberGroupingStrategy
An enum declaring the strategy for when and how to display grouping separators (i....
Definition: unumberformatter.h:276
U_CAPI
#define U_CAPI
This is used to declare a function as a public ICU C API.
Definition: umachine.h:110
unumf_resultAsValue
const U_CAPI UFormattedValue * unumf_resultAsValue(const UFormattedNumber *uresult, UErrorCode *ec)
Returns a representation of a UFormattedNumber as a UFormattedValue, which can be subsequently passed...
unumf_close
U_CAPI void unumf_close(UNumberFormatter *uformatter)
Releases the UNumberFormatter created by unumf_openForSkeletonAndLocale().
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.
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:491
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...
UNUM_GROUPING_AUTO
@ UNUM_GROUPING_AUTO
Display grouping using the default strategy for all locales.
Definition: unumberformatter.h:313
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:525