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.

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

mercurial