Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/unum.h @ 69:33d812a61356

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