1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/i18n/unicode/numfmt.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,1127 @@
1.4 +/*
1.5 +********************************************************************************
1.6 +* Copyright (C) 1997-2013, International Business Machines Corporation and others.
1.7 +* All Rights Reserved.
1.8 +********************************************************************************
1.9 +*
1.10 +* File NUMFMT.H
1.11 +*
1.12 +* Modification History:
1.13 +*
1.14 +* Date Name Description
1.15 +* 02/19/97 aliu Converted from java.
1.16 +* 03/18/97 clhuang Updated per C++ implementation.
1.17 +* 04/17/97 aliu Changed DigitCount to int per code review.
1.18 +* 07/20/98 stephen JDK 1.2 sync up. Added scientific support.
1.19 +* Changed naming conventions to match C++ guidelines
1.20 +* Derecated Java style constants (eg, INTEGER_FIELD)
1.21 +********************************************************************************
1.22 +*/
1.23 +
1.24 +#ifndef NUMFMT_H
1.25 +#define NUMFMT_H
1.26 +
1.27 +
1.28 +#include "unicode/utypes.h"
1.29 +
1.30 +/**
1.31 + * \file
1.32 + * \brief C++ API: Abstract base class for all number formats.
1.33 + */
1.34 +
1.35 +#if !UCONFIG_NO_FORMATTING
1.36 +
1.37 +#include "unicode/unistr.h"
1.38 +#include "unicode/format.h"
1.39 +#include "unicode/unum.h" // UNumberFormatStyle
1.40 +#include "unicode/locid.h"
1.41 +#include "unicode/stringpiece.h"
1.42 +#include "unicode/curramt.h"
1.43 +
1.44 +class NumberFormatTest;
1.45 +
1.46 +U_NAMESPACE_BEGIN
1.47 +
1.48 +#if !UCONFIG_NO_SERVICE
1.49 +class NumberFormatFactory;
1.50 +class StringEnumeration;
1.51 +#endif
1.52 +
1.53 +/**
1.54 + *
1.55 + * Abstract base class for all number formats. Provides interface for
1.56 + * formatting and parsing a number. Also provides methods for
1.57 + * determining which locales have number formats, and what their names
1.58 + * are.
1.59 + * <P>
1.60 + * NumberFormat helps you to format and parse numbers for any locale.
1.61 + * Your code can be completely independent of the locale conventions
1.62 + * for decimal points, thousands-separators, or even the particular
1.63 + * decimal digits used, or whether the number format is even decimal.
1.64 + * <P>
1.65 + * To format a number for the current Locale, use one of the static
1.66 + * factory methods:
1.67 + * <pre>
1.68 + * \code
1.69 + * double myNumber = 7.0;
1.70 + * UnicodeString myString;
1.71 + * UErrorCode success = U_ZERO_ERROR;
1.72 + * NumberFormat* nf = NumberFormat::createInstance(success)
1.73 + * nf->format(myNumber, myString);
1.74 + * cout << " Example 1: " << myString << endl;
1.75 + * \endcode
1.76 + * </pre>
1.77 + * Note that there are additional factory methods within subclasses of
1.78 + * NumberFormat.
1.79 + * <P>
1.80 + * If you are formatting multiple numbers, it is more efficient to get
1.81 + * the format and use it multiple times so that the system doesn't
1.82 + * have to fetch the information about the local language and country
1.83 + * conventions multiple times.
1.84 + * <pre>
1.85 + * \code
1.86 + * UnicodeString myString;
1.87 + * UErrorCode success = U_ZERO_ERROR;
1.88 + * nf = NumberFormat::createInstance( success );
1.89 + * int32_t a[] = { 123, 3333, -1234567 };
1.90 + * const int32_t a_len = sizeof(a) / sizeof(a[0]);
1.91 + * myString.remove();
1.92 + * for (int32_t i = 0; i < a_len; i++) {
1.93 + * nf->format(a[i], myString);
1.94 + * myString += " ; ";
1.95 + * }
1.96 + * cout << " Example 2: " << myString << endl;
1.97 + * \endcode
1.98 + * </pre>
1.99 + * To format a number for a different Locale, specify it in the
1.100 + * call to createInstance().
1.101 + * <pre>
1.102 + * \code
1.103 + * nf = NumberFormat::createInstance( Locale::FRENCH, success );
1.104 + * \endcode
1.105 + * </pre>
1.106 + * You can use a NumberFormat to parse also.
1.107 + * <pre>
1.108 + * \code
1.109 + * UErrorCode success;
1.110 + * Formattable result(-999); // initialized with error code
1.111 + * nf->parse(myString, result, success);
1.112 + * \endcode
1.113 + * </pre>
1.114 + * Use createInstance to get the normal number format for that country.
1.115 + * There are other static factory methods available. Use getCurrency
1.116 + * to get the currency number format for that country. Use getPercent
1.117 + * to get a format for displaying percentages. With this format, a
1.118 + * fraction from 0.53 is displayed as 53%.
1.119 + * <P>
1.120 + * Starting from ICU 4.2, you can use createInstance() by passing in a 'style'
1.121 + * as parameter to get the correct instance.
1.122 + * For example,
1.123 + * use createInstance(...kNumberStyle...) to get the normal number format,
1.124 + * createInstance(...kPercentStyle...) to get a format for displaying
1.125 + * percentage,
1.126 + * createInstance(...kScientificStyle...) to get a format for displaying
1.127 + * scientific number,
1.128 + * createInstance(...kCurrencyStyle...) to get the currency number format,
1.129 + * in which the currency is represented by its symbol, for example, "$3.00".
1.130 + * createInstance(...kIsoCurrencyStyle...) to get the currency number format,
1.131 + * in which the currency is represented by its ISO code, for example "USD3.00".
1.132 + * createInstance(...kPluralCurrencyStyle...) to get the currency number format,
1.133 + * in which the currency is represented by its full name in plural format,
1.134 + * for example, "3.00 US dollars" or "1.00 US dollar".
1.135 + * <P>
1.136 + * You can also control the display of numbers with such methods as
1.137 + * getMinimumFractionDigits. If you want even more control over the
1.138 + * format or parsing, or want to give your users more control, you can
1.139 + * try casting the NumberFormat you get from the factory methods to a
1.140 + * DecimalNumberFormat. This will work for the vast majority of
1.141 + * countries; just remember to put it in a try block in case you
1.142 + * encounter an unusual one.
1.143 + * <P>
1.144 + * You can also use forms of the parse and format methods with
1.145 + * ParsePosition and FieldPosition to allow you to:
1.146 + * <ul type=round>
1.147 + * <li>(a) progressively parse through pieces of a string.
1.148 + * <li>(b) align the decimal point and other areas.
1.149 + * </ul>
1.150 + * For example, you can align numbers in two ways.
1.151 + * <P>
1.152 + * If you are using a monospaced font with spacing for alignment, you
1.153 + * can pass the FieldPosition in your format call, with field =
1.154 + * INTEGER_FIELD. On output, getEndIndex will be set to the offset
1.155 + * between the last character of the integer and the decimal. Add
1.156 + * (desiredSpaceCount - getEndIndex) spaces at the front of the
1.157 + * string.
1.158 + * <P>
1.159 + * If you are using proportional fonts, instead of padding with
1.160 + * spaces, measure the width of the string in pixels from the start to
1.161 + * getEndIndex. Then move the pen by (desiredPixelWidth -
1.162 + * widthToAlignmentPoint) before drawing the text. It also works
1.163 + * where there is no decimal, but possibly additional characters at
1.164 + * the end, e.g. with parentheses in negative numbers: "(12)" for -12.
1.165 + * <p>
1.166 + * <em>User subclasses are not supported.</em> While clients may write
1.167 + * subclasses, such code will not necessarily work and will not be
1.168 + * guaranteed to work stably from release to release.
1.169 + *
1.170 + * @stable ICU 2.0
1.171 + */
1.172 +class U_I18N_API NumberFormat : public Format {
1.173 +public:
1.174 + /**
1.175 + * Alignment Field constants used to construct a FieldPosition object.
1.176 + * Signifies that the position of the integer part or fraction part of
1.177 + * a formatted number should be returned.
1.178 + *
1.179 + * Note: as of ICU 4.4, the values in this enum have been extended to
1.180 + * support identification of all number format fields, not just those
1.181 + * pertaining to alignment.
1.182 + *
1.183 + * These constants are provided for backwards compatibility only.
1.184 + * Please use the C style constants defined in the header file unum.h.
1.185 + *
1.186 + * @see FieldPosition
1.187 + * @stable ICU 2.0
1.188 + */
1.189 + enum EAlignmentFields {
1.190 + /** @stable ICU 2.0 */
1.191 + kIntegerField = UNUM_INTEGER_FIELD,
1.192 + /** @stable ICU 2.0 */
1.193 + kFractionField = UNUM_FRACTION_FIELD,
1.194 + /** @stable ICU 2.0 */
1.195 + kDecimalSeparatorField = UNUM_DECIMAL_SEPARATOR_FIELD,
1.196 + /** @stable ICU 2.0 */
1.197 + kExponentSymbolField = UNUM_EXPONENT_SYMBOL_FIELD,
1.198 + /** @stable ICU 2.0 */
1.199 + kExponentSignField = UNUM_EXPONENT_SIGN_FIELD,
1.200 + /** @stable ICU 2.0 */
1.201 + kExponentField = UNUM_EXPONENT_FIELD,
1.202 + /** @stable ICU 2.0 */
1.203 + kGroupingSeparatorField = UNUM_GROUPING_SEPARATOR_FIELD,
1.204 + /** @stable ICU 2.0 */
1.205 + kCurrencyField = UNUM_CURRENCY_FIELD,
1.206 + /** @stable ICU 2.0 */
1.207 + kPercentField = UNUM_PERCENT_FIELD,
1.208 + /** @stable ICU 2.0 */
1.209 + kPermillField = UNUM_PERMILL_FIELD,
1.210 + /** @stable ICU 2.0 */
1.211 + kSignField = UNUM_SIGN_FIELD,
1.212 +
1.213 + /**
1.214 + * These constants are provided for backwards compatibility only.
1.215 + * Please use the constants defined in the header file unum.h.
1.216 + */
1.217 + /** @stable ICU 2.0 */
1.218 + INTEGER_FIELD = UNUM_INTEGER_FIELD,
1.219 + /** @stable ICU 2.0 */
1.220 + FRACTION_FIELD = UNUM_FRACTION_FIELD
1.221 + };
1.222 +
1.223 + /**
1.224 + * Destructor.
1.225 + * @stable ICU 2.0
1.226 + */
1.227 + virtual ~NumberFormat();
1.228 +
1.229 + /**
1.230 + * Return true if the given Format objects are semantically equal.
1.231 + * Objects of different subclasses are considered unequal.
1.232 + * @return true if the given Format objects are semantically equal.
1.233 + * @stable ICU 2.0
1.234 + */
1.235 + virtual UBool operator==(const Format& other) const;
1.236 +
1.237 +
1.238 + using Format::format;
1.239 +
1.240 + /**
1.241 + * Format an object to produce a string. This method handles
1.242 + * Formattable objects with numeric types. If the Formattable
1.243 + * object type is not a numeric type, then it returns a failing
1.244 + * UErrorCode.
1.245 + *
1.246 + * @param obj The object to format.
1.247 + * @param appendTo Output parameter to receive result.
1.248 + * Result is appended to existing contents.
1.249 + * @param pos On input: an alignment field, if desired.
1.250 + * On output: the offsets of the alignment field.
1.251 + * @param status Output param filled with success/failure status.
1.252 + * @return Reference to 'appendTo' parameter.
1.253 + * @stable ICU 2.0
1.254 + */
1.255 + virtual UnicodeString& format(const Formattable& obj,
1.256 + UnicodeString& appendTo,
1.257 + FieldPosition& pos,
1.258 + UErrorCode& status) const;
1.259 +
1.260 + /**
1.261 + * Format an object to produce a string. This method handles
1.262 + * Formattable objects with numeric types. If the Formattable
1.263 + * object type is not a numeric type, then it returns a failing
1.264 + * UErrorCode.
1.265 + *
1.266 + * @param obj The object to format.
1.267 + * @param appendTo Output parameter to receive result.
1.268 + * Result is appended to existing contents.
1.269 + * @param posIter On return, can be used to iterate over positions
1.270 + * of fields generated by this format call. Can be
1.271 + * NULL.
1.272 + * @param status Output param filled with success/failure status.
1.273 + * @return Reference to 'appendTo' parameter.
1.274 + * @stable 4.4
1.275 + */
1.276 + virtual UnicodeString& format(const Formattable& obj,
1.277 + UnicodeString& appendTo,
1.278 + FieldPositionIterator* posIter,
1.279 + UErrorCode& status) const;
1.280 +
1.281 + /**
1.282 + * Parse a string to produce an object. This methods handles
1.283 + * parsing of numeric strings into Formattable objects with numeric
1.284 + * types.
1.285 + * <P>
1.286 + * Before calling, set parse_pos.index to the offset you want to
1.287 + * start parsing at in the source. After calling, parse_pos.index
1.288 + * indicates the position after the successfully parsed text. If
1.289 + * an error occurs, parse_pos.index is unchanged.
1.290 + * <P>
1.291 + * When parsing, leading whitespace is discarded (with successful
1.292 + * parse), while trailing whitespace is left as is.
1.293 + * <P>
1.294 + * See Format::parseObject() for more.
1.295 + *
1.296 + * @param source The string to be parsed into an object.
1.297 + * @param result Formattable to be set to the parse result.
1.298 + * If parse fails, return contents are undefined.
1.299 + * @param parse_pos The position to start parsing at. Upon return
1.300 + * this param is set to the position after the
1.301 + * last character successfully parsed. If the
1.302 + * source is not parsed successfully, this param
1.303 + * will remain unchanged.
1.304 + * @return A newly created Formattable* object, or NULL
1.305 + * on failure. The caller owns this and should
1.306 + * delete it when done.
1.307 + * @stable ICU 2.0
1.308 + */
1.309 + virtual void parseObject(const UnicodeString& source,
1.310 + Formattable& result,
1.311 + ParsePosition& parse_pos) const;
1.312 +
1.313 + /**
1.314 + * Format a double number. These methods call the NumberFormat
1.315 + * pure virtual format() methods with the default FieldPosition.
1.316 + *
1.317 + * @param number The value to be formatted.
1.318 + * @param appendTo Output parameter to receive result.
1.319 + * Result is appended to existing contents.
1.320 + * @return Reference to 'appendTo' parameter.
1.321 + * @stable ICU 2.0
1.322 + */
1.323 + UnicodeString& format( double number,
1.324 + UnicodeString& appendTo) const;
1.325 +
1.326 + /**
1.327 + * Format a long number. These methods call the NumberFormat
1.328 + * pure virtual format() methods with the default FieldPosition.
1.329 + *
1.330 + * @param number The value to be formatted.
1.331 + * @param appendTo Output parameter to receive result.
1.332 + * Result is appended to existing contents.
1.333 + * @return Reference to 'appendTo' parameter.
1.334 + * @stable ICU 2.0
1.335 + */
1.336 + UnicodeString& format( int32_t number,
1.337 + UnicodeString& appendTo) const;
1.338 +
1.339 + /**
1.340 + * Format an int64 number. These methods call the NumberFormat
1.341 + * pure virtual format() methods with the default FieldPosition.
1.342 + *
1.343 + * @param number The value to be formatted.
1.344 + * @param appendTo Output parameter to receive result.
1.345 + * Result is appended to existing contents.
1.346 + * @return Reference to 'appendTo' parameter.
1.347 + * @stable ICU 2.8
1.348 + */
1.349 + UnicodeString& format( int64_t number,
1.350 + UnicodeString& appendTo) const;
1.351 +
1.352 + /**
1.353 + * Format a double number. Concrete subclasses must implement
1.354 + * these pure virtual methods.
1.355 + *
1.356 + * @param number The value to be formatted.
1.357 + * @param appendTo Output parameter to receive result.
1.358 + * Result is appended to existing contents.
1.359 + * @param pos On input: an alignment field, if desired.
1.360 + * On output: the offsets of the alignment field.
1.361 + * @return Reference to 'appendTo' parameter.
1.362 + * @stable ICU 2.0
1.363 + */
1.364 + virtual UnicodeString& format(double number,
1.365 + UnicodeString& appendTo,
1.366 + FieldPosition& pos) const = 0;
1.367 + /**
1.368 + * Format a double number. By default, the parent function simply
1.369 + * calls the base class and does not return an error status.
1.370 + * Therefore, the status may be ignored in some subclasses.
1.371 + *
1.372 + * @param number The value to be formatted.
1.373 + * @param appendTo Output parameter to receive result.
1.374 + * Result is appended to existing contents.
1.375 + * @param pos On input: an alignment field, if desired.
1.376 + * On output: the offsets of the alignment field.
1.377 + * @param status error status
1.378 + * @return Reference to 'appendTo' parameter.
1.379 + * @internal
1.380 + */
1.381 + virtual UnicodeString& format(double number,
1.382 + UnicodeString& appendTo,
1.383 + FieldPosition& pos,
1.384 + UErrorCode &status) const;
1.385 + /**
1.386 + * Format a double number. Subclasses must implement
1.387 + * this method.
1.388 + *
1.389 + * @param number The value to be formatted.
1.390 + * @param appendTo Output parameter to receive result.
1.391 + * Result is appended to existing contents.
1.392 + * @param posIter On return, can be used to iterate over positions
1.393 + * of fields generated by this format call.
1.394 + * Can be NULL.
1.395 + * @param status Output param filled with success/failure status.
1.396 + * @return Reference to 'appendTo' parameter.
1.397 + * @stable 4.4
1.398 + */
1.399 + virtual UnicodeString& format(double number,
1.400 + UnicodeString& appendTo,
1.401 + FieldPositionIterator* posIter,
1.402 + UErrorCode& status) const;
1.403 + /**
1.404 + * Format a long number. Concrete subclasses must implement
1.405 + * these pure virtual methods.
1.406 + *
1.407 + * @param number The value to be formatted.
1.408 + * @param appendTo Output parameter to receive result.
1.409 + * Result is appended to existing contents.
1.410 + * @param pos On input: an alignment field, if desired.
1.411 + * On output: the offsets of the alignment field.
1.412 + * @return Reference to 'appendTo' parameter.
1.413 + * @stable ICU 2.0
1.414 + */
1.415 + virtual UnicodeString& format(int32_t number,
1.416 + UnicodeString& appendTo,
1.417 + FieldPosition& pos) const = 0;
1.418 +
1.419 + /**
1.420 + * Format a long number. Concrete subclasses may override
1.421 + * this function to provide status return.
1.422 + *
1.423 + * @param number The value to be formatted.
1.424 + * @param appendTo Output parameter to receive result.
1.425 + * Result is appended to existing contents.
1.426 + * @param pos On input: an alignment field, if desired.
1.427 + * On output: the offsets of the alignment field.
1.428 + * @param status the output status.
1.429 + * @return Reference to 'appendTo' parameter.
1.430 + * @internal
1.431 + */
1.432 + virtual UnicodeString& format(int32_t number,
1.433 + UnicodeString& appendTo,
1.434 + FieldPosition& pos,
1.435 + UErrorCode &status) const;
1.436 +
1.437 + /**
1.438 + * Format an int32 number. Subclasses must implement
1.439 + * this method.
1.440 + *
1.441 + * @param number The value to be formatted.
1.442 + * @param appendTo Output parameter to receive result.
1.443 + * Result is appended to existing contents.
1.444 + * @param posIter On return, can be used to iterate over positions
1.445 + * of fields generated by this format call.
1.446 + * Can be NULL.
1.447 + * @param status Output param filled with success/failure status.
1.448 + * @return Reference to 'appendTo' parameter.
1.449 + * @stable 4.4
1.450 + */
1.451 + virtual UnicodeString& format(int32_t number,
1.452 + UnicodeString& appendTo,
1.453 + FieldPositionIterator* posIter,
1.454 + UErrorCode& status) const;
1.455 + /**
1.456 + * Format an int64 number. (Not abstract to retain compatibility
1.457 + * with earlier releases, however subclasses should override this
1.458 + * method as it just delegates to format(int32_t number...);
1.459 + *
1.460 + * @param number The value to be formatted.
1.461 + * @param appendTo Output parameter to receive result.
1.462 + * Result is appended to existing contents.
1.463 + * @param pos On input: an alignment field, if desired.
1.464 + * On output: the offsets of the alignment field.
1.465 + * @return Reference to 'appendTo' parameter.
1.466 + * @stable ICU 2.8
1.467 + */
1.468 + virtual UnicodeString& format(int64_t number,
1.469 + UnicodeString& appendTo,
1.470 + FieldPosition& pos) const;
1.471 +
1.472 + /**
1.473 + * Format an int64 number. (Not abstract to retain compatibility
1.474 + * with earlier releases, however subclasses should override this
1.475 + * method as it just delegates to format(int32_t number...);
1.476 + *
1.477 + * @param number The value to be formatted.
1.478 + * @param appendTo Output parameter to receive result.
1.479 + * Result is appended to existing contents.
1.480 + * @param pos On input: an alignment field, if desired.
1.481 + * On output: the offsets of the alignment field.
1.482 + * @return Reference to 'appendTo' parameter.
1.483 + * @internal
1.484 + */
1.485 + virtual UnicodeString& format(int64_t number,
1.486 + UnicodeString& appendTo,
1.487 + FieldPosition& pos,
1.488 + UErrorCode& status) const;
1.489 + /**
1.490 + * Format an int64 number. Subclasses must implement
1.491 + * this method.
1.492 + *
1.493 + * @param number The value to be formatted.
1.494 + * @param appendTo Output parameter to receive result.
1.495 + * Result is appended to existing contents.
1.496 + * @param posIter On return, can be used to iterate over positions
1.497 + * of fields generated by this format call.
1.498 + * Can be NULL.
1.499 + * @param status Output param filled with success/failure status.
1.500 + * @return Reference to 'appendTo' parameter.
1.501 + * @stable 4.4
1.502 + */
1.503 + virtual UnicodeString& format(int64_t number,
1.504 + UnicodeString& appendTo,
1.505 + FieldPositionIterator* posIter,
1.506 + UErrorCode& status) const;
1.507 +
1.508 + /**
1.509 + * Format a decimal number. Subclasses must implement
1.510 + * this method. The syntax of the unformatted number is a "numeric string"
1.511 + * as defined in the Decimal Arithmetic Specification, available at
1.512 + * http://speleotrove.com/decimal
1.513 + *
1.514 + * @param number The unformatted number, as a string, to be formatted.
1.515 + * @param appendTo Output parameter to receive result.
1.516 + * Result is appended to existing contents.
1.517 + * @param posIter On return, can be used to iterate over positions
1.518 + * of fields generated by this format call.
1.519 + * Can be NULL.
1.520 + * @param status Output param filled with success/failure status.
1.521 + * @return Reference to 'appendTo' parameter.
1.522 + * @stable 4.4
1.523 + */
1.524 + virtual UnicodeString& format(const StringPiece &number,
1.525 + UnicodeString& appendTo,
1.526 + FieldPositionIterator* posIter,
1.527 + UErrorCode& status) const;
1.528 +public:
1.529 + /**
1.530 + * Format a decimal number.
1.531 + * The number is a DigitList wrapper onto a floating point decimal number.
1.532 + * The default implementation in NumberFormat converts the decimal number
1.533 + * to a double and formats that. Subclasses of NumberFormat that want
1.534 + * to specifically handle big decimal numbers must override this method.
1.535 + * class DecimalFormat does so.
1.536 + *
1.537 + * @param number The number, a DigitList format Decimal Floating Point.
1.538 + * @param appendTo Output parameter to receive result.
1.539 + * Result is appended to existing contents.
1.540 + * @param posIter On return, can be used to iterate over positions
1.541 + * of fields generated by this format call.
1.542 + * @param status Output param filled with success/failure status.
1.543 + * @return Reference to 'appendTo' parameter.
1.544 + * @internal
1.545 + */
1.546 + virtual UnicodeString& format(const DigitList &number,
1.547 + UnicodeString& appendTo,
1.548 + FieldPositionIterator* posIter,
1.549 + UErrorCode& status) const;
1.550 +
1.551 + /**
1.552 + * Format a decimal number.
1.553 + * The number is a DigitList wrapper onto a floating point decimal number.
1.554 + * The default implementation in NumberFormat converts the decimal number
1.555 + * to a double and formats that. Subclasses of NumberFormat that want
1.556 + * to specifically handle big decimal numbers must override this method.
1.557 + * class DecimalFormat does so.
1.558 + *
1.559 + * @param number The number, a DigitList format Decimal Floating Point.
1.560 + * @param appendTo Output parameter to receive result.
1.561 + * Result is appended to existing contents.
1.562 + * @param pos On input: an alignment field, if desired.
1.563 + * On output: the offsets of the alignment field.
1.564 + * @param status Output param filled with success/failure status.
1.565 + * @return Reference to 'appendTo' parameter.
1.566 + * @internal
1.567 + */
1.568 + virtual UnicodeString& format(const DigitList &number,
1.569 + UnicodeString& appendTo,
1.570 + FieldPosition& pos,
1.571 + UErrorCode& status) const;
1.572 +
1.573 +public:
1.574 +
1.575 + /**
1.576 + * Return a long if possible (e.g. within range LONG_MAX,
1.577 + * LONG_MAX], and with no decimals), otherwise a double. If
1.578 + * IntegerOnly is set, will stop at a decimal point (or equivalent;
1.579 + * e.g. for rational numbers "1 2/3", will stop after the 1).
1.580 + * <P>
1.581 + * If no object can be parsed, index is unchanged, and NULL is
1.582 + * returned.
1.583 + * <P>
1.584 + * This is a pure virtual which concrete subclasses must implement.
1.585 + *
1.586 + * @param text The text to be parsed.
1.587 + * @param result Formattable to be set to the parse result.
1.588 + * If parse fails, return contents are undefined.
1.589 + * @param parsePosition The position to start parsing at on input.
1.590 + * On output, moved to after the last successfully
1.591 + * parse character. On parse failure, does not change.
1.592 + * @stable ICU 2.0
1.593 + */
1.594 + virtual void parse(const UnicodeString& text,
1.595 + Formattable& result,
1.596 + ParsePosition& parsePosition) const = 0;
1.597 +
1.598 + /**
1.599 + * Parse a string as a numeric value, and return a Formattable
1.600 + * numeric object. This method parses integers only if IntegerOnly
1.601 + * is set.
1.602 + *
1.603 + * @param text The text to be parsed.
1.604 + * @param result Formattable to be set to the parse result.
1.605 + * If parse fails, return contents are undefined.
1.606 + * @param status Output parameter set to a failure error code
1.607 + * when a failure occurs.
1.608 + * @see NumberFormat::isParseIntegerOnly
1.609 + * @stable ICU 2.0
1.610 + */
1.611 + virtual void parse(const UnicodeString& text,
1.612 + Formattable& result,
1.613 + UErrorCode& status) const;
1.614 +
1.615 + /**
1.616 + * Parses text from the given string as a currency amount. Unlike
1.617 + * the parse() method, this method will attempt to parse a generic
1.618 + * currency name, searching for a match of this object's locale's
1.619 + * currency display names, or for a 3-letter ISO currency code.
1.620 + * This method will fail if this format is not a currency format,
1.621 + * that is, if it does not contain the currency pattern symbol
1.622 + * (U+00A4) in its prefix or suffix.
1.623 + *
1.624 + * @param text the string to parse
1.625 + * @param pos input-output position; on input, the position within text
1.626 + * to match; must have 0 <= pos.getIndex() < text.length();
1.627 + * on output, the position after the last matched character.
1.628 + * If the parse fails, the position in unchanged upon output.
1.629 + * @return if parse succeeds, a pointer to a newly-created CurrencyAmount
1.630 + * object (owned by the caller) containing information about
1.631 + * the parsed currency; if parse fails, this is NULL.
1.632 + * @stable ICU 49
1.633 + */
1.634 + virtual CurrencyAmount* parseCurrency(const UnicodeString& text,
1.635 + ParsePosition& pos) const;
1.636 +
1.637 + /**
1.638 + * Return true if this format will parse numbers as integers
1.639 + * only. For example in the English locale, with ParseIntegerOnly
1.640 + * true, the string "1234." would be parsed as the integer value
1.641 + * 1234 and parsing would stop at the "." character. Of course,
1.642 + * the exact format accepted by the parse operation is locale
1.643 + * dependant and determined by sub-classes of NumberFormat.
1.644 + * @return true if this format will parse numbers as integers
1.645 + * only.
1.646 + * @stable ICU 2.0
1.647 + */
1.648 + UBool isParseIntegerOnly(void) const;
1.649 +
1.650 + /**
1.651 + * Sets whether or not numbers should be parsed as integers only.
1.652 + * @param value set True, this format will parse numbers as integers
1.653 + * only.
1.654 + * @see isParseIntegerOnly
1.655 + * @stable ICU 2.0
1.656 + */
1.657 + virtual void setParseIntegerOnly(UBool value);
1.658 +
1.659 + /**
1.660 + * Sets whether lenient parsing should be enabled (it is off by default).
1.661 + *
1.662 + * @param enable <code>TRUE</code> if lenient parsing should be used,
1.663 + * <code>FALSE</code> otherwise.
1.664 + * @stable ICU 4.8
1.665 + */
1.666 + virtual void setLenient(UBool enable);
1.667 +
1.668 + /**
1.669 + * Returns whether lenient parsing is enabled (it is off by default).
1.670 + *
1.671 + * @return <code>TRUE</code> if lenient parsing is enabled,
1.672 + * <code>FALSE</code> otherwise.
1.673 + * @see #setLenient
1.674 + * @stable ICU 4.8
1.675 + */
1.676 + virtual UBool isLenient(void) const;
1.677 +
1.678 + /**
1.679 + * Returns the default number format for the current default
1.680 + * locale. The default format is one of the styles provided by
1.681 + * the other factory methods: getNumberInstance,
1.682 + * getCurrencyInstance or getPercentInstance. Exactly which one
1.683 + * is locale dependant.
1.684 + * @stable ICU 2.0
1.685 + */
1.686 + static NumberFormat* U_EXPORT2 createInstance(UErrorCode&);
1.687 +
1.688 + /**
1.689 + * Returns the default number format for the specified locale.
1.690 + * The default format is one of the styles provided by the other
1.691 + * factory methods: getNumberInstance, getCurrencyInstance or
1.692 + * getPercentInstance. Exactly which one is locale dependant.
1.693 + * @param inLocale the given locale.
1.694 + * @stable ICU 2.0
1.695 + */
1.696 + static NumberFormat* U_EXPORT2 createInstance(const Locale& inLocale,
1.697 + UErrorCode&);
1.698 +
1.699 + /**
1.700 + * Creates the specified decimal format style of the desired locale.
1.701 + * @param desiredLocale the given locale.
1.702 + * @param style the given style.
1.703 + * @param errorCode Output param filled with success/failure status.
1.704 + * @return A new NumberFormat instance.
1.705 + * @stable ICU 4.8
1.706 + */
1.707 + static NumberFormat* U_EXPORT2 createInstance(const Locale& desiredLocale,
1.708 + UNumberFormatStyle style,
1.709 + UErrorCode& errorCode);
1.710 +
1.711 + /**
1.712 + * Returns a currency format for the current default locale.
1.713 + * @stable ICU 2.0
1.714 + */
1.715 + static NumberFormat* U_EXPORT2 createCurrencyInstance(UErrorCode&);
1.716 +
1.717 + /**
1.718 + * Returns a currency format for the specified locale.
1.719 + * @param inLocale the given locale.
1.720 + * @stable ICU 2.0
1.721 + */
1.722 + static NumberFormat* U_EXPORT2 createCurrencyInstance(const Locale& inLocale,
1.723 + UErrorCode&);
1.724 +
1.725 + /**
1.726 + * Returns a percentage format for the current default locale.
1.727 + * @stable ICU 2.0
1.728 + */
1.729 + static NumberFormat* U_EXPORT2 createPercentInstance(UErrorCode&);
1.730 +
1.731 + /**
1.732 + * Returns a percentage format for the specified locale.
1.733 + * @param inLocale the given locale.
1.734 + * @stable ICU 2.0
1.735 + */
1.736 + static NumberFormat* U_EXPORT2 createPercentInstance(const Locale& inLocale,
1.737 + UErrorCode&);
1.738 +
1.739 + /**
1.740 + * Returns a scientific format for the current default locale.
1.741 + * @stable ICU 2.0
1.742 + */
1.743 + static NumberFormat* U_EXPORT2 createScientificInstance(UErrorCode&);
1.744 +
1.745 + /**
1.746 + * Returns a scientific format for the specified locale.
1.747 + * @param inLocale the given locale.
1.748 + * @stable ICU 2.0
1.749 + */
1.750 + static NumberFormat* U_EXPORT2 createScientificInstance(const Locale& inLocale,
1.751 + UErrorCode&);
1.752 +
1.753 + /**
1.754 + * Get the set of Locales for which NumberFormats are installed.
1.755 + * @param count Output param to receive the size of the locales
1.756 + * @stable ICU 2.0
1.757 + */
1.758 + static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
1.759 +
1.760 +#if !UCONFIG_NO_SERVICE
1.761 + /**
1.762 + * Register a new NumberFormatFactory. The factory will be adopted.
1.763 + * @param toAdopt the NumberFormatFactory instance to be adopted
1.764 + * @param status the in/out status code, no special meanings are assigned
1.765 + * @return a registry key that can be used to unregister this factory
1.766 + * @stable ICU 2.6
1.767 + */
1.768 + static URegistryKey U_EXPORT2 registerFactory(NumberFormatFactory* toAdopt, UErrorCode& status);
1.769 +
1.770 + /**
1.771 + * Unregister a previously-registered NumberFormatFactory using the key returned from the
1.772 + * register call. Key becomes invalid after a successful call and should not be used again.
1.773 + * The NumberFormatFactory corresponding to the key will be deleted.
1.774 + * @param key the registry key returned by a previous call to registerFactory
1.775 + * @param status the in/out status code, no special meanings are assigned
1.776 + * @return TRUE if the factory for the key was successfully unregistered
1.777 + * @stable ICU 2.6
1.778 + */
1.779 + static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status);
1.780 +
1.781 + /**
1.782 + * Return a StringEnumeration over the locales available at the time of the call,
1.783 + * including registered locales.
1.784 + * @return a StringEnumeration over the locales available at the time of the call
1.785 + * @stable ICU 2.6
1.786 + */
1.787 + static StringEnumeration* U_EXPORT2 getAvailableLocales(void);
1.788 +#endif /* UCONFIG_NO_SERVICE */
1.789 +
1.790 + /**
1.791 + * Returns true if grouping is used in this format. For example,
1.792 + * in the English locale, with grouping on, the number 1234567
1.793 + * might be formatted as "1,234,567". The grouping separator as
1.794 + * well as the size of each group is locale dependant and is
1.795 + * determined by sub-classes of NumberFormat.
1.796 + * @see setGroupingUsed
1.797 + * @stable ICU 2.0
1.798 + */
1.799 + UBool isGroupingUsed(void) const;
1.800 +
1.801 + /**
1.802 + * Set whether or not grouping will be used in this format.
1.803 + * @param newValue True, grouping will be used in this format.
1.804 + * @see getGroupingUsed
1.805 + * @stable ICU 2.0
1.806 + */
1.807 + virtual void setGroupingUsed(UBool newValue);
1.808 +
1.809 + /**
1.810 + * Returns the maximum number of digits allowed in the integer portion of a
1.811 + * number.
1.812 + * @return the maximum number of digits allowed in the integer portion of a
1.813 + * number.
1.814 + * @see setMaximumIntegerDigits
1.815 + * @stable ICU 2.0
1.816 + */
1.817 + int32_t getMaximumIntegerDigits(void) const;
1.818 +
1.819 + /**
1.820 + * Sets the maximum number of digits allowed in the integer portion of a
1.821 + * number. maximumIntegerDigits must be >= minimumIntegerDigits. If the
1.822 + * new value for maximumIntegerDigits is less than the current value
1.823 + * of minimumIntegerDigits, then minimumIntegerDigits will also be set to
1.824 + * the new value.
1.825 + *
1.826 + * @param newValue the new value for the maximum number of digits
1.827 + * allowed in the integer portion of a number.
1.828 + * @see getMaximumIntegerDigits
1.829 + * @stable ICU 2.0
1.830 + */
1.831 + virtual void setMaximumIntegerDigits(int32_t newValue);
1.832 +
1.833 + /**
1.834 + * Returns the minimum number of digits allowed in the integer portion of a
1.835 + * number.
1.836 + * @return the minimum number of digits allowed in the integer portion of a
1.837 + * number.
1.838 + * @see setMinimumIntegerDigits
1.839 + * @stable ICU 2.0
1.840 + */
1.841 + int32_t getMinimumIntegerDigits(void) const;
1.842 +
1.843 + /**
1.844 + * Sets the minimum number of digits allowed in the integer portion of a
1.845 + * number. minimumIntegerDigits must be <= maximumIntegerDigits. If the
1.846 + * new value for minimumIntegerDigits exceeds the current value
1.847 + * of maximumIntegerDigits, then maximumIntegerDigits will also be set to
1.848 + * the new value.
1.849 + * @param newValue the new value to be set.
1.850 + * @see getMinimumIntegerDigits
1.851 + * @stable ICU 2.0
1.852 + */
1.853 + virtual void setMinimumIntegerDigits(int32_t newValue);
1.854 +
1.855 + /**
1.856 + * Returns the maximum number of digits allowed in the fraction portion of a
1.857 + * number.
1.858 + * @return the maximum number of digits allowed in the fraction portion of a
1.859 + * number.
1.860 + * @see setMaximumFractionDigits
1.861 + * @stable ICU 2.0
1.862 + */
1.863 + int32_t getMaximumFractionDigits(void) const;
1.864 +
1.865 + /**
1.866 + * Sets the maximum number of digits allowed in the fraction portion of a
1.867 + * number. maximumFractionDigits must be >= minimumFractionDigits. If the
1.868 + * new value for maximumFractionDigits is less than the current value
1.869 + * of minimumFractionDigits, then minimumFractionDigits will also be set to
1.870 + * the new value.
1.871 + * @param newValue the new value to be set.
1.872 + * @see getMaximumFractionDigits
1.873 + * @stable ICU 2.0
1.874 + */
1.875 + virtual void setMaximumFractionDigits(int32_t newValue);
1.876 +
1.877 + /**
1.878 + * Returns the minimum number of digits allowed in the fraction portion of a
1.879 + * number.
1.880 + * @return the minimum number of digits allowed in the fraction portion of a
1.881 + * number.
1.882 + * @see setMinimumFractionDigits
1.883 + * @stable ICU 2.0
1.884 + */
1.885 + int32_t getMinimumFractionDigits(void) const;
1.886 +
1.887 + /**
1.888 + * Sets the minimum number of digits allowed in the fraction portion of a
1.889 + * number. minimumFractionDigits must be <= maximumFractionDigits. If the
1.890 + * new value for minimumFractionDigits exceeds the current value
1.891 + * of maximumFractionDigits, then maximumIntegerDigits will also be set to
1.892 + * the new value
1.893 + * @param newValue the new value to be set.
1.894 + * @see getMinimumFractionDigits
1.895 + * @stable ICU 2.0
1.896 + */
1.897 + virtual void setMinimumFractionDigits(int32_t newValue);
1.898 +
1.899 + /**
1.900 + * Sets the currency used to display currency
1.901 + * amounts. This takes effect immediately, if this format is a
1.902 + * currency format. If this format is not a currency format, then
1.903 + * the currency is used if and when this object becomes a
1.904 + * currency format.
1.905 + * @param theCurrency a 3-letter ISO code indicating new currency
1.906 + * to use. It need not be null-terminated. May be the empty
1.907 + * string or NULL to indicate no currency.
1.908 + * @param ec input-output error code
1.909 + * @stable ICU 3.0
1.910 + */
1.911 + virtual void setCurrency(const UChar* theCurrency, UErrorCode& ec);
1.912 +
1.913 + /**
1.914 + * Gets the currency used to display currency
1.915 + * amounts. This may be an empty string for some subclasses.
1.916 + * @return a 3-letter null-terminated ISO code indicating
1.917 + * the currency in use, or a pointer to the empty string.
1.918 + * @stable ICU 2.6
1.919 + */
1.920 + const UChar* getCurrency() const;
1.921 +
1.922 +public:
1.923 +
1.924 + /**
1.925 + * Return the class ID for this class. This is useful for
1.926 + * comparing to a return value from getDynamicClassID(). Note that,
1.927 + * because NumberFormat is an abstract base class, no fully constructed object
1.928 + * will have the class ID returned by NumberFormat::getStaticClassID().
1.929 + * @return The class ID for all objects of this class.
1.930 + * @stable ICU 2.0
1.931 + */
1.932 + static UClassID U_EXPORT2 getStaticClassID(void);
1.933 +
1.934 + /**
1.935 + * Returns a unique class ID POLYMORPHICALLY. Pure virtual override.
1.936 + * This method is to implement a simple version of RTTI, since not all
1.937 + * C++ compilers support genuine RTTI. Polymorphic operator==() and
1.938 + * clone() methods call this method.
1.939 + * <P>
1.940 + * @return The class ID for this object. All objects of a
1.941 + * given class have the same class ID. Objects of
1.942 + * other classes have different class IDs.
1.943 + * @stable ICU 2.0
1.944 + */
1.945 + virtual UClassID getDynamicClassID(void) const = 0;
1.946 +
1.947 +protected:
1.948 +
1.949 + /**
1.950 + * Default constructor for subclass use only.
1.951 + * @stable ICU 2.0
1.952 + */
1.953 + NumberFormat();
1.954 +
1.955 + /**
1.956 + * Copy constructor.
1.957 + * @stable ICU 2.0
1.958 + */
1.959 + NumberFormat(const NumberFormat&);
1.960 +
1.961 + /**
1.962 + * Assignment operator.
1.963 + * @stable ICU 2.0
1.964 + */
1.965 + NumberFormat& operator=(const NumberFormat&);
1.966 +
1.967 + /**
1.968 + * Returns the currency in effect for this formatter. Subclasses
1.969 + * should override this method as needed. Unlike getCurrency(),
1.970 + * this method should never return "".
1.971 + * @result output parameter for null-terminated result, which must
1.972 + * have a capacity of at least 4
1.973 + * @internal
1.974 + */
1.975 + virtual void getEffectiveCurrency(UChar* result, UErrorCode& ec) const;
1.976 +
1.977 +#ifndef U_HIDE_INTERNAL_API
1.978 + /**
1.979 + * Creates the specified number format style of the desired locale.
1.980 + * If mustBeDecimalFormat is TRUE, then the returned pointer is
1.981 + * either a DecimalFormat or it is NULL.
1.982 + * @internal
1.983 + */
1.984 + static NumberFormat* makeInstance(const Locale& desiredLocale,
1.985 + UNumberFormatStyle style,
1.986 + UBool mustBeDecimalFormat,
1.987 + UErrorCode& errorCode);
1.988 +#endif /* U_HIDE_INTERNAL_API */
1.989 +
1.990 +private:
1.991 +
1.992 + static UBool isStyleSupported(UNumberFormatStyle style);
1.993 +
1.994 + /**
1.995 + * Creates the specified decimal format style of the desired locale.
1.996 + * @param desiredLocale the given locale.
1.997 + * @param style the given style.
1.998 + * @param errorCode Output param filled with success/failure status.
1.999 + * @return A new NumberFormat instance.
1.1000 + */
1.1001 + static NumberFormat* makeInstance(const Locale& desiredLocale,
1.1002 + UNumberFormatStyle style,
1.1003 + UErrorCode& errorCode);
1.1004 +
1.1005 + UBool fGroupingUsed;
1.1006 + int32_t fMaxIntegerDigits;
1.1007 + int32_t fMinIntegerDigits;
1.1008 + int32_t fMaxFractionDigits;
1.1009 + int32_t fMinFractionDigits;
1.1010 +
1.1011 + protected:
1.1012 + static const int32_t gDefaultMaxIntegerDigits;
1.1013 + static const int32_t gDefaultMinIntegerDigits;
1.1014 +
1.1015 + private:
1.1016 + UBool fParseIntegerOnly;
1.1017 + UBool fLenient; // TRUE => lenient parse is enabled
1.1018 +
1.1019 + // ISO currency code
1.1020 + UChar fCurrency[4];
1.1021 +
1.1022 + friend class ICUNumberFormatFactory; // access to makeInstance
1.1023 + friend class ICUNumberFormatService;
1.1024 + friend class ::NumberFormatTest; // access to isStyleSupported()
1.1025 +};
1.1026 +
1.1027 +#if !UCONFIG_NO_SERVICE
1.1028 +/**
1.1029 + * A NumberFormatFactory is used to register new number formats. The factory
1.1030 + * should be able to create any of the predefined formats for each locale it
1.1031 + * supports. When registered, the locales it supports extend or override the
1.1032 + * locale already supported by ICU.
1.1033 + *
1.1034 + * @stable ICU 2.6
1.1035 + */
1.1036 +class U_I18N_API NumberFormatFactory : public UObject {
1.1037 +public:
1.1038 +
1.1039 + /**
1.1040 + * Destructor
1.1041 + * @stable ICU 3.0
1.1042 + */
1.1043 + virtual ~NumberFormatFactory();
1.1044 +
1.1045 + /**
1.1046 + * Return true if this factory will be visible. Default is true.
1.1047 + * If not visible, the locales supported by this factory will not
1.1048 + * be listed by getAvailableLocales.
1.1049 + * @stable ICU 2.6
1.1050 + */
1.1051 + virtual UBool visible(void) const = 0;
1.1052 +
1.1053 + /**
1.1054 + * Return the locale names directly supported by this factory. The number of names
1.1055 + * is returned in count;
1.1056 + * @stable ICU 2.6
1.1057 + */
1.1058 + virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const = 0;
1.1059 +
1.1060 + /**
1.1061 + * Return a number format of the appropriate type. If the locale
1.1062 + * is not supported, return null. If the locale is supported, but
1.1063 + * the type is not provided by this service, return null. Otherwise
1.1064 + * return an appropriate instance of NumberFormat.
1.1065 + * @stable ICU 2.6
1.1066 + */
1.1067 + virtual NumberFormat* createFormat(const Locale& loc, UNumberFormatStyle formatType) = 0;
1.1068 +};
1.1069 +
1.1070 +/**
1.1071 + * A NumberFormatFactory that supports a single locale. It can be visible or invisible.
1.1072 + * @stable ICU 2.6
1.1073 + */
1.1074 +class U_I18N_API SimpleNumberFormatFactory : public NumberFormatFactory {
1.1075 +protected:
1.1076 + /**
1.1077 + * True if the locale supported by this factory is visible.
1.1078 + * @stable ICU 2.6
1.1079 + */
1.1080 + const UBool _visible;
1.1081 +
1.1082 + /**
1.1083 + * The locale supported by this factory, as a UnicodeString.
1.1084 + * @stable ICU 2.6
1.1085 + */
1.1086 + UnicodeString _id;
1.1087 +
1.1088 +public:
1.1089 + /**
1.1090 + * @stable ICU 2.6
1.1091 + */
1.1092 + SimpleNumberFormatFactory(const Locale& locale, UBool visible = TRUE);
1.1093 +
1.1094 + /**
1.1095 + * @stable ICU 3.0
1.1096 + */
1.1097 + virtual ~SimpleNumberFormatFactory();
1.1098 +
1.1099 + /**
1.1100 + * @stable ICU 2.6
1.1101 + */
1.1102 + virtual UBool visible(void) const;
1.1103 +
1.1104 + /**
1.1105 + * @stable ICU 2.6
1.1106 + */
1.1107 + virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const;
1.1108 +};
1.1109 +#endif /* #if !UCONFIG_NO_SERVICE */
1.1110 +
1.1111 +// -------------------------------------
1.1112 +
1.1113 +inline UBool
1.1114 +NumberFormat::isParseIntegerOnly() const
1.1115 +{
1.1116 + return fParseIntegerOnly;
1.1117 +}
1.1118 +
1.1119 +inline UBool
1.1120 +NumberFormat::isLenient() const
1.1121 +{
1.1122 + return fLenient;
1.1123 +}
1.1124 +
1.1125 +U_NAMESPACE_END
1.1126 +
1.1127 +#endif /* #if !UCONFIG_NO_FORMATTING */
1.1128 +
1.1129 +#endif // _NUMFMT
1.1130 +//eof
