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