ICU 60.1  60.1
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/localpointer.h"
22 #include "unicode/uloc.h"
23 #include "unicode/ucurr.h"
24 #include "unicode/umisc.h"
25 #include "unicode/parseerr.h"
26 #include "unicode/uformattable.h"
28 #include "unicode/ufieldpositer.h"
29 
137 typedef void* UNumberFormat;
138 
142 typedef enum UNumberFormatStyle {
246 
247 #ifndef U_HIDE_DEPRECATED_API
248 
253 #endif /* U_HIDE_DEPRECATED_API */
254 
266 
276  UNUM_ROUND_CEILING,
277  UNUM_ROUND_FLOOR,
278  UNUM_ROUND_DOWN,
279  UNUM_ROUND_UP,
285 #ifndef U_HIDE_DEPRECATED_API
286 
291 #endif /* U_HIDE_DEPRECATED_API */
292  UNUM_ROUND_HALFDOWN = UNUM_ROUND_HALFEVEN + 1,
293  UNUM_ROUND_HALFUP,
300 
305  UNUM_PAD_BEFORE_PREFIX,
306  UNUM_PAD_AFTER_PREFIX,
307  UNUM_PAD_BEFORE_SUFFIX,
308  UNUM_PAD_AFTER_SUFFIX
310 
315 typedef enum UNumberCompactStyle {
322 
334 
335  /* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API,
336  * it is needed for layout of DecimalFormatSymbols object. */
342 };
351 typedef enum UNumberFormatFields {
374 #ifndef U_HIDE_DEPRECATED_API
375 
380 #endif /* U_HIDE_DEPRECATED_API */
382 
383 
417 U_STABLE UNumberFormat* U_EXPORT2
419  const UChar* pattern,
420  int32_t patternLength,
421  const char* locale,
422  UParseError* parseErr,
423  UErrorCode* status);
424 
425 
432 U_STABLE void U_EXPORT2
434 
435 #if U_SHOW_CPLUSPLUS_API
436 
438 
449 
451 
452 #endif
453 
462 U_STABLE UNumberFormat* U_EXPORT2
463 unum_clone(const UNumberFormat *fmt,
464  UErrorCode *status);
465 
490 U_STABLE int32_t U_EXPORT2
491 unum_format( const UNumberFormat* fmt,
492  int32_t number,
493  UChar* result,
494  int32_t resultLength,
495  UFieldPosition *pos,
496  UErrorCode* status);
497 
522 U_STABLE int32_t U_EXPORT2
524  int64_t number,
525  UChar* result,
526  int32_t resultLength,
527  UFieldPosition *pos,
528  UErrorCode* status);
529 
554 U_STABLE int32_t U_EXPORT2
555 unum_formatDouble( const UNumberFormat* fmt,
556  double number,
557  UChar* result,
558  int32_t resultLength,
559  UFieldPosition *pos, /* 0 if ignore */
560  UErrorCode* status);
561 
562 #ifndef U_HIDE_DRAFT_API
563 
605 U_DRAFT int32_t U_EXPORT2
607  double number,
608  UChar* result,
609  int32_t resultLength,
610  UFieldPositionIterator* fpositer,
611  UErrorCode* status);
612 
613 #endif /* U_HIDE_DRAFT_API */
614 
643 U_STABLE int32_t U_EXPORT2
645  const char * number,
646  int32_t length,
647  UChar* result,
648  int32_t resultLength,
649  UFieldPosition *pos, /* 0 if ignore */
650  UErrorCode* status);
651 
676 U_STABLE int32_t U_EXPORT2
678  double number,
679  UChar* currency,
680  UChar* result,
681  int32_t resultLength,
682  UFieldPosition* pos,
683  UErrorCode* status);
684 
705 U_STABLE int32_t U_EXPORT2
707  const UFormattable *number,
708  UChar *result,
709  int32_t resultLength,
710  UFieldPosition *pos,
711  UErrorCode *status);
712 
732 U_STABLE int32_t U_EXPORT2
733 unum_parse( const UNumberFormat* fmt,
734  const UChar* text,
735  int32_t textLength,
736  int32_t *parsePos /* 0 = start */,
737  UErrorCode *status);
738 
758 U_STABLE int64_t U_EXPORT2
759 unum_parseInt64(const UNumberFormat* fmt,
760  const UChar* text,
761  int32_t textLength,
762  int32_t *parsePos /* 0 = start */,
763  UErrorCode *status);
764 
784 U_STABLE double U_EXPORT2
785 unum_parseDouble( const UNumberFormat* fmt,
786  const UChar* text,
787  int32_t textLength,
788  int32_t *parsePos /* 0 = start */,
789  UErrorCode *status);
790 
791 
819 U_STABLE int32_t U_EXPORT2
821  const UChar* text,
822  int32_t textLength,
823  int32_t *parsePos /* 0 = start */,
824  char *outBuf,
825  int32_t outBufLength,
826  UErrorCode *status);
827 
847 U_STABLE double U_EXPORT2
849  const UChar* text,
850  int32_t textLength,
851  int32_t* parsePos, /* 0 = start */
852  UChar* currency,
853  UErrorCode* status);
854 
875 U_STABLE UFormattable* U_EXPORT2
877  UFormattable *result,
878  const UChar* text,
879  int32_t textLength,
880  int32_t* parsePos, /* 0 = start */
881  UErrorCode* status);
882 
899 U_STABLE void U_EXPORT2
901  UBool localized,
902  const UChar *pattern,
903  int32_t patternLength,
904  UParseError *parseError,
905  UErrorCode *status
906  );
907 
918 U_STABLE const char* U_EXPORT2
919 unum_getAvailable(int32_t localeIndex);
920 
930 U_STABLE int32_t U_EXPORT2
931 unum_countAvailable(void);
932 
933 #if UCONFIG_HAVE_PARSEALLINPUT
934 /* The UNumberFormatAttributeValue type cannot be #ifndef U_HIDE_INTERNAL_API, needed for .h variable declaration */
938 typedef enum UNumberFormatAttributeValue {
939 #ifndef U_HIDE_INTERNAL_API
940 
941  UNUM_NO = 0,
943  UNUM_YES = 1,
945  UNUM_MAYBE = 2
946 #else
947 
948  UNUM_FORMAT_ATTRIBUTE_VALUE_HIDDEN
949 #endif /* U_HIDE_INTERNAL_API */
950 } UNumberFormatAttributeValue;
951 #endif
952 
1000 #if UCONFIG_HAVE_PARSEALLINPUT
1001 
1005  UNUM_PARSE_ALL_INPUT = 20,
1006 #endif
1007 
1017 #ifndef U_HIDE_INTERNAL_API
1018 
1025  /* TODO: test C API when it becomes @draft */
1026 #endif /* U_HIDE_INTERNAL_API */
1027 
1035 
1036  /* The following cannot be #ifndef U_HIDE_INTERNAL_API, needed in .h file variable declararions */
1041 
1055 
1065 
1066  /* The following cannot be #ifndef U_HIDE_INTERNAL_API, needed in .h file variable declararions */
1071 
1089 U_STABLE int32_t U_EXPORT2
1090 unum_getAttribute(const UNumberFormat* fmt,
1091  UNumberFormatAttribute attr);
1092 
1112 U_STABLE void U_EXPORT2
1115  int32_t newValue);
1116 
1117 
1132 U_STABLE double U_EXPORT2
1134  UNumberFormatAttribute attr);
1135 
1150 U_STABLE void U_EXPORT2
1153  double newValue);
1154 
1188 
1207 U_STABLE int32_t U_EXPORT2
1210  UChar* result,
1211  int32_t resultLength,
1212  UErrorCode* status);
1213 
1230 U_STABLE void U_EXPORT2
1233  const UChar* newValue,
1234  int32_t newValueLength,
1235  UErrorCode *status);
1236 
1253 U_STABLE int32_t U_EXPORT2
1254 unum_toPattern( const UNumberFormat* fmt,
1255  UBool isPatternLocalized,
1256  UChar* result,
1257  int32_t resultLength,
1258  UErrorCode* status);
1259 
1260 
1265 typedef enum UNumberFormatSymbol {
1341 
1346 
1347 #ifndef U_HIDE_DEPRECATED_API
1348 
1353 #endif /* U_HIDE_DEPRECATED_API */
1355 
1372 U_STABLE int32_t U_EXPORT2
1373 unum_getSymbol(const UNumberFormat *fmt,
1374  UNumberFormatSymbol symbol,
1375  UChar *buffer,
1376  int32_t size,
1377  UErrorCode *status);
1378 
1392 U_STABLE void U_EXPORT2
1394  UNumberFormatSymbol symbol,
1395  const UChar *value,
1396  int32_t length,
1397  UErrorCode *status);
1398 
1399 
1409 U_STABLE const char* U_EXPORT2
1411  ULocDataLocaleType type,
1412  UErrorCode* status);
1413 
1422 U_STABLE void U_EXPORT2
1424 
1434 U_STABLE UDisplayContext U_EXPORT2
1435 unum_getContext(const UNumberFormat *fmt, UDisplayContextType type, UErrorCode* status);
1436 
1437 #endif /* #if !UCONFIG_NO_FORMATTING */
1438 
1439 #endif
Default format.
Definition: unum.h:259
void unum_setDoubleAttribute(UNumberFormat *fmt, UNumberFormatAttribute attr, double newValue)
Set a numeric attribute associated with a UNumberFormat.
C API: UFormattable is a thin wrapper for primitive types used for formatting and parsing...
void unum_setSymbol(UNumberFormat *fmt, UNumberFormatSymbol symbol, const UChar *value, int32_t length, UErrorCode *status)
Set a symbol associated with a UNumberFormat.
UNumberFormatRoundingMode
The possible number format rounding modes.
Definition: unum.h:275
double unum_getDoubleAttribute(const UNumberFormat *fmt, UNumberFormatAttribute attr)
Get a numeric attribute associated with a UNumberFormat.
The exponential symbol.
Definition: unum.h:1289
The monetary grouping separator.
Definition: unum.h:1304
One more than the highest normal UNumberFormatStyle value.
Definition: unum.h:252
Negative prefix.
Definition: unum.h:1162
void unum_setContext(UNumberFormat *fmt, UDisplayContext value, UErrorCode *status)
Set a particular UDisplayContext value in the formatter, such as UDISPCTX_CAPITALIZATION_FOR_STANDALO...
Numbering system rule-based format.
Definition: unum.h:195
const char * unum_getAvailable(int32_t localeIndex)
Get a locale for which decimal formatting patterns are available.
Currency format (generic).
Definition: unum.h:161
Decimal format ("normal" style).
Definition: unum.h:152
void unum_applyPattern(UNumberFormat *format, UBool localized, const UChar *pattern, int32_t patternLength, UParseError *parseError, UErrorCode *status)
Set the pattern used by 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:1054
UDisplayContext
Display context settings.
Significant digit symbol.
Definition: unum.h:1300
Currency format with a currency symbol, e.g., "$1.00", using non-accounting style for negative values...
Definition: unum.h:245
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.
Rule-based format defined by a pattern string.
Definition: unum.h:200
Lenient parse mode used by rule-based formats.
Definition: unum.h:999
Decimal format expressed using compact notation (short form, corresponds to UNumberCompactStyle=UNUM_...
Definition: unum.h:231
UCurrencySpacing
Constants for specifying currency spacing.
Definition: unum.h:327
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.
C API:misc definitions.
ROUND_UNNECESSARY reports an error if formatted result is not exact.
Definition: unum.h:298
struct UFieldPositionIterator UFieldPositionIterator
C typedef for struct UFieldPositionIterator.
Definition: ufieldpositer.h:44
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.
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.
The grouping separator.
Definition: unum.h:1269
Limit of boolean attributes.
Definition: unum.h:1069
Integer digits.
Definition: unum.h:966
Fraction digits.
Definition: unum.h:972
UNumberFormatSymbol
Constants for specifying a number format symbol.
Definition: unum.h:1265
Half-even rounding, misspelled name.
Definition: unum.h:290
Positive prefix.
Definition: unum.h:1158
The ISO currency code.
Definition: unum.h:1168
Multiplication sign.
Definition: unum.h:1345
C API: Display context types (enum values)
The minus sign.
Definition: unum.h:1279
Nan symbol.
Definition: unum.h:1297
Currency format with an ISO currency code, e.g., "USD1.00".
Definition: unum.h:205
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.
Currency format with a currency symbol given CASH usage, e.g., "NT$3" instead of "NT$3.23".
Definition: unum.h:224
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.
Decimal format defined by a pattern string.
Definition: unum.h:147
Use significant digits.
Definition: unum.h:989
Percent format.
Definition: unum.h:166
Half-even rounding.
Definition: unum.h:284
The position at which padding will take place.
Definition: unum.h:984
Decimal format expressed using compact notation (long form, corresponds to UNumberCompactStyle=UNUM_L...
Definition: unum.h:238
#define U_NAMESPACE_BEGIN
This is used to begin a declaration of a public ICU C++ API.
Definition: uversion.h:131
Spellout rule-based format.
Definition: unum.h:178
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:142
int32_t unum_countAvailable(void)
Determine how many locales have decimal formatting patterns available.
The percent sign.
Definition: unum.h:1273
Infinity symbol.
Definition: unum.h:1295
#define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction)
"Smart pointer" definition macro, deletes objects via the closeFunction.
Definition: localpointer.h:487
void * UNumberFormat
A number formatter.
Definition: unum.h:137
Minimum fraction digits.
Definition: unum.h:970
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:351
C++ API: "Smart pointers" for use with and in ICU4C C++ code.
C API: Encapsulates information about a currency.
Maximum significant digits.
Definition: unum.h:995
Currency format with a pluralized currency name, e.g., "1.00 US dollar" and "3.00 US dollars"...
Definition: unum.h:211
One more than the highest normal UNumberFormatSymbol value.
Definition: unum.h:1352
Parse integers only.
Definition: unum.h:956
Scale, which adjusts the position of the decimal point when formatting.
Definition: unum.h:1016
UNumberFormatTextAttribute
The possible UNumberFormat text attributes.
Definition: unum.h:1156
UNumberFormat * unum_clone(const UNumberFormat *fmt, UErrorCode *status)
Open a copy of a UNumberFormat.
Maximum fraction digits.
Definition: unum.h:968
Secondary grouping size.
Definition: unum.h:986
The width to which the output of format() is padded.
Definition: unum.h:982
Alias for UNUM_PATTERN_DECIMAL.
Definition: unum.h:264
"Smart pointer" class, closes a UNumberFormat via unum_close().
One below the first bitfield-boolean item.
Definition: unum.h:1040
UNumberFormatPadPosition
The possible number format pad positions.
Definition: unum.h:304
Per mill symbol.
Definition: unum.h:1291
The pattern separator.
Definition: unum.h:1271
UDisplayContext unum_getContext(const UNumberFormat *fmt, UDisplayContextType type, UErrorCode *status)
Get the formatter's UDisplayContext value for the specified UDisplayContextType, such as UDISPCTX_TYP...
Scientific format.
Definition: unum.h:171
Use grouping separator.
Definition: unum.h:958
Minimum grouping digits, technology preview.
Definition: unum.h:1024
int32_t unum_formatDouble(const UNumberFormat *fmt, double number, UChar *result, int32_t resultLength, UFieldPosition *pos, UErrorCode *status)
Format a double using a UNumberFormat.
If 1, specifies that if setting the "max integer digits" attribute would truncate a value...
Definition: unum.h:1047
uint16_t UChar
The base type for UTF-16 code units and pointers.
Definition: umachine.h:349
Positive suffix.
Definition: unum.h:1160
Multiplier.
Definition: unum.h:974
Minimum integer digits.
Definition: unum.h:964
const char * unum_getLocaleByType(const UNumberFormat *fmt, ULocDataLocaleType type, UErrorCode *status)
Get the locale for this number format object.
#define U_NAMESPACE_END
This is used to end a declaration of a public ICU C++ API.
Definition: uversion.h:132
UNumberCompactStyle
Constants for specifying short or long format.
Definition: unum.h:315
UDisplayContextType
Display context types, for getting values of a particular setting.
Ordinal rule-based format .
Definition: unum.h:185
Escape padding character.
Definition: unum.h:1293
C API: Parse Error Information.
void unum_setAttribute(UNumberFormat *fmt, UNumberFormatAttribute attr, int32_t newValue)
Set a numeric attribute associated with a UNumberFormat.
The character used to pad to the format width.
Definition: unum.h:1166
if this attribute is set to 1, specifies that, if the pattern contains a decimal mark the input is re...
Definition: unum.h:1064
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.
Rounding Mode.
Definition: unum.h:978
The decimal separator.
Definition: unum.h:1267
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...
UErrorCode
Error code to replace exception handling, so that the code is compatible with all C++ compilers...
Definition: utypes.h:396
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:218
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.
int32_t unum_getSymbol(const UNumberFormat *fmt, UNumberFormatSymbol symbol, UChar *buffer, int32_t size, UErrorCode *status)
Get a symbol associated with a UNumberFormat.
Rounding increment.
Definition: unum.h:980
C API: UFieldPositionIterator for use with format APIs.
Minimum significant digits.
Definition: unum.h:992
A UParseError struct is used to returned detailed information about parsing errors.
Definition: parseerr.h:58
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.
Basic definitions for ICU, for both C and C++ APIs.
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 international currency symbol.
Definition: unum.h:1285
int32_t unum_getAttribute(const UNumberFormat *fmt, UNumberFormatAttribute attr)
Get a numeric attribute associated with a UNumberFormat.
The default rule set, such as "%spellout-numbering-year:", "%spellout-cardinal:", "%spellout-ordinal-...
Definition: unum.h:1177
The monetary separator.
Definition: unum.h:1287
int32_t unum_toPattern(const UNumberFormat *fmt, UBool isPatternLocalized, UChar *result, int32_t resultLength, UErrorCode *status)
Extract the pattern from a UNumberFormat.
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.
if this attribute is set to 0, it is set to UNUM_CURRENCY_STANDARD purpose, otherwise it is UNUM_CURR...
Definition: unum.h:1034
The currency symbol.
Definition: unum.h:1283
The plus sign.
Definition: unum.h:1281
Duration rule-based format.
Definition: unum.h:190
#define U_DRAFT
This is used to declare a function as a draft public ICU C API.
Definition: umachine.h:113
void * UFormattable
Opaque type representing various types of data which may be used for formatting and parsing operation...
Definition: uformattable.h:70
UNumberFormatAttribute
The possible UNumberFormat numeric attributes.
Definition: unum.h:954
void unum_close(UNumberFormat *fmt)
Close a UNumberFormat.
Negative suffix.
Definition: unum.h:1164
One more than the highest normal UNumberFormatFields value.
Definition: unum.h:379
Grouping size.
Definition: unum.h:976
One more than the highest normal UCurrencySpacing value.
Definition: unum.h:341
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.
The public rule sets.
Definition: unum.h:1186
#define U_STABLE
This is used to declare a function as a stable public ICU C API.
Definition: umachine.h:111
int8_t UBool
The ICU boolean type.
Definition: umachine.h:236
Maximum integer digits.
Definition: unum.h:962
Character representing a digit in the pattern.
Definition: unum.h:1277
C API: Locale.
Always show decimal point.
Definition: unum.h:960
void unum_setTextAttribute(UNumberFormat *fmt, UNumberFormatTextAttribute tag, const UChar *newValue, int32_t newValueLength, UErrorCode *status)
Set a text attribute associated with a UNumberFormat.