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