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