[INTL] Implement supportedLocalesOf on Intl Constructors
[WebKit.git] / Source / JavaScriptCore / icu / unicode / unum.h
1 /*
2 *******************************************************************************
3 * Copyright (C) 1997-2010, 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 /**
24  * \file
25  * \brief C API: NumberFormat
26  *
27  * <h2> Number Format C API </h2>
28  *
29  * Number Format C API  Provides functions for
30  * formatting and parsing a number.  Also provides methods for
31  * determining which locales have number formats, and what their names
32  * are.
33  * <P>
34  * UNumberFormat helps you to format and parse numbers for any locale.
35  * Your code can be completely independent of the locale conventions
36  * for decimal points, thousands-separators, or even the particular
37  * decimal digits used, or whether the number format is even decimal.
38  * There are different number format styles like decimal, currency,
39  * percent and spellout.
40  * <P>
41  * To format a number for the current Locale, use one of the static
42  * factory methods:
43  * <pre>
44  * \code
45  *    UChar myString[20];
46  *    double myNumber = 7.0;
47  *    UErrorCode status = U_ZERO_ERROR;
48  *    UNumberFormat* nf = unum_open(UNUM_DEFAULT, NULL, -1, NULL, NULL, &status);
49  *    unum_formatDouble(nf, myNumber, myString, 20, NULL, &status);
50  *    printf(" Example 1: %s\n", austrdup(myString) ); //austrdup( a function used to convert UChar* to char*)
51  * \endcode
52  * </pre>
53  * If you are formatting multiple numbers, it is more efficient to get
54  * the format and use it multiple times so that the system doesn't
55  * have to fetch the information about the local language and country
56  * conventions multiple times.
57  * <pre>
58  * \code
59  * uint32_t i, resultlength, reslenneeded;
60  * UErrorCode status = U_ZERO_ERROR;
61  * UFieldPosition pos;
62  * uint32_t a[] = { 123, 3333, -1234567 };
63  * const uint32_t a_len = sizeof(a) / sizeof(a[0]);
64  * UNumberFormat* nf;
65  * UChar* result = NULL;
66  *
67  * nf = unum_open(UNUM_DEFAULT, NULL, -1, NULL, NULL, &status);
68  * for (i = 0; i < a_len; i++) {
69  *    resultlength=0;
70  *    reslenneeded=unum_format(nf, a[i], NULL, resultlength, &pos, &status);
71  *    result = NULL;
72  *    if(status==U_BUFFER_OVERFLOW_ERROR){
73  *       status=U_ZERO_ERROR;
74  *       resultlength=reslenneeded+1;
75  *       result=(UChar*)malloc(sizeof(UChar) * resultlength);
76  *       unum_format(nf, a[i], result, resultlength, &pos, &status);
77  *    }
78  *    printf( " Example 2: %s\n", austrdup(result));
79  *    free(result);
80  * }
81  * \endcode
82  * </pre>
83  * To format a number for a different Locale, specify it in the
84  * call to unum_open().
85  * <pre>
86  * \code
87  *     UNumberFormat* nf = unum_open(UNUM_DEFAULT, NULL, -1, "fr_FR", NULL, &success)
88  * \endcode
89  * </pre>
90  * You can use a NumberFormat API unum_parse() to parse.
91  * <pre>
92  * \code
93  *    UErrorCode status = U_ZERO_ERROR;
94  *    int32_t pos=0;
95  *    int32_t num;
96  *    num = unum_parse(nf, str, u_strlen(str), &pos, &status);
97  * \endcode
98  * </pre>
99  * Use UNUM_DECIMAL to get the normal number format for that country.
100  * There are other static options available.  Use UNUM_CURRENCY
101  * to get the currency number format for that country.  Use UNUM_PERCENT
102  * to get a format for displaying percentages. With this format, a
103  * fraction from 0.53 is displayed as 53%.
104  * <P>
105  * Use a pattern to create either a DecimalFormat or a RuleBasedNumberFormat
106  * formatter.  The pattern must conform to the syntax defined for those
107  * formatters.
108  * <P>
109  * You can also control the display of numbers with such function as
110  * unum_getAttribues() and unum_setAtributes(), which let you set the
111  * miminum fraction digits, grouping, etc.
112  * @see UNumberFormatAttributes for more details
113  * <P>
114  * You can also use forms of the parse and format methods with
115  * ParsePosition and UFieldPosition to allow you to:
116  * <ul type=round>
117  *   <li>(a) progressively parse through pieces of a string.
118  *   <li>(b) align the decimal point and other areas.
119  * </ul>
120  * <p>
121  * It is also possible to change or set the symbols used for a particular
122  * locale like the currency symbol, the grouping seperator , monetary seperator
123  * etc by making use of functions unum_setSymbols() and unum_getSymbols().
124  */
125
126 /** A number formatter.
127  *  For usage in C programs.
128  *  @stable ICU 2.0
129  */
130 typedef void* UNumberFormat;
131
132 /** The possible number format styles. 
133  *  @stable ICU 2.0
134  */
135 typedef enum UNumberFormatStyle {
136     /**
137      * Decimal format defined by pattern 
138      * @stable ICU 3.0
139      */
140     UNUM_PATTERN_DECIMAL=0,
141     /** Decimal format */
142     UNUM_DECIMAL=1,
143     /** Currency format */
144     UNUM_CURRENCY,
145     /** Percent format */
146     UNUM_PERCENT,
147     /** Scientific format */
148     UNUM_SCIENTIFIC,
149     /** Spellout rule-based format */
150     UNUM_SPELLOUT,
151     /** 
152      * Ordinal rule-based format 
153      * @stable ICU 3.0
154      */
155     UNUM_ORDINAL,
156     /** 
157      * Duration rule-based format 
158      * @stable ICU 3.0
159      */
160     UNUM_DURATION,
161     /** 
162      * Numbering system rule-based format 
163      * @stable ICU 4.2
164      */
165     UNUM_NUMBERING_SYSTEM,
166     /** 
167      * Rule-based format defined by pattern 
168      * @stable ICU 3.0
169      */
170     UNUM_PATTERN_RULEBASED,
171     /** Default format */
172     UNUM_DEFAULT = UNUM_DECIMAL,
173     /** (Alias for UNUM_PATTERN_DECIMAL) */
174     UNUM_IGNORE = UNUM_PATTERN_DECIMAL
175 } UNumberFormatStyle;
176
177 /** The possible number format rounding modes. 
178  *  @stable ICU 2.0
179  */
180 typedef enum UNumberFormatRoundingMode {
181     UNUM_ROUND_CEILING,
182     UNUM_ROUND_FLOOR,
183     UNUM_ROUND_DOWN,
184     UNUM_ROUND_UP,
185     /**
186      * Half-even rounding, misspelled name
187      * @deprecated, ICU 3.8
188      */
189     UNUM_FOUND_HALFEVEN,
190     UNUM_ROUND_HALFDOWN,
191     UNUM_ROUND_HALFUP,
192     /**
193      * Half-even rounding
194      * @stable, ICU 3.8
195      */
196     UNUM_ROUND_HALFEVEN = UNUM_FOUND_HALFEVEN
197 } UNumberFormatRoundingMode;
198
199 /** The possible number format pad positions. 
200  *  @stable ICU 2.0
201  */
202 typedef enum UNumberFormatPadPosition {
203     UNUM_PAD_BEFORE_PREFIX,
204     UNUM_PAD_AFTER_PREFIX,
205     UNUM_PAD_BEFORE_SUFFIX,
206     UNUM_PAD_AFTER_SUFFIX
207 } UNumberFormatPadPosition;
208
209 /**
210  * Create and return a new UNumberFormat for formatting and parsing
211  * numbers.  A UNumberFormat may be used to format numbers by calling
212  * {@link #unum_format }, and to parse numbers by calling {@link #unum_parse }.
213  * The caller must call {@link #unum_close } when done to release resources
214  * used by this object.
215  * @param style The type of number format to open: one of
216  * UNUM_DECIMAL, UNUM_CURRENCY, UNUM_PERCENT, UNUM_SCIENTIFIC, UNUM_SPELLOUT,
217  * UNUM_PATTERN_DECIMAL, UNUM_PATTERN_RULEBASED, or UNUM_DEFAULT.
218  * If UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED is passed then the
219  * number format is opened using the given pattern, which must conform
220  * to the syntax described in DecimalFormat or RuleBasedNumberFormat,
221  * respectively.
222  * @param pattern A pattern specifying the format to use. 
223  * This parameter is ignored unless the style is
224  * UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED.
225  * @param patternLength The number of characters in the pattern, or -1
226  * if null-terminated. This parameter is ignored unless the style is
227  * UNUM_PATTERN.
228  * @param locale A locale identifier to use to determine formatting
229  * and parsing conventions, or NULL to use the default locale.
230  * @param parseErr A pointer to a UParseError struct to receive the
231  * details of any parsing errors, or NULL if no parsing error details
232  * are desired.
233  * @param status A pointer to an input-output UErrorCode.
234  * @return A pointer to a newly created UNumberFormat, or NULL if an
235  * error occurred.
236  * @see unum_close
237  * @see DecimalFormat
238  * @stable ICU 2.0
239  */
240 U_STABLE UNumberFormat* U_EXPORT2 
241 unum_open(  UNumberFormatStyle    style,
242             const    UChar*    pattern,
243             int32_t            patternLength,
244             const    char*     locale,
245             UParseError*       parseErr,
246             UErrorCode*        status);
247
248
249 /**
250 * Close a UNumberFormat.
251 * Once closed, a UNumberFormat may no longer be used.
252 * @param fmt The formatter to close.
253 * @stable ICU 2.0
254 */
255 U_STABLE void U_EXPORT2 
256 unum_close(UNumberFormat* fmt);
257
258 #if U_SHOW_CPLUSPLUS_API
259
260 U_NAMESPACE_BEGIN
261
262 /**
263  * \class LocalUNumberFormatPointer
264  * "Smart pointer" class, closes a UNumberFormat via unum_close().
265  * For most methods see the LocalPointerBase base class.
266  *
267  * @see LocalPointerBase
268  * @see LocalPointer
269  * @stable ICU 4.4
270  */
271 U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberFormatPointer, UNumberFormat, unum_close);
272
273 U_NAMESPACE_END
274
275 #endif
276
277 /**
278  * Open a copy of a UNumberFormat.
279  * This function performs a deep copy.
280  * @param fmt The format to copy
281  * @param status A pointer to an UErrorCode to receive any errors.
282  * @return A pointer to a UNumberFormat identical to fmt.
283  * @stable ICU 2.0
284  */
285 U_STABLE UNumberFormat* U_EXPORT2 
286 unum_clone(const UNumberFormat *fmt,
287        UErrorCode *status);
288
289 /**
290 * Format an integer using a UNumberFormat.
291 * The integer will be formatted according to the UNumberFormat's locale.
292 * @param fmt The formatter to use.
293 * @param number The number to format.
294 * @param result A pointer to a buffer to receive the formatted number.
295 * @param resultLength The maximum size of result.
296 * @param pos    A pointer to a UFieldPosition.  On input, position->field
297 * is read.  On output, position->beginIndex and position->endIndex indicate
298 * the beginning and ending indices of field number position->field, if such
299 * a field exists.  This parameter may be NULL, in which case no field
300 * @param status A pointer to an UErrorCode to receive any errors
301 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
302 * @see unum_formatInt64
303 * @see unum_formatDouble
304 * @see unum_parse
305 * @see unum_parseInt64
306 * @see unum_parseDouble
307 * @see UFieldPosition
308 * @stable ICU 2.0
309 */
310 U_STABLE int32_t U_EXPORT2 
311 unum_format(    const    UNumberFormat*    fmt,
312         int32_t            number,
313         UChar*            result,
314         int32_t            resultLength,
315         UFieldPosition    *pos,
316         UErrorCode*        status);
317
318 /**
319 * Format an int64 using a UNumberFormat.
320 * The int64 will be formatted according to the UNumberFormat's locale.
321 * @param fmt The formatter to use.
322 * @param number The number to format.
323 * @param result A pointer to a buffer to receive the formatted number.
324 * @param resultLength The maximum size of result.
325 * @param pos    A pointer to a UFieldPosition.  On input, position->field
326 * is read.  On output, position->beginIndex and position->endIndex indicate
327 * the beginning and ending indices of field number position->field, if such
328 * a field exists.  This parameter may be NULL, in which case no field
329 * @param status A pointer to an UErrorCode to receive any errors
330 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
331 * @see unum_format
332 * @see unum_formatDouble
333 * @see unum_parse
334 * @see unum_parseInt64
335 * @see unum_parseDouble
336 * @see UFieldPosition
337 * @stable ICU 2.0
338 */
339 U_STABLE int32_t U_EXPORT2 
340 unum_formatInt64(const UNumberFormat *fmt,
341         int64_t         number,
342         UChar*          result,
343         int32_t         resultLength,
344         UFieldPosition *pos,
345         UErrorCode*     status);
346
347 /**
348 * Format a double using a UNumberFormat.
349 * The double will be formatted according to the UNumberFormat's locale.
350 * @param fmt The formatter to use.
351 * @param number The number to format.
352 * @param result A pointer to a buffer to receive the formatted number.
353 * @param resultLength The maximum size of result.
354 * @param pos    A pointer to a UFieldPosition.  On input, position->field
355 * is read.  On output, position->beginIndex and position->endIndex indicate
356 * the beginning and ending indices of field number position->field, if such
357 * a field exists.  This parameter may be NULL, in which case no field
358 * @param status A pointer to an UErrorCode to receive any errors
359 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
360 * @see unum_format
361 * @see unum_formatInt64
362 * @see unum_parse
363 * @see unum_parseInt64
364 * @see unum_parseDouble
365 * @see UFieldPosition
366 * @stable ICU 2.0
367 */
368 U_STABLE int32_t U_EXPORT2 
369 unum_formatDouble(    const    UNumberFormat*  fmt,
370             double          number,
371             UChar*          result,
372             int32_t         resultLength,
373             UFieldPosition  *pos, /* 0 if ignore */
374             UErrorCode*     status);
375
376 /**
377 * Format a decimal number using a UNumberFormat.
378 * The number will be formatted according to the UNumberFormat's locale.
379 * The syntax of the input number is a "numeric string"
380 * as defined in the Decimal Arithmetic Specification, available at
381 * http://speleotrove.com/decimal
382 * @param fmt The formatter to use.
383 * @param number The number to format.
384 * @param length The length of the input number, or -1 if the input is nul-terminated.
385 * @param result A pointer to a buffer to receive the formatted number.
386 * @param resultLength The maximum size of result.
387 * @param pos    A pointer to a UFieldPosition.  On input, position->field
388 *               is read.  On output, position->beginIndex and position->endIndex indicate
389 *               the beginning and ending indices of field number position->field, if such
390 *               a field exists.  This parameter may be NULL, in which case it is ignored.
391 * @param status A pointer to an UErrorCode to receive any errors
392 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
393 * @see unum_format
394 * @see unum_formatInt64
395 * @see unum_parse
396 * @see unum_parseInt64
397 * @see unum_parseDouble
398 * @see UFieldPosition
399 * @stable ICU 4.4 
400 */
401 U_STABLE int32_t U_EXPORT2 
402 unum_formatDecimal(    const    UNumberFormat*  fmt,
403             const char *    number,
404             int32_t         length,
405             UChar*          result,
406             int32_t         resultLength,
407             UFieldPosition  *pos, /* 0 if ignore */
408             UErrorCode*     status);
409
410 /**
411  * Format a double currency amount using a UNumberFormat.
412  * The double will be formatted according to the UNumberFormat's locale.
413  * @param fmt the formatter to use
414  * @param number the number to format
415  * @param currency the 3-letter null-terminated ISO 4217 currency code
416  * @param result a pointer to the buffer to receive the formatted number
417  * @param resultLength the maximum number of UChars to write to result
418  * @param pos a pointer to a UFieldPosition.  On input,
419  * position->field is read.  On output, position->beginIndex and
420  * position->endIndex indicate the beginning and ending indices of
421  * field number position->field, if such a field exists.  This
422  * parameter may be NULL, in which case it is ignored.
423  * @param status a pointer to an input-output UErrorCode
424  * @return the total buffer size needed; if greater than resultLength,
425  * the output was truncated.
426  * @see unum_formatDouble
427  * @see unum_parseDoubleCurrency
428  * @see UFieldPosition
429  * @stable ICU 3.0
430  */
431 U_STABLE int32_t U_EXPORT2 
432 unum_formatDoubleCurrency(const UNumberFormat* fmt,
433                           double number,
434                           UChar* currency,
435                           UChar* result,
436                           int32_t resultLength,
437                           UFieldPosition* pos, /* ignored if 0 */
438                           UErrorCode* status);
439
440 /**
441 * Parse a string into an integer using a UNumberFormat.
442 * The string will be parsed according to the UNumberFormat's locale.
443 * @param fmt The formatter to use.
444 * @param text The text to parse.
445 * @param textLength The length of text, or -1 if null-terminated.
446 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which
447 * to begin parsing.  If not 0, on output the offset at which parsing ended.
448 * @param status A pointer to an UErrorCode to receive any errors
449 * @return The value of the parsed integer
450 * @see unum_parseInt64
451 * @see unum_parseDouble
452 * @see unum_format
453 * @see unum_formatInt64
454 * @see unum_formatDouble
455 * @stable ICU 2.0
456 */
457 U_STABLE int32_t U_EXPORT2 
458 unum_parse(    const   UNumberFormat*  fmt,
459         const   UChar*          text,
460         int32_t         textLength,
461         int32_t         *parsePos /* 0 = start */,
462         UErrorCode      *status);
463
464 /**
465 * Parse a string into an int64 using a UNumberFormat.
466 * The string will be parsed according to the UNumberFormat's locale.
467 * @param fmt The formatter to use.
468 * @param text The text to parse.
469 * @param textLength The length of text, or -1 if null-terminated.
470 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which
471 * to begin parsing.  If not 0, on output the offset at which parsing ended.
472 * @param status A pointer to an UErrorCode to receive any errors
473 * @return The value of the parsed integer
474 * @see unum_parse
475 * @see unum_parseDouble
476 * @see unum_format
477 * @see unum_formatInt64
478 * @see unum_formatDouble
479 * @stable ICU 2.8
480 */
481 U_STABLE int64_t U_EXPORT2 
482 unum_parseInt64(const UNumberFormat*  fmt,
483         const UChar*  text,
484         int32_t       textLength,
485         int32_t       *parsePos /* 0 = start */,
486         UErrorCode    *status);
487
488 /**
489 * Parse a string into a double using a UNumberFormat.
490 * The string will be parsed according to the UNumberFormat's locale.
491 * @param fmt The formatter to use.
492 * @param text The text to parse.
493 * @param textLength The length of text, or -1 if null-terminated.
494 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which
495 * to begin parsing.  If not 0, on output the offset at which parsing ended.
496 * @param status A pointer to an UErrorCode to receive any errors
497 * @return The value of the parsed double
498 * @see unum_parse
499 * @see unum_parseInt64
500 * @see unum_format
501 * @see unum_formatInt64
502 * @see unum_formatDouble
503 * @stable ICU 2.0
504 */
505 U_STABLE double U_EXPORT2 
506 unum_parseDouble(    const   UNumberFormat*  fmt,
507             const   UChar*          text,
508             int32_t         textLength,
509             int32_t         *parsePos /* 0 = start */,
510             UErrorCode      *status);
511
512
513 /**
514 * Parse a number from a string into an unformatted numeric string using a UNumberFormat.
515 * The input string will be parsed according to the UNumberFormat's locale.
516 * The syntax of the output is a "numeric string"
517 * as defined in the Decimal Arithmetic Specification, available at
518 * http://speleotrove.com/decimal
519 * @param fmt The formatter to use.
520 * @param text The text to parse.
521 * @param textLength The length of text, or -1 if null-terminated.
522 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which
523 *                 to begin parsing.  If not 0, on output the offset at which parsing ended.
524 * @param outBuf A (char *) buffer to receive the parsed number as a string.  The output string
525 *               will be nul-terminated if there is sufficient space.
526 * @param outBufLength The size of the output buffer.  May be zero, in which case
527 *               the outBuf pointer may be NULL, and the function will return the
528 *               size of the output string.
529 * @param status A pointer to an UErrorCode to receive any errors
530 * @return the length of the output string, not including any terminating nul.
531 * @see unum_parse
532 * @see unum_parseInt64
533 * @see unum_format
534 * @see unum_formatInt64
535 * @see unum_formatDouble
536 * @stable ICU 4.4
537 */
538 U_STABLE int32_t U_EXPORT2 
539 unum_parseDecimal(const   UNumberFormat*  fmt,
540                  const   UChar*          text,
541                          int32_t         textLength,
542                          int32_t         *parsePos /* 0 = start */,
543                          char            *outBuf,
544                          int32_t         outBufLength,
545                          UErrorCode      *status);
546
547 /**
548  * Parse a string into a double and a currency using a UNumberFormat.
549  * The string will be parsed according to the UNumberFormat's locale.
550  * @param fmt the formatter to use
551  * @param text the text to parse
552  * @param textLength the length of text, or -1 if null-terminated
553  * @param parsePos a pointer to an offset index into text at which to
554  * begin parsing. On output, *parsePos will point after the last
555  * parsed character.  This parameter may be 0, in which case parsing
556  * begins at offset 0.
557  * @param currency a pointer to the buffer to receive the parsed null-
558  * terminated currency.  This buffer must have a capacity of at least
559  * 4 UChars.
560  * @param status a pointer to an input-output UErrorCode
561  * @return the parsed double
562  * @see unum_parseDouble
563  * @see unum_formatDoubleCurrency
564  * @stable ICU 3.0
565  */
566 U_STABLE double U_EXPORT2
567 unum_parseDoubleCurrency(const UNumberFormat* fmt,
568                          const UChar* text,
569                          int32_t textLength,
570                          int32_t* parsePos, /* 0 = start */
571                          UChar* currency,
572                          UErrorCode* status);
573
574 /**
575  * Set the pattern used by a UNumberFormat.  This can only be used
576  * on a DecimalFormat, other formats return U_ILLEGAL_ARGUMENT_ERROR
577  * in the status.
578  * @param format The formatter to set.
579  * @param localized TRUE if the pattern is localized, FALSE otherwise.
580  * @param pattern The new pattern
581  * @param patternLength The length of pattern, or -1 if null-terminated.
582  * @param parseError A pointer to UParseError to recieve information
583  * about errors occurred during parsing, or NULL if no parse error
584  * information is desired.
585  * @param status A pointer to an input-output UErrorCode.
586  * @see unum_toPattern
587  * @see DecimalFormat
588  * @stable ICU 2.0
589  */
590 U_STABLE void U_EXPORT2 
591 unum_applyPattern(          UNumberFormat  *format,
592                             UBool          localized,
593                     const   UChar          *pattern,
594                             int32_t         patternLength,
595                             UParseError    *parseError,
596                             UErrorCode     *status
597                                     );
598
599 /**
600 * Get a locale for which decimal formatting patterns are available.
601 * A UNumberFormat in a locale returned by this function will perform the correct
602 * formatting and parsing for the locale.  The results of this call are not
603 * valid for rule-based number formats.
604 * @param localeIndex The index of the desired locale.
605 * @return A locale for which number formatting patterns are available, or 0 if none.
606 * @see unum_countAvailable
607 * @stable ICU 2.0
608 */
609 U_STABLE const char* U_EXPORT2 
610 unum_getAvailable(int32_t localeIndex);
611
612 /**
613 * Determine how many locales have decimal formatting patterns available.  The
614 * results of this call are not valid for rule-based number formats.
615 * This function is useful for determining the loop ending condition for
616 * calls to {@link #unum_getAvailable }.
617 * @return The number of locales for which decimal formatting patterns are available.
618 * @see unum_getAvailable
619 * @stable ICU 2.0
620 */
621 U_STABLE int32_t U_EXPORT2 
622 unum_countAvailable(void);
623
624 /** The possible UNumberFormat numeric attributes @stable ICU 2.0 */
625 typedef enum UNumberFormatAttribute {
626   /** Parse integers only */
627   UNUM_PARSE_INT_ONLY,
628   /** Use grouping separator */
629   UNUM_GROUPING_USED,
630   /** Always show decimal point */
631   UNUM_DECIMAL_ALWAYS_SHOWN,
632   /** Maximum integer digits */
633   UNUM_MAX_INTEGER_DIGITS,
634   /** Minimum integer digits */
635   UNUM_MIN_INTEGER_DIGITS,
636   /** Integer digits */
637   UNUM_INTEGER_DIGITS,
638   /** Maximum fraction digits */
639   UNUM_MAX_FRACTION_DIGITS,
640   /** Minimum fraction digits */
641   UNUM_MIN_FRACTION_DIGITS,
642   /** Fraction digits */
643   UNUM_FRACTION_DIGITS,
644   /** Multiplier */
645   UNUM_MULTIPLIER,
646   /** Grouping size */
647   UNUM_GROUPING_SIZE,
648   /** Rounding Mode */
649   UNUM_ROUNDING_MODE,
650   /** Rounding increment */
651   UNUM_ROUNDING_INCREMENT,
652   /** The width to which the output of <code>format()</code> is padded. */
653   UNUM_FORMAT_WIDTH,
654   /** The position at which padding will take place. */
655   UNUM_PADDING_POSITION,
656   /** Secondary grouping size */
657   UNUM_SECONDARY_GROUPING_SIZE,
658   /** Use significant digits
659    * @stable ICU 3.0 */
660   UNUM_SIGNIFICANT_DIGITS_USED,
661   /** Minimum significant digits
662    * @stable ICU 3.0 */
663   UNUM_MIN_SIGNIFICANT_DIGITS,
664   /** Maximum significant digits
665    * @stable ICU 3.0 */
666   UNUM_MAX_SIGNIFICANT_DIGITS,
667   /** Lenient parse mode used by rule-based formats.
668    * @stable ICU 3.0
669    */
670   UNUM_LENIENT_PARSE
671 } UNumberFormatAttribute;
672
673 /**
674 * Get a numeric attribute associated with a UNumberFormat.
675 * An example of a numeric attribute is the number of integer digits a formatter will produce.
676 * @param fmt The formatter to query.
677 * @param attr The attribute to query; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED,
678 * UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS,
679 * UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER,
680 * UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE.
681 * @return The value of attr.
682 * @see unum_setAttribute
683 * @see unum_getDoubleAttribute
684 * @see unum_setDoubleAttribute
685 * @see unum_getTextAttribute
686 * @see unum_setTextAttribute
687 * @stable ICU 2.0
688 */
689 U_STABLE int32_t U_EXPORT2 
690 unum_getAttribute(const UNumberFormat*          fmt,
691           UNumberFormatAttribute  attr);
692
693 /**
694 * Set a numeric attribute associated with a UNumberFormat.
695 * An example of a numeric attribute is the number of integer digits a formatter will produce.  If the
696 * formatter does not understand the attribute, the call is ignored.  Rule-based formatters only understand
697 * the lenient-parse attribute.
698 * @param fmt The formatter to set.
699 * @param attr The attribute to set; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED,
700 * UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS,
701 * UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER,
702 * UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE,
703 * or UNUM_LENIENT_PARSE.
704 * @param newValue The new value of attr.
705 * @see unum_getAttribute
706 * @see unum_getDoubleAttribute
707 * @see unum_setDoubleAttribute
708 * @see unum_getTextAttribute
709 * @see unum_setTextAttribute
710 * @stable ICU 2.0
711 */
712 U_STABLE void U_EXPORT2 
713 unum_setAttribute(    UNumberFormat*          fmt,
714             UNumberFormatAttribute  attr,
715             int32_t                 newValue);
716
717
718 /**
719 * Get a numeric attribute associated with a UNumberFormat.
720 * An example of a numeric attribute is the number of integer digits a formatter will produce.
721 * If the formatter does not understand the attribute, -1 is returned.
722 * @param fmt The formatter to query.
723 * @param attr The attribute to query; e.g. UNUM_ROUNDING_INCREMENT.
724 * @return The value of attr.
725 * @see unum_getAttribute
726 * @see unum_setAttribute
727 * @see unum_setDoubleAttribute
728 * @see unum_getTextAttribute
729 * @see unum_setTextAttribute
730 * @stable ICU 2.0
731 */
732 U_STABLE double U_EXPORT2 
733 unum_getDoubleAttribute(const UNumberFormat*          fmt,
734           UNumberFormatAttribute  attr);
735
736 /**
737 * Set a numeric attribute associated with a UNumberFormat.
738 * An example of a numeric attribute is the number of integer digits a formatter will produce.
739 * If the formatter does not understand the attribute, this call is ignored.
740 * @param fmt The formatter to set.
741 * @param attr The attribute to set; e.g. UNUM_ROUNDING_INCREMENT.
742 * @param newValue The new value of attr.
743 * @see unum_getAttribute
744 * @see unum_setAttribute
745 * @see unum_getDoubleAttribute
746 * @see unum_getTextAttribute
747 * @see unum_setTextAttribute
748 * @stable ICU 2.0
749 */
750 U_STABLE void U_EXPORT2 
751 unum_setDoubleAttribute(    UNumberFormat*          fmt,
752             UNumberFormatAttribute  attr,
753             double                 newValue);
754
755 /** The possible UNumberFormat text attributes @stable ICU 2.0*/
756 typedef enum UNumberFormatTextAttribute {
757   /** Positive prefix */
758   UNUM_POSITIVE_PREFIX,
759   /** Positive suffix */
760   UNUM_POSITIVE_SUFFIX,
761   /** Negative prefix */
762   UNUM_NEGATIVE_PREFIX,
763   /** Negative suffix */
764   UNUM_NEGATIVE_SUFFIX,
765   /** The character used to pad to the format width. */
766   UNUM_PADDING_CHARACTER,
767   /** The ISO currency code */
768   UNUM_CURRENCY_CODE,
769   /**
770    * The default rule set.  This is only available with rule-based formatters.
771    * @stable ICU 3.0
772    */
773   UNUM_DEFAULT_RULESET,
774   /**
775    * The public rule sets.  This is only available with rule-based formatters.
776    * This is a read-only attribute.  The public rulesets are returned as a
777    * single string, with each ruleset name delimited by ';' (semicolon).
778    * @stable ICU 3.0
779    */
780   UNUM_PUBLIC_RULESETS
781 } UNumberFormatTextAttribute;
782
783 /**
784 * Get a text attribute associated with a UNumberFormat.
785 * An example of a text attribute is the suffix for positive numbers.  If the formatter
786 * does not understand the attributre, U_UNSUPPORTED_ERROR is returned as the status.
787 * Rule-based formatters only understand UNUM_DEFAULT_RULESET and UNUM_PUBLIC_RULESETS.
788 * @param fmt The formatter to query.
789 * @param tag The attribute to query; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX,
790 * UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE,
791 * UNUM_DEFAULT_RULESET, or UNUM_PUBLIC_RULESETS.
792 * @param result A pointer to a buffer to receive the attribute.
793 * @param resultLength The maximum size of result.
794 * @param status A pointer to an UErrorCode to receive any errors
795 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
796 * @see unum_setTextAttribute
797 * @see unum_getAttribute
798 * @see unum_setAttribute
799 * @stable ICU 2.0
800 */
801 U_STABLE int32_t U_EXPORT2 
802 unum_getTextAttribute(    const    UNumberFormat*                    fmt,
803             UNumberFormatTextAttribute      tag,
804             UChar*                            result,
805             int32_t                            resultLength,
806             UErrorCode*                        status);
807
808 /**
809 * Set a text attribute associated with a UNumberFormat.
810 * An example of a text attribute is the suffix for positive numbers.  Rule-based formatters
811 * only understand UNUM_DEFAULT_RULESET.
812 * @param fmt The formatter to set.
813 * @param tag The attribute to set; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX,
814 * UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE,
815 * or UNUM_DEFAULT_RULESET.
816 * @param newValue The new value of attr.
817 * @param newValueLength The length of newValue, or -1 if null-terminated.
818 * @param status A pointer to an UErrorCode to receive any errors
819 * @see unum_getTextAttribute
820 * @see unum_getAttribute
821 * @see unum_setAttribute
822 * @stable ICU 2.0
823 */
824 U_STABLE void U_EXPORT2 
825 unum_setTextAttribute(    UNumberFormat*                    fmt,
826             UNumberFormatTextAttribute      tag,
827             const    UChar*                            newValue,
828             int32_t                            newValueLength,
829             UErrorCode                        *status);
830
831 /**
832  * Extract the pattern from a UNumberFormat.  The pattern will follow
833  * the DecimalFormat pattern syntax.
834  * @param fmt The formatter to query.
835  * @param isPatternLocalized TRUE if the pattern should be localized,
836  * FALSE otherwise.  This is ignored if the formatter is a rule-based
837  * formatter.
838  * @param result A pointer to a buffer to receive the pattern.
839  * @param resultLength The maximum size of result.
840  * @param status A pointer to an input-output UErrorCode.
841  * @return The total buffer size needed; if greater than resultLength,
842  * the output was truncated.
843  * @see unum_applyPattern
844  * @see DecimalFormat
845  * @stable ICU 2.0
846  */
847 U_STABLE int32_t U_EXPORT2 
848 unum_toPattern(    const    UNumberFormat*          fmt,
849         UBool                  isPatternLocalized,
850         UChar*                  result,
851         int32_t                 resultLength,
852         UErrorCode*             status);
853
854
855 /**
856  * Constants for specifying a number format symbol.
857  * @stable ICU 2.0
858  */
859 typedef enum UNumberFormatSymbol {
860   /** The decimal separator */
861   UNUM_DECIMAL_SEPARATOR_SYMBOL = 0,
862   /** The grouping separator */
863   UNUM_GROUPING_SEPARATOR_SYMBOL = 1,
864   /** The pattern separator */
865   UNUM_PATTERN_SEPARATOR_SYMBOL = 2,
866   /** The percent sign */
867   UNUM_PERCENT_SYMBOL = 3,
868   /** Zero*/
869   UNUM_ZERO_DIGIT_SYMBOL = 4,
870   /** Character representing a digit in the pattern */
871   UNUM_DIGIT_SYMBOL = 5,
872   /** The minus sign */
873   UNUM_MINUS_SIGN_SYMBOL = 6,
874   /** The plus sign */
875   UNUM_PLUS_SIGN_SYMBOL = 7,
876   /** The currency symbol */
877   UNUM_CURRENCY_SYMBOL = 8,
878   /** The international currency symbol */
879   UNUM_INTL_CURRENCY_SYMBOL = 9,
880   /** The monetary separator */
881   UNUM_MONETARY_SEPARATOR_SYMBOL = 10,
882   /** The exponential symbol */
883   UNUM_EXPONENTIAL_SYMBOL = 11,
884   /** Per mill symbol */
885   UNUM_PERMILL_SYMBOL = 12,
886   /** Escape padding character */
887   UNUM_PAD_ESCAPE_SYMBOL = 13,
888   /** Infinity symbol */
889   UNUM_INFINITY_SYMBOL = 14,
890   /** Nan symbol */
891   UNUM_NAN_SYMBOL = 15,
892   /** Significant digit symbol
893    * @stable ICU 3.0 */
894   UNUM_SIGNIFICANT_DIGIT_SYMBOL = 16,
895   /** The monetary grouping separator 
896    * @stable ICU 3.6
897    */
898   UNUM_MONETARY_GROUPING_SEPARATOR_SYMBOL = 17,  
899   /** One
900    * @draft ICU 4.6
901    */
902   UNUM_ONE_DIGIT_SYMBOL = 18,
903   /** Two
904    * @draft ICU 4.6
905    */
906   UNUM_TWO_DIGIT_SYMBOL = 19,
907   /** Three
908    * @draft ICU 4.6
909    */
910   UNUM_THREE_DIGIT_SYMBOL = 20,
911   /** Four
912    * @draft ICU 4.6
913    */
914   UNUM_FOUR_DIGIT_SYMBOL = 21,
915   /** Five
916    * @draft ICU 4.6
917    */
918   UNUM_FIVE_DIGIT_SYMBOL = 22,
919   /** Six
920    * @draft ICU 4.6
921    */
922   UNUM_SIX_DIGIT_SYMBOL = 23,
923   /** Seven
924     * @draft ICU 4.6
925    */
926   UNUM_SEVEN_DIGIT_SYMBOL = 24,
927   /** Eight
928    * @draft ICU 4.6
929    */
930   UNUM_EIGHT_DIGIT_SYMBOL = 25,
931   /** Nine
932    * @draft ICU 4.6
933    */
934   UNUM_NINE_DIGIT_SYMBOL = 26,
935   /** count symbol constants */
936   UNUM_FORMAT_SYMBOL_COUNT = 27
937 } UNumberFormatSymbol;
938
939 /**
940 * Get a symbol associated with a UNumberFormat.
941 * A UNumberFormat uses symbols to represent the special locale-dependent
942 * characters in a number, for example the percent sign. This API is not
943 * supported for rule-based formatters.
944 * @param fmt The formatter to query.
945 * @param symbol The UNumberFormatSymbol constant for the symbol to get
946 * @param buffer The string buffer that will receive the symbol string;
947 *               if it is NULL, then only the length of the symbol is returned
948 * @param size The size of the string buffer
949 * @param status A pointer to an UErrorCode to receive any errors
950 * @return The length of the symbol; the buffer is not modified if
951 *         <code>length&gt;=size</code>
952 * @see unum_setSymbol
953 * @stable ICU 2.0
954 */
955 U_STABLE int32_t U_EXPORT2
956 unum_getSymbol(const UNumberFormat *fmt,
957                UNumberFormatSymbol symbol,
958                UChar *buffer,
959                int32_t size,
960                UErrorCode *status);
961
962 /**
963 * Set a symbol associated with a UNumberFormat.
964 * A UNumberFormat uses symbols to represent the special locale-dependent
965 * characters in a number, for example the percent sign.  This API is not
966 * supported for rule-based formatters.
967 * @param fmt The formatter to set.
968 * @param symbol The UNumberFormatSymbol constant for the symbol to set
969 * @param value The string to set the symbol to
970 * @param length The length of the string, or -1 for a zero-terminated string
971 * @param status A pointer to an UErrorCode to receive any errors.
972 * @see unum_getSymbol
973 * @stable ICU 2.0
974 */
975 U_STABLE void U_EXPORT2
976 unum_setSymbol(UNumberFormat *fmt,
977                UNumberFormatSymbol symbol,
978                const UChar *value,
979                int32_t length,
980                UErrorCode *status);
981
982
983 /**
984  * Get the locale for this number format object.
985  * You can choose between valid and actual locale.
986  * @param fmt The formatter to get the locale from
987  * @param type type of the locale we're looking for (valid or actual) 
988  * @param status error code for the operation
989  * @return the locale name
990  * @stable ICU 2.8
991  */
992 U_STABLE const char* U_EXPORT2
993 unum_getLocaleByType(const UNumberFormat *fmt,
994                      ULocDataLocaleType type,
995                      UErrorCode* status); 
996
997 #endif /* #if !UCONFIG_NO_FORMATTING */
998
999 #endif