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