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"
26#include "unicode/udisplaycontext.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
34/**
35 * \file
36 * \brief C API: Compatibility APIs for number formatting.
37 *
38 * <h2> Number Format C API </h2>
39 *
40 * <p><strong>IMPORTANT:</strong> New users with are strongly encouraged to
41 * see if unumberformatter.h fits their use case. Although not deprecated,
42 * this header is provided for backwards compatibility only.
43 *
44 * Number Format C API Provides functions for
45 * formatting and parsing a number. Also provides methods for
46 * determining which locales have number formats, and what their names
47 * are.
48 * <P>
49 * UNumberFormat helps you to format and parse numbers for any locale.
50 * Your code can be completely independent of the locale conventions
51 * for decimal points, thousands-separators, or even the particular
52 * decimal digits used, or whether the number format is even decimal.
53 * There are different number format styles like decimal, currency,
54 * percent and spellout.
55 * <P>
56 * To format a number for the current Locale, use one of the static
57 * factory methods:
58 * <pre>
59 * \code
60 * UChar myString[20];
61 * double myNumber = 7.0;
62 * UErrorCode status = U_ZERO_ERROR;
63 * UNumberFormat* nf = unum_open(UNUM_DEFAULT, NULL, -1, NULL, NULL, &status);
64 * unum_formatDouble(nf, myNumber, myString, 20, NULL, &status);
65 * printf(" Example 1: %s\n", austrdup(myString) ); //austrdup( a function used to convert UChar* to char*)
66 * \endcode
67 * </pre>
68 * If you are formatting multiple numbers, it is more efficient to get
69 * the format and use it multiple times so that the system doesn't
70 * have to fetch the information about the local language and country
71 * conventions multiple times.
72 * <pre>
73 * \code
74 * uint32_t i, resultlength, reslenneeded;
75 * UErrorCode status = U_ZERO_ERROR;
76 * UFieldPosition pos;
77 * uint32_t a[] = { 123, 3333, -1234567 };
78 * const uint32_t a_len = sizeof(a) / sizeof(a[0]);
79 * UNumberFormat* nf;
80 * UChar* result = NULL;
81 *
82 * nf = unum_open(UNUM_DEFAULT, NULL, -1, NULL, NULL, &status);
83 * for (i = 0; i < a_len; i++) {
84 * resultlength=0;
85 * reslenneeded=unum_format(nf, a[i], NULL, resultlength, &pos, &status);
86 * result = NULL;
87 * if(status==U_BUFFER_OVERFLOW_ERROR){
88 * status=U_ZERO_ERROR;
89 * resultlength=reslenneeded+1;
90 * result=(UChar*)malloc(sizeof(UChar) * resultlength);
91 * unum_format(nf, a[i], result, resultlength, &pos, &status);
92 * }
93 * printf( " Example 2: %s\n", austrdup(result));
94 * free(result);
95 * }
96 * \endcode
97 * </pre>
98 * To format a number for a different Locale, specify it in the
99 * call to unum_open().
100 * <pre>
101 * \code
102 * UNumberFormat* nf = unum_open(UNUM_DEFAULT, NULL, -1, "fr_FR", NULL, &success)
103 * \endcode
104 * </pre>
105 * You can use a NumberFormat API unum_parse() to parse.
106 * <pre>
107 * \code
108 * UErrorCode status = U_ZERO_ERROR;
109 * int32_t pos=0;
110 * int32_t num;
111 * num = unum_parse(nf, str, u_strlen(str), &pos, &status);
112 * \endcode
113 * </pre>
114 * Use UNUM_DECIMAL to get the normal number format for that country.
115 * There are other static options available. Use UNUM_CURRENCY
116 * to get the currency number format for that country. Use UNUM_PERCENT
117 * to get a format for displaying percentages. With this format, a
118 * fraction from 0.53 is displayed as 53%.
119 * <P>
120 * Use a pattern to create either a DecimalFormat or a RuleBasedNumberFormat
121 * formatter. The pattern must conform to the syntax defined for those
122 * formatters.
123 * <P>
124 * You can also control the display of numbers with such function as
125 * unum_getAttributes() and unum_setAttributes(), which let you set the
126 * minimum fraction digits, grouping, etc.
127 * @see UNumberFormatAttributes for more details
128 * <P>
129 * You can also use forms of the parse and format methods with
130 * ParsePosition and UFieldPosition to allow you to:
131 * <ul type=round>
132 * <li>(a) progressively parse through pieces of a string.
133 * <li>(b) align the decimal point and other areas.
134 * </ul>
135 * <p>
136 * It is also possible to change or set the symbols used for a particular
137 * locale like the currency symbol, the grouping separator , monetary separator
138 * etc by making use of functions unum_setSymbols() and unum_getSymbols().
139 */
140
141/** A number formatter.
142 * For usage in C programs.
143 * @stable ICU 2.0
144 */
145typedef void* UNumberFormat;
146
147/** The possible number format styles.
148 * @stable ICU 2.0
149 */
150typedef enum UNumberFormatStyle {
151 /**
152 * Decimal format defined by a pattern string.
153 * @stable ICU 3.0
154 */
155 UNUM_PATTERN_DECIMAL=0,
156 /**
157 * Decimal format ("normal" style).
158 * @stable ICU 2.0
159 */
160 UNUM_DECIMAL=1,
161 /**
162 * Currency format (generic).
163 * Defaults to UNUM_CURRENCY_STANDARD style
164 * (using currency symbol, e.g., "$1.00", with non-accounting
165 * style for negative values e.g. using minus sign).
166 * The specific style may be specified using the -cf- locale key.
167 * @stable ICU 2.0
168 */
169 UNUM_CURRENCY=2,
170 /**
171 * Percent format
172 * @stable ICU 2.0
173 */
174 UNUM_PERCENT=3,
175 /**
176 * Scientific format
177 * @stable ICU 2.1
178 */
179 UNUM_SCIENTIFIC=4,
180 /**
181 * Spellout rule-based format. The default ruleset can be specified/changed using
182 * unum_setTextAttribute with UNUM_DEFAULT_RULESET; the available public rulesets
183 * can be listed using unum_getTextAttribute with UNUM_PUBLIC_RULESETS.
184 * @stable ICU 2.0
185 */
186 UNUM_SPELLOUT=5,
187 /**
188 * Ordinal rule-based format . The default ruleset can be specified/changed using
189 * unum_setTextAttribute with UNUM_DEFAULT_RULESET; the available public rulesets
190 * can be listed using unum_getTextAttribute with UNUM_PUBLIC_RULESETS.
191 * @stable ICU 3.0
192 */
193 UNUM_ORDINAL=6,
194 /**
195 * Duration rule-based format
196 * @stable ICU 3.0
197 */
198 UNUM_DURATION=7,
199 /**
200 * Numbering system rule-based format
201 * @stable ICU 4.2
202 */
203 UNUM_NUMBERING_SYSTEM=8,
204 /**
205 * Rule-based format defined by a pattern string.
206 * @stable ICU 3.0
207 */
208 UNUM_PATTERN_RULEBASED=9,
209 /**
210 * Currency format with an ISO currency code, e.g., "USD1.00".
211 * @stable ICU 4.8
212 */
213 UNUM_CURRENCY_ISO=10,
214 /**
215 * Currency format with a pluralized currency name,
216 * e.g., "1.00 US dollar" and "3.00 US dollars".
217 * @stable ICU 4.8
218 */
219 UNUM_CURRENCY_PLURAL=11,
220 /**
221 * Currency format for accounting, e.g., "($3.00)" for
222 * negative currency amount instead of "-$3.00" ({@link #UNUM_CURRENCY}).
223 * Overrides any style specified using -cf- key in locale.
224 * @stable ICU 53
225 */
226 UNUM_CURRENCY_ACCOUNTING=12,
227 /**
228 * Currency format with a currency symbol given CASH usage, e.g.,
229 * "NT$3" instead of "NT$3.23".
230 * @stable ICU 54
231 */
232 UNUM_CASH_CURRENCY=13,
233 /**
234 * Decimal format expressed using compact notation
235 * (short form, corresponds to UNumberCompactStyle=UNUM_SHORT)
236 * e.g. "23K", "45B"
237 * @stable ICU 56
238 */
239 UNUM_DECIMAL_COMPACT_SHORT=14,
240 /**
241 * Decimal format expressed using compact notation
242 * (long form, corresponds to UNumberCompactStyle=UNUM_LONG)
243 * e.g. "23 thousand", "45 billion"
244 * @stable ICU 56
245 */
246 UNUM_DECIMAL_COMPACT_LONG=15,
247 /**
248 * Currency format with a currency symbol, e.g., "$1.00",
249 * using non-accounting style for negative values (e.g. minus sign).
250 * Overrides any style specified using -cf- key in locale.
251 * @stable ICU 56
252 */
253 UNUM_CURRENCY_STANDARD=16,
254
255#ifndef U_HIDE_DEPRECATED_API
256 /**
257 * One more than the highest normal UNumberFormatStyle value.
258 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
259 */
260 UNUM_FORMAT_STYLE_COUNT=17,
261#endif /* U_HIDE_DEPRECATED_API */
262
263 /**
264 * Default format
265 * @stable ICU 2.0
266 */
267 UNUM_DEFAULT = UNUM_DECIMAL,
268 /**
269 * Alias for UNUM_PATTERN_DECIMAL
270 * @stable ICU 3.0
271 */
272 UNUM_IGNORE = UNUM_PATTERN_DECIMAL
273} UNumberFormatStyle;
274
275/** The possible number format pad positions.
276 * @stable ICU 2.0
277 */
278typedef enum UNumberFormatPadPosition {
279 UNUM_PAD_BEFORE_PREFIX,
280 UNUM_PAD_AFTER_PREFIX,
281 UNUM_PAD_BEFORE_SUFFIX,
282 UNUM_PAD_AFTER_SUFFIX
283} UNumberFormatPadPosition;
284
285/**
286 * Constants for specifying short or long format.
287 * @stable ICU 51
288 */
289typedef enum UNumberCompactStyle {
290 /** @stable ICU 51 */
291 UNUM_SHORT,
292 /** @stable ICU 51 */
293 UNUM_LONG
294 /** @stable ICU 51 */
295} UNumberCompactStyle;
296
297/**
298 * Constants for specifying currency spacing
299 * @stable ICU 4.8
300 */
301enum UCurrencySpacing {
302 /** @stable ICU 4.8 */
303 UNUM_CURRENCY_MATCH,
304 /** @stable ICU 4.8 */
305 UNUM_CURRENCY_SURROUNDING_MATCH,
306 /** @stable ICU 4.8 */
307 UNUM_CURRENCY_INSERT,
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 /**
313 * One more than the highest normal UCurrencySpacing value.
314 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
315 */
316 UNUM_CURRENCY_SPACING_COUNT
317#endif // U_FORCE_HIDE_DEPRECATED_API
318};
319typedef enum UCurrencySpacing UCurrencySpacing; /**< @stable ICU 4.8 */
320
321
322/**
323 * FieldPosition and UFieldPosition selectors for format fields
324 * defined by NumberFormat and UNumberFormat.
325 * @stable ICU 49
326 */
327typedef enum UNumberFormatFields {
328 /** @stable ICU 49 */
329 UNUM_INTEGER_FIELD,
330 /** @stable ICU 49 */
331 UNUM_FRACTION_FIELD,
332 /** @stable ICU 49 */
333 UNUM_DECIMAL_SEPARATOR_FIELD,
334 /** @stable ICU 49 */
335 UNUM_EXPONENT_SYMBOL_FIELD,
336 /** @stable ICU 49 */
337 UNUM_EXPONENT_SIGN_FIELD,
338 /** @stable ICU 49 */
339 UNUM_EXPONENT_FIELD,
340 /** @stable ICU 49 */
341 UNUM_GROUPING_SEPARATOR_FIELD,
342 /** @stable ICU 49 */
343 UNUM_CURRENCY_FIELD,
344 /** @stable ICU 49 */
345 UNUM_PERCENT_FIELD,
346 /** @stable ICU 49 */
347 UNUM_PERMILL_FIELD,
348 /** @stable ICU 49 */
349 UNUM_SIGN_FIELD,
350 /** @stable ICU 64 */
351 UNUM_MEASURE_UNIT_FIELD,
352 /** @stable ICU 64 */
353 UNUM_COMPACT_FIELD,
354 /**
355 * Approximately sign. In ICU 70, this was categorized under the generic SIGN field.
356 * @stable ICU 71
357 */
358 UNUM_APPROXIMATELY_SIGN_FIELD,
359
360#ifndef U_HIDE_DEPRECATED_API
361 /**
362 * One more than the highest normal UNumberFormatFields value.
363 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
364 */
365 UNUM_FIELD_COUNT
366#endif /* U_HIDE_DEPRECATED_API */
367} UNumberFormatFields;
368
369
370/**
371 * Selectors with special numeric values to use locale default minimum grouping
372 * digits for the DecimalFormat/UNumberFormat setMinimumGroupingDigits method.
373 * Do not use these constants with the [U]NumberFormatter API.
374 *
375 * @stable ICU 68
376 */
377typedef enum UNumberFormatMinimumGroupingDigits {
378 /**
379 * Display grouping using the default strategy for all locales.
380 * @stable ICU 68
381 */
382 UNUM_MINIMUM_GROUPING_DIGITS_AUTO = -2,
383 /**
384 * Display grouping using locale defaults, except do not show grouping on
385 * values smaller than 10000 (such that there is a minimum of two digits
386 * before the first separator).
387 * @stable ICU 68
388 */
389 UNUM_MINIMUM_GROUPING_DIGITS_MIN2 = -3,
390} UNumberFormatMinimumGroupingDigits;
391
392/**
393 * Create and return a new UNumberFormat for formatting and parsing
394 * numbers. A UNumberFormat may be used to format numbers by calling
395 * {@link #unum_format }, and to parse numbers by calling {@link #unum_parse }.
396 * The caller must call {@link #unum_close } when done to release resources
397 * used by this object.
398 * @param style The type of number format to open: one of
399 * UNUM_DECIMAL, UNUM_CURRENCY, UNUM_PERCENT, UNUM_SCIENTIFIC,
400 * UNUM_CURRENCY_ISO, UNUM_CURRENCY_PLURAL, UNUM_SPELLOUT,
401 * UNUM_ORDINAL, UNUM_DURATION, UNUM_NUMBERING_SYSTEM,
402 * UNUM_PATTERN_DECIMAL, UNUM_PATTERN_RULEBASED, or UNUM_DEFAULT.
403 * If UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED is passed then the
404 * number format is opened using the given pattern, which must conform
405 * to the syntax described in DecimalFormat or RuleBasedNumberFormat,
406 * respectively.
407 *
408 * <p><strong>NOTE::</strong> New users with are strongly encouraged to
409 * use unumf_openForSkeletonAndLocale instead of unum_open.
410 *
411 * @param pattern A pattern specifying the format to use.
412 * This parameter is ignored unless the style is
413 * UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED.
414 * @param patternLength The number of characters in the pattern, or -1
415 * if null-terminated. This parameter is ignored unless the style is
416 * UNUM_PATTERN.
417 * @param locale A locale identifier to use to determine formatting
418 * and parsing conventions, or NULL to use the default locale.
419 * @param parseErr A pointer to a UParseError struct to receive the
420 * details of any parsing errors, or NULL if no parsing error details
421 * are desired.
422 * @param status A pointer to an input-output UErrorCode.
423 * @return A pointer to a newly created UNumberFormat, or NULL if an
424 * error occurred.
425 * @see unum_close
426 * @see DecimalFormat
427 * @stable ICU 2.0
428 */
429U_CAPI UNumberFormat* U_EXPORT2
430unum_open( UNumberFormatStyle style,
431 const UChar* pattern,
432 int32_t patternLength,
433 const char* locale,
434 UParseError* parseErr,
435 UErrorCode* status);
436
437
438/**
439* Close a UNumberFormat.
440* Once closed, a UNumberFormat may no longer be used.
441* @param fmt The formatter to close.
442* @stable ICU 2.0
443*/
444U_CAPI void U_EXPORT2
445unum_close(UNumberFormat* fmt);
446
447#if U_SHOW_CPLUSPLUS_API
448
449U_NAMESPACE_BEGIN
450
451/**
452 * \class LocalUNumberFormatPointer
453 * "Smart pointer" class, closes a UNumberFormat via unum_close().
454 * For most methods see the LocalPointerBase base class.
455 *
456 * @see LocalPointerBase
457 * @see LocalPointer
458 * @stable ICU 4.4
459 */
460U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberFormatPointer, UNumberFormat, unum_close);
461
462U_NAMESPACE_END
463
464#endif
465
466/**
467 * Open a copy of a UNumberFormat.
468 * This function performs a deep copy.
469 * @param fmt The format to copy
470 * @param status A pointer to an UErrorCode to receive any errors.
471 * @return A pointer to a UNumberFormat identical to fmt.
472 * @stable ICU 2.0
473 */
474U_CAPI UNumberFormat* U_EXPORT2
475unum_clone(const UNumberFormat *fmt,
476 UErrorCode *status);
477
478/**
479* Format an integer using a UNumberFormat.
480* The integer will be formatted according to the UNumberFormat's locale.
481* @param fmt The formatter to use.
482* @param number The number to format.
483* @param result A pointer to a buffer to receive the NULL-terminated formatted number. If
484* the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
485* then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number
486* doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR.
487* @param resultLength The maximum size of result.
488* @param pos A pointer to a UFieldPosition. On input, position->field
489* is read. On output, position->beginIndex and position->endIndex indicate
490* the beginning and ending indices of field number position->field, if such
491* a field exists. This parameter may be NULL, in which case no field
492* @param status A pointer to an UErrorCode to receive any errors
493* @return The total buffer size needed; if greater than resultLength, the output was truncated.
494* @see unum_formatInt64
495* @see unum_formatDouble
496* @see unum_parse
497* @see unum_parseInt64
498* @see unum_parseDouble
499* @see UFieldPosition
500* @stable ICU 2.0
501*/
502U_CAPI int32_t U_EXPORT2
503unum_format( const UNumberFormat* fmt,
504 int32_t number,
505 UChar* result,
506 int32_t resultLength,
507 UFieldPosition *pos,
508 UErrorCode* status);
509
510/**
511* Format an int64 using a UNumberFormat.
512* The int64 will be formatted according to the UNumberFormat's locale.
513* @param fmt The formatter to use.
514* @param number The number to format.
515* @param result A pointer to a buffer to receive the NULL-terminated formatted number. If
516* the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
517* then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number
518* doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR.
519* @param resultLength The maximum size of result.
520* @param pos A pointer to a UFieldPosition. On input, position->field
521* is read. On output, position->beginIndex and position->endIndex indicate
522* the beginning and ending indices of field number position->field, if such
523* a field exists. This parameter may be NULL, in which case no field
524* @param status A pointer to an UErrorCode to receive any errors
525* @return The total buffer size needed; if greater than resultLength, the output was truncated.
526* @see unum_format
527* @see unum_formatDouble
528* @see unum_parse
529* @see unum_parseInt64
530* @see unum_parseDouble
531* @see UFieldPosition
532* @stable ICU 2.0
533*/
534U_CAPI int32_t U_EXPORT2
535unum_formatInt64(const UNumberFormat *fmt,
536 int64_t number,
537 UChar* result,
538 int32_t resultLength,
539 UFieldPosition *pos,
540 UErrorCode* status);
541
542/**
543* Format a double using a UNumberFormat.
544* The double will be formatted according to the UNumberFormat's locale.
545* @param fmt The formatter to use.
546* @param number The number to format.
547* @param result A pointer to a buffer to receive the NULL-terminated formatted number. If
548* the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
549* then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number
550* doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR.
551* @param resultLength The maximum size of result.
552* @param pos A pointer to a UFieldPosition. On input, position->field
553* is read. On output, position->beginIndex and position->endIndex indicate
554* the beginning and ending indices of field number position->field, if such
555* a field exists. This parameter may be NULL, in which case no field
556* @param status A pointer to an UErrorCode to receive any errors
557* @return The total buffer size needed; if greater than resultLength, the output was truncated.
558* @see unum_format
559* @see unum_formatInt64
560* @see unum_parse
561* @see unum_parseInt64
562* @see unum_parseDouble
563* @see UFieldPosition
564* @stable ICU 2.0
565*/
566U_CAPI int32_t U_EXPORT2
567unum_formatDouble( const UNumberFormat* fmt,
568 double number,
569 UChar* result,
570 int32_t resultLength,
571 UFieldPosition *pos, /* 0 if ignore */
572 UErrorCode* status);
573
574/**
575* Format a double using a UNumberFormat according to the UNumberFormat's locale,
576* and initialize a UFieldPositionIterator that enumerates the subcomponents of
577* the resulting string.
578*
579* @param format
580* The formatter to use.
581* @param number
582* The number to format.
583* @param result
584* A pointer to a buffer to receive the NULL-terminated formatted
585* number. If the formatted number fits into dest but cannot be
586* NULL-terminated (length == resultLength) then the error code is set
587* to U_STRING_NOT_TERMINATED_WARNING. If the formatted number doesn't
588* fit into result then the error code is set to
589* U_BUFFER_OVERFLOW_ERROR.
590* @param resultLength
591* The maximum size of result.
592* @param fpositer
593* A pointer to a UFieldPositionIterator created by {@link #ufieldpositer_open}
594* (may be NULL if field position information is not needed, but in this
595* case it's preferable to use {@link #unum_formatDouble}). Iteration
596* information already present in the UFieldPositionIterator is deleted,
597* and the iterator is reset to apply to the fields in the formatted
598* string created by this function call. The field values and indexes
599* returned by {@link #ufieldpositer_next} represent fields denoted by
600* the UNumberFormatFields enum. Fields are not returned in a guaranteed
601* order. Fields cannot overlap, but they may nest. For example, 1234
602* could format as "1,234" which might consist of a grouping separator
603* field for ',' and an integer field encompassing the entire string.
604* @param status
605* A pointer to an UErrorCode to receive any errors
606* @return
607* The total buffer size needed; if greater than resultLength, the
608* output was truncated.
609* @see unum_formatDouble
610* @see unum_parse
611* @see unum_parseDouble
612* @see UFieldPositionIterator
613* @see UNumberFormatFields
614* @stable ICU 59
615*/
616U_CAPI int32_t U_EXPORT2
617unum_formatDoubleForFields(const UNumberFormat* format,
618 double number,
619 UChar* result,
620 int32_t resultLength,
621 UFieldPositionIterator* fpositer,
622 UErrorCode* status);
623
624
625/**
626* Format a decimal number using a UNumberFormat.
627* The number will be formatted according to the UNumberFormat's locale.
628* The syntax of the input number is a "numeric string"
629* as defined in the Decimal Arithmetic Specification, available at
630* http://speleotrove.com/decimal
631* @param fmt The formatter to use.
632* @param number The number to format.
633* @param length The length of the input number, or -1 if the input is nul-terminated.
634* @param result A pointer to a buffer to receive the NULL-terminated formatted number. If
635* the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
636* then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number
637* doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR.
638* @param resultLength The maximum size of result.
639* @param pos A pointer to a UFieldPosition. On input, position->field
640* is read. On output, position->beginIndex and position->endIndex indicate
641* the beginning and ending indices of field number position->field, if such
642* a field exists. This parameter may be NULL, in which case it is ignored.
643* @param status A pointer to an UErrorCode to receive any errors
644* @return The total buffer size needed; if greater than resultLength, the output was truncated.
645* @see unum_format
646* @see unum_formatInt64
647* @see unum_parse
648* @see unum_parseInt64
649* @see unum_parseDouble
650* @see UFieldPosition
651* @stable ICU 4.4
652*/
653U_CAPI int32_t U_EXPORT2
654unum_formatDecimal( const UNumberFormat* fmt,
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
662/**
663 * Format a double currency amount using a UNumberFormat.
664 * The double will be formatted according to the UNumberFormat's locale.
665 *
666 * To format an exact decimal value with a currency, use
667 * `unum_setTextAttribute(UNUM_CURRENCY_CODE, ...)` followed by unum_formatDecimal.
668 * Your UNumberFormat must be created with the UNUM_CURRENCY style. Alternatively,
669 * consider using unumf_openForSkeletonAndLocale.
670 *
671 * @param fmt the formatter to use
672 * @param number the number to format
673 * @param currency the 3-letter null-terminated ISO 4217 currency code
674 * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If
675 * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
676 * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number
677 * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR.
678 * @param resultLength the maximum number of UChars to write to result
679 * @param pos a pointer to a UFieldPosition. On input,
680 * position->field is read. On output, position->beginIndex and
681 * position->endIndex indicate the beginning and ending indices of
682 * field number position->field, if such a field exists. This
683 * parameter may be NULL, in which case it is ignored.
684 * @param status a pointer to an input-output UErrorCode
685 * @return the total buffer size needed; if greater than resultLength,
686 * the output was truncated.
687 * @see unum_formatDouble
688 * @see unum_parseDoubleCurrency
689 * @see UFieldPosition
690 * @stable ICU 3.0
691 */
692U_CAPI int32_t U_EXPORT2
693unum_formatDoubleCurrency(const UNumberFormat* fmt,
694 double number,
695 UChar* currency,
696 UChar* result,
697 int32_t resultLength,
698 UFieldPosition* pos,
699 UErrorCode* status);
700
701/**
702 * Format a UFormattable into a string.
703 * @param fmt the formatter to use
704 * @param number the number to format, as a UFormattable
705 * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If
706 * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
707 * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number
708 * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR.
709 * @param resultLength the maximum number of UChars to write to result
710 * @param pos a pointer to a UFieldPosition. On input,
711 * position->field is read. On output, position->beginIndex and
712 * position->endIndex indicate the beginning and ending indices of
713 * field number position->field, if such a field exists. This
714 * parameter may be NULL, in which case it is ignored.
715 * @param status a pointer to an input-output UErrorCode
716 * @return the total buffer size needed; if greater than resultLength,
717 * the output was truncated. Will return 0 on error.
718 * @see unum_parseToUFormattable
719 * @stable ICU 52
720 */
721U_CAPI int32_t U_EXPORT2
722unum_formatUFormattable(const UNumberFormat* fmt,
723 const UFormattable *number,
724 UChar *result,
725 int32_t resultLength,
726 UFieldPosition *pos,
727 UErrorCode *status);
728
729/**
730* Parse a string into an integer using a UNumberFormat.
731* The string will be parsed according to the UNumberFormat's locale.
732* Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT
733* and UNUM_DECIMAL_COMPACT_LONG.
734* @param fmt The formatter to use.
735* @param text The text to parse.
736* @param textLength The length of text, or -1 if null-terminated.
737* @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which
738* to begin parsing. If not NULL, on output the offset at which parsing ended.
739* @param status A pointer to an UErrorCode to receive any errors
740* @return The value of the parsed integer
741* @see unum_parseInt64
742* @see unum_parseDouble
743* @see unum_format
744* @see unum_formatInt64
745* @see unum_formatDouble
746* @stable ICU 2.0
747*/
748U_CAPI int32_t U_EXPORT2
749unum_parse( const UNumberFormat* fmt,
750 const UChar* text,
751 int32_t textLength,
752 int32_t *parsePos /* 0 = start */,
753 UErrorCode *status);
754
755/**
756* Parse a string into an int64 using a UNumberFormat.
757* The string will be parsed according to the UNumberFormat's locale.
758* Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT
759* and UNUM_DECIMAL_COMPACT_LONG.
760* @param fmt The formatter to use.
761* @param text The text to parse.
762* @param textLength The length of text, or -1 if null-terminated.
763* @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which
764* to begin parsing. If not NULL, on output the offset at which parsing ended.
765* @param status A pointer to an UErrorCode to receive any errors
766* @return The value of the parsed integer
767* @see unum_parse
768* @see unum_parseDouble
769* @see unum_format
770* @see unum_formatInt64
771* @see unum_formatDouble
772* @stable ICU 2.8
773*/
774U_CAPI int64_t U_EXPORT2
775unum_parseInt64(const UNumberFormat* fmt,
776 const UChar* text,
777 int32_t textLength,
778 int32_t *parsePos /* 0 = start */,
779 UErrorCode *status);
780
781/**
782* Parse a string into a double using a UNumberFormat.
783* The string will be parsed according to the UNumberFormat's locale.
784* Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT
785* and UNUM_DECIMAL_COMPACT_LONG.
786* @param fmt The formatter to use.
787* @param text The text to parse.
788* @param textLength The length of text, or -1 if null-terminated.
789* @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which
790* to begin parsing. If not NULL, on output the offset at which parsing ended.
791* @param status A pointer to an UErrorCode to receive any errors
792* @return The value of the parsed double
793* @see unum_parse
794* @see unum_parseInt64
795* @see unum_format
796* @see unum_formatInt64
797* @see unum_formatDouble
798* @stable ICU 2.0
799*/
800U_CAPI double U_EXPORT2
801unum_parseDouble( const UNumberFormat* fmt,
802 const UChar* text,
803 int32_t textLength,
804 int32_t *parsePos /* 0 = start */,
805 UErrorCode *status);
806
807
808/**
809* Parse a number from a string into an unformatted numeric string using a UNumberFormat.
810* The input string will be parsed according to the UNumberFormat's locale.
811* The syntax of the output is a "numeric string"
812* as defined in the Decimal Arithmetic Specification, available at
813* http://speleotrove.com/decimal
814* Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT
815* and UNUM_DECIMAL_COMPACT_LONG.
816* @param fmt The formatter to use.
817* @param text The text to parse.
818* @param textLength The length of text, or -1 if null-terminated.
819* @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which
820* to begin parsing. If not NULL, on output the offset at which parsing ended.
821* @param outBuf A (char *) buffer to receive the parsed number as a string. The output string
822* will be nul-terminated if there is sufficient space.
823* @param outBufLength The size of the output buffer. May be zero, in which case
824* the outBuf pointer may be NULL, and the function will return the
825* size of the output string.
826* @param status A pointer to an UErrorCode to receive any errors
827* @return the length of the output string, not including any terminating nul.
828* @see unum_parse
829* @see unum_parseInt64
830* @see unum_format
831* @see unum_formatInt64
832* @see unum_formatDouble
833* @stable ICU 4.4
834*/
835U_CAPI int32_t U_EXPORT2
836unum_parseDecimal(const UNumberFormat* fmt,
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
844/**
845 * Parse a string into a double and a currency using a UNumberFormat.
846 * The string will be parsed according to the UNumberFormat's locale.
847 * @param fmt the formatter to use
848 * @param text the text to parse
849 * @param textLength the length of text, or -1 if null-terminated
850 * @param parsePos a pointer to an offset index into text at which to
851 * begin parsing. On output, *parsePos will point after the last
852 * parsed character. This parameter may be NULL, in which case parsing
853 * begins at offset 0.
854 * @param currency a pointer to the buffer to receive the parsed null-
855 * terminated currency. This buffer must have a capacity of at least
856 * 4 UChars.
857 * @param status a pointer to an input-output UErrorCode
858 * @return the parsed double
859 * @see unum_parseDouble
860 * @see unum_formatDoubleCurrency
861 * @stable ICU 3.0
862 */
863U_CAPI double U_EXPORT2
864unum_parseDoubleCurrency(const UNumberFormat* fmt,
865 const UChar* text,
866 int32_t textLength,
867 int32_t* parsePos, /* 0 = start */
868 UChar* currency,
869 UErrorCode* status);
870
871/**
872 * Parse a UChar string into a UFormattable.
873 * Example code:
874 * \snippet test/cintltst/cnumtst.c unum_parseToUFormattable
875 * Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT
876 * and UNUM_DECIMAL_COMPACT_LONG.
877 * @param fmt the formatter to use
878 * @param result the UFormattable to hold the result. If NULL, a new UFormattable will be allocated (which the caller must close with ufmt_close).
879 * @param text the text to parse
880 * @param textLength the length of text, or -1 if null-terminated
881 * @param parsePos a pointer to an offset index into text at which to
882 * begin parsing. On output, *parsePos will point after the last
883 * parsed character. This parameter may be NULL in which case parsing
884 * begins at offset 0.
885 * @param status a pointer to an input-output UErrorCode
886 * @return the UFormattable. Will be ==result unless NULL was passed in for result, in which case it will be the newly opened UFormattable.
887 * @see ufmt_getType
888 * @see ufmt_close
889 * @stable ICU 52
890 */
891U_CAPI UFormattable* U_EXPORT2
892unum_parseToUFormattable(const UNumberFormat* fmt,
893 UFormattable *result,
894 const UChar* text,
895 int32_t textLength,
896 int32_t* parsePos, /* 0 = start */
897 UErrorCode* status);
898
899/**
900 * Set the pattern used by a UNumberFormat. This can only be used
901 * on a DecimalFormat, other formats return U_UNSUPPORTED_ERROR
902 * in the status.
903 * @param format The formatter to set.
904 * @param localized true if the pattern is localized, false otherwise.
905 * @param pattern The new pattern
906 * @param patternLength The length of pattern, or -1 if null-terminated.
907 * @param parseError A pointer to UParseError to receive information
908 * about errors occurred during parsing, or NULL if no parse error
909 * information is desired.
910 * @param status A pointer to an input-output UErrorCode.
911 * @see unum_toPattern
912 * @see DecimalFormat
913 * @stable ICU 2.0
914 */
915U_CAPI void U_EXPORT2
916unum_applyPattern( UNumberFormat *format,
917 UBool localized,
918 const UChar *pattern,
919 int32_t patternLength,
920 UParseError *parseError,
921 UErrorCode *status
922 );
923
924/**
925* Get a locale for which decimal formatting patterns are available.
926* A UNumberFormat in a locale returned by this function will perform the correct
927* formatting and parsing for the locale. The results of this call are not
928* valid for rule-based number formats.
929* @param localeIndex The index of the desired locale.
930* @return A locale for which number formatting patterns are available, or 0 if none.
931* @see unum_countAvailable
932* @stable ICU 2.0
933*/
934U_CAPI const char* U_EXPORT2
935unum_getAvailable(int32_t localeIndex);
936
937/**
938* Determine how many locales have decimal formatting patterns available. The
939* results of this call are not valid for rule-based number formats.
940* This function is useful for determining the loop ending condition for
941* calls to {@link #unum_getAvailable }.
942* @return The number of locales for which decimal formatting patterns are available.
943* @see unum_getAvailable
944* @stable ICU 2.0
945*/
946U_CAPI int32_t U_EXPORT2
947unum_countAvailable(void);
948
949#if UCONFIG_HAVE_PARSEALLINPUT
950/* The UNumberFormatAttributeValue type cannot be #ifndef U_HIDE_INTERNAL_API, needed for .h variable declaration */
951/**
952 * @internal
953 */
954typedef enum UNumberFormatAttributeValue {
955#ifndef U_HIDE_INTERNAL_API
956 /** @internal */
957 UNUM_NO = 0,
958 /** @internal */
959 UNUM_YES = 1,
960 /** @internal */
961 UNUM_MAYBE = 2
962#else
963 /** @internal */
964 UNUM_FORMAT_ATTRIBUTE_VALUE_HIDDEN
965#endif /* U_HIDE_INTERNAL_API */
966} UNumberFormatAttributeValue;
967#endif
968
969/** The possible UNumberFormat numeric attributes @stable ICU 2.0 */
970typedef enum UNumberFormatAttribute {
971 /** Parse integers only */
972 UNUM_PARSE_INT_ONLY,
973 /** Use grouping separator */
974 UNUM_GROUPING_USED,
975 /** Always show decimal point */
976 UNUM_DECIMAL_ALWAYS_SHOWN,
977 /** Maximum integer digits */
978 UNUM_MAX_INTEGER_DIGITS,
979 /** Minimum integer digits */
980 UNUM_MIN_INTEGER_DIGITS,
981 /** Integer digits */
982 UNUM_INTEGER_DIGITS,
983 /** Maximum fraction digits */
984 UNUM_MAX_FRACTION_DIGITS,
985 /** Minimum fraction digits */
986 UNUM_MIN_FRACTION_DIGITS,
987 /** Fraction digits */
988 UNUM_FRACTION_DIGITS,
989 /** Multiplier */
990 UNUM_MULTIPLIER,
991 /** Grouping size */
992 UNUM_GROUPING_SIZE,
993 /** Rounding Mode */
994 UNUM_ROUNDING_MODE,
995 /** Rounding increment */
996 UNUM_ROUNDING_INCREMENT,
997 /** The width to which the output of <code>format()</code> is padded. */
998 UNUM_FORMAT_WIDTH,
999 /** The position at which padding will take place. */
1000 UNUM_PADDING_POSITION,
1001 /** Secondary grouping size */
1002 UNUM_SECONDARY_GROUPING_SIZE,
1003 /** Use significant digits
1004 * @stable ICU 3.0 */
1005 UNUM_SIGNIFICANT_DIGITS_USED,
1006 /** Minimum significant digits
1007 * @stable ICU 3.0 */
1008 UNUM_MIN_SIGNIFICANT_DIGITS,
1009 /** Maximum significant digits
1010 * @stable ICU 3.0 */
1011 UNUM_MAX_SIGNIFICANT_DIGITS,
1012 /** Lenient parse mode used by rule-based formats.
1013 * @stable ICU 3.0
1014 */
1015 UNUM_LENIENT_PARSE,
1016#if UCONFIG_HAVE_PARSEALLINPUT
1017 /** Consume all input. (may use fastpath). Set to UNUM_YES (require fastpath), UNUM_NO (skip fastpath), or UNUM_MAYBE (heuristic).
1018 * This is an internal ICU API. Do not use.
1019 * @internal
1020 */
1021 UNUM_PARSE_ALL_INPUT = 20,
1022#endif
1023 /**
1024 * Scale, which adjusts the position of the
1025 * decimal point when formatting. Amounts will be multiplied by 10 ^ (scale)
1026 * before they are formatted. The default value for the scale is 0 ( no adjustment ).
1027 *
1028 * <p>Example: setting the scale to 3, 123 formats as "123,000"
1029 * <p>Example: setting the scale to -4, 123 formats as "0.0123"
1030 *
1031 * This setting is analogous to getMultiplierScale() and setMultiplierScale() in decimfmt.h.
1032 *
1033 * @stable ICU 51 */
1034 UNUM_SCALE = 21,
1035
1036 /**
1037 * Minimum grouping digits; most commonly set to 2 to print "1000" instead of "1,000".
1038 * See DecimalFormat::getMinimumGroupingDigits().
1039 *
1040 * For better control over grouping strategies, use UNumberFormatter.
1041 *
1042 * @stable ICU 64
1043 */
1044 UNUM_MINIMUM_GROUPING_DIGITS = 22,
1045
1046 /**
1047 * if this attribute is set to 0, it is set to UNUM_CURRENCY_STANDARD purpose,
1048 * otherwise it is UNUM_CASH_CURRENCY purpose
1049 * Default: 0 (UNUM_CURRENCY_STANDARD purpose)
1050 * @stable ICU 54
1051 */
1052 UNUM_CURRENCY_USAGE = 23,
1053
1054#ifndef U_HIDE_INTERNAL_API
1055 /** One below the first bitfield-boolean item.
1056 * All items after this one are stored in boolean form.
1057 * @internal */
1058 UNUM_MAX_NONBOOLEAN_ATTRIBUTE = 0x0FFF,
1059#endif /* U_HIDE_INTERNAL_API */
1060
1061 /** If 1, specifies that if setting the "max integer digits" attribute would truncate a value, set an error status rather than silently truncating.
1062 * For example, formatting the value 1234 with 4 max int digits would succeed, but formatting 12345 would fail. There is no effect on parsing.
1063 * Default: 0 (not set)
1064 * @stable ICU 50
1065 */
1066 UNUM_FORMAT_FAIL_IF_MORE_THAN_MAX_DIGITS = 0x1000,
1067 /**
1068 * if this attribute is set to 1, specifies that, if the pattern doesn't contain an exponent, the exponent will not be parsed. If the pattern does contain an exponent, this attribute has no effect.
1069 * Has no effect on formatting.
1070 * Default: 0 (unset)
1071 * @stable ICU 50
1072 */
1073 UNUM_PARSE_NO_EXPONENT = 0x1001,
1074
1075 /**
1076 * if this attribute is set to 1, specifies that, if the pattern contains a
1077 * decimal mark the input is required to have one. If this attribute is set to 0,
1078 * specifies that input does not have to contain a decimal mark.
1079 * Has no effect on formatting.
1080 * Default: 0 (unset)
1081 * @stable ICU 54
1082 */
1083 UNUM_PARSE_DECIMAL_MARK_REQUIRED = 0x1002,
1084
1085 /**
1086 * Parsing: if set to 1, parsing is sensitive to case (lowercase/uppercase).
1087 *
1088 * @stable ICU 64
1089 */
1090 UNUM_PARSE_CASE_SENSITIVE = 0x1003,
1091
1092 /**
1093 * Formatting: if set to 1, whether to show the plus sign on non-negative numbers.
1094 *
1095 * For better control over sign display, use UNumberFormatter.
1096 *
1097 * @stable ICU 64
1098 */
1099 UNUM_SIGN_ALWAYS_SHOWN = 0x1004,
1100
1101#ifndef U_HIDE_INTERNAL_API
1102 /** Limit of boolean attributes. (value should
1103 * not depend on U_HIDE conditionals)
1104 * @internal */
1105 UNUM_LIMIT_BOOLEAN_ATTRIBUTE = 0x1005,
1106#endif /* U_HIDE_INTERNAL_API */
1107
1108} UNumberFormatAttribute;
1109
1110/**
1111* Returns true if the formatter supports the specified attribute and false if not.
1112* @param fmt The formatter to query.
1113* @param attr The attribute to query. This can be any value of UNumberFormatterAttribute,
1114* regardless of type.
1115* @return True if the requested attribute is supported by the formatter; false if not.
1116* @see unum_getAttribute
1117* @see unum_setAttribute
1118* @see unum_getDoubleAttribute
1119* @see unum_setDoubleAttribute
1120* @see unum_getTextAttribute
1121* @see unum_setTextAttribute
1122* @stable ICU 72
1123*/
1124U_CAPI bool U_EXPORT2
1125unum_hasAttribute(const UNumberFormat* fmt,
1126 UNumberFormatAttribute attr);
1127
1128/**
1129* Get a numeric attribute associated with a UNumberFormat.
1130* An example of a numeric attribute is the number of integer digits a formatter will produce.
1131* @param fmt The formatter to query.
1132* @param attr The attribute to query; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED,
1133* UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS,
1134* UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER,
1135* UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE,
1136* UNUM_SCALE, UNUM_MINIMUM_GROUPING_DIGITS.
1137* @return The value of attr, or -1 if the formatter doesn't have the requested attribute. The caller should use unum_hasAttribute() to tell if the attribute
1138* is available, rather than relaying on this function returning -1.
1139* @see unum_hasAttribute
1140* @see unum_setAttribute
1141* @see unum_getDoubleAttribute
1142* @see unum_setDoubleAttribute
1143* @stable ICU 2.0
1144*/
1145U_CAPI int32_t U_EXPORT2
1146unum_getAttribute(const UNumberFormat* fmt,
1147 UNumberFormatAttribute attr);
1148
1149/**
1150* Set a numeric attribute associated with a UNumberFormat.
1151* An example of a numeric attribute is the number of integer digits a formatter will produce. If the
1152* formatter does not understand the attribute, the call is ignored. Rule-based formatters only understand
1153* the lenient-parse attribute. The caller can use unum_hasAttribute() to find out if the formatter supports the attribute.
1154* @param fmt The formatter to set.
1155* @param attr The attribute to set; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED,
1156* UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS,
1157* UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER,
1158* UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE,
1159* UNUM_LENIENT_PARSE, UNUM_SCALE, UNUM_MINIMUM_GROUPING_DIGITS.
1160* @param newValue The new value of attr.
1161* @see unum_hasAttribute
1162* @see unum_getAttribute
1163* @see unum_getDoubleAttribute
1164* @see unum_setDoubleAttribute
1165* @see unum_getTextAttribute
1166* @see unum_setTextAttribute
1167* @stable ICU 2.0
1168*/
1169U_CAPI void U_EXPORT2
1170unum_setAttribute( UNumberFormat* fmt,
1171 UNumberFormatAttribute attr,
1172 int32_t newValue);
1173
1174
1175/**
1176* Get a numeric attribute associated with a UNumberFormat.
1177* An example of a numeric attribute is the number of integer digits a formatter will produce.
1178* If the formatter does not understand the attribute, -1 is returned. The caller should use unum_hasAttribute()
1179* to determine if the attribute is supported, rather than relying on this function returning -1.
1180* @param fmt The formatter to query.
1181* @param attr The attribute to query; e.g. UNUM_ROUNDING_INCREMENT.
1182* @return The value of attr, or -1 if the formatter doesn't understand the attribute.
1183* @see unum_hasAttribute
1184* @see unum_getAttribute
1185* @see unum_setAttribute
1186* @see unum_setDoubleAttribute
1187* @see unum_getTextAttribute
1188* @see unum_setTextAttribute
1189* @stable ICU 2.0
1190*/
1191U_CAPI double U_EXPORT2
1192unum_getDoubleAttribute(const UNumberFormat* fmt,
1193 UNumberFormatAttribute attr);
1194
1195/**
1196* Set a numeric attribute associated with a UNumberFormat.
1197* An example of a numeric attribute is the number of integer digits a formatter will produce.
1198* If the formatter does not understand the attribute, this call is ignored. The caller can use
1199* unum_hasAttribute() to tell in advance whether the formatter understands the attribute.
1200* @param fmt The formatter to set.
1201* @param attr The attribute to set; e.g. UNUM_ROUNDING_INCREMENT.
1202* @param newValue The new value of attr.
1203* @see unum_hasAttribute
1204* @see unum_getAttribute
1205* @see unum_setAttribute
1206* @see unum_getDoubleAttribute
1207* @see unum_getTextAttribute
1208* @see unum_setTextAttribute
1209* @stable ICU 2.0
1210*/
1211U_CAPI void U_EXPORT2
1212unum_setDoubleAttribute( UNumberFormat* fmt,
1213 UNumberFormatAttribute attr,
1214 double newValue);
1215
1216/** The possible UNumberFormat text attributes @stable ICU 2.0*/
1217typedef enum UNumberFormatTextAttribute {
1218 /** Positive prefix */
1219 UNUM_POSITIVE_PREFIX,
1220 /** Positive suffix */
1221 UNUM_POSITIVE_SUFFIX,
1222 /** Negative prefix */
1223 UNUM_NEGATIVE_PREFIX,
1224 /** Negative suffix */
1225 UNUM_NEGATIVE_SUFFIX,
1226 /** The character used to pad to the format width. */
1227 UNUM_PADDING_CHARACTER,
1228 /** The ISO currency code */
1229 UNUM_CURRENCY_CODE,
1230 /**
1231 * The default rule set, such as "%spellout-numbering-year:", "%spellout-cardinal:",
1232 * "%spellout-ordinal-masculine-plural:", "%spellout-ordinal-feminine:", or
1233 * "%spellout-ordinal-neuter:". The available public rulesets can be listed using
1234 * unum_getTextAttribute with UNUM_PUBLIC_RULESETS. This is only available with
1235 * rule-based formatters.
1236 * @stable ICU 3.0
1237 */
1238 UNUM_DEFAULT_RULESET,
1239 /**
1240 * The public rule sets. This is only available with rule-based formatters.
1241 * This is a read-only attribute. The public rulesets are returned as a
1242 * single string, with each ruleset name delimited by ';' (semicolon). See the
1243 * CLDR LDML spec for more information about RBNF rulesets:
1244 * http://www.unicode.org/reports/tr35/tr35-numbers.html#Rule-Based_Number_Formatting
1245 * @stable ICU 3.0
1246 */
1247 UNUM_PUBLIC_RULESETS
1248} UNumberFormatTextAttribute;
1249
1250/**
1251* Get a text attribute associated with a UNumberFormat.
1252* An example of a text attribute is the suffix for positive numbers. If the formatter
1253* does not understand the attribute, U_UNSUPPORTED_ERROR is returned as the status.
1254* Rule-based formatters only understand UNUM_DEFAULT_RULESET and UNUM_PUBLIC_RULESETS.
1255* @param fmt The formatter to query.
1256* @param tag The attribute to query; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX,
1257* UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE,
1258* UNUM_DEFAULT_RULESET, or UNUM_PUBLIC_RULESETS.
1259* @param result A pointer to a buffer to receive the attribute.
1260* @param resultLength The maximum size of result.
1261* @param status A pointer to an UErrorCode to receive any errors
1262* @return The total buffer size needed; if greater than resultLength, the output was truncated.
1263* @see unum_setTextAttribute
1264* @see unum_getAttribute
1265* @see unum_setAttribute
1266* @stable ICU 2.0
1267*/
1268U_CAPI int32_t U_EXPORT2
1269unum_getTextAttribute( const UNumberFormat* fmt,
1270 UNumberFormatTextAttribute tag,
1271 UChar* result,
1272 int32_t resultLength,
1273 UErrorCode* status);
1274
1275/**
1276* Set a text attribute associated with a UNumberFormat.
1277* An example of a text attribute is the suffix for positive numbers. Rule-based formatters
1278* only understand UNUM_DEFAULT_RULESET.
1279* @param fmt The formatter to set.
1280* @param tag The attribute to set; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX,
1281* UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE,
1282* or UNUM_DEFAULT_RULESET.
1283* @param newValue The new value of attr.
1284* @param newValueLength The length of newValue, or -1 if null-terminated.
1285* @param status A pointer to an UErrorCode to receive any errors
1286* @see unum_getTextAttribute
1287* @see unum_getAttribute
1288* @see unum_setAttribute
1289* @stable ICU 2.0
1290*/
1291U_CAPI void U_EXPORT2
1292unum_setTextAttribute( UNumberFormat* fmt,
1293 UNumberFormatTextAttribute tag,
1294 const UChar* newValue,
1295 int32_t newValueLength,
1296 UErrorCode *status);
1297
1298/**
1299 * Extract the pattern from a UNumberFormat. The pattern will follow
1300 * the DecimalFormat pattern syntax.
1301 * @param fmt The formatter to query.
1302 * @param isPatternLocalized true if the pattern should be localized,
1303 * false otherwise. This is ignored if the formatter is a rule-based
1304 * formatter.
1305 * @param result A pointer to a buffer to receive the pattern.
1306 * @param resultLength The maximum size of result.
1307 * @param status A pointer to an input-output UErrorCode.
1308 * @return The total buffer size needed; if greater than resultLength,
1309 * the output was truncated.
1310 * @see unum_applyPattern
1311 * @see DecimalFormat
1312 * @stable ICU 2.0
1313 */
1314U_CAPI int32_t U_EXPORT2
1315unum_toPattern( const UNumberFormat* fmt,
1316 UBool isPatternLocalized,
1317 UChar* result,
1318 int32_t resultLength,
1319 UErrorCode* status);
1320
1321
1322/**
1323 * Constants for specifying a number format symbol.
1324 * @stable ICU 2.0
1325 */
1326typedef enum UNumberFormatSymbol {
1327 /** The decimal separator */
1328 UNUM_DECIMAL_SEPARATOR_SYMBOL = 0,
1329 /** The grouping separator */
1330 UNUM_GROUPING_SEPARATOR_SYMBOL = 1,
1331 /** The pattern separator */
1332 UNUM_PATTERN_SEPARATOR_SYMBOL = 2,
1333 /** The percent sign */
1334 UNUM_PERCENT_SYMBOL = 3,
1335 /** Zero*/
1336 UNUM_ZERO_DIGIT_SYMBOL = 4,
1337 /** Character representing a digit in the pattern */
1338 UNUM_DIGIT_SYMBOL = 5,
1339 /** The minus sign */
1340 UNUM_MINUS_SIGN_SYMBOL = 6,
1341 /** The plus sign */
1342 UNUM_PLUS_SIGN_SYMBOL = 7,
1343 /** The currency symbol */
1344 UNUM_CURRENCY_SYMBOL = 8,
1345 /** The international currency symbol */
1346 UNUM_INTL_CURRENCY_SYMBOL = 9,
1347 /** The monetary separator */
1348 UNUM_MONETARY_SEPARATOR_SYMBOL = 10,
1349 /** The exponential symbol */
1350 UNUM_EXPONENTIAL_SYMBOL = 11,
1351 /** Per mill symbol */
1352 UNUM_PERMILL_SYMBOL = 12,
1353 /** Escape padding character */
1354 UNUM_PAD_ESCAPE_SYMBOL = 13,
1355 /** Infinity symbol */
1356 UNUM_INFINITY_SYMBOL = 14,
1357 /** Nan symbol */
1358 UNUM_NAN_SYMBOL = 15,
1359 /** Significant digit symbol
1360 * @stable ICU 3.0 */
1361 UNUM_SIGNIFICANT_DIGIT_SYMBOL = 16,
1362 /** The monetary grouping separator
1363 * @stable ICU 3.6
1364 */
1365 UNUM_MONETARY_GROUPING_SEPARATOR_SYMBOL = 17,
1366 /** One
1367 * @stable ICU 4.6
1368 */
1369 UNUM_ONE_DIGIT_SYMBOL = 18,
1370 /** Two
1371 * @stable ICU 4.6
1372 */
1373 UNUM_TWO_DIGIT_SYMBOL = 19,
1374 /** Three
1375 * @stable ICU 4.6
1376 */
1377 UNUM_THREE_DIGIT_SYMBOL = 20,
1378 /** Four
1379 * @stable ICU 4.6
1380 */
1381 UNUM_FOUR_DIGIT_SYMBOL = 21,
1382 /** Five
1383 * @stable ICU 4.6
1384 */
1385 UNUM_FIVE_DIGIT_SYMBOL = 22,
1386 /** Six
1387 * @stable ICU 4.6
1388 */
1389 UNUM_SIX_DIGIT_SYMBOL = 23,
1390 /** Seven
1391 * @stable ICU 4.6
1392 */
1393 UNUM_SEVEN_DIGIT_SYMBOL = 24,
1394 /** Eight
1395 * @stable ICU 4.6
1396 */
1397 UNUM_EIGHT_DIGIT_SYMBOL = 25,
1398 /** Nine
1399 * @stable ICU 4.6
1400 */
1401 UNUM_NINE_DIGIT_SYMBOL = 26,
1402
1403 /** Multiplication sign
1404 * @stable ICU 54
1405 */
1406 UNUM_EXPONENT_MULTIPLICATION_SYMBOL = 27,
1407
1408#ifndef U_HIDE_INTERNAL_API
1409 /** Approximately sign.
1410 * @internal
1411 */
1412 UNUM_APPROXIMATELY_SIGN_SYMBOL = 28,
1413#endif
1414
1415#ifndef U_HIDE_DEPRECATED_API
1416 /**
1417 * One more than the highest normal UNumberFormatSymbol value.
1418 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
1419 */
1420 UNUM_FORMAT_SYMBOL_COUNT = 29
1421#endif /* U_HIDE_DEPRECATED_API */
1422} UNumberFormatSymbol;
1423
1424/**
1425* Get a symbol associated with a UNumberFormat.
1426* A UNumberFormat uses symbols to represent the special locale-dependent
1427* characters in a number, for example the percent sign. This API is not
1428* supported for rule-based formatters.
1429* @param fmt The formatter to query.
1430* @param symbol The UNumberFormatSymbol constant for the symbol to get
1431* @param buffer The string buffer that will receive the symbol string;
1432* if it is NULL, then only the length of the symbol is returned
1433* @param size The size of the string buffer
1434* @param status A pointer to an UErrorCode to receive any errors
1435* @return The length of the symbol; the buffer is not modified if
1436* <code>length&gt;=size</code>
1437* @see unum_setSymbol
1438* @stable ICU 2.0
1439*/
1440U_CAPI int32_t U_EXPORT2
1441unum_getSymbol(const UNumberFormat *fmt,
1442 UNumberFormatSymbol symbol,
1443 UChar *buffer,
1444 int32_t size,
1445 UErrorCode *status);
1446
1447/**
1448* Set a symbol associated with a UNumberFormat.
1449* A UNumberFormat uses symbols to represent the special locale-dependent
1450* characters in a number, for example the percent sign. This API is not
1451* supported for rule-based formatters.
1452* @param fmt The formatter to set.
1453* @param symbol The UNumberFormatSymbol constant for the symbol to set
1454* @param value The string to set the symbol to
1455* @param length The length of the string, or -1 for a zero-terminated string
1456* @param status A pointer to an UErrorCode to receive any errors.
1457* @see unum_getSymbol
1458* @stable ICU 2.0
1459*/
1460U_CAPI void U_EXPORT2
1461unum_setSymbol(UNumberFormat *fmt,
1462 UNumberFormatSymbol symbol,
1463 const UChar *value,
1464 int32_t length,
1465 UErrorCode *status);
1466
1467
1468/**
1469 * Get the locale for this number format object.
1470 * You can choose between valid and actual locale.
1471 * @param fmt The formatter to get the locale from
1472 * @param type type of the locale we're looking for (valid or actual)
1473 * @param status error code for the operation
1474 * @return the locale name
1475 * @stable ICU 2.8
1476 */
1477U_CAPI const char* U_EXPORT2
1478unum_getLocaleByType(const UNumberFormat *fmt,
1479 ULocDataLocaleType type,
1480 UErrorCode* status);
1481
1482/**
1483 * Set a particular UDisplayContext value in the formatter, such as
1484 * UDISPCTX_CAPITALIZATION_FOR_STANDALONE.
1485 * @param fmt The formatter for which to set a UDisplayContext value.
1486 * @param value The UDisplayContext value to set.
1487 * @param status A pointer to an UErrorCode to receive any errors
1488 * @stable ICU 53
1489 */
1490U_CAPI void U_EXPORT2
1491unum_setContext(UNumberFormat* fmt, UDisplayContext value, UErrorCode* status);
1492
1493/**
1494 * Get the formatter's UDisplayContext value for the specified UDisplayContextType,
1495 * such as UDISPCTX_TYPE_CAPITALIZATION.
1496 * @param fmt The formatter to query.
1497 * @param type The UDisplayContextType whose value to return
1498 * @param status A pointer to an UErrorCode to receive any errors
1499 * @return The UDisplayContextValue for the specified type.
1500 * @stable ICU 53
1501 */
1502U_CAPI UDisplayContext U_EXPORT2
1503unum_getContext(const UNumberFormat *fmt, UDisplayContextType type, UErrorCode* status);
1504
1505#endif /* #if !UCONFIG_NO_FORMATTING */
1506
1507#endif
1508

source code of include/unicode/unum.h