Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/numfmt.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-2016, International Business Machines Corporation and others.
jpayne@69 6 * All Rights Reserved.
jpayne@69 7 ********************************************************************************
jpayne@69 8 *
jpayne@69 9 * File NUMFMT.H
jpayne@69 10 *
jpayne@69 11 * Modification History:
jpayne@69 12 *
jpayne@69 13 * Date Name Description
jpayne@69 14 * 02/19/97 aliu Converted from java.
jpayne@69 15 * 03/18/97 clhuang Updated per C++ implementation.
jpayne@69 16 * 04/17/97 aliu Changed DigitCount to int per code review.
jpayne@69 17 * 07/20/98 stephen JDK 1.2 sync up. Added scientific support.
jpayne@69 18 * Changed naming conventions to match C++ guidelines
jpayne@69 19 * Derecated Java style constants (eg, INTEGER_FIELD)
jpayne@69 20 ********************************************************************************
jpayne@69 21 */
jpayne@69 22
jpayne@69 23 #ifndef NUMFMT_H
jpayne@69 24 #define NUMFMT_H
jpayne@69 25
jpayne@69 26
jpayne@69 27 #include "unicode/utypes.h"
jpayne@69 28
jpayne@69 29 #if U_SHOW_CPLUSPLUS_API
jpayne@69 30
jpayne@69 31 /**
jpayne@69 32 * \file
jpayne@69 33 * \brief C++ API: Compatibility APIs for number formatting.
jpayne@69 34 */
jpayne@69 35
jpayne@69 36 #if !UCONFIG_NO_FORMATTING
jpayne@69 37
jpayne@69 38 #include "unicode/unistr.h"
jpayne@69 39 #include "unicode/format.h"
jpayne@69 40 #include "unicode/unum.h" // UNumberFormatStyle
jpayne@69 41 #include "unicode/locid.h"
jpayne@69 42 #include "unicode/stringpiece.h"
jpayne@69 43 #include "unicode/curramt.h"
jpayne@69 44 #include "unicode/udisplaycontext.h"
jpayne@69 45
jpayne@69 46 class NumberFormatTest;
jpayne@69 47
jpayne@69 48 U_NAMESPACE_BEGIN
jpayne@69 49
jpayne@69 50 class SharedNumberFormat;
jpayne@69 51
jpayne@69 52 #if !UCONFIG_NO_SERVICE
jpayne@69 53 class NumberFormatFactory;
jpayne@69 54 class StringEnumeration;
jpayne@69 55 #endif
jpayne@69 56
jpayne@69 57 /**
jpayne@69 58 * <p><strong>IMPORTANT:</strong> New users are strongly encouraged to see if
jpayne@69 59 * numberformatter.h fits their use case. Although not deprecated, this header
jpayne@69 60 * is provided for backwards compatibility only.
jpayne@69 61 *
jpayne@69 62 * Abstract base class for all number formats. Provides interface for
jpayne@69 63 * formatting and parsing a number. Also provides methods for
jpayne@69 64 * determining which locales have number formats, and what their names
jpayne@69 65 * are.
jpayne@69 66 *
jpayne@69 67 * \headerfile unicode/numfmt.h "unicode/numfmt.h"
jpayne@69 68 * <P>
jpayne@69 69 * NumberFormat helps you to format and parse numbers for any locale.
jpayne@69 70 * Your code can be completely independent of the locale conventions
jpayne@69 71 * for decimal points, thousands-separators, or even the particular
jpayne@69 72 * decimal digits used, or whether the number format is even decimal.
jpayne@69 73 * <P>
jpayne@69 74 * To format a number for the current Locale, use one of the static
jpayne@69 75 * factory methods:
jpayne@69 76 * \code
jpayne@69 77 * #include <iostream>
jpayne@69 78 * #include "unicode/numfmt.h"
jpayne@69 79 * #include "unicode/unistr.h"
jpayne@69 80 * #include "unicode/ustream.h"
jpayne@69 81 * using namespace std;
jpayne@69 82 *
jpayne@69 83 * int main() {
jpayne@69 84 * double myNumber = 7.0;
jpayne@69 85 * UnicodeString myString;
jpayne@69 86 * UErrorCode success = U_ZERO_ERROR;
jpayne@69 87 * NumberFormat* nf = NumberFormat::createInstance(success);
jpayne@69 88 * nf->format(myNumber, myString);
jpayne@69 89 * cout << " Example 1: " << myString << endl;
jpayne@69 90 * }
jpayne@69 91 * \endcode
jpayne@69 92 * Note that there are additional factory methods within subclasses of
jpayne@69 93 * NumberFormat.
jpayne@69 94 * <P>
jpayne@69 95 * If you are formatting multiple numbers, it is more efficient to get
jpayne@69 96 * the format and use it multiple times so that the system doesn't
jpayne@69 97 * have to fetch the information about the local language and country
jpayne@69 98 * conventions multiple times.
jpayne@69 99 * \code
jpayne@69 100 * UnicodeString myString;
jpayne@69 101 * UErrorCode success = U_ZERO_ERROR;
jpayne@69 102 * NumberFormat *nf = NumberFormat::createInstance( success );
jpayne@69 103 * for (int32_t number: {123, 3333, -1234567}) {
jpayne@69 104 * nf->format(number, myString);
jpayne@69 105 * myString += "; ";
jpayne@69 106 * }
jpayne@69 107 * cout << " Example 2: " << myString << endl;
jpayne@69 108 * \endcode
jpayne@69 109 * To format a number for a different Locale, specify it in the
jpayne@69 110 * call to \c createInstance().
jpayne@69 111 * \code
jpayne@69 112 * nf = NumberFormat::createInstance(Locale::getFrench(), success);
jpayne@69 113 * \endcode
jpayne@69 114 * You can use a \c NumberFormat to parse also.
jpayne@69 115 * \code
jpayne@69 116 * UErrorCode success;
jpayne@69 117 * Formattable result(-999); // initialized with error code
jpayne@69 118 * nf->parse(myString, result, success);
jpayne@69 119 * \endcode
jpayne@69 120 * Use \c createInstance() to get the normal number format for a \c Locale.
jpayne@69 121 * There are other static factory methods available. Use \c createCurrencyInstance()
jpayne@69 122 * to get the currency number format for that country. Use \c createPercentInstance()
jpayne@69 123 * to get a format for displaying percentages. With this format, a
jpayne@69 124 * fraction from 0.53 is displayed as 53%.
jpayne@69 125 * <P>
jpayne@69 126 * The type of number formatting can be specified by passing a 'style' parameter to \c createInstance().
jpayne@69 127 * For example, use\n
jpayne@69 128 * \c createInstance(locale, UNUM_DECIMAL, errorCode) to get the normal number format,\n
jpayne@69 129 * \c createInstance(locale, UNUM_PERCENT, errorCode) to get a format for displaying percentage,\n
jpayne@69 130 * \c createInstance(locale, UNUM_SCIENTIFIC, errorCode) to get a format for displaying scientific number,\n
jpayne@69 131 * \c createInstance(locale, UNUM_CURRENCY, errorCode) to get the currency number format,
jpayne@69 132 * in which the currency is represented by its symbol, for example, "$3.00".\n
jpayne@69 133 * \c createInstance(locale, UNUM_CURRENCY_ISO, errorCode) to get the currency number format,
jpayne@69 134 * in which the currency is represented by its ISO code, for example "USD3.00".\n
jpayne@69 135 * \c createInstance(locale, UNUM_CURRENCY_PLURAL, errorCode) to get the currency number format,
jpayne@69 136 * in which the currency is represented by its full name in plural format,
jpayne@69 137 * for example, "3.00 US dollars" or "1.00 US dollar".
jpayne@69 138 * <P>
jpayne@69 139 * You can also control the display of numbers with such methods as
jpayne@69 140 * \c getMinimumFractionDigits(). If you want even more control over the
jpayne@69 141 * format or parsing, or want to give your users more control, you can
jpayne@69 142 * try dynamic_casting the \c NumberFormat you get from the factory methods to a
jpayne@69 143 * \c DecimalFormat. This will work for the vast majority of
jpayne@69 144 * countries; just remember to test for NULL in case you
jpayne@69 145 * encounter an unusual one.
jpayne@69 146 * <P>
jpayne@69 147 * You can also use forms of the parse and format methods with
jpayne@69 148 * \c ParsePosition and \c FieldPosition to allow you to:
jpayne@69 149 * <ul type=round>
jpayne@69 150 * <li>(a) progressively parse through pieces of a string.
jpayne@69 151 * <li>(b) align the decimal point and other areas.
jpayne@69 152 * </ul>
jpayne@69 153 * For example, you can align numbers in two ways.
jpayne@69 154 * <P>
jpayne@69 155 * If you are using a monospaced font with spacing for alignment, you
jpayne@69 156 * can pass the \c FieldPosition in your format call, with field =
jpayne@69 157 * \c UNUM_INTEGER_FIELD. On output, \c getEndIndex will be set to the offset
jpayne@69 158 * between the last character of the integer and the decimal. Add
jpayne@69 159 * (desiredSpaceCount - getEndIndex) spaces at the front of the
jpayne@69 160 * string.
jpayne@69 161 * <P>
jpayne@69 162 * If you are using proportional fonts, instead of padding with
jpayne@69 163 * spaces, measure the width of the string in pixels from the start to
jpayne@69 164 * getEndIndex. Then move the pen by (desiredPixelWidth -
jpayne@69 165 * widthToAlignmentPoint) before drawing the text. It also works
jpayne@69 166 * where there is no decimal, but possibly additional characters at
jpayne@69 167 * the end, e.g. with parentheses in negative numbers: "(12)" for -12.
jpayne@69 168 * <p>
jpayne@69 169 * <em>User subclasses are not supported.</em> While clients may write
jpayne@69 170 * subclasses, such code will not necessarily work and will not be
jpayne@69 171 * guaranteed to work stably from release to release.
jpayne@69 172 *
jpayne@69 173 * @stable ICU 2.0
jpayne@69 174 */
jpayne@69 175 class U_I18N_API NumberFormat : public Format {
jpayne@69 176 public:
jpayne@69 177 /**
jpayne@69 178 * Rounding mode.
jpayne@69 179 *
jpayne@69 180 * <p>
jpayne@69 181 * For more detail on rounding modes, see:
jpayne@69 182 * http://userguide.icu-project.org/formatparse/numbers/rounding-modes
jpayne@69 183 *
jpayne@69 184 * @stable ICU 2.4
jpayne@69 185 */
jpayne@69 186 enum ERoundingMode {
jpayne@69 187 kRoundCeiling, /**< Round towards positive infinity */
jpayne@69 188 kRoundFloor, /**< Round towards negative infinity */
jpayne@69 189 kRoundDown, /**< Round towards zero */
jpayne@69 190 kRoundUp, /**< Round away from zero */
jpayne@69 191 kRoundHalfEven, /**< Round towards the nearest integer, or
jpayne@69 192 towards the nearest even integer if equidistant */
jpayne@69 193 kRoundHalfDown, /**< Round towards the nearest integer, or
jpayne@69 194 towards zero if equidistant */
jpayne@69 195 kRoundHalfUp, /**< Round towards the nearest integer, or
jpayne@69 196 away from zero if equidistant */
jpayne@69 197 /**
jpayne@69 198 * Return U_FORMAT_INEXACT_ERROR if number does not format exactly.
jpayne@69 199 * @stable ICU 4.8
jpayne@69 200 */
jpayne@69 201 kRoundUnnecessary
jpayne@69 202 };
jpayne@69 203
jpayne@69 204 /**
jpayne@69 205 * Alignment Field constants used to construct a FieldPosition object.
jpayne@69 206 * Signifies that the position of the integer part or fraction part of
jpayne@69 207 * a formatted number should be returned.
jpayne@69 208 *
jpayne@69 209 * Note: as of ICU 4.4, the values in this enum have been extended to
jpayne@69 210 * support identification of all number format fields, not just those
jpayne@69 211 * pertaining to alignment.
jpayne@69 212 *
jpayne@69 213 * These constants are provided for backwards compatibility only.
jpayne@69 214 * Please use the C style constants defined in the header file unum.h.
jpayne@69 215 *
jpayne@69 216 * @see FieldPosition
jpayne@69 217 * @stable ICU 2.0
jpayne@69 218 */
jpayne@69 219 enum EAlignmentFields {
jpayne@69 220 /** @stable ICU 2.0 */
jpayne@69 221 kIntegerField = UNUM_INTEGER_FIELD,
jpayne@69 222 /** @stable ICU 2.0 */
jpayne@69 223 kFractionField = UNUM_FRACTION_FIELD,
jpayne@69 224 /** @stable ICU 2.0 */
jpayne@69 225 kDecimalSeparatorField = UNUM_DECIMAL_SEPARATOR_FIELD,
jpayne@69 226 /** @stable ICU 2.0 */
jpayne@69 227 kExponentSymbolField = UNUM_EXPONENT_SYMBOL_FIELD,
jpayne@69 228 /** @stable ICU 2.0 */
jpayne@69 229 kExponentSignField = UNUM_EXPONENT_SIGN_FIELD,
jpayne@69 230 /** @stable ICU 2.0 */
jpayne@69 231 kExponentField = UNUM_EXPONENT_FIELD,
jpayne@69 232 /** @stable ICU 2.0 */
jpayne@69 233 kGroupingSeparatorField = UNUM_GROUPING_SEPARATOR_FIELD,
jpayne@69 234 /** @stable ICU 2.0 */
jpayne@69 235 kCurrencyField = UNUM_CURRENCY_FIELD,
jpayne@69 236 /** @stable ICU 2.0 */
jpayne@69 237 kPercentField = UNUM_PERCENT_FIELD,
jpayne@69 238 /** @stable ICU 2.0 */
jpayne@69 239 kPermillField = UNUM_PERMILL_FIELD,
jpayne@69 240 /** @stable ICU 2.0 */
jpayne@69 241 kSignField = UNUM_SIGN_FIELD,
jpayne@69 242 /** @stable ICU 64 */
jpayne@69 243 kMeasureUnitField = UNUM_MEASURE_UNIT_FIELD,
jpayne@69 244 /** @stable ICU 64 */
jpayne@69 245 kCompactField = UNUM_COMPACT_FIELD,
jpayne@69 246
jpayne@69 247 /**
jpayne@69 248 * These constants are provided for backwards compatibility only.
jpayne@69 249 * Please use the constants defined in the header file unum.h.
jpayne@69 250 */
jpayne@69 251 /** @stable ICU 2.0 */
jpayne@69 252 INTEGER_FIELD = UNUM_INTEGER_FIELD,
jpayne@69 253 /** @stable ICU 2.0 */
jpayne@69 254 FRACTION_FIELD = UNUM_FRACTION_FIELD
jpayne@69 255 };
jpayne@69 256
jpayne@69 257 /**
jpayne@69 258 * Destructor.
jpayne@69 259 * @stable ICU 2.0
jpayne@69 260 */
jpayne@69 261 virtual ~NumberFormat();
jpayne@69 262
jpayne@69 263 /**
jpayne@69 264 * Clones this object polymorphically.
jpayne@69 265 * The caller owns the result and should delete it when done.
jpayne@69 266 * @return clone, or nullptr if an error occurred
jpayne@69 267 * @stable ICU 2.0
jpayne@69 268 */
jpayne@69 269 virtual NumberFormat* clone() const = 0;
jpayne@69 270
jpayne@69 271 /**
jpayne@69 272 * Return true if the given Format objects are semantically equal.
jpayne@69 273 * Objects of different subclasses are considered unequal.
jpayne@69 274 * @return true if the given Format objects are semantically equal.
jpayne@69 275 * @stable ICU 2.0
jpayne@69 276 */
jpayne@69 277 virtual UBool operator==(const Format& other) const;
jpayne@69 278
jpayne@69 279
jpayne@69 280 using Format::format;
jpayne@69 281
jpayne@69 282 /**
jpayne@69 283 * Format an object to produce a string. This method handles
jpayne@69 284 * Formattable objects with numeric types. If the Formattable
jpayne@69 285 * object type is not a numeric type, then it returns a failing
jpayne@69 286 * UErrorCode.
jpayne@69 287 *
jpayne@69 288 * @param obj The object to format.
jpayne@69 289 * @param appendTo Output parameter to receive result.
jpayne@69 290 * Result is appended to existing contents.
jpayne@69 291 * @param pos On input: an alignment field, if desired.
jpayne@69 292 * On output: the offsets of the alignment field.
jpayne@69 293 * @param status Output param filled with success/failure status.
jpayne@69 294 * @return Reference to 'appendTo' parameter.
jpayne@69 295 * @stable ICU 2.0
jpayne@69 296 */
jpayne@69 297 virtual UnicodeString& format(const Formattable& obj,
jpayne@69 298 UnicodeString& appendTo,
jpayne@69 299 FieldPosition& pos,
jpayne@69 300 UErrorCode& status) const;
jpayne@69 301
jpayne@69 302 /**
jpayne@69 303 * Format an object to produce a string. This method handles
jpayne@69 304 * Formattable objects with numeric types. If the Formattable
jpayne@69 305 * object type is not a numeric type, then it returns a failing
jpayne@69 306 * UErrorCode.
jpayne@69 307 *
jpayne@69 308 * @param obj The object to format.
jpayne@69 309 * @param appendTo Output parameter to receive result.
jpayne@69 310 * Result is appended to existing contents.
jpayne@69 311 * @param posIter On return, can be used to iterate over positions
jpayne@69 312 * of fields generated by this format call. Can be
jpayne@69 313 * NULL.
jpayne@69 314 * @param status Output param filled with success/failure status.
jpayne@69 315 * @return Reference to 'appendTo' parameter.
jpayne@69 316 * @stable ICU 4.4
jpayne@69 317 */
jpayne@69 318 virtual UnicodeString& format(const Formattable& obj,
jpayne@69 319 UnicodeString& appendTo,
jpayne@69 320 FieldPositionIterator* posIter,
jpayne@69 321 UErrorCode& status) const;
jpayne@69 322
jpayne@69 323 /**
jpayne@69 324 * Parse a string to produce an object. This methods handles
jpayne@69 325 * parsing of numeric strings into Formattable objects with numeric
jpayne@69 326 * types.
jpayne@69 327 * <P>
jpayne@69 328 * Before calling, set parse_pos.index to the offset you want to
jpayne@69 329 * start parsing at in the source. After calling, parse_pos.index
jpayne@69 330 * indicates the position after the successfully parsed text. If
jpayne@69 331 * an error occurs, parse_pos.index is unchanged.
jpayne@69 332 * <P>
jpayne@69 333 * When parsing, leading whitespace is discarded (with successful
jpayne@69 334 * parse), while trailing whitespace is left as is.
jpayne@69 335 * <P>
jpayne@69 336 * See Format::parseObject() for more.
jpayne@69 337 *
jpayne@69 338 * @param source The string to be parsed into an object.
jpayne@69 339 * @param result Formattable to be set to the parse result.
jpayne@69 340 * If parse fails, return contents are undefined.
jpayne@69 341 * @param parse_pos The position to start parsing at. Upon return
jpayne@69 342 * this param is set to the position after the
jpayne@69 343 * last character successfully parsed. If the
jpayne@69 344 * source is not parsed successfully, this param
jpayne@69 345 * will remain unchanged.
jpayne@69 346 * @return A newly created Formattable* object, or NULL
jpayne@69 347 * on failure. The caller owns this and should
jpayne@69 348 * delete it when done.
jpayne@69 349 * @stable ICU 2.0
jpayne@69 350 */
jpayne@69 351 virtual void parseObject(const UnicodeString& source,
jpayne@69 352 Formattable& result,
jpayne@69 353 ParsePosition& parse_pos) const;
jpayne@69 354
jpayne@69 355 /**
jpayne@69 356 * Format a double number. These methods call the NumberFormat
jpayne@69 357 * pure virtual format() methods with the default FieldPosition.
jpayne@69 358 *
jpayne@69 359 * @param number The value to be formatted.
jpayne@69 360 * @param appendTo Output parameter to receive result.
jpayne@69 361 * Result is appended to existing contents.
jpayne@69 362 * @return Reference to 'appendTo' parameter.
jpayne@69 363 * @stable ICU 2.0
jpayne@69 364 */
jpayne@69 365 UnicodeString& format( double number,
jpayne@69 366 UnicodeString& appendTo) const;
jpayne@69 367
jpayne@69 368 /**
jpayne@69 369 * Format a long number. These methods call the NumberFormat
jpayne@69 370 * pure virtual format() methods with the default FieldPosition.
jpayne@69 371 *
jpayne@69 372 * @param number The value to be formatted.
jpayne@69 373 * @param appendTo Output parameter to receive result.
jpayne@69 374 * Result is appended to existing contents.
jpayne@69 375 * @return Reference to 'appendTo' parameter.
jpayne@69 376 * @stable ICU 2.0
jpayne@69 377 */
jpayne@69 378 UnicodeString& format( int32_t number,
jpayne@69 379 UnicodeString& appendTo) const;
jpayne@69 380
jpayne@69 381 /**
jpayne@69 382 * Format an int64 number. These methods call the NumberFormat
jpayne@69 383 * pure virtual format() methods with the default FieldPosition.
jpayne@69 384 *
jpayne@69 385 * @param number The value to be formatted.
jpayne@69 386 * @param appendTo Output parameter to receive result.
jpayne@69 387 * Result is appended to existing contents.
jpayne@69 388 * @return Reference to 'appendTo' parameter.
jpayne@69 389 * @stable ICU 2.8
jpayne@69 390 */
jpayne@69 391 UnicodeString& format( int64_t number,
jpayne@69 392 UnicodeString& appendTo) const;
jpayne@69 393
jpayne@69 394 /**
jpayne@69 395 * Format a double number. Concrete subclasses must implement
jpayne@69 396 * these pure virtual methods.
jpayne@69 397 *
jpayne@69 398 * @param number The value to be formatted.
jpayne@69 399 * @param appendTo Output parameter to receive result.
jpayne@69 400 * Result is appended to existing contents.
jpayne@69 401 * @param pos On input: an alignment field, if desired.
jpayne@69 402 * On output: the offsets of the alignment field.
jpayne@69 403 * @return Reference to 'appendTo' parameter.
jpayne@69 404 * @stable ICU 2.0
jpayne@69 405 */
jpayne@69 406 virtual UnicodeString& format(double number,
jpayne@69 407 UnicodeString& appendTo,
jpayne@69 408 FieldPosition& pos) const = 0;
jpayne@69 409 /**
jpayne@69 410 * Format a double number. By default, the parent function simply
jpayne@69 411 * calls the base class and does not return an error status.
jpayne@69 412 * Therefore, the status may be ignored in some subclasses.
jpayne@69 413 *
jpayne@69 414 * @param number The value to be formatted.
jpayne@69 415 * @param appendTo Output parameter to receive result.
jpayne@69 416 * Result is appended to existing contents.
jpayne@69 417 * @param pos On input: an alignment field, if desired.
jpayne@69 418 * On output: the offsets of the alignment field.
jpayne@69 419 * @param status error status
jpayne@69 420 * @return Reference to 'appendTo' parameter.
jpayne@69 421 * @internal
jpayne@69 422 */
jpayne@69 423 virtual UnicodeString& format(double number,
jpayne@69 424 UnicodeString& appendTo,
jpayne@69 425 FieldPosition& pos,
jpayne@69 426 UErrorCode &status) const;
jpayne@69 427 /**
jpayne@69 428 * Format a double number. Subclasses must implement
jpayne@69 429 * this method.
jpayne@69 430 *
jpayne@69 431 * @param number The value to be formatted.
jpayne@69 432 * @param appendTo Output parameter to receive result.
jpayne@69 433 * Result is appended to existing contents.
jpayne@69 434 * @param posIter On return, can be used to iterate over positions
jpayne@69 435 * of fields generated by this format call.
jpayne@69 436 * Can be NULL.
jpayne@69 437 * @param status Output param filled with success/failure status.
jpayne@69 438 * @return Reference to 'appendTo' parameter.
jpayne@69 439 * @stable ICU 4.4
jpayne@69 440 */
jpayne@69 441 virtual UnicodeString& format(double number,
jpayne@69 442 UnicodeString& appendTo,
jpayne@69 443 FieldPositionIterator* posIter,
jpayne@69 444 UErrorCode& status) const;
jpayne@69 445 /**
jpayne@69 446 * Format a long number. Concrete subclasses must implement
jpayne@69 447 * these pure virtual methods.
jpayne@69 448 *
jpayne@69 449 * @param number The value to be formatted.
jpayne@69 450 * @param appendTo Output parameter to receive result.
jpayne@69 451 * Result is appended to existing contents.
jpayne@69 452 * @param pos On input: an alignment field, if desired.
jpayne@69 453 * On output: the offsets of the alignment field.
jpayne@69 454 * @return Reference to 'appendTo' parameter.
jpayne@69 455 * @stable ICU 2.0
jpayne@69 456 */
jpayne@69 457 virtual UnicodeString& format(int32_t number,
jpayne@69 458 UnicodeString& appendTo,
jpayne@69 459 FieldPosition& pos) const = 0;
jpayne@69 460
jpayne@69 461 /**
jpayne@69 462 * Format a long number. Concrete subclasses may override
jpayne@69 463 * this function to provide status return.
jpayne@69 464 *
jpayne@69 465 * @param number The value to be formatted.
jpayne@69 466 * @param appendTo Output parameter to receive result.
jpayne@69 467 * Result is appended to existing contents.
jpayne@69 468 * @param pos On input: an alignment field, if desired.
jpayne@69 469 * On output: the offsets of the alignment field.
jpayne@69 470 * @param status the output status.
jpayne@69 471 * @return Reference to 'appendTo' parameter.
jpayne@69 472 * @internal
jpayne@69 473 */
jpayne@69 474 virtual UnicodeString& format(int32_t number,
jpayne@69 475 UnicodeString& appendTo,
jpayne@69 476 FieldPosition& pos,
jpayne@69 477 UErrorCode &status) const;
jpayne@69 478
jpayne@69 479 /**
jpayne@69 480 * Format an int32 number. Subclasses must implement
jpayne@69 481 * this method.
jpayne@69 482 *
jpayne@69 483 * @param number The value to be formatted.
jpayne@69 484 * @param appendTo Output parameter to receive result.
jpayne@69 485 * Result is appended to existing contents.
jpayne@69 486 * @param posIter On return, can be used to iterate over positions
jpayne@69 487 * of fields generated by this format call.
jpayne@69 488 * Can be NULL.
jpayne@69 489 * @param status Output param filled with success/failure status.
jpayne@69 490 * @return Reference to 'appendTo' parameter.
jpayne@69 491 * @stable ICU 4.4
jpayne@69 492 */
jpayne@69 493 virtual UnicodeString& format(int32_t number,
jpayne@69 494 UnicodeString& appendTo,
jpayne@69 495 FieldPositionIterator* posIter,
jpayne@69 496 UErrorCode& status) const;
jpayne@69 497 /**
jpayne@69 498 * Format an int64 number. (Not abstract to retain compatibility
jpayne@69 499 * with earlier releases, however subclasses should override this
jpayne@69 500 * method as it just delegates to format(int32_t number...);
jpayne@69 501 *
jpayne@69 502 * @param number The value to be formatted.
jpayne@69 503 * @param appendTo Output parameter to receive result.
jpayne@69 504 * Result is appended to existing contents.
jpayne@69 505 * @param pos On input: an alignment field, if desired.
jpayne@69 506 * On output: the offsets of the alignment field.
jpayne@69 507 * @return Reference to 'appendTo' parameter.
jpayne@69 508 * @stable ICU 2.8
jpayne@69 509 */
jpayne@69 510 virtual UnicodeString& format(int64_t number,
jpayne@69 511 UnicodeString& appendTo,
jpayne@69 512 FieldPosition& pos) const;
jpayne@69 513
jpayne@69 514 /**
jpayne@69 515 * Format an int64 number. (Not abstract to retain compatibility
jpayne@69 516 * with earlier releases, however subclasses should override this
jpayne@69 517 * method as it just delegates to format(int32_t number...);
jpayne@69 518 *
jpayne@69 519 * @param number The value to be formatted.
jpayne@69 520 * @param appendTo Output parameter to receive result.
jpayne@69 521 * Result is appended to existing contents.
jpayne@69 522 * @param pos On input: an alignment field, if desired.
jpayne@69 523 * On output: the offsets of the alignment field.
jpayne@69 524 * @param status Output param filled with success/failure status.
jpayne@69 525 * @return Reference to 'appendTo' parameter.
jpayne@69 526 * @internal
jpayne@69 527 */
jpayne@69 528 virtual UnicodeString& format(int64_t number,
jpayne@69 529 UnicodeString& appendTo,
jpayne@69 530 FieldPosition& pos,
jpayne@69 531 UErrorCode& status) const;
jpayne@69 532 /**
jpayne@69 533 * Format an int64 number. Subclasses must implement
jpayne@69 534 * this method.
jpayne@69 535 *
jpayne@69 536 * @param number The value to be formatted.
jpayne@69 537 * @param appendTo Output parameter to receive result.
jpayne@69 538 * Result is appended to existing contents.
jpayne@69 539 * @param posIter On return, can be used to iterate over positions
jpayne@69 540 * of fields generated by this format call.
jpayne@69 541 * Can be NULL.
jpayne@69 542 * @param status Output param filled with success/failure status.
jpayne@69 543 * @return Reference to 'appendTo' parameter.
jpayne@69 544 * @stable ICU 4.4
jpayne@69 545 */
jpayne@69 546 virtual UnicodeString& format(int64_t number,
jpayne@69 547 UnicodeString& appendTo,
jpayne@69 548 FieldPositionIterator* posIter,
jpayne@69 549 UErrorCode& status) const;
jpayne@69 550
jpayne@69 551 /**
jpayne@69 552 * Format a decimal number. Subclasses must implement
jpayne@69 553 * this method. The syntax of the unformatted number is a "numeric string"
jpayne@69 554 * as defined in the Decimal Arithmetic Specification, available at
jpayne@69 555 * http://speleotrove.com/decimal
jpayne@69 556 *
jpayne@69 557 * @param number The unformatted number, as a string, to be formatted.
jpayne@69 558 * @param appendTo Output parameter to receive result.
jpayne@69 559 * Result is appended to existing contents.
jpayne@69 560 * @param posIter On return, can be used to iterate over positions
jpayne@69 561 * of fields generated by this format call.
jpayne@69 562 * Can be NULL.
jpayne@69 563 * @param status Output param filled with success/failure status.
jpayne@69 564 * @return Reference to 'appendTo' parameter.
jpayne@69 565 * @stable ICU 4.4
jpayne@69 566 */
jpayne@69 567 virtual UnicodeString& format(StringPiece number,
jpayne@69 568 UnicodeString& appendTo,
jpayne@69 569 FieldPositionIterator* posIter,
jpayne@69 570 UErrorCode& status) const;
jpayne@69 571
jpayne@69 572 // Can't use #ifndef U_HIDE_INTERNAL_API because these are virtual methods
jpayne@69 573
jpayne@69 574 /**
jpayne@69 575 * Format a decimal number.
jpayne@69 576 * The number is a DecimalQuantity wrapper onto a floating point decimal number.
jpayne@69 577 * The default implementation in NumberFormat converts the decimal number
jpayne@69 578 * to a double and formats that. Subclasses of NumberFormat that want
jpayne@69 579 * to specifically handle big decimal numbers must override this method.
jpayne@69 580 * class DecimalFormat does so.
jpayne@69 581 *
jpayne@69 582 * @param number The number, a DecimalQuantity format Decimal Floating Point.
jpayne@69 583 * @param appendTo Output parameter to receive result.
jpayne@69 584 * Result is appended to existing contents.
jpayne@69 585 * @param posIter On return, can be used to iterate over positions
jpayne@69 586 * of fields generated by this format call.
jpayne@69 587 * @param status Output param filled with success/failure status.
jpayne@69 588 * @return Reference to 'appendTo' parameter.
jpayne@69 589 * @internal
jpayne@69 590 */
jpayne@69 591 virtual UnicodeString& format(const number::impl::DecimalQuantity &number,
jpayne@69 592 UnicodeString& appendTo,
jpayne@69 593 FieldPositionIterator* posIter,
jpayne@69 594 UErrorCode& status) const;
jpayne@69 595
jpayne@69 596 /**
jpayne@69 597 * Format a decimal number.
jpayne@69 598 * The number is a DecimalQuantity wrapper onto a floating point decimal number.
jpayne@69 599 * The default implementation in NumberFormat converts the decimal number
jpayne@69 600 * to a double and formats that. Subclasses of NumberFormat that want
jpayne@69 601 * to specifically handle big decimal numbers must override this method.
jpayne@69 602 * class DecimalFormat does so.
jpayne@69 603 *
jpayne@69 604 * @param number The number, a DecimalQuantity format Decimal Floating Point.
jpayne@69 605 * @param appendTo Output parameter to receive result.
jpayne@69 606 * Result is appended to existing contents.
jpayne@69 607 * @param pos On input: an alignment field, if desired.
jpayne@69 608 * On output: the offsets of the alignment field.
jpayne@69 609 * @param status Output param filled with success/failure status.
jpayne@69 610 * @return Reference to 'appendTo' parameter.
jpayne@69 611 * @internal
jpayne@69 612 */
jpayne@69 613 virtual UnicodeString& format(const number::impl::DecimalQuantity &number,
jpayne@69 614 UnicodeString& appendTo,
jpayne@69 615 FieldPosition& pos,
jpayne@69 616 UErrorCode& status) const;
jpayne@69 617
jpayne@69 618 /**
jpayne@69 619 * Return a long if possible (e.g. within range LONG_MAX,
jpayne@69 620 * LONG_MAX], and with no decimals), otherwise a double. If
jpayne@69 621 * IntegerOnly is set, will stop at a decimal point (or equivalent;
jpayne@69 622 * e.g. for rational numbers "1 2/3", will stop after the 1).
jpayne@69 623 * <P>
jpayne@69 624 * If no object can be parsed, index is unchanged, and NULL is
jpayne@69 625 * returned.
jpayne@69 626 * <P>
jpayne@69 627 * This is a pure virtual which concrete subclasses must implement.
jpayne@69 628 *
jpayne@69 629 * @param text The text to be parsed.
jpayne@69 630 * @param result Formattable to be set to the parse result.
jpayne@69 631 * If parse fails, return contents are undefined.
jpayne@69 632 * @param parsePosition The position to start parsing at on input.
jpayne@69 633 * On output, moved to after the last successfully
jpayne@69 634 * parse character. On parse failure, does not change.
jpayne@69 635 * @stable ICU 2.0
jpayne@69 636 */
jpayne@69 637 virtual void parse(const UnicodeString& text,
jpayne@69 638 Formattable& result,
jpayne@69 639 ParsePosition& parsePosition) const = 0;
jpayne@69 640
jpayne@69 641 /**
jpayne@69 642 * Parse a string as a numeric value, and return a Formattable
jpayne@69 643 * numeric object. This method parses integers only if IntegerOnly
jpayne@69 644 * is set.
jpayne@69 645 *
jpayne@69 646 * @param text The text to be parsed.
jpayne@69 647 * @param result Formattable to be set to the parse result.
jpayne@69 648 * If parse fails, return contents are undefined.
jpayne@69 649 * @param status Output parameter set to a failure error code
jpayne@69 650 * when a failure occurs. The error code when the
jpayne@69 651 * string fails to parse is U_INVALID_FORMAT_ERROR,
jpayne@69 652 * unless overridden by a subclass.
jpayne@69 653 * @see NumberFormat::isParseIntegerOnly
jpayne@69 654 * @stable ICU 2.0
jpayne@69 655 */
jpayne@69 656 virtual void parse(const UnicodeString& text,
jpayne@69 657 Formattable& result,
jpayne@69 658 UErrorCode& status) const;
jpayne@69 659
jpayne@69 660 /**
jpayne@69 661 * Parses text from the given string as a currency amount. Unlike
jpayne@69 662 * the parse() method, this method will attempt to parse a generic
jpayne@69 663 * currency name, searching for a match of this object's locale's
jpayne@69 664 * currency display names, or for a 3-letter ISO currency code.
jpayne@69 665 * This method will fail if this format is not a currency format,
jpayne@69 666 * that is, if it does not contain the currency pattern symbol
jpayne@69 667 * (U+00A4) in its prefix or suffix.
jpayne@69 668 *
jpayne@69 669 * @param text the string to parse
jpayne@69 670 * @param pos input-output position; on input, the position within text
jpayne@69 671 * to match; must have 0 <= pos.getIndex() < text.length();
jpayne@69 672 * on output, the position after the last matched character.
jpayne@69 673 * If the parse fails, the position in unchanged upon output.
jpayne@69 674 * @return if parse succeeds, a pointer to a newly-created CurrencyAmount
jpayne@69 675 * object (owned by the caller) containing information about
jpayne@69 676 * the parsed currency; if parse fails, this is NULL.
jpayne@69 677 * @stable ICU 49
jpayne@69 678 */
jpayne@69 679 virtual CurrencyAmount* parseCurrency(const UnicodeString& text,
jpayne@69 680 ParsePosition& pos) const;
jpayne@69 681
jpayne@69 682 /**
jpayne@69 683 * Return true if this format will parse numbers as integers
jpayne@69 684 * only. For example in the English locale, with ParseIntegerOnly
jpayne@69 685 * true, the string "1234." would be parsed as the integer value
jpayne@69 686 * 1234 and parsing would stop at the "." character. Of course,
jpayne@69 687 * the exact format accepted by the parse operation is locale
jpayne@69 688 * dependant and determined by sub-classes of NumberFormat.
jpayne@69 689 * @return true if this format will parse numbers as integers
jpayne@69 690 * only.
jpayne@69 691 * @stable ICU 2.0
jpayne@69 692 */
jpayne@69 693 UBool isParseIntegerOnly(void) const;
jpayne@69 694
jpayne@69 695 /**
jpayne@69 696 * Sets whether or not numbers should be parsed as integers only.
jpayne@69 697 * @param value set True, this format will parse numbers as integers
jpayne@69 698 * only.
jpayne@69 699 * @see isParseIntegerOnly
jpayne@69 700 * @stable ICU 2.0
jpayne@69 701 */
jpayne@69 702 virtual void setParseIntegerOnly(UBool value);
jpayne@69 703
jpayne@69 704 /**
jpayne@69 705 * Sets whether lenient parsing should be enabled (it is off by default).
jpayne@69 706 *
jpayne@69 707 * @param enable \c TRUE if lenient parsing should be used,
jpayne@69 708 * \c FALSE otherwise.
jpayne@69 709 * @stable ICU 4.8
jpayne@69 710 */
jpayne@69 711 virtual void setLenient(UBool enable);
jpayne@69 712
jpayne@69 713 /**
jpayne@69 714 * Returns whether lenient parsing is enabled (it is off by default).
jpayne@69 715 *
jpayne@69 716 * @return \c TRUE if lenient parsing is enabled,
jpayne@69 717 * \c FALSE otherwise.
jpayne@69 718 * @see #setLenient
jpayne@69 719 * @stable ICU 4.8
jpayne@69 720 */
jpayne@69 721 virtual UBool isLenient(void) const;
jpayne@69 722
jpayne@69 723 /**
jpayne@69 724 * Create a default style NumberFormat for the current default locale.
jpayne@69 725 * The default formatting style is locale dependent.
jpayne@69 726 * <p>
jpayne@69 727 * <strong>NOTE:</strong> New users are strongly encouraged to use
jpayne@69 728 * {@link icu::number::NumberFormatter} instead of NumberFormat.
jpayne@69 729 * @stable ICU 2.0
jpayne@69 730 */
jpayne@69 731 static NumberFormat* U_EXPORT2 createInstance(UErrorCode&);
jpayne@69 732
jpayne@69 733 /**
jpayne@69 734 * Create a default style NumberFormat for the specified locale.
jpayne@69 735 * The default formatting style is locale dependent.
jpayne@69 736 * @param inLocale the given locale.
jpayne@69 737 * <p>
jpayne@69 738 * <strong>NOTE:</strong> New users are strongly encouraged to use
jpayne@69 739 * {@link icu::number::NumberFormatter} instead of NumberFormat.
jpayne@69 740 * @stable ICU 2.0
jpayne@69 741 */
jpayne@69 742 static NumberFormat* U_EXPORT2 createInstance(const Locale& inLocale,
jpayne@69 743 UErrorCode&);
jpayne@69 744
jpayne@69 745 /**
jpayne@69 746 * Create a specific style NumberFormat for the specified locale.
jpayne@69 747 * <p>
jpayne@69 748 * <strong>NOTE:</strong> New users are strongly encouraged to use
jpayne@69 749 * {@link icu::number::NumberFormatter} instead of NumberFormat.
jpayne@69 750 * @param desiredLocale the given locale.
jpayne@69 751 * @param style the given style.
jpayne@69 752 * @param errorCode Output param filled with success/failure status.
jpayne@69 753 * @return A new NumberFormat instance.
jpayne@69 754 * @stable ICU 4.8
jpayne@69 755 */
jpayne@69 756 static NumberFormat* U_EXPORT2 createInstance(const Locale& desiredLocale,
jpayne@69 757 UNumberFormatStyle style,
jpayne@69 758 UErrorCode& errorCode);
jpayne@69 759
jpayne@69 760 #ifndef U_HIDE_INTERNAL_API
jpayne@69 761
jpayne@69 762 /**
jpayne@69 763 * ICU use only.
jpayne@69 764 * Creates NumberFormat instance without using the cache.
jpayne@69 765 * @internal
jpayne@69 766 */
jpayne@69 767 static NumberFormat* internalCreateInstance(
jpayne@69 768 const Locale& desiredLocale,
jpayne@69 769 UNumberFormatStyle style,
jpayne@69 770 UErrorCode& errorCode);
jpayne@69 771
jpayne@69 772 /**
jpayne@69 773 * ICU use only.
jpayne@69 774 * Returns handle to the shared, cached NumberFormat instance for given
jpayne@69 775 * locale. On success, caller must call removeRef() on returned value
jpayne@69 776 * once it is done with the shared instance.
jpayne@69 777 * @internal
jpayne@69 778 */
jpayne@69 779 static const SharedNumberFormat* U_EXPORT2 createSharedInstance(
jpayne@69 780 const Locale& inLocale, UNumberFormatStyle style, UErrorCode& status);
jpayne@69 781
jpayne@69 782 #endif /* U_HIDE_INTERNAL_API */
jpayne@69 783
jpayne@69 784 /**
jpayne@69 785 * Returns a currency format for the current default locale.
jpayne@69 786 * <p>
jpayne@69 787 * <strong>NOTE:</strong> New users are strongly encouraged to use
jpayne@69 788 * {@link icu::number::NumberFormatter} instead of NumberFormat.
jpayne@69 789 * @stable ICU 2.0
jpayne@69 790 */
jpayne@69 791 static NumberFormat* U_EXPORT2 createCurrencyInstance(UErrorCode&);
jpayne@69 792
jpayne@69 793 /**
jpayne@69 794 * Returns a currency format for the specified locale.
jpayne@69 795 * <p>
jpayne@69 796 * <strong>NOTE:</strong> New users are strongly encouraged to use
jpayne@69 797 * {@link icu::number::NumberFormatter} instead of NumberFormat.
jpayne@69 798 * @param inLocale the given locale.
jpayne@69 799 * @stable ICU 2.0
jpayne@69 800 */
jpayne@69 801 static NumberFormat* U_EXPORT2 createCurrencyInstance(const Locale& inLocale,
jpayne@69 802 UErrorCode&);
jpayne@69 803
jpayne@69 804 /**
jpayne@69 805 * Returns a percentage format for the current default locale.
jpayne@69 806 * <p>
jpayne@69 807 * <strong>NOTE:</strong> New users are strongly encouraged to use
jpayne@69 808 * {@link icu::number::NumberFormatter} instead of NumberFormat.
jpayne@69 809 * @stable ICU 2.0
jpayne@69 810 */
jpayne@69 811 static NumberFormat* U_EXPORT2 createPercentInstance(UErrorCode&);
jpayne@69 812
jpayne@69 813 /**
jpayne@69 814 * Returns a percentage format for the specified locale.
jpayne@69 815 * <p>
jpayne@69 816 * <strong>NOTE:</strong> New users are strongly encouraged to use
jpayne@69 817 * {@link icu::number::NumberFormatter} instead of NumberFormat.
jpayne@69 818 * @param inLocale the given locale.
jpayne@69 819 * @stable ICU 2.0
jpayne@69 820 */
jpayne@69 821 static NumberFormat* U_EXPORT2 createPercentInstance(const Locale& inLocale,
jpayne@69 822 UErrorCode&);
jpayne@69 823
jpayne@69 824 /**
jpayne@69 825 * Returns a scientific format for the current default locale.
jpayne@69 826 * <p>
jpayne@69 827 * <strong>NOTE:</strong> New users are strongly encouraged to use
jpayne@69 828 * {@link icu::number::NumberFormatter} instead of NumberFormat.
jpayne@69 829 * @stable ICU 2.0
jpayne@69 830 */
jpayne@69 831 static NumberFormat* U_EXPORT2 createScientificInstance(UErrorCode&);
jpayne@69 832
jpayne@69 833 /**
jpayne@69 834 * Returns a scientific format for the specified locale.
jpayne@69 835 * <p>
jpayne@69 836 * <strong>NOTE:</strong> New users are strongly encouraged to use
jpayne@69 837 * {@link icu::number::NumberFormatter} instead of NumberFormat.
jpayne@69 838 * @param inLocale the given locale.
jpayne@69 839 * @stable ICU 2.0
jpayne@69 840 */
jpayne@69 841 static NumberFormat* U_EXPORT2 createScientificInstance(const Locale& inLocale,
jpayne@69 842 UErrorCode&);
jpayne@69 843
jpayne@69 844 /**
jpayne@69 845 * Get the set of Locales for which NumberFormats are installed.
jpayne@69 846 * @param count Output param to receive the size of the locales
jpayne@69 847 * @stable ICU 2.0
jpayne@69 848 */
jpayne@69 849 static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
jpayne@69 850
jpayne@69 851 #if !UCONFIG_NO_SERVICE
jpayne@69 852 /**
jpayne@69 853 * Register a new NumberFormatFactory. The factory will be adopted.
jpayne@69 854 * Because ICU may choose to cache NumberFormat objects internally,
jpayne@69 855 * this must be called at application startup, prior to any calls to
jpayne@69 856 * NumberFormat::createInstance to avoid undefined behavior.
jpayne@69 857 * @param toAdopt the NumberFormatFactory instance to be adopted
jpayne@69 858 * @param status the in/out status code, no special meanings are assigned
jpayne@69 859 * @return a registry key that can be used to unregister this factory
jpayne@69 860 * @stable ICU 2.6
jpayne@69 861 */
jpayne@69 862 static URegistryKey U_EXPORT2 registerFactory(NumberFormatFactory* toAdopt, UErrorCode& status);
jpayne@69 863
jpayne@69 864 /**
jpayne@69 865 * Unregister a previously-registered NumberFormatFactory using the key returned from the
jpayne@69 866 * register call. Key becomes invalid after a successful call and should not be used again.
jpayne@69 867 * The NumberFormatFactory corresponding to the key will be deleted.
jpayne@69 868 * Because ICU may choose to cache NumberFormat objects internally,
jpayne@69 869 * this should be called during application shutdown, after all calls to
jpayne@69 870 * NumberFormat::createInstance to avoid undefined behavior.
jpayne@69 871 * @param key the registry key returned by a previous call to registerFactory
jpayne@69 872 * @param status the in/out status code, no special meanings are assigned
jpayne@69 873 * @return TRUE if the factory for the key was successfully unregistered
jpayne@69 874 * @stable ICU 2.6
jpayne@69 875 */
jpayne@69 876 static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status);
jpayne@69 877
jpayne@69 878 /**
jpayne@69 879 * Return a StringEnumeration over the locales available at the time of the call,
jpayne@69 880 * including registered locales.
jpayne@69 881 * @return a StringEnumeration over the locales available at the time of the call
jpayne@69 882 * @stable ICU 2.6
jpayne@69 883 */
jpayne@69 884 static StringEnumeration* U_EXPORT2 getAvailableLocales(void);
jpayne@69 885 #endif /* UCONFIG_NO_SERVICE */
jpayne@69 886
jpayne@69 887 /**
jpayne@69 888 * Returns true if grouping is used in this format. For example,
jpayne@69 889 * in the English locale, with grouping on, the number 1234567
jpayne@69 890 * might be formatted as "1,234,567". The grouping separator as
jpayne@69 891 * well as the size of each group is locale dependent and is
jpayne@69 892 * determined by sub-classes of NumberFormat.
jpayne@69 893 * @see setGroupingUsed
jpayne@69 894 * @stable ICU 2.0
jpayne@69 895 */
jpayne@69 896 UBool isGroupingUsed(void) const;
jpayne@69 897
jpayne@69 898 /**
jpayne@69 899 * Set whether or not grouping will be used in this format.
jpayne@69 900 * @param newValue True, grouping will be used in this format.
jpayne@69 901 * @see getGroupingUsed
jpayne@69 902 * @stable ICU 2.0
jpayne@69 903 */
jpayne@69 904 virtual void setGroupingUsed(UBool newValue);
jpayne@69 905
jpayne@69 906 /**
jpayne@69 907 * Returns the maximum number of digits allowed in the integer portion of a
jpayne@69 908 * number.
jpayne@69 909 * @return the maximum number of digits allowed in the integer portion of a
jpayne@69 910 * number.
jpayne@69 911 * @see setMaximumIntegerDigits
jpayne@69 912 * @stable ICU 2.0
jpayne@69 913 */
jpayne@69 914 int32_t getMaximumIntegerDigits(void) const;
jpayne@69 915
jpayne@69 916 /**
jpayne@69 917 * Sets the maximum number of digits allowed in the integer portion of a
jpayne@69 918 * number. maximumIntegerDigits must be >= minimumIntegerDigits. If the
jpayne@69 919 * new value for maximumIntegerDigits is less than the current value
jpayne@69 920 * of minimumIntegerDigits, then minimumIntegerDigits will also be set to
jpayne@69 921 * the new value.
jpayne@69 922 *
jpayne@69 923 * @param newValue the new value for the maximum number of digits
jpayne@69 924 * allowed in the integer portion of a number.
jpayne@69 925 * @see getMaximumIntegerDigits
jpayne@69 926 * @stable ICU 2.0
jpayne@69 927 */
jpayne@69 928 virtual void setMaximumIntegerDigits(int32_t newValue);
jpayne@69 929
jpayne@69 930 /**
jpayne@69 931 * Returns the minimum number of digits allowed in the integer portion of a
jpayne@69 932 * number.
jpayne@69 933 * @return the minimum number of digits allowed in the integer portion of a
jpayne@69 934 * number.
jpayne@69 935 * @see setMinimumIntegerDigits
jpayne@69 936 * @stable ICU 2.0
jpayne@69 937 */
jpayne@69 938 int32_t getMinimumIntegerDigits(void) const;
jpayne@69 939
jpayne@69 940 /**
jpayne@69 941 * Sets the minimum number of digits allowed in the integer portion of a
jpayne@69 942 * number. minimumIntegerDigits must be &lt;= maximumIntegerDigits. If the
jpayne@69 943 * new value for minimumIntegerDigits exceeds the current value
jpayne@69 944 * of maximumIntegerDigits, then maximumIntegerDigits will also be set to
jpayne@69 945 * the new value.
jpayne@69 946 * @param newValue the new value to be set.
jpayne@69 947 * @see getMinimumIntegerDigits
jpayne@69 948 * @stable ICU 2.0
jpayne@69 949 */
jpayne@69 950 virtual void setMinimumIntegerDigits(int32_t newValue);
jpayne@69 951
jpayne@69 952 /**
jpayne@69 953 * Returns the maximum number of digits allowed in the fraction portion of a
jpayne@69 954 * number.
jpayne@69 955 * @return the maximum number of digits allowed in the fraction portion of a
jpayne@69 956 * number.
jpayne@69 957 * @see setMaximumFractionDigits
jpayne@69 958 * @stable ICU 2.0
jpayne@69 959 */
jpayne@69 960 int32_t getMaximumFractionDigits(void) const;
jpayne@69 961
jpayne@69 962 /**
jpayne@69 963 * Sets the maximum number of digits allowed in the fraction portion of a
jpayne@69 964 * number. maximumFractionDigits must be >= minimumFractionDigits. If the
jpayne@69 965 * new value for maximumFractionDigits is less than the current value
jpayne@69 966 * of minimumFractionDigits, then minimumFractionDigits will also be set to
jpayne@69 967 * the new value.
jpayne@69 968 * @param newValue the new value to be set.
jpayne@69 969 * @see getMaximumFractionDigits
jpayne@69 970 * @stable ICU 2.0
jpayne@69 971 */
jpayne@69 972 virtual void setMaximumFractionDigits(int32_t newValue);
jpayne@69 973
jpayne@69 974 /**
jpayne@69 975 * Returns the minimum number of digits allowed in the fraction portion of a
jpayne@69 976 * number.
jpayne@69 977 * @return the minimum number of digits allowed in the fraction portion of a
jpayne@69 978 * number.
jpayne@69 979 * @see setMinimumFractionDigits
jpayne@69 980 * @stable ICU 2.0
jpayne@69 981 */
jpayne@69 982 int32_t getMinimumFractionDigits(void) const;
jpayne@69 983
jpayne@69 984 /**
jpayne@69 985 * Sets the minimum number of digits allowed in the fraction portion of a
jpayne@69 986 * number. minimumFractionDigits must be &lt;= maximumFractionDigits. If the
jpayne@69 987 * new value for minimumFractionDigits exceeds the current value
jpayne@69 988 * of maximumFractionDigits, then maximumIntegerDigits will also be set to
jpayne@69 989 * the new value
jpayne@69 990 * @param newValue the new value to be set.
jpayne@69 991 * @see getMinimumFractionDigits
jpayne@69 992 * @stable ICU 2.0
jpayne@69 993 */
jpayne@69 994 virtual void setMinimumFractionDigits(int32_t newValue);
jpayne@69 995
jpayne@69 996 /**
jpayne@69 997 * Sets the currency used to display currency
jpayne@69 998 * amounts. This takes effect immediately, if this format is a
jpayne@69 999 * currency format. If this format is not a currency format, then
jpayne@69 1000 * the currency is used if and when this object becomes a
jpayne@69 1001 * currency format.
jpayne@69 1002 * @param theCurrency a 3-letter ISO code indicating new currency
jpayne@69 1003 * to use. It need not be null-terminated. May be the empty
jpayne@69 1004 * string or NULL to indicate no currency.
jpayne@69 1005 * @param ec input-output error code
jpayne@69 1006 * @stable ICU 3.0
jpayne@69 1007 */
jpayne@69 1008 virtual void setCurrency(const char16_t* theCurrency, UErrorCode& ec);
jpayne@69 1009
jpayne@69 1010 /**
jpayne@69 1011 * Gets the currency used to display currency
jpayne@69 1012 * amounts. This may be an empty string for some subclasses.
jpayne@69 1013 * @return a 3-letter null-terminated ISO code indicating
jpayne@69 1014 * the currency in use, or a pointer to the empty string.
jpayne@69 1015 * @stable ICU 2.6
jpayne@69 1016 */
jpayne@69 1017 const char16_t* getCurrency() const;
jpayne@69 1018
jpayne@69 1019 /**
jpayne@69 1020 * Set a particular UDisplayContext value in the formatter, such as
jpayne@69 1021 * UDISPCTX_CAPITALIZATION_FOR_STANDALONE.
jpayne@69 1022 * @param value The UDisplayContext value to set.
jpayne@69 1023 * @param status Input/output status. If at entry this indicates a failure
jpayne@69 1024 * status, the function will do nothing; otherwise this will be
jpayne@69 1025 * updated with any new status from the function.
jpayne@69 1026 * @stable ICU 53
jpayne@69 1027 */
jpayne@69 1028 virtual void setContext(UDisplayContext value, UErrorCode& status);
jpayne@69 1029
jpayne@69 1030 /**
jpayne@69 1031 * Get the formatter's UDisplayContext value for the specified UDisplayContextType,
jpayne@69 1032 * such as UDISPCTX_TYPE_CAPITALIZATION.
jpayne@69 1033 * @param type The UDisplayContextType whose value to return
jpayne@69 1034 * @param status Input/output status. If at entry this indicates a failure
jpayne@69 1035 * status, the function will do nothing; otherwise this will be
jpayne@69 1036 * updated with any new status from the function.
jpayne@69 1037 * @return The UDisplayContextValue for the specified type.
jpayne@69 1038 * @stable ICU 53
jpayne@69 1039 */
jpayne@69 1040 virtual UDisplayContext getContext(UDisplayContextType type, UErrorCode& status) const;
jpayne@69 1041
jpayne@69 1042 /**
jpayne@69 1043 * Get the rounding mode. This will always return NumberFormat::ERoundingMode::kRoundUnnecessary
jpayne@69 1044 * if the subclass does not support rounding.
jpayne@69 1045 * @return A rounding mode
jpayne@69 1046 * @stable ICU 60
jpayne@69 1047 */
jpayne@69 1048 virtual ERoundingMode getRoundingMode(void) const;
jpayne@69 1049
jpayne@69 1050 /**
jpayne@69 1051 * Set the rounding mode. If a subclass does not support rounding, this will do nothing.
jpayne@69 1052 * @param roundingMode A rounding mode
jpayne@69 1053 * @stable ICU 60
jpayne@69 1054 */
jpayne@69 1055 virtual void setRoundingMode(ERoundingMode roundingMode);
jpayne@69 1056
jpayne@69 1057 public:
jpayne@69 1058
jpayne@69 1059 /**
jpayne@69 1060 * Return the class ID for this class. This is useful for
jpayne@69 1061 * comparing to a return value from getDynamicClassID(). Note that,
jpayne@69 1062 * because NumberFormat is an abstract base class, no fully constructed object
jpayne@69 1063 * will have the class ID returned by NumberFormat::getStaticClassID().
jpayne@69 1064 * @return The class ID for all objects of this class.
jpayne@69 1065 * @stable ICU 2.0
jpayne@69 1066 */
jpayne@69 1067 static UClassID U_EXPORT2 getStaticClassID(void);
jpayne@69 1068
jpayne@69 1069 /**
jpayne@69 1070 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override.
jpayne@69 1071 * This method is to implement a simple version of RTTI, since not all
jpayne@69 1072 * C++ compilers support genuine RTTI. Polymorphic operator==() and
jpayne@69 1073 * clone() methods call this method.
jpayne@69 1074 * <P>
jpayne@69 1075 * @return The class ID for this object. All objects of a
jpayne@69 1076 * given class have the same class ID. Objects of
jpayne@69 1077 * other classes have different class IDs.
jpayne@69 1078 * @stable ICU 2.0
jpayne@69 1079 */
jpayne@69 1080 virtual UClassID getDynamicClassID(void) const = 0;
jpayne@69 1081
jpayne@69 1082 protected:
jpayne@69 1083
jpayne@69 1084 /**
jpayne@69 1085 * Default constructor for subclass use only.
jpayne@69 1086 * @stable ICU 2.0
jpayne@69 1087 */
jpayne@69 1088 NumberFormat();
jpayne@69 1089
jpayne@69 1090 /**
jpayne@69 1091 * Copy constructor.
jpayne@69 1092 * @stable ICU 2.0
jpayne@69 1093 */
jpayne@69 1094 NumberFormat(const NumberFormat&);
jpayne@69 1095
jpayne@69 1096 /**
jpayne@69 1097 * Assignment operator.
jpayne@69 1098 * @stable ICU 2.0
jpayne@69 1099 */
jpayne@69 1100 NumberFormat& operator=(const NumberFormat&);
jpayne@69 1101
jpayne@69 1102 /**
jpayne@69 1103 * Returns the currency in effect for this formatter. Subclasses
jpayne@69 1104 * should override this method as needed. Unlike getCurrency(),
jpayne@69 1105 * this method should never return "".
jpayne@69 1106 * @result output parameter for null-terminated result, which must
jpayne@69 1107 * have a capacity of at least 4
jpayne@69 1108 * @internal
jpayne@69 1109 */
jpayne@69 1110 virtual void getEffectiveCurrency(char16_t* result, UErrorCode& ec) const;
jpayne@69 1111
jpayne@69 1112 #ifndef U_HIDE_INTERNAL_API
jpayne@69 1113 /**
jpayne@69 1114 * Creates the specified number format style of the desired locale.
jpayne@69 1115 * If mustBeDecimalFormat is TRUE, then the returned pointer is
jpayne@69 1116 * either a DecimalFormat or it is NULL.
jpayne@69 1117 * @internal
jpayne@69 1118 */
jpayne@69 1119 static NumberFormat* makeInstance(const Locale& desiredLocale,
jpayne@69 1120 UNumberFormatStyle style,
jpayne@69 1121 UBool mustBeDecimalFormat,
jpayne@69 1122 UErrorCode& errorCode);
jpayne@69 1123 #endif /* U_HIDE_INTERNAL_API */
jpayne@69 1124
jpayne@69 1125 private:
jpayne@69 1126
jpayne@69 1127 static UBool isStyleSupported(UNumberFormatStyle style);
jpayne@69 1128
jpayne@69 1129 /**
jpayne@69 1130 * Creates the specified decimal format style of the desired locale.
jpayne@69 1131 * @param desiredLocale the given locale.
jpayne@69 1132 * @param style the given style.
jpayne@69 1133 * @param errorCode Output param filled with success/failure status.
jpayne@69 1134 * @return A new NumberFormat instance.
jpayne@69 1135 */
jpayne@69 1136 static NumberFormat* makeInstance(const Locale& desiredLocale,
jpayne@69 1137 UNumberFormatStyle style,
jpayne@69 1138 UErrorCode& errorCode);
jpayne@69 1139
jpayne@69 1140 UBool fGroupingUsed;
jpayne@69 1141 int32_t fMaxIntegerDigits;
jpayne@69 1142 int32_t fMinIntegerDigits;
jpayne@69 1143 int32_t fMaxFractionDigits;
jpayne@69 1144 int32_t fMinFractionDigits;
jpayne@69 1145
jpayne@69 1146 protected:
jpayne@69 1147 /** \internal */
jpayne@69 1148 static const int32_t gDefaultMaxIntegerDigits;
jpayne@69 1149 /** \internal */
jpayne@69 1150 static const int32_t gDefaultMinIntegerDigits;
jpayne@69 1151
jpayne@69 1152 private:
jpayne@69 1153 UBool fParseIntegerOnly;
jpayne@69 1154 UBool fLenient; // TRUE => lenient parse is enabled
jpayne@69 1155
jpayne@69 1156 // ISO currency code
jpayne@69 1157 char16_t fCurrency[4];
jpayne@69 1158
jpayne@69 1159 UDisplayContext fCapitalizationContext;
jpayne@69 1160
jpayne@69 1161 friend class ICUNumberFormatFactory; // access to makeInstance
jpayne@69 1162 friend class ICUNumberFormatService;
jpayne@69 1163 friend class ::NumberFormatTest; // access to isStyleSupported()
jpayne@69 1164 };
jpayne@69 1165
jpayne@69 1166 #if !UCONFIG_NO_SERVICE
jpayne@69 1167 /**
jpayne@69 1168 * A NumberFormatFactory is used to register new number formats. The factory
jpayne@69 1169 * should be able to create any of the predefined formats for each locale it
jpayne@69 1170 * supports. When registered, the locales it supports extend or override the
jpayne@69 1171 * locale already supported by ICU.
jpayne@69 1172 *
jpayne@69 1173 * @stable ICU 2.6
jpayne@69 1174 */
jpayne@69 1175 class U_I18N_API NumberFormatFactory : public UObject {
jpayne@69 1176 public:
jpayne@69 1177
jpayne@69 1178 /**
jpayne@69 1179 * Destructor
jpayne@69 1180 * @stable ICU 3.0
jpayne@69 1181 */
jpayne@69 1182 virtual ~NumberFormatFactory();
jpayne@69 1183
jpayne@69 1184 /**
jpayne@69 1185 * Return true if this factory will be visible. Default is true.
jpayne@69 1186 * If not visible, the locales supported by this factory will not
jpayne@69 1187 * be listed by getAvailableLocales.
jpayne@69 1188 * @stable ICU 2.6
jpayne@69 1189 */
jpayne@69 1190 virtual UBool visible(void) const = 0;
jpayne@69 1191
jpayne@69 1192 /**
jpayne@69 1193 * Return the locale names directly supported by this factory. The number of names
jpayne@69 1194 * is returned in count;
jpayne@69 1195 * @stable ICU 2.6
jpayne@69 1196 */
jpayne@69 1197 virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const = 0;
jpayne@69 1198
jpayne@69 1199 /**
jpayne@69 1200 * Return a number format of the appropriate type. If the locale
jpayne@69 1201 * is not supported, return null. If the locale is supported, but
jpayne@69 1202 * the type is not provided by this service, return null. Otherwise
jpayne@69 1203 * return an appropriate instance of NumberFormat.
jpayne@69 1204 * @stable ICU 2.6
jpayne@69 1205 */
jpayne@69 1206 virtual NumberFormat* createFormat(const Locale& loc, UNumberFormatStyle formatType) = 0;
jpayne@69 1207 };
jpayne@69 1208
jpayne@69 1209 /**
jpayne@69 1210 * A NumberFormatFactory that supports a single locale. It can be visible or invisible.
jpayne@69 1211 * @stable ICU 2.6
jpayne@69 1212 */
jpayne@69 1213 class U_I18N_API SimpleNumberFormatFactory : public NumberFormatFactory {
jpayne@69 1214 protected:
jpayne@69 1215 /**
jpayne@69 1216 * True if the locale supported by this factory is visible.
jpayne@69 1217 * @stable ICU 2.6
jpayne@69 1218 */
jpayne@69 1219 const UBool _visible;
jpayne@69 1220
jpayne@69 1221 /**
jpayne@69 1222 * The locale supported by this factory, as a UnicodeString.
jpayne@69 1223 * @stable ICU 2.6
jpayne@69 1224 */
jpayne@69 1225 UnicodeString _id;
jpayne@69 1226
jpayne@69 1227 public:
jpayne@69 1228 /**
jpayne@69 1229 * @stable ICU 2.6
jpayne@69 1230 */
jpayne@69 1231 SimpleNumberFormatFactory(const Locale& locale, UBool visible = TRUE);
jpayne@69 1232
jpayne@69 1233 /**
jpayne@69 1234 * @stable ICU 3.0
jpayne@69 1235 */
jpayne@69 1236 virtual ~SimpleNumberFormatFactory();
jpayne@69 1237
jpayne@69 1238 /**
jpayne@69 1239 * @stable ICU 2.6
jpayne@69 1240 */
jpayne@69 1241 virtual UBool visible(void) const;
jpayne@69 1242
jpayne@69 1243 /**
jpayne@69 1244 * @stable ICU 2.6
jpayne@69 1245 */
jpayne@69 1246 virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const;
jpayne@69 1247 };
jpayne@69 1248 #endif /* #if !UCONFIG_NO_SERVICE */
jpayne@69 1249
jpayne@69 1250 // -------------------------------------
jpayne@69 1251
jpayne@69 1252 inline UBool
jpayne@69 1253 NumberFormat::isParseIntegerOnly() const
jpayne@69 1254 {
jpayne@69 1255 return fParseIntegerOnly;
jpayne@69 1256 }
jpayne@69 1257
jpayne@69 1258 inline UBool
jpayne@69 1259 NumberFormat::isLenient() const
jpayne@69 1260 {
jpayne@69 1261 return fLenient;
jpayne@69 1262 }
jpayne@69 1263
jpayne@69 1264 U_NAMESPACE_END
jpayne@69 1265
jpayne@69 1266 #endif /* #if !UCONFIG_NO_FORMATTING */
jpayne@69 1267
jpayne@69 1268 #endif /* U_SHOW_CPLUSPLUS_API */
jpayne@69 1269
jpayne@69 1270 #endif // _NUMFMT
jpayne@69 1271 //eof