michael@0: * NumberFormat helps you to format and parse numbers for any locale. michael@0: * Your code can be completely independent of the locale conventions michael@0: * for decimal points, thousands-separators, or even the particular michael@0: * decimal digits used, or whether the number format is even decimal. michael@0: *
michael@0: * To format a number for the current Locale, use one of the static michael@0: * factory methods: michael@0: *
michael@0: * \code michael@0: * double myNumber = 7.0; michael@0: * UnicodeString myString; michael@0: * UErrorCode success = U_ZERO_ERROR; michael@0: * NumberFormat* nf = NumberFormat::createInstance(success) michael@0: * nf->format(myNumber, myString); michael@0: * cout << " Example 1: " << myString << endl; michael@0: * \endcode michael@0: *michael@0: * Note that there are additional factory methods within subclasses of michael@0: * NumberFormat. michael@0: *
michael@0: * If you are formatting multiple numbers, it is more efficient to get michael@0: * the format and use it multiple times so that the system doesn't michael@0: * have to fetch the information about the local language and country michael@0: * conventions multiple times. michael@0: *
michael@0: * \code
michael@0: * UnicodeString myString;
michael@0: * UErrorCode success = U_ZERO_ERROR;
michael@0: * nf = NumberFormat::createInstance( success );
michael@0: * int32_t a[] = { 123, 3333, -1234567 };
michael@0: * const int32_t a_len = sizeof(a) / sizeof(a[0]);
michael@0: * myString.remove();
michael@0: * for (int32_t i = 0; i < a_len; i++) {
michael@0: * nf->format(a[i], myString);
michael@0: * myString += " ; ";
michael@0: * }
michael@0: * cout << " Example 2: " << myString << endl;
michael@0: * \endcode
michael@0: *
michael@0: * To format a number for a different Locale, specify it in the
michael@0: * call to createInstance().
michael@0: * michael@0: * \code michael@0: * nf = NumberFormat::createInstance( Locale::FRENCH, success ); michael@0: * \endcode michael@0: *michael@0: * You can use a NumberFormat to parse also. michael@0: *
michael@0: * \code michael@0: * UErrorCode success; michael@0: * Formattable result(-999); // initialized with error code michael@0: * nf->parse(myString, result, success); michael@0: * \endcode michael@0: *michael@0: * Use createInstance to get the normal number format for that country. michael@0: * There are other static factory methods available. Use getCurrency michael@0: * to get the currency number format for that country. Use getPercent michael@0: * to get a format for displaying percentages. With this format, a michael@0: * fraction from 0.53 is displayed as 53%. michael@0: *
michael@0: * Starting from ICU 4.2, you can use createInstance() by passing in a 'style' michael@0: * as parameter to get the correct instance. michael@0: * For example, michael@0: * use createInstance(...kNumberStyle...) to get the normal number format, michael@0: * createInstance(...kPercentStyle...) to get a format for displaying michael@0: * percentage, michael@0: * createInstance(...kScientificStyle...) to get a format for displaying michael@0: * scientific number, michael@0: * createInstance(...kCurrencyStyle...) to get the currency number format, michael@0: * in which the currency is represented by its symbol, for example, "$3.00". michael@0: * createInstance(...kIsoCurrencyStyle...) to get the currency number format, michael@0: * in which the currency is represented by its ISO code, for example "USD3.00". michael@0: * createInstance(...kPluralCurrencyStyle...) to get the currency number format, michael@0: * in which the currency is represented by its full name in plural format, michael@0: * for example, "3.00 US dollars" or "1.00 US dollar". michael@0: *
michael@0: * You can also control the display of numbers with such methods as michael@0: * getMinimumFractionDigits. If you want even more control over the michael@0: * format or parsing, or want to give your users more control, you can michael@0: * try casting the NumberFormat you get from the factory methods to a michael@0: * DecimalNumberFormat. This will work for the vast majority of michael@0: * countries; just remember to put it in a try block in case you michael@0: * encounter an unusual one. michael@0: *
michael@0: * You can also use forms of the parse and format methods with michael@0: * ParsePosition and FieldPosition to allow you to: michael@0: *
michael@0: * If you are using a monospaced font with spacing for alignment, you michael@0: * can pass the FieldPosition in your format call, with field = michael@0: * INTEGER_FIELD. On output, getEndIndex will be set to the offset michael@0: * between the last character of the integer and the decimal. Add michael@0: * (desiredSpaceCount - getEndIndex) spaces at the front of the michael@0: * string. michael@0: *
michael@0: * If you are using proportional fonts, instead of padding with michael@0: * spaces, measure the width of the string in pixels from the start to michael@0: * getEndIndex. Then move the pen by (desiredPixelWidth - michael@0: * widthToAlignmentPoint) before drawing the text. It also works michael@0: * where there is no decimal, but possibly additional characters at michael@0: * the end, e.g. with parentheses in negative numbers: "(12)" for -12. michael@0: *
michael@0: * User subclasses are not supported. While clients may write michael@0: * subclasses, such code will not necessarily work and will not be michael@0: * guaranteed to work stably from release to release. michael@0: * michael@0: * @stable ICU 2.0 michael@0: */ michael@0: class U_I18N_API NumberFormat : public Format { michael@0: public: michael@0: /** michael@0: * Alignment Field constants used to construct a FieldPosition object. michael@0: * Signifies that the position of the integer part or fraction part of michael@0: * a formatted number should be returned. michael@0: * michael@0: * Note: as of ICU 4.4, the values in this enum have been extended to michael@0: * support identification of all number format fields, not just those michael@0: * pertaining to alignment. michael@0: * michael@0: * These constants are provided for backwards compatibility only. michael@0: * Please use the C style constants defined in the header file unum.h. michael@0: * michael@0: * @see FieldPosition michael@0: * @stable ICU 2.0 michael@0: */ michael@0: enum EAlignmentFields { michael@0: /** @stable ICU 2.0 */ michael@0: kIntegerField = UNUM_INTEGER_FIELD, michael@0: /** @stable ICU 2.0 */ michael@0: kFractionField = UNUM_FRACTION_FIELD, michael@0: /** @stable ICU 2.0 */ michael@0: kDecimalSeparatorField = UNUM_DECIMAL_SEPARATOR_FIELD, michael@0: /** @stable ICU 2.0 */ michael@0: kExponentSymbolField = UNUM_EXPONENT_SYMBOL_FIELD, michael@0: /** @stable ICU 2.0 */ michael@0: kExponentSignField = UNUM_EXPONENT_SIGN_FIELD, michael@0: /** @stable ICU 2.0 */ michael@0: kExponentField = UNUM_EXPONENT_FIELD, michael@0: /** @stable ICU 2.0 */ michael@0: kGroupingSeparatorField = UNUM_GROUPING_SEPARATOR_FIELD, michael@0: /** @stable ICU 2.0 */ michael@0: kCurrencyField = UNUM_CURRENCY_FIELD, michael@0: /** @stable ICU 2.0 */ michael@0: kPercentField = UNUM_PERCENT_FIELD, michael@0: /** @stable ICU 2.0 */ michael@0: kPermillField = UNUM_PERMILL_FIELD, michael@0: /** @stable ICU 2.0 */ michael@0: kSignField = UNUM_SIGN_FIELD, michael@0: michael@0: /** michael@0: * These constants are provided for backwards compatibility only. michael@0: * Please use the constants defined in the header file unum.h. michael@0: */ michael@0: /** @stable ICU 2.0 */ michael@0: INTEGER_FIELD = UNUM_INTEGER_FIELD, michael@0: /** @stable ICU 2.0 */ michael@0: FRACTION_FIELD = UNUM_FRACTION_FIELD michael@0: }; michael@0: michael@0: /** michael@0: * Destructor. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual ~NumberFormat(); michael@0: michael@0: /** michael@0: * Return true if the given Format objects are semantically equal. michael@0: * Objects of different subclasses are considered unequal. michael@0: * @return true if the given Format objects are semantically equal. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UBool operator==(const Format& other) const; michael@0: michael@0: michael@0: using Format::format; michael@0: michael@0: /** michael@0: * Format an object to produce a string. This method handles michael@0: * Formattable objects with numeric types. If the Formattable michael@0: * object type is not a numeric type, then it returns a failing michael@0: * UErrorCode. michael@0: * michael@0: * @param obj The object to format. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param pos On input: an alignment field, if desired. michael@0: * On output: the offsets of the alignment field. michael@0: * @param status Output param filled with success/failure status. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UnicodeString& format(const Formattable& obj, michael@0: UnicodeString& appendTo, michael@0: FieldPosition& pos, michael@0: UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Format an object to produce a string. This method handles michael@0: * Formattable objects with numeric types. If the Formattable michael@0: * object type is not a numeric type, then it returns a failing michael@0: * UErrorCode. michael@0: * michael@0: * @param obj The object to format. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param posIter On return, can be used to iterate over positions michael@0: * of fields generated by this format call. Can be michael@0: * NULL. michael@0: * @param status Output param filled with success/failure status. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable 4.4 michael@0: */ michael@0: virtual UnicodeString& format(const Formattable& obj, michael@0: UnicodeString& appendTo, michael@0: FieldPositionIterator* posIter, michael@0: UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Parse a string to produce an object. This methods handles michael@0: * parsing of numeric strings into Formattable objects with numeric michael@0: * types. michael@0: *
michael@0: * Before calling, set parse_pos.index to the offset you want to michael@0: * start parsing at in the source. After calling, parse_pos.index michael@0: * indicates the position after the successfully parsed text. If michael@0: * an error occurs, parse_pos.index is unchanged. michael@0: *
michael@0: * When parsing, leading whitespace is discarded (with successful michael@0: * parse), while trailing whitespace is left as is. michael@0: *
michael@0: * See Format::parseObject() for more. michael@0: * michael@0: * @param source The string to be parsed into an object. michael@0: * @param result Formattable to be set to the parse result. michael@0: * If parse fails, return contents are undefined. michael@0: * @param parse_pos The position to start parsing at. Upon return michael@0: * this param is set to the position after the michael@0: * last character successfully parsed. If the michael@0: * source is not parsed successfully, this param michael@0: * will remain unchanged. michael@0: * @return A newly created Formattable* object, or NULL michael@0: * on failure. The caller owns this and should michael@0: * delete it when done. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void parseObject(const UnicodeString& source, michael@0: Formattable& result, michael@0: ParsePosition& parse_pos) const; michael@0: michael@0: /** michael@0: * Format a double number. These methods call the NumberFormat michael@0: * pure virtual format() methods with the default FieldPosition. michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UnicodeString& format( double number, michael@0: UnicodeString& appendTo) const; michael@0: michael@0: /** michael@0: * Format a long number. These methods call the NumberFormat michael@0: * pure virtual format() methods with the default FieldPosition. michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UnicodeString& format( int32_t number, michael@0: UnicodeString& appendTo) const; michael@0: michael@0: /** michael@0: * Format an int64 number. These methods call the NumberFormat michael@0: * pure virtual format() methods with the default FieldPosition. michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable ICU 2.8 michael@0: */ michael@0: UnicodeString& format( int64_t number, michael@0: UnicodeString& appendTo) const; michael@0: michael@0: /** michael@0: * Format a double number. Concrete subclasses must implement michael@0: * these pure virtual methods. michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param pos On input: an alignment field, if desired. michael@0: * On output: the offsets of the alignment field. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UnicodeString& format(double number, michael@0: UnicodeString& appendTo, michael@0: FieldPosition& pos) const = 0; michael@0: /** michael@0: * Format a double number. By default, the parent function simply michael@0: * calls the base class and does not return an error status. michael@0: * Therefore, the status may be ignored in some subclasses. michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param pos On input: an alignment field, if desired. michael@0: * On output: the offsets of the alignment field. michael@0: * @param status error status michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @internal michael@0: */ michael@0: virtual UnicodeString& format(double number, michael@0: UnicodeString& appendTo, michael@0: FieldPosition& pos, michael@0: UErrorCode &status) const; michael@0: /** michael@0: * Format a double number. Subclasses must implement michael@0: * this method. michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param posIter On return, can be used to iterate over positions michael@0: * of fields generated by this format call. michael@0: * Can be NULL. michael@0: * @param status Output param filled with success/failure status. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable 4.4 michael@0: */ michael@0: virtual UnicodeString& format(double number, michael@0: UnicodeString& appendTo, michael@0: FieldPositionIterator* posIter, michael@0: UErrorCode& status) const; michael@0: /** michael@0: * Format a long number. Concrete subclasses must implement michael@0: * these pure virtual methods. michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param pos On input: an alignment field, if desired. michael@0: * On output: the offsets of the alignment field. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UnicodeString& format(int32_t number, michael@0: UnicodeString& appendTo, michael@0: FieldPosition& pos) const = 0; michael@0: michael@0: /** michael@0: * Format a long number. Concrete subclasses may override michael@0: * this function to provide status return. michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param pos On input: an alignment field, if desired. michael@0: * On output: the offsets of the alignment field. michael@0: * @param status the output status. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @internal michael@0: */ michael@0: virtual UnicodeString& format(int32_t number, michael@0: UnicodeString& appendTo, michael@0: FieldPosition& pos, michael@0: UErrorCode &status) const; michael@0: michael@0: /** michael@0: * Format an int32 number. Subclasses must implement michael@0: * this method. michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param posIter On return, can be used to iterate over positions michael@0: * of fields generated by this format call. michael@0: * Can be NULL. michael@0: * @param status Output param filled with success/failure status. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable 4.4 michael@0: */ michael@0: virtual UnicodeString& format(int32_t number, michael@0: UnicodeString& appendTo, michael@0: FieldPositionIterator* posIter, michael@0: UErrorCode& status) const; michael@0: /** michael@0: * Format an int64 number. (Not abstract to retain compatibility michael@0: * with earlier releases, however subclasses should override this michael@0: * method as it just delegates to format(int32_t number...); michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param pos On input: an alignment field, if desired. michael@0: * On output: the offsets of the alignment field. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable ICU 2.8 michael@0: */ michael@0: virtual UnicodeString& format(int64_t number, michael@0: UnicodeString& appendTo, michael@0: FieldPosition& pos) const; michael@0: michael@0: /** michael@0: * Format an int64 number. (Not abstract to retain compatibility michael@0: * with earlier releases, however subclasses should override this michael@0: * method as it just delegates to format(int32_t number...); michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param pos On input: an alignment field, if desired. michael@0: * On output: the offsets of the alignment field. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @internal michael@0: */ michael@0: virtual UnicodeString& format(int64_t number, michael@0: UnicodeString& appendTo, michael@0: FieldPosition& pos, michael@0: UErrorCode& status) const; michael@0: /** michael@0: * Format an int64 number. Subclasses must implement michael@0: * this method. michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param posIter On return, can be used to iterate over positions michael@0: * of fields generated by this format call. michael@0: * Can be NULL. michael@0: * @param status Output param filled with success/failure status. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable 4.4 michael@0: */ michael@0: virtual UnicodeString& format(int64_t number, michael@0: UnicodeString& appendTo, michael@0: FieldPositionIterator* posIter, michael@0: UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Format a decimal number. Subclasses must implement michael@0: * this method. The syntax of the unformatted number is a "numeric string" michael@0: * as defined in the Decimal Arithmetic Specification, available at michael@0: * http://speleotrove.com/decimal michael@0: * michael@0: * @param number The unformatted number, as a string, to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param posIter On return, can be used to iterate over positions michael@0: * of fields generated by this format call. michael@0: * Can be NULL. michael@0: * @param status Output param filled with success/failure status. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable 4.4 michael@0: */ michael@0: virtual UnicodeString& format(const StringPiece &number, michael@0: UnicodeString& appendTo, michael@0: FieldPositionIterator* posIter, michael@0: UErrorCode& status) const; michael@0: public: michael@0: /** michael@0: * Format a decimal number. michael@0: * The number is a DigitList wrapper onto a floating point decimal number. michael@0: * The default implementation in NumberFormat converts the decimal number michael@0: * to a double and formats that. Subclasses of NumberFormat that want michael@0: * to specifically handle big decimal numbers must override this method. michael@0: * class DecimalFormat does so. michael@0: * michael@0: * @param number The number, a DigitList format Decimal Floating Point. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param posIter On return, can be used to iterate over positions michael@0: * of fields generated by this format call. michael@0: * @param status Output param filled with success/failure status. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @internal michael@0: */ michael@0: virtual UnicodeString& format(const DigitList &number, michael@0: UnicodeString& appendTo, michael@0: FieldPositionIterator* posIter, michael@0: UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Format a decimal number. michael@0: * The number is a DigitList wrapper onto a floating point decimal number. michael@0: * The default implementation in NumberFormat converts the decimal number michael@0: * to a double and formats that. Subclasses of NumberFormat that want michael@0: * to specifically handle big decimal numbers must override this method. michael@0: * class DecimalFormat does so. michael@0: * michael@0: * @param number The number, a DigitList format Decimal Floating Point. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param pos On input: an alignment field, if desired. michael@0: * On output: the offsets of the alignment field. michael@0: * @param status Output param filled with success/failure status. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @internal michael@0: */ michael@0: virtual UnicodeString& format(const DigitList &number, michael@0: UnicodeString& appendTo, michael@0: FieldPosition& pos, michael@0: UErrorCode& status) const; michael@0: michael@0: public: michael@0: michael@0: /** michael@0: * Return a long if possible (e.g. within range LONG_MAX, michael@0: * LONG_MAX], and with no decimals), otherwise a double. If michael@0: * IntegerOnly is set, will stop at a decimal point (or equivalent; michael@0: * e.g. for rational numbers "1 2/3", will stop after the 1). michael@0: *
michael@0: * If no object can be parsed, index is unchanged, and NULL is michael@0: * returned. michael@0: *
michael@0: * This is a pure virtual which concrete subclasses must implement.
michael@0: *
michael@0: * @param text The text to be parsed.
michael@0: * @param result Formattable to be set to the parse result.
michael@0: * If parse fails, return contents are undefined.
michael@0: * @param parsePosition The position to start parsing at on input.
michael@0: * On output, moved to after the last successfully
michael@0: * parse character. On parse failure, does not change.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: virtual void parse(const UnicodeString& text,
michael@0: Formattable& result,
michael@0: ParsePosition& parsePosition) const = 0;
michael@0:
michael@0: /**
michael@0: * Parse a string as a numeric value, and return a Formattable
michael@0: * numeric object. This method parses integers only if IntegerOnly
michael@0: * is set.
michael@0: *
michael@0: * @param text The text to be parsed.
michael@0: * @param result Formattable to be set to the parse result.
michael@0: * If parse fails, return contents are undefined.
michael@0: * @param status Output parameter set to a failure error code
michael@0: * when a failure occurs.
michael@0: * @see NumberFormat::isParseIntegerOnly
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: virtual void parse(const UnicodeString& text,
michael@0: Formattable& result,
michael@0: UErrorCode& status) const;
michael@0:
michael@0: /**
michael@0: * Parses text from the given string as a currency amount. Unlike
michael@0: * the parse() method, this method will attempt to parse a generic
michael@0: * currency name, searching for a match of this object's locale's
michael@0: * currency display names, or for a 3-letter ISO currency code.
michael@0: * This method will fail if this format is not a currency format,
michael@0: * that is, if it does not contain the currency pattern symbol
michael@0: * (U+00A4) in its prefix or suffix.
michael@0: *
michael@0: * @param text the string to parse
michael@0: * @param pos input-output position; on input, the position within text
michael@0: * to match; must have 0 <= pos.getIndex() < text.length();
michael@0: * on output, the position after the last matched character.
michael@0: * If the parse fails, the position in unchanged upon output.
michael@0: * @return if parse succeeds, a pointer to a newly-created CurrencyAmount
michael@0: * object (owned by the caller) containing information about
michael@0: * the parsed currency; if parse fails, this is NULL.
michael@0: * @stable ICU 49
michael@0: */
michael@0: virtual CurrencyAmount* parseCurrency(const UnicodeString& text,
michael@0: ParsePosition& pos) const;
michael@0:
michael@0: /**
michael@0: * Return true if this format will parse numbers as integers
michael@0: * only. For example in the English locale, with ParseIntegerOnly
michael@0: * true, the string "1234." would be parsed as the integer value
michael@0: * 1234 and parsing would stop at the "." character. Of course,
michael@0: * the exact format accepted by the parse operation is locale
michael@0: * dependant and determined by sub-classes of NumberFormat.
michael@0: * @return true if this format will parse numbers as integers
michael@0: * only.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: UBool isParseIntegerOnly(void) const;
michael@0:
michael@0: /**
michael@0: * Sets whether or not numbers should be parsed as integers only.
michael@0: * @param value set True, this format will parse numbers as integers
michael@0: * only.
michael@0: * @see isParseIntegerOnly
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: virtual void setParseIntegerOnly(UBool value);
michael@0:
michael@0: /**
michael@0: * Sets whether lenient parsing should be enabled (it is off by default).
michael@0: *
michael@0: * @param enable TRUE if lenient parsing should be used,
michael@0: * FALSE otherwise.
michael@0: * @stable ICU 4.8
michael@0: */
michael@0: virtual void setLenient(UBool enable);
michael@0:
michael@0: /**
michael@0: * Returns whether lenient parsing is enabled (it is off by default).
michael@0: *
michael@0: * @return TRUE if lenient parsing is enabled,
michael@0: * FALSE otherwise.
michael@0: * @see #setLenient
michael@0: * @stable ICU 4.8
michael@0: */
michael@0: virtual UBool isLenient(void) const;
michael@0:
michael@0: /**
michael@0: * Returns the default number format for the current default
michael@0: * locale. The default format is one of the styles provided by
michael@0: * the other factory methods: getNumberInstance,
michael@0: * getCurrencyInstance or getPercentInstance. Exactly which one
michael@0: * is locale dependant.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: static NumberFormat* U_EXPORT2 createInstance(UErrorCode&);
michael@0:
michael@0: /**
michael@0: * Returns the default number format for the specified locale.
michael@0: * The default format is one of the styles provided by the other
michael@0: * factory methods: getNumberInstance, getCurrencyInstance or
michael@0: * getPercentInstance. Exactly which one is locale dependant.
michael@0: * @param inLocale the given locale.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: static NumberFormat* U_EXPORT2 createInstance(const Locale& inLocale,
michael@0: UErrorCode&);
michael@0:
michael@0: /**
michael@0: * Creates the specified decimal format style of the desired locale.
michael@0: * @param desiredLocale the given locale.
michael@0: * @param style the given style.
michael@0: * @param errorCode Output param filled with success/failure status.
michael@0: * @return A new NumberFormat instance.
michael@0: * @stable ICU 4.8
michael@0: */
michael@0: static NumberFormat* U_EXPORT2 createInstance(const Locale& desiredLocale,
michael@0: UNumberFormatStyle style,
michael@0: UErrorCode& errorCode);
michael@0:
michael@0: /**
michael@0: * Returns a currency format for the current default locale.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: static NumberFormat* U_EXPORT2 createCurrencyInstance(UErrorCode&);
michael@0:
michael@0: /**
michael@0: * Returns a currency format for the specified locale.
michael@0: * @param inLocale the given locale.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: static NumberFormat* U_EXPORT2 createCurrencyInstance(const Locale& inLocale,
michael@0: UErrorCode&);
michael@0:
michael@0: /**
michael@0: * Returns a percentage format for the current default locale.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: static NumberFormat* U_EXPORT2 createPercentInstance(UErrorCode&);
michael@0:
michael@0: /**
michael@0: * Returns a percentage format for the specified locale.
michael@0: * @param inLocale the given locale.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: static NumberFormat* U_EXPORT2 createPercentInstance(const Locale& inLocale,
michael@0: UErrorCode&);
michael@0:
michael@0: /**
michael@0: * Returns a scientific format for the current default locale.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: static NumberFormat* U_EXPORT2 createScientificInstance(UErrorCode&);
michael@0:
michael@0: /**
michael@0: * Returns a scientific format for the specified locale.
michael@0: * @param inLocale the given locale.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: static NumberFormat* U_EXPORT2 createScientificInstance(const Locale& inLocale,
michael@0: UErrorCode&);
michael@0:
michael@0: /**
michael@0: * Get the set of Locales for which NumberFormats are installed.
michael@0: * @param count Output param to receive the size of the locales
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
michael@0:
michael@0: #if !UCONFIG_NO_SERVICE
michael@0: /**
michael@0: * Register a new NumberFormatFactory. The factory will be adopted.
michael@0: * @param toAdopt the NumberFormatFactory instance to be adopted
michael@0: * @param status the in/out status code, no special meanings are assigned
michael@0: * @return a registry key that can be used to unregister this factory
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: static URegistryKey U_EXPORT2 registerFactory(NumberFormatFactory* toAdopt, UErrorCode& status);
michael@0:
michael@0: /**
michael@0: * Unregister a previously-registered NumberFormatFactory using the key returned from the
michael@0: * register call. Key becomes invalid after a successful call and should not be used again.
michael@0: * The NumberFormatFactory corresponding to the key will be deleted.
michael@0: * @param key the registry key returned by a previous call to registerFactory
michael@0: * @param status the in/out status code, no special meanings are assigned
michael@0: * @return TRUE if the factory for the key was successfully unregistered
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status);
michael@0:
michael@0: /**
michael@0: * Return a StringEnumeration over the locales available at the time of the call,
michael@0: * including registered locales.
michael@0: * @return a StringEnumeration over the locales available at the time of the call
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: static StringEnumeration* U_EXPORT2 getAvailableLocales(void);
michael@0: #endif /* UCONFIG_NO_SERVICE */
michael@0:
michael@0: /**
michael@0: * Returns true if grouping is used in this format. For example,
michael@0: * in the English locale, with grouping on, the number 1234567
michael@0: * might be formatted as "1,234,567". The grouping separator as
michael@0: * well as the size of each group is locale dependant and is
michael@0: * determined by sub-classes of NumberFormat.
michael@0: * @see setGroupingUsed
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: UBool isGroupingUsed(void) const;
michael@0:
michael@0: /**
michael@0: * Set whether or not grouping will be used in this format.
michael@0: * @param newValue True, grouping will be used in this format.
michael@0: * @see getGroupingUsed
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: virtual void setGroupingUsed(UBool newValue);
michael@0:
michael@0: /**
michael@0: * Returns the maximum number of digits allowed in the integer portion of a
michael@0: * number.
michael@0: * @return the maximum number of digits allowed in the integer portion of a
michael@0: * number.
michael@0: * @see setMaximumIntegerDigits
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: int32_t getMaximumIntegerDigits(void) const;
michael@0:
michael@0: /**
michael@0: * Sets the maximum number of digits allowed in the integer portion of a
michael@0: * number. maximumIntegerDigits must be >= minimumIntegerDigits. If the
michael@0: * new value for maximumIntegerDigits is less than the current value
michael@0: * of minimumIntegerDigits, then minimumIntegerDigits will also be set to
michael@0: * the new value.
michael@0: *
michael@0: * @param newValue the new value for the maximum number of digits
michael@0: * allowed in the integer portion of a number.
michael@0: * @see getMaximumIntegerDigits
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: virtual void setMaximumIntegerDigits(int32_t newValue);
michael@0:
michael@0: /**
michael@0: * Returns the minimum number of digits allowed in the integer portion of a
michael@0: * number.
michael@0: * @return the minimum number of digits allowed in the integer portion of a
michael@0: * number.
michael@0: * @see setMinimumIntegerDigits
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: int32_t getMinimumIntegerDigits(void) const;
michael@0:
michael@0: /**
michael@0: * Sets the minimum number of digits allowed in the integer portion of a
michael@0: * number. minimumIntegerDigits must be <= maximumIntegerDigits. If the
michael@0: * new value for minimumIntegerDigits exceeds the current value
michael@0: * of maximumIntegerDigits, then maximumIntegerDigits will also be set to
michael@0: * the new value.
michael@0: * @param newValue the new value to be set.
michael@0: * @see getMinimumIntegerDigits
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: virtual void setMinimumIntegerDigits(int32_t newValue);
michael@0:
michael@0: /**
michael@0: * Returns the maximum number of digits allowed in the fraction portion of a
michael@0: * number.
michael@0: * @return the maximum number of digits allowed in the fraction portion of a
michael@0: * number.
michael@0: * @see setMaximumFractionDigits
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: int32_t getMaximumFractionDigits(void) const;
michael@0:
michael@0: /**
michael@0: * Sets the maximum number of digits allowed in the fraction portion of a
michael@0: * number. maximumFractionDigits must be >= minimumFractionDigits. If the
michael@0: * new value for maximumFractionDigits is less than the current value
michael@0: * of minimumFractionDigits, then minimumFractionDigits will also be set to
michael@0: * the new value.
michael@0: * @param newValue the new value to be set.
michael@0: * @see getMaximumFractionDigits
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: virtual void setMaximumFractionDigits(int32_t newValue);
michael@0:
michael@0: /**
michael@0: * Returns the minimum number of digits allowed in the fraction portion of a
michael@0: * number.
michael@0: * @return the minimum number of digits allowed in the fraction portion of a
michael@0: * number.
michael@0: * @see setMinimumFractionDigits
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: int32_t getMinimumFractionDigits(void) const;
michael@0:
michael@0: /**
michael@0: * Sets the minimum number of digits allowed in the fraction portion of a
michael@0: * number. minimumFractionDigits must be <= maximumFractionDigits. If the
michael@0: * new value for minimumFractionDigits exceeds the current value
michael@0: * of maximumFractionDigits, then maximumIntegerDigits will also be set to
michael@0: * the new value
michael@0: * @param newValue the new value to be set.
michael@0: * @see getMinimumFractionDigits
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: virtual void setMinimumFractionDigits(int32_t newValue);
michael@0:
michael@0: /**
michael@0: * Sets the currency used to display currency
michael@0: * amounts. This takes effect immediately, if this format is a
michael@0: * currency format. If this format is not a currency format, then
michael@0: * the currency is used if and when this object becomes a
michael@0: * currency format.
michael@0: * @param theCurrency a 3-letter ISO code indicating new currency
michael@0: * to use. It need not be null-terminated. May be the empty
michael@0: * string or NULL to indicate no currency.
michael@0: * @param ec input-output error code
michael@0: * @stable ICU 3.0
michael@0: */
michael@0: virtual void setCurrency(const UChar* theCurrency, UErrorCode& ec);
michael@0:
michael@0: /**
michael@0: * Gets the currency used to display currency
michael@0: * amounts. This may be an empty string for some subclasses.
michael@0: * @return a 3-letter null-terminated ISO code indicating
michael@0: * the currency in use, or a pointer to the empty string.
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: const UChar* getCurrency() const;
michael@0:
michael@0: public:
michael@0:
michael@0: /**
michael@0: * Return the class ID for this class. This is useful for
michael@0: * comparing to a return value from getDynamicClassID(). Note that,
michael@0: * because NumberFormat is an abstract base class, no fully constructed object
michael@0: * will have the class ID returned by NumberFormat::getStaticClassID().
michael@0: * @return The class ID for all objects of this class.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: static UClassID U_EXPORT2 getStaticClassID(void);
michael@0:
michael@0: /**
michael@0: * Returns a unique class ID POLYMORPHICALLY. Pure virtual override.
michael@0: * This method is to implement a simple version of RTTI, since not all
michael@0: * C++ compilers support genuine RTTI. Polymorphic operator==() and
michael@0: * clone() methods call this method.
michael@0: *
michael@0: * @return The class ID for this object. All objects of a michael@0: * given class have the same class ID. Objects of michael@0: * other classes have different class IDs. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UClassID getDynamicClassID(void) const = 0; michael@0: michael@0: protected: michael@0: michael@0: /** michael@0: * Default constructor for subclass use only. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: NumberFormat(); michael@0: michael@0: /** michael@0: * Copy constructor. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: NumberFormat(const NumberFormat&); michael@0: michael@0: /** michael@0: * Assignment operator. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: NumberFormat& operator=(const NumberFormat&); michael@0: michael@0: /** michael@0: * Returns the currency in effect for this formatter. Subclasses michael@0: * should override this method as needed. Unlike getCurrency(), michael@0: * this method should never return "". michael@0: * @result output parameter for null-terminated result, which must michael@0: * have a capacity of at least 4 michael@0: * @internal michael@0: */ michael@0: virtual void getEffectiveCurrency(UChar* result, UErrorCode& ec) const; michael@0: michael@0: #ifndef U_HIDE_INTERNAL_API michael@0: /** michael@0: * Creates the specified number format style of the desired locale. michael@0: * If mustBeDecimalFormat is TRUE, then the returned pointer is michael@0: * either a DecimalFormat or it is NULL. michael@0: * @internal michael@0: */ michael@0: static NumberFormat* makeInstance(const Locale& desiredLocale, michael@0: UNumberFormatStyle style, michael@0: UBool mustBeDecimalFormat, michael@0: UErrorCode& errorCode); michael@0: #endif /* U_HIDE_INTERNAL_API */ michael@0: michael@0: private: michael@0: michael@0: static UBool isStyleSupported(UNumberFormatStyle style); michael@0: michael@0: /** michael@0: * Creates the specified decimal format style of the desired locale. michael@0: * @param desiredLocale the given locale. michael@0: * @param style the given style. michael@0: * @param errorCode Output param filled with success/failure status. michael@0: * @return A new NumberFormat instance. michael@0: */ michael@0: static NumberFormat* makeInstance(const Locale& desiredLocale, michael@0: UNumberFormatStyle style, michael@0: UErrorCode& errorCode); michael@0: michael@0: UBool fGroupingUsed; michael@0: int32_t fMaxIntegerDigits; michael@0: int32_t fMinIntegerDigits; michael@0: int32_t fMaxFractionDigits; michael@0: int32_t fMinFractionDigits; michael@0: michael@0: protected: michael@0: static const int32_t gDefaultMaxIntegerDigits; michael@0: static const int32_t gDefaultMinIntegerDigits; michael@0: michael@0: private: michael@0: UBool fParseIntegerOnly; michael@0: UBool fLenient; // TRUE => lenient parse is enabled michael@0: michael@0: // ISO currency code michael@0: UChar fCurrency[4]; michael@0: michael@0: friend class ICUNumberFormatFactory; // access to makeInstance michael@0: friend class ICUNumberFormatService; michael@0: friend class ::NumberFormatTest; // access to isStyleSupported() michael@0: }; michael@0: michael@0: #if !UCONFIG_NO_SERVICE michael@0: /** michael@0: * A NumberFormatFactory is used to register new number formats. The factory michael@0: * should be able to create any of the predefined formats for each locale it michael@0: * supports. When registered, the locales it supports extend or override the michael@0: * locale already supported by ICU. michael@0: * michael@0: * @stable ICU 2.6 michael@0: */ michael@0: class U_I18N_API NumberFormatFactory : public UObject { michael@0: public: michael@0: michael@0: /** michael@0: * Destructor michael@0: * @stable ICU 3.0 michael@0: */ michael@0: virtual ~NumberFormatFactory(); michael@0: michael@0: /** michael@0: * Return true if this factory will be visible. Default is true. michael@0: * If not visible, the locales supported by this factory will not michael@0: * be listed by getAvailableLocales. michael@0: * @stable ICU 2.6 michael@0: */ michael@0: virtual UBool visible(void) const = 0; michael@0: michael@0: /** michael@0: * Return the locale names directly supported by this factory. The number of names michael@0: * is returned in count; michael@0: * @stable ICU 2.6 michael@0: */ michael@0: virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const = 0; michael@0: michael@0: /** michael@0: * Return a number format of the appropriate type. If the locale michael@0: * is not supported, return null. If the locale is supported, but michael@0: * the type is not provided by this service, return null. Otherwise michael@0: * return an appropriate instance of NumberFormat. michael@0: * @stable ICU 2.6 michael@0: */ michael@0: virtual NumberFormat* createFormat(const Locale& loc, UNumberFormatStyle formatType) = 0; michael@0: }; michael@0: michael@0: /** michael@0: * A NumberFormatFactory that supports a single locale. It can be visible or invisible. michael@0: * @stable ICU 2.6 michael@0: */ michael@0: class U_I18N_API SimpleNumberFormatFactory : public NumberFormatFactory { michael@0: protected: michael@0: /** michael@0: * True if the locale supported by this factory is visible. michael@0: * @stable ICU 2.6 michael@0: */ michael@0: const UBool _visible; michael@0: michael@0: /** michael@0: * The locale supported by this factory, as a UnicodeString. michael@0: * @stable ICU 2.6 michael@0: */ michael@0: UnicodeString _id; michael@0: michael@0: public: michael@0: /** michael@0: * @stable ICU 2.6 michael@0: */ michael@0: SimpleNumberFormatFactory(const Locale& locale, UBool visible = TRUE); michael@0: michael@0: /** michael@0: * @stable ICU 3.0 michael@0: */ michael@0: virtual ~SimpleNumberFormatFactory(); michael@0: michael@0: /** michael@0: * @stable ICU 2.6 michael@0: */ michael@0: virtual UBool visible(void) const; michael@0: michael@0: /** michael@0: * @stable ICU 2.6 michael@0: */ michael@0: virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const; michael@0: }; michael@0: #endif /* #if !UCONFIG_NO_SERVICE */ michael@0: michael@0: // ------------------------------------- michael@0: michael@0: inline UBool michael@0: NumberFormat::isParseIntegerOnly() const michael@0: { michael@0: return fParseIntegerOnly; michael@0: } michael@0: michael@0: inline UBool michael@0: NumberFormat::isLenient() const michael@0: { michael@0: return fLenient; michael@0: } michael@0: michael@0: U_NAMESPACE_END michael@0: michael@0: #endif /* #if !UCONFIG_NO_FORMATTING */ michael@0: michael@0: #endif // _NUMFMT michael@0: //eof