ICU 71.1: unumberformatter.h Source File

ICU 71.1 71.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
119 typedef enum UNumberRoundingPriority {
125 UNUM_ROUNDING_PRIORITY_RELAXED,
126
132 UNUM_ROUNDING_PRIORITY_STRICT,
133} UNumberRoundingPriority;
134
153 typedef enum UNumberUnitWidth {
165 UNUM_UNIT_WIDTH_NARROW = 0,
166
181 UNUM_UNIT_WIDTH_SHORT = 1,
182
192 UNUM_UNIT_WIDTH_FULL_NAME = 2,
193
203 UNUM_UNIT_WIDTH_ISO_CODE = 3,
204
214 UNUM_UNIT_WIDTH_FORMAL = 4,
215
225 UNUM_UNIT_WIDTH_VARIANT = 5,
226
234 UNUM_UNIT_WIDTH_HIDDEN = 6,
235
236 // Do not conditionalize the following with #ifndef U_HIDE_INTERNAL_API,
237 // needed for unconditionalized struct MacroProps
243 UNUM_UNIT_WIDTH_COUNT = 7
244} UNumberUnitWidth;
245
272 typedef enum UNumberGroupingStrategy {
278 UNUM_GROUPING_OFF,
279
294 UNUM_GROUPING_MIN2,
295
309 UNUM_GROUPING_AUTO,
310
325 UNUM_GROUPING_ON_ALIGNED,
326
333 UNUM_GROUPING_THOUSANDS
334
335#ifndef U_HIDE_INTERNAL_API
336 ,
342 UNUM_GROUPING_COUNT
343#endif /* U_HIDE_INTERNAL_API */
344
345} UNumberGroupingStrategy;
346
366 typedef enum UNumberSignDisplay {
376 UNUM_SIGN_AUTO,
377
384 UNUM_SIGN_ALWAYS,
385
391 UNUM_SIGN_NEVER,
392
407 UNUM_SIGN_ACCOUNTING,
408
417 UNUM_SIGN_ACCOUNTING_ALWAYS,
418
425 UNUM_SIGN_EXCEPT_ZERO,
426
434 UNUM_SIGN_ACCOUNTING_EXCEPT_ZERO,
435
441 UNUM_SIGN_NEGATIVE,
442
448 UNUM_SIGN_ACCOUNTING_NEGATIVE,
449
450 // Do not conditionalize the following with #ifndef U_HIDE_INTERNAL_API,
451 // needed for unconditionalized struct MacroProps
457 UNUM_SIGN_COUNT = 9,
458} UNumberSignDisplay;
459
471 typedef enum UNumberDecimalSeparatorDisplay {
478 UNUM_DECIMAL_SEPARATOR_AUTO,
479
485 UNUM_DECIMAL_SEPARATOR_ALWAYS,
486
487 // Do not conditionalize the following with #ifndef U_HIDE_INTERNAL_API,
488 // needed for unconditionalized struct MacroProps
494 UNUM_DECIMAL_SEPARATOR_COUNT
495} UNumberDecimalSeparatorDisplay;
496
505 typedef enum UNumberTrailingZeroDisplay {
511 UNUM_TRAILING_ZERO_AUTO,
512
518 UNUM_TRAILING_ZERO_HIDE_IF_WHOLE,
519} UNumberTrailingZeroDisplay;
520
521struct UNumberFormatter;
529 typedef struct UNumberFormatter UNumberFormatter;
530
531struct UFormattedNumber;
539 typedef struct UFormattedNumber UFormattedNumber;
540
541
562 U_CAPI UNumberFormatter* U_EXPORT2
563unumf_openForSkeletonAndLocale(const UChar* skeleton, int32_t skeletonLen, const char* locale,
564 UErrorCode* ec);
565
566
582 U_CAPI UNumberFormatter* U_EXPORT2
583unumf_openForSkeletonAndLocaleWithError(
584 const UChar* skeleton, int32_t skeletonLen, const char* locale, UParseError* perror, UErrorCode* ec);
585
586
595 U_CAPI UFormattedNumber* U_EXPORT2
596unumf_openResult(UErrorCode* ec);
597
598
614 U_CAPI void U_EXPORT2
615unumf_formatInt(const UNumberFormatter* uformatter, int64_t value, UFormattedNumber* uresult,
616 UErrorCode* ec);
617
618
634 U_CAPI void U_EXPORT2
635unumf_formatDouble(const UNumberFormatter* uformatter, double value, UFormattedNumber* uresult,
636 UErrorCode* ec);
637
638
658 U_CAPI void U_EXPORT2
659unumf_formatDecimal(const UNumberFormatter* uformatter, const char* value, int32_t valueLen,
660 UFormattedNumber* uresult, UErrorCode* ec);
661
676 U_CAPI const UFormattedValue* U_EXPORT2
677unumf_resultAsValue(const UFormattedNumber* uresult, UErrorCode* ec);
678
679
699 U_CAPI int32_t U_EXPORT2
700unumf_resultToString(const UFormattedNumber* uresult, UChar* buffer, int32_t bufferCapacity,
701 UErrorCode* ec);
702
703
737 U_CAPI UBool U_EXPORT2
738unumf_resultNextFieldPosition(const UFormattedNumber* uresult, UFieldPosition* ufpos, UErrorCode* ec);
739
740
762 U_CAPI void U_EXPORT2
763unumf_resultGetAllFieldPositions(const UFormattedNumber* uresult, UFieldPositionIterator* ufpositer,
764 UErrorCode* ec);
765
766
785 U_CAPI int32_t U_EXPORT2
786unumf_resultToDecimalNumber(
787 const UFormattedNumber* uresult,
788 char* dest,
789 int32_t destCapacity,
790 UErrorCode* ec);
791
792
799 U_CAPI void U_EXPORT2
800unumf_close(UNumberFormatter* uformatter);
801
802
809 U_CAPI void U_EXPORT2
810unumf_closeResult(UFormattedNumber* uresult);
811
812
813#if U_SHOW_CPLUSPLUS_API
814U_NAMESPACE_BEGIN
815
831 U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberFormatterPointer, UNumberFormatter, unumf_close);
832
848 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedNumberPointer, UFormattedNumber, unumf_closeResult);
849
850U_NAMESPACE_END
851#endif // U_SHOW_CPLUSPLUS_API
852
853#endif /* #if !UCONFIG_NO_FORMATTING */
854#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:119
UNUM_ROUNDING_PRIORITY_RELAXED
@ UNUM_ROUNDING_PRIORITY_RELAXED
Favor greater precision by relaxing one of the rounding constraints.
Definition: unumberformatter.h:125
UNUM_ROUNDING_PRIORITY_STRICT
@ UNUM_ROUNDING_PRIORITY_STRICT
Favor adherence to all rounding constraints by producing lower precision.
Definition: unumberformatter.h:132
UNumberSignDisplay
UNumberSignDisplay
An enum declaring how to denote positive and negative numbers.
Definition: unumberformatter.h:366
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:384
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:434
UNUM_SIGN_ACCOUNTING_NEGATIVE
@ UNUM_SIGN_ACCOUNTING_NEGATIVE
Same as ACCOUNTING, but do not show the sign on negative zero.
Definition: unumberformatter.h:448
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:376
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:407
UNUM_SIGN_NEVER
@ UNUM_SIGN_NEVER
Do not show the sign on positive or negative numbers.
Definition: unumberformatter.h:391
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:417
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:425
UNUM_SIGN_NEGATIVE
@ UNUM_SIGN_NEGATIVE
Same as AUTO, but do not show the sign on negative zero.
Definition: unumberformatter.h:441
UNUM_SIGN_COUNT
@ UNUM_SIGN_COUNT
One more than the highest UNumberSignDisplay value.
Definition: unumberformatter.h:457
UNumberDecimalSeparatorDisplay
UNumberDecimalSeparatorDisplay
An enum declaring how to render the decimal separator.
Definition: unumberformatter.h:471
UNUM_DECIMAL_SEPARATOR_COUNT
@ UNUM_DECIMAL_SEPARATOR_COUNT
One more than the highest UNumberDecimalSeparatorDisplay value.
Definition: unumberformatter.h:494
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:478
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:485
UNumberTrailingZeroDisplay
UNumberTrailingZeroDisplay
An enum declaring how to render trailing zeros.
Definition: unumberformatter.h:505
UNUM_TRAILING_ZERO_AUTO
@ UNUM_TRAILING_ZERO_AUTO
Display trailing zeros according to the settings for minimum fraction and significant digits.
Definition: unumberformatter.h:511
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:518
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:153
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:234
UNUM_UNIT_WIDTH_FULL_NAME
@ UNUM_UNIT_WIDTH_FULL_NAME
Print the full name of the unit, without any abbreviations.
Definition: unumberformatter.h:192
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:214
UNUM_UNIT_WIDTH_NARROW
@ UNUM_UNIT_WIDTH_NARROW
Print an abbreviated version of the unit name.
Definition: unumberformatter.h:165
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:225
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:203
UNUM_UNIT_WIDTH_SHORT
@ UNUM_UNIT_WIDTH_SHORT
Print an abbreviated version of the unit name.
Definition: unumberformatter.h:181
UNUM_UNIT_WIDTH_COUNT
@ UNUM_UNIT_WIDTH_COUNT
One more than the highest UNumberUnitWidth value.
Definition: unumberformatter.h:243
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:529
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:539
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:272
UNUM_GROUPING_THOUSANDS
@ UNUM_GROUPING_THOUSANDS
Use the Western defaults: groups of 3 and enabled for all numbers 1000 or greater.
Definition: unumberformatter.h:333
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:294
UNUM_GROUPING_ON_ALIGNED
@ UNUM_GROUPING_ON_ALIGNED
Always display the grouping separator on values of at least 1000.
Definition: unumberformatter.h:325
UNUM_GROUPING_AUTO
@ UNUM_GROUPING_AUTO
Display grouping using the default strategy for all locales.
Definition: unumberformatter.h:309
UNUM_GROUPING_OFF
@ UNUM_GROUPING_OFF
Do not display grouping separators in any locale.
Definition: unumberformatter.h:278
UNUM_GROUPING_COUNT
@ UNUM_GROUPING_COUNT
One more than the highest UNumberGroupingStrategy value.
Definition: unumberformatter.h:342
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