ICU 74.2  74.2
unum.h
Go to the documentation of this file.
1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /*
4 *******************************************************************************
5 * Copyright (C) 1997-2015, International Business Machines Corporation and others.
6 * All Rights Reserved.
7 * Modification History:
8 *
9 * Date Name Description
10 * 06/24/99 helena Integrated Alan's NF enhancements and Java2 bug fixes
11 *******************************************************************************
12 */
13 
14 #ifndef _UNUM
15 #define _UNUM
16 
17 #include "unicode/utypes.h"
18 
19 #if !UCONFIG_NO_FORMATTING
20 
21 #include "unicode/uloc.h"
22 #include "unicode/ucurr.h"
23 #include "unicode/umisc.h"
24 #include "unicode/parseerr.h"
25 #include "unicode/uformattable.h"
27 #include "unicode/ufieldpositer.h"
28 #include "unicode/unumberoptions.h"
29 
30 #if U_SHOW_CPLUSPLUS_API
31 #include "unicode/localpointer.h"
32 #endif // U_SHOW_CPLUSPLUS_API
33 
145 typedef void* UNumberFormat;
146 
150 typedef enum UNumberFormatStyle {
254 
255 #ifndef U_HIDE_DEPRECATED_API
256 
261 #endif /* U_HIDE_DEPRECATED_API */
262 
274 
279  UNUM_PAD_BEFORE_PREFIX,
280  UNUM_PAD_AFTER_PREFIX,
281  UNUM_PAD_BEFORE_SUFFIX,
282  UNUM_PAD_AFTER_SUFFIX
284 
289 typedef enum UNumberCompactStyle {
296 
308 
309  /* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API,
310  * it is needed for layout of DecimalFormatSymbols object. */
311 #ifndef U_FORCE_HIDE_DEPRECATED_API
312 
317 #endif // U_FORCE_HIDE_DEPRECATED_API
318 };
327 typedef enum UNumberFormatFields {
359 
360 #ifndef U_HIDE_DEPRECATED_API
361 
366 #endif /* U_HIDE_DEPRECATED_API */
368 
369 
391 
429 U_CAPI UNumberFormat* U_EXPORT2
431  const UChar* pattern,
432  int32_t patternLength,
433  const char* locale,
434  UParseError* parseErr,
435  UErrorCode* status);
436 
437 
444 U_CAPI void U_EXPORT2
446 
447 #if U_SHOW_CPLUSPLUS_API
448 
449 U_NAMESPACE_BEGIN
450 
461 
462 U_NAMESPACE_END
463 
464 #endif
465 
474 U_CAPI UNumberFormat* U_EXPORT2
475 unum_clone(const UNumberFormat *fmt,
476  UErrorCode *status);
477 
502 U_CAPI int32_t U_EXPORT2
503 unum_format( const UNumberFormat* fmt,
504  int32_t number,
505  UChar* result,
506  int32_t resultLength,
507  UFieldPosition *pos,
508  UErrorCode* status);
509 
534 U_CAPI int32_t U_EXPORT2
536  int64_t number,
537  UChar* result,
538  int32_t resultLength,
539  UFieldPosition *pos,
540  UErrorCode* status);
541 
566 U_CAPI int32_t U_EXPORT2
567 unum_formatDouble( const UNumberFormat* fmt,
568  double number,
569  UChar* result,
570  int32_t resultLength,
571  UFieldPosition *pos, /* 0 if ignore */
572  UErrorCode* status);
573 
616 U_CAPI int32_t U_EXPORT2
618  double number,
619  UChar* result,
620  int32_t resultLength,
621  UFieldPositionIterator* fpositer,
622  UErrorCode* status);
623 
624 
653 U_CAPI int32_t U_EXPORT2
655  const char * number,
656  int32_t length,
657  UChar* result,
658  int32_t resultLength,
659  UFieldPosition *pos, /* 0 if ignore */
660  UErrorCode* status);
661 
692 U_CAPI int32_t U_EXPORT2
694  double number,
695  UChar* currency,
696  UChar* result,
697  int32_t resultLength,
698  UFieldPosition* pos,
699  UErrorCode* status);
700 
721 U_CAPI int32_t U_EXPORT2
723  const UFormattable *number,
724  UChar *result,
725  int32_t resultLength,
726  UFieldPosition *pos,
727  UErrorCode *status);
728 
748 U_CAPI int32_t U_EXPORT2
749 unum_parse( const UNumberFormat* fmt,
750  const UChar* text,
751  int32_t textLength,
752  int32_t *parsePos /* 0 = start */,
753  UErrorCode *status);
754 
774 U_CAPI int64_t U_EXPORT2
775 unum_parseInt64(const UNumberFormat* fmt,
776  const UChar* text,
777  int32_t textLength,
778  int32_t *parsePos /* 0 = start */,
779  UErrorCode *status);
780 
800 U_CAPI double U_EXPORT2
801 unum_parseDouble( const UNumberFormat* fmt,
802  const UChar* text,
803  int32_t textLength,
804  int32_t *parsePos /* 0 = start */,
805  UErrorCode *status);
806 
807 
835 U_CAPI int32_t U_EXPORT2
837  const UChar* text,
838  int32_t textLength,
839  int32_t *parsePos /* 0 = start */,
840  char *outBuf,
841  int32_t outBufLength,
842  UErrorCode *status);
843 
863 U_CAPI double U_EXPORT2
865  const UChar* text,
866  int32_t textLength,
867  int32_t* parsePos, /* 0 = start */
868  UChar* currency,
869  UErrorCode* status);
870 
891 U_CAPI UFormattable* U_EXPORT2
893  UFormattable *result,
894  const UChar* text,
895  int32_t textLength,
896  int32_t* parsePos, /* 0 = start */
897  UErrorCode* status);
898 
915 U_CAPI void U_EXPORT2
917  UBool localized,
918  const UChar *pattern,
919  int32_t patternLength,
920  UParseError *parseError,
921  UErrorCode *status
922  );
923 
934 U_CAPI const char* U_EXPORT2
935 unum_getAvailable(int32_t localeIndex);
936 
946 U_CAPI int32_t U_EXPORT2
947 unum_countAvailable(void);
948 
949 #if UCONFIG_HAVE_PARSEALLINPUT
950 /* The UNumberFormatAttributeValue type cannot be #ifndef U_HIDE_INTERNAL_API, needed for .h variable declaration */
954 typedef enum UNumberFormatAttributeValue {
955 #ifndef U_HIDE_INTERNAL_API
956 
957  UNUM_NO = 0,
959  UNUM_YES = 1,
961  UNUM_MAYBE = 2
962 #else
963 
964  UNUM_FORMAT_ATTRIBUTE_VALUE_HIDDEN
965 #endif /* U_HIDE_INTERNAL_API */
966 } UNumberFormatAttributeValue;
967 #endif
968 
1016 #if UCONFIG_HAVE_PARSEALLINPUT
1017 
1021  UNUM_PARSE_ALL_INPUT = 20,
1022 #endif
1023 
1035 
1045 
1053 
1054 #ifndef U_HIDE_INTERNAL_API
1055 
1059 #endif /* U_HIDE_INTERNAL_API */
1060 
1074 
1084 
1091 
1100 
1101 #ifndef U_HIDE_INTERNAL_API
1102 
1106 #endif /* U_HIDE_INTERNAL_API */
1107 
1109 
1124 U_CAPI bool U_EXPORT2
1125 unum_hasAttribute(const UNumberFormat* fmt,
1126  UNumberFormatAttribute attr);
1127 
1145 U_CAPI int32_t U_EXPORT2
1146 unum_getAttribute(const UNumberFormat* fmt,
1147  UNumberFormatAttribute attr);
1148 
1169 U_CAPI void U_EXPORT2
1172  int32_t newValue);
1173 
1174 
1191 U_CAPI double U_EXPORT2
1193  UNumberFormatAttribute attr);
1194 
1211 U_CAPI void U_EXPORT2
1214  double newValue);
1215 
1249 
1268 U_CAPI int32_t U_EXPORT2
1271  UChar* result,
1272  int32_t resultLength,
1273  UErrorCode* status);
1274 
1291 U_CAPI void U_EXPORT2
1294  const UChar* newValue,
1295  int32_t newValueLength,
1296  UErrorCode *status);
1297 
1314 U_CAPI int32_t U_EXPORT2
1315 unum_toPattern( const UNumberFormat* fmt,
1316  UBool isPatternLocalized,
1317  UChar* result,
1318  int32_t resultLength,
1319  UErrorCode* status);
1320 
1321 
1326 typedef enum UNumberFormatSymbol {
1402 
1407 
1408 #ifndef U_HIDE_INTERNAL_API
1409 
1413 #endif
1414 
1415 #ifndef U_HIDE_DEPRECATED_API
1416 
1421 #endif /* U_HIDE_DEPRECATED_API */
1423 
1440 U_CAPI int32_t U_EXPORT2
1441 unum_getSymbol(const UNumberFormat *fmt,
1442  UNumberFormatSymbol symbol,
1443  UChar *buffer,
1444  int32_t size,
1445  UErrorCode *status);
1446 
1460 U_CAPI void U_EXPORT2
1462  UNumberFormatSymbol symbol,
1463  const UChar *value,
1464  int32_t length,
1465  UErrorCode *status);
1466 
1467 
1477 U_CAPI const char* U_EXPORT2
1479  ULocDataLocaleType type,
1480  UErrorCode* status);
1481 
1490 U_CAPI void U_EXPORT2
1492 
1502 U_CAPI UDisplayContext U_EXPORT2
1503 unum_getContext(const UNumberFormat *fmt, UDisplayContextType type, UErrorCode* status);
1504 
1505 #endif /* #if !UCONFIG_NO_FORMATTING */
1506 
1507 #endif
Default format.
Definition: unum.h:267
U_CAPI int32_t unum_parse(const UNumberFormat *fmt, const UChar *text, int32_t textLength, int32_t *parsePos, UErrorCode *status)
Parse a string into an integer using a UNumberFormat.
C API: UFormattable is a thin wrapper for primitive types used for formatting and parsing...
U_CAPI void unum_setAttribute(UNumberFormat *fmt, UNumberFormatAttribute attr, int32_t newValue)
Set a numeric attribute associated with a UNumberFormat.
The exponential symbol.
Definition: unum.h:1350
The monetary grouping separator.
Definition: unum.h:1365
U_CAPI bool unum_hasAttribute(const UNumberFormat *fmt, UNumberFormatAttribute attr)
Returns true if the formatter supports the specified attribute and false if not.
One more than the highest normal UNumberFormatStyle value.
Definition: unum.h:260
Negative prefix.
Definition: unum.h:1223
Numbering system rule-based format.
Definition: unum.h:203
#define U_CAPI
This is used to declare a function as a public ICU C API.
Definition: umachine.h:110
U_CAPI double unum_parseDouble(const UNumberFormat *fmt, const UChar *text, int32_t textLength, int32_t *parsePos, UErrorCode *status)
Parse a string into a double using a UNumberFormat.
Currency format (generic).
Definition: unum.h:169
Decimal format ("normal" style).
Definition: unum.h:160
U_CAPI int32_t unum_formatInt64(const UNumberFormat *fmt, int64_t number, UChar *result, int32_t resultLength, UFieldPosition *pos, UErrorCode *status)
Format an int64 using a UNumberFormat.
if this attribute is set to 1, specifies that, if the pattern doesn't contain an exponent, the exponent will not be parsed.
Definition: unum.h:1073
UDisplayContext
Display context settings.
Significant digit symbol.
Definition: unum.h:1361
U_CAPI UNumberFormat * unum_open(UNumberFormatStyle style, const UChar *pattern, int32_t patternLength, const char *locale, UParseError *parseErr, UErrorCode *status)
Create and return a new UNumberFormat for formatting and parsing numbers.
Currency format with a currency symbol, e.g., "$1.00", using non-accounting style for negative values...
Definition: unum.h:253
Rule-based format defined by a pattern string.
Definition: unum.h:208
Formatting: if set to 1, whether to show the plus sign on non-negative numbers.
Definition: unum.h:1099
Lenient parse mode used by rule-based formats.
Definition: unum.h:1015
Display grouping using the default strategy for all locales.
Definition: unum.h:382
Decimal format expressed using compact notation (short form, corresponds to UNumberCompactStyle=UNUM_...
Definition: unum.h:239
UCurrencySpacing
Constants for specifying currency spacing.
Definition: unum.h:301
C API: Miscellaneous definitions.
struct UFieldPositionIterator UFieldPositionIterator
C typedef for struct UFieldPositionIterator.
Definition: ufieldpositer.h:46
The grouping separator.
Definition: unum.h:1330
Limit of boolean attributes.
Definition: unum.h:1105
Integer digits.
Definition: unum.h:982
Fraction digits.
Definition: unum.h:988
U_CAPI double unum_getDoubleAttribute(const UNumberFormat *fmt, UNumberFormatAttribute attr)
Get a numeric attribute associated with a UNumberFormat.
UNumberFormatSymbol
Constants for specifying a number format symbol.
Definition: unum.h:1326
Positive prefix.
Definition: unum.h:1219
The ISO currency code.
Definition: unum.h:1229
Multiplication sign.
Definition: unum.h:1406
C API: Display context types (enum values)
The minus sign.
Definition: unum.h:1340
Nan symbol.
Definition: unum.h:1358
U_CAPI int64_t unum_parseInt64(const UNumberFormat *fmt, const UChar *text, int32_t textLength, int32_t *parsePos, UErrorCode *status)
Parse a string into an int64 using a UNumberFormat.
Currency format with an ISO currency code, e.g., "USD1.00".
Definition: unum.h:213
C API: Header-only input options for various number formatting APIs.
Currency format with a currency symbol given CASH usage, e.g., "NT$3" instead of "NT$3.23".
Definition: unum.h:232
Decimal format defined by a pattern string.
Definition: unum.h:155
Use significant digits.
Definition: unum.h:1005
Percent format.
Definition: unum.h:174
The position at which padding will take place.
Definition: unum.h:1000
Decimal format expressed using compact notation (long form, corresponds to UNumberCompactStyle=UNUM_L...
Definition: unum.h:246
Spellout rule-based format.
Definition: unum.h:186
U_CAPI int32_t unum_getTextAttribute(const UNumberFormat *fmt, UNumberFormatTextAttribute tag, UChar *result, int32_t resultLength, UErrorCode *status)
Get a text attribute associated with a UNumberFormat.
UNumberFormatStyle
The possible number format styles.
Definition: unum.h:150
The percent sign.
Definition: unum.h:1334
Infinity symbol.
Definition: unum.h:1356
#define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction)
"Smart pointer" definition macro, deletes objects via the closeFunction.
Definition: localpointer.h:550
void * UNumberFormat
A number formatter.
Definition: unum.h:145
Minimum fraction digits.
Definition: unum.h:986
A struct representing a range of text containing a specific field.
Definition: umisc.h:34
UNumberFormatFields
FieldPosition and UFieldPosition selectors for format fields defined by NumberFormat and UNumberForma...
Definition: unum.h:327
C++ API: "Smart pointers" for use with and in ICU4C C++ code.
C API: Encapsulates information about a currency.
U_CAPI void unum_setSymbol(UNumberFormat *fmt, UNumberFormatSymbol symbol, const UChar *value, int32_t length, UErrorCode *status)
Set a symbol associated with a UNumberFormat.
Maximum significant digits.
Definition: unum.h:1011
Currency format with a pluralized currency name, e.g., "1.00 US dollar" and "3.00 US dollars"...
Definition: unum.h:219
One more than the highest normal UNumberFormatSymbol value.
Definition: unum.h:1420
Parse integers only.
Definition: unum.h:972
U_CAPI int32_t unum_format(const UNumberFormat *fmt, int32_t number, UChar *result, int32_t resultLength, UFieldPosition *pos, UErrorCode *status)
Format an integer using a UNumberFormat.
Scale, which adjusts the position of the decimal point when formatting.
Definition: unum.h:1034
UNumberFormatTextAttribute
The possible UNumberFormat text attributes.
Definition: unum.h:1217
U_CAPI int32_t unum_formatDecimal(const UNumberFormat *fmt, const char *number, int32_t length, UChar *result, int32_t resultLength, UFieldPosition *pos, UErrorCode *status)
Format a decimal number using a UNumberFormat.
U_CAPI void unum_setTextAttribute(UNumberFormat *fmt, UNumberFormatTextAttribute tag, const UChar *newValue, int32_t newValueLength, UErrorCode *status)
Set a text attribute associated with a UNumberFormat.
Parsing: if set to 1, parsing is sensitive to case (lowercase/uppercase).
Definition: unum.h:1090
Maximum fraction digits.
Definition: unum.h:984
Secondary grouping size.
Definition: unum.h:1002
UNumberFormatMinimumGroupingDigits
Selectors with special numeric values to use locale default minimum grouping digits for the DecimalFo...
Definition: unum.h:377
The width to which the output of format() is padded.
Definition: unum.h:998
Alias for UNUM_PATTERN_DECIMAL.
Definition: unum.h:272
"Smart pointer" class, closes a UNumberFormat via unum_close().
One below the first bitfield-boolean item.
Definition: unum.h:1058
UNumberFormatPadPosition
The possible number format pad positions.
Definition: unum.h:278
Per mill symbol.
Definition: unum.h:1352
The pattern separator.
Definition: unum.h:1332
U_CAPI void unum_applyPattern(UNumberFormat *format, UBool localized, const UChar *pattern, int32_t patternLength, UParseError *parseError, UErrorCode *status)
Set the pattern used by a UNumberFormat.
Scientific format.
Definition: unum.h:179
Use grouping separator.
Definition: unum.h:974
Minimum grouping digits; most commonly set to 2 to print "1000" instead of "1,000".
Definition: unum.h:1044
U_CAPI int32_t unum_parseDecimal(const UNumberFormat *fmt, const UChar *text, int32_t textLength, int32_t *parsePos, char *outBuf, int32_t outBufLength, UErrorCode *status)
Parse a number from a string into an unformatted numeric string using a UNumberFormat.
If 1, specifies that if setting the "max integer digits" attribute would truncate a value...
Definition: unum.h:1066
U_CAPI int32_t unum_formatUFormattable(const UNumberFormat *fmt, const UFormattable *number, UChar *result, int32_t resultLength, UFieldPosition *pos, UErrorCode *status)
Format a UFormattable into a string.
char16_t UChar
The base type for UTF-16 code units and pointers.
Definition: umachine.h:386
Positive suffix.
Definition: unum.h:1221
Multiplier.
Definition: unum.h:990
Minimum integer digits.
Definition: unum.h:980
UNumberCompactStyle
Constants for specifying short or long format.
Definition: unum.h:289
UDisplayContextType
Display context types, for getting values of a particular setting.
Ordinal rule-based format .
Definition: unum.h:193
Escape padding character.
Definition: unum.h:1354
C API: Parse Error Information.
U_CAPI int32_t unum_formatDouble(const UNumberFormat *fmt, double number, UChar *result, int32_t resultLength, UFieldPosition *pos, UErrorCode *status)
Format a double using a UNumberFormat.
U_CAPI const char * unum_getAvailable(int32_t localeIndex)
Get a locale for which decimal formatting patterns are available.
U_CAPI void unum_setDoubleAttribute(UNumberFormat *fmt, UNumberFormatAttribute attr, double newValue)
Set a numeric attribute associated with a UNumberFormat.
The character used to pad to the format width.
Definition: unum.h:1227
if this attribute is set to 1, specifies that, if the pattern contains a decimal mark the input is re...
Definition: unum.h:1083
Approximately sign.
Definition: unum.h:358
Rounding Mode.
Definition: unum.h:994
U_CAPI UFormattable * unum_parseToUFormattable(const UNumberFormat *fmt, UFormattable *result, const UChar *text, int32_t textLength, int32_t *parsePos, UErrorCode *status)
Parse a UChar string into a UFormattable.
The decimal separator.
Definition: unum.h:1328
Approximately sign.
Definition: unum.h:1412
U_CAPI const char * unum_getLocaleByType(const UNumberFormat *fmt, ULocDataLocaleType type, UErrorCode *status)
Get the locale for this number format object.
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415
ULocDataLocaleType
Constants for *_getLocale() Allow user to select whether she wants information on requested...
Definition: uloc.h:338
Currency format for accounting, e.g., "($3.00)" for negative currency amount instead of "-$3...
Definition: unum.h:226
U_CAPI UNumberFormat * unum_clone(const UNumberFormat *fmt, UErrorCode *status)
Open a copy of a UNumberFormat.
U_CAPI int32_t unum_formatDoubleForFields(const UNumberFormat *format, double number, UChar *result, int32_t resultLength, UFieldPositionIterator *fpositer, UErrorCode *status)
Format a double using a UNumberFormat according to the UNumberFormat's locale, and initialize a UFiel...
Rounding increment.
Definition: unum.h:996
U_CAPI int32_t unum_formatDoubleCurrency(const UNumberFormat *fmt, double number, UChar *currency, UChar *result, int32_t resultLength, UFieldPosition *pos, UErrorCode *status)
Format a double currency amount using a UNumberFormat.
U_CAPI void unum_setContext(UNumberFormat *fmt, UDisplayContext value, UErrorCode *status)
Set a particular UDisplayContext value in the formatter, such as UDISPCTX_CAPITALIZATION_FOR_STANDALO...
C API: UFieldPositionIterator for use with format APIs.
Minimum significant digits.
Definition: unum.h:1008
U_CAPI int32_t unum_toPattern(const UNumberFormat *fmt, UBool isPatternLocalized, UChar *result, int32_t resultLength, UErrorCode *status)
Extract the pattern from a UNumberFormat.
A UParseError struct is used to returned detailed information about parsing errors.
Definition: parseerr.h:58
Basic definitions for ICU, for both C and C++ APIs.
The international currency symbol.
Definition: unum.h:1346
The default rule set, such as "%spellout-numbering-year:", "%spellout-cardinal:", "%spellout-ordinal-...
Definition: unum.h:1238
The monetary separator.
Definition: unum.h:1348
U_CAPI int32_t unum_countAvailable(void)
Determine how many locales have decimal formatting patterns available.
if this attribute is set to 0, it is set to UNUM_CURRENCY_STANDARD purpose, otherwise it is UNUM_CASH...
Definition: unum.h:1052
U_CAPI void unum_close(UNumberFormat *fmt)
Close a UNumberFormat.
The currency symbol.
Definition: unum.h:1344
The plus sign.
Definition: unum.h:1342
Duration rule-based format.
Definition: unum.h:198
void * UFormattable
Opaque type representing various types of data which may be used for formatting and parsing operation...
Definition: uformattable.h:72
UNumberFormatAttribute
The possible UNumberFormat numeric attributes.
Definition: unum.h:970
Negative suffix.
Definition: unum.h:1225
One more than the highest normal UNumberFormatFields value.
Definition: unum.h:365
Display grouping using locale defaults, except do not show grouping on values smaller than 10000 (suc...
Definition: unum.h:389
Grouping size.
Definition: unum.h:992
U_CAPI double unum_parseDoubleCurrency(const UNumberFormat *fmt, const UChar *text, int32_t textLength, int32_t *parsePos, UChar *currency, UErrorCode *status)
Parse a string into a double and a currency using a UNumberFormat.
U_CAPI int32_t unum_getAttribute(const UNumberFormat *fmt, UNumberFormatAttribute attr)
Get a numeric attribute associated with a UNumberFormat.
One more than the highest normal UCurrencySpacing value.
Definition: unum.h:316
U_CAPI int32_t unum_getSymbol(const UNumberFormat *fmt, UNumberFormatSymbol symbol, UChar *buffer, int32_t size, UErrorCode *status)
Get a symbol associated with a UNumberFormat.
The public rule sets.
Definition: unum.h:1247
U_CAPI UDisplayContext unum_getContext(const UNumberFormat *fmt, UDisplayContextType type, UErrorCode *status)
Get the formatter's UDisplayContext value for the specified UDisplayContextType, such as UDISPCTX_TYP...
int8_t UBool
The ICU boolean type, a signed-byte integer.
Definition: umachine.h:247
Maximum integer digits.
Definition: unum.h:978
Character representing a digit in the pattern.
Definition: unum.h:1338
C API: Locale ID functionality similar to C++ class Locale.
Always show decimal point.
Definition: unum.h:976