[apple/icu.git] / icuSources / i18n / unicode / compactdecimalformat.h

/*
********************************************************************************
*   Copyright (C) 2012-2014, International Business Machines
*   Corporation and others.  All Rights Reserved.
********************************************************************************
*
* File COMPACTDECIMALFORMAT.H
********************************************************************************
*/

#ifndef __COMPACT_DECIMAL_FORMAT_H__
#define __COMPACT_DECIMAL_FORMAT_H__

#include "unicode/utypes.h"
/**
 * \file
 * \brief C++ API: Formats decimal numbers in compact form.
 */

#if !UCONFIG_NO_FORMATTING

#include "unicode/decimfmt.h"

struct UHashtable;

U_NAMESPACE_BEGIN

class PluralRules;

/**
 * The CompactDecimalFormat produces abbreviated numbers, suitable for display in
 * environments will limited real estate. For example, 'Hits: 1.2B' instead of
 * 'Hits: 1,200,000,000'. The format will be appropriate for the given language,
 * such as "1,2 Mrd." for German.
 * <p>
 * For numbers under 1000 trillion (under 10^15, such as 123,456,789,012,345),
 * the result will be short for supported languages. However, the result may
 * sometimes exceed 7 characters, such as when there are combining marks or thin
 * characters. In such cases, the visual width in fonts should still be short.
 * <p>
 * By default, there are 3 significant digits. After creation, if more than
 * three significant digits are set (with setMaximumSignificantDigits), or if a
 * fixed number of digits are set (with setMaximumIntegerDigits or
 * setMaximumFractionDigits), then result may be wider.
 * <p>
 * At this time, parsing is not supported, and will produce a U_UNSUPPORTED_ERROR.
 * Resetting the pattern prefixes or suffixes is not supported; the method calls
 * are ignored.
 * <p>
 * @stable ICU 51
 */
class U_I18N_API CompactDecimalFormat : public DecimalFormat {
public:

     /**
      * Returns a compact decimal instance for specified locale.
      * @param inLocale the given locale.
      * @param style whether to use short or long style.
      * @param status error code returned  here.
      * @stable ICU 51
      */
     static CompactDecimalFormat* U_EXPORT2 createInstance(
          const Locale& inLocale, UNumberCompactStyle style, UErrorCode& status);

    /**
     * Copy constructor.
     *
     * @param source    the DecimalFormat object to be copied from.
     * @stable ICU 51
      */
    CompactDecimalFormat(const CompactDecimalFormat& source);

    /**
     * Destructor.
     * @stable ICU 51
     */
    virtual ~CompactDecimalFormat();

    /**
     * Assignment operator.
     *
     * @param rhs    the DecimalFormat object to be copied.
     * @stable ICU 51
     */
    CompactDecimalFormat& operator=(const CompactDecimalFormat& rhs);

    /**
     * Clone this Format object polymorphically. The caller owns the
     * result and should delete it when done.
     *
     * @return    a polymorphic copy of this CompactDecimalFormat.
     * @stable ICU 51
     */
    virtual Format* clone() const;

    /**
     * Return TRUE if the given Format objects are semantically equal.
     * Objects of different subclasses are considered unequal.
     *
     * @param other    the object to be compared with.
     * @return         TRUE if the given Format objects are semantically equal.
     * @stable ICU 51
     */
    virtual UBool operator==(const Format& other) const;


    using DecimalFormat::format;

    /**
     * Format a double or long number using base-10 representation.
     *
     * @param number    The value to be formatted.
     * @param appendTo  Output parameter to receive result.
     *                  Result is appended to existing contents.
     * @param pos       On input: an alignment field, if desired.
     *                  On output: the offsets of the alignment field.
     * @return          Reference to 'appendTo' parameter.
     * @stable ICU 51
     */
    virtual UnicodeString& format(double number,
                                  UnicodeString& appendTo,
                                  FieldPosition& pos) const;

    /**
     * Format a double or long number using base-10 representation.
     * Currently sets status to U_UNSUPPORTED_ERROR.
     *
     * @param number    The value to be formatted.
     * @param appendTo  Output parameter to receive result.
     *                  Result is appended to existing contents.
     * @param posIter   On return, can be used to iterate over positions
     *                  of fields generated by this format call.
     *                  Can be NULL.
     * @param status    Output param filled with success/failure status.
     * @return          Reference to 'appendTo' parameter.
     * @internal
     */
    virtual UnicodeString& format(double number,
                                  UnicodeString& appendTo,
                                  FieldPositionIterator* posIter,
                                  UErrorCode& status) const;

    /**
     * Format an int64 number using base-10 representation.
     *
     * @param number    The value to be formatted.
     * @param appendTo  Output parameter to receive result.
     *                  Result is appended to existing contents.
     * @param pos       On input: an alignment field, if desired.
     *                  On output: the offsets of the alignment field.
     * @return          Reference to 'appendTo' parameter.
     * @stable ICU 51
     */
    virtual UnicodeString& format(int64_t number,
                                  UnicodeString& appendTo,
                                  FieldPosition& pos) const;

    /**
     * Format an int64 number using base-10 representation.
     * Currently sets status to U_UNSUPPORTED_ERROR
     *
     * @param number    The value to be formatted.
     * @param appendTo  Output parameter to receive result.
     *                  Result is appended to existing contents.
     * @param posIter   On return, can be used to iterate over positions
     *                  of fields generated by this format call.
     *                  Can be NULL.
     * @param status    Output param filled with success/failure status.
     * @return          Reference to 'appendTo' parameter.
     * @internal
     */
    virtual UnicodeString& format(int64_t number,
                                  UnicodeString& appendTo,
                                  FieldPositionIterator* posIter,
                                  UErrorCode& status) const;

    /**
     * Format a decimal number. Currently sets status to U_UNSUPPORTED_ERROR
     * The syntax of the unformatted number is a "numeric string"
     * as defined in the Decimal Arithmetic Specification, available at
     * http://speleotrove.com/decimal
     *
     * @param number    The unformatted number, as a string.
     * @param appendTo  Output parameter to receive result.
     *                  Result is appended to existing contents.
     * @param posIter   On return, can be used to iterate over positions
     *                  of fields generated by this format call.
     *                  Can be NULL.
     * @param status    Output param filled with success/failure status.
     * @return          Reference to 'appendTo' parameter.
     * @internal
     */
    virtual UnicodeString& format(const StringPiece &number,
                                  UnicodeString& appendTo,
                                  FieldPositionIterator* posIter,
                                  UErrorCode& status) const;

    /**
     * Format a decimal number. Currently sets status to U_UNSUPPORTED_ERROR
     * The number is a DigitList wrapper onto a floating point decimal number.
     * The default implementation in NumberFormat converts the decimal number
     * to a double and formats that.
     *
     * @param number    The number, a DigitList format Decimal Floating Point.
     * @param appendTo  Output parameter to receive result.
     *                  Result is appended to existing contents.
     * @param posIter   On return, can be used to iterate over positions
     *                  of fields generated by this format call.
     * @param status    Output param filled with success/failure status.
     * @return          Reference to 'appendTo' parameter.
     * @internal
     */
    virtual UnicodeString& format(const DigitList &number,
                                  UnicodeString& appendTo,
                                  FieldPositionIterator* posIter,
                                  UErrorCode& status) const;

    /**
     * Format a decimal number. Currently sets status to U_UNSUPPORTED_ERROR.
     * The number is a DigitList wrapper onto a floating point decimal number.
     * The default implementation in NumberFormat converts the decimal number
     * to a double and formats that.  
     *
     * @param number    The number, a DigitList format Decimal Floating Point.
     * @param appendTo  Output parameter to receive result.
     *                  Result is appended to existing contents.
     * @param pos       On input: an alignment field, if desired.
     *                  On output: the offsets of the alignment field.
     * @param status    Output param filled with success/failure status.
     * @return          Reference to 'appendTo' parameter.
     * @internal
     */
    virtual UnicodeString& format(const DigitList &number,
                                  UnicodeString& appendTo,
                                  FieldPosition& pos,
                                  UErrorCode& status) const;

   /**
    * CompactDecimalFormat does not support parsing. This implementation
    * does nothing.
    * @param text           Unused.
    * @param result         Does not change.
    * @param parsePosition  Does not change.
    * @see Formattable
    * @stable ICU 51
    */
    virtual void parse(const UnicodeString& text,
                       Formattable& result,
                       ParsePosition& parsePosition) const;

    /**
     * CompactDecimalFormat does not support parsing. This implementation
     * sets status to U_UNSUPPORTED_ERROR
     *
     * @param text      Unused. 
     * @param result    Does not change.
     * @param status    Always set to U_UNSUPPORTED_ERROR.
     * @stable ICU 51
     */
    virtual void parse(const UnicodeString& text,
                       Formattable& result,
                       UErrorCode& status) const;

    /**
     * Parses text from the given string as a currency amount.  Unlike
     * the parse() method, this method will attempt to parse a generic
     * currency name, searching for a match of this object's locale's
     * currency display names, or for a 3-letter ISO currency code.
     * This method will fail if this format is not a currency format,
     * that is, if it does not contain the currency pattern symbol
     * (U+00A4) in its prefix or suffix. This implementation always returns
     * NULL.
     *
     * @param text the string to parse
     * @param pos  input-output position; on input, the position within text
     *             to match; must have 0 <= pos.getIndex() < text.length();
     *             on output, the position after the last matched character.
     *             If the parse fails, the position in unchanged upon output.
     * @return     if parse succeeds, a pointer to a newly-created CurrencyAmount
     *             object (owned by the caller) containing information about
     *             the parsed currency; if parse fails, this is NULL.
     * @internal
     */
    virtual CurrencyAmount* parseCurrency(const UnicodeString& text,
                                          ParsePosition& pos) const;

    /**
     * Return the class ID for this class.  This is useful only for
     * comparing to a return value from getDynamicClassID().  For example:
     * <pre>
     * .      Base* polymorphic_pointer = createPolymorphicObject();
     * .      if (polymorphic_pointer->getDynamicClassID() ==
     * .          Derived::getStaticClassID()) ...
     * </pre>
     * @return          The class ID for all objects of this class.
     * @stable ICU 51
     */
    static UClassID U_EXPORT2 getStaticClassID();

    /**
     * Returns a unique class ID POLYMORPHICALLY.  Pure virtual override.
     * This method is to implement a simple version of RTTI, since not all
     * C++ compilers support genuine RTTI.  Polymorphic operator==() and
     * clone() methods call this method.
     *
     * @return          The class ID for this object. All objects of a
     *                  given class have the same class ID.  Objects of
     *                  other classes have different class IDs.
     * @stable ICU 51
     */
    virtual UClassID getDynamicClassID() const;

private:

    const UHashtable* _unitsByVariant;
    const double* _divisors;
    PluralRules* _pluralRules;

    // Default constructor not implemented.
    CompactDecimalFormat(const DecimalFormat &, const UHashtable* unitsByVariant, const double* divisors, PluralRules* pluralRules);

    UBool eqHelper(const CompactDecimalFormat& that) const;
};

U_NAMESPACE_END

#endif /* #if !UCONFIG_NO_FORMATTING */

#endif // __COMPACT_DECIMAL_FORMAT_H__
//eof
Commit	Line	Data
51004dcb A	1	/*
51004dcb A	2	********************************************************************************
57a6839d	3	* Copyright (C) 2012-2014, International Business Machines
51004dcb A	4	* Corporation and others. All Rights Reserved.
	5	********************************************************************************
	6	*
	7	* File COMPACTDECIMALFORMAT.H
	8	********************************************************************************
	9	*/
	10
	11	#ifndef __COMPACT_DECIMAL_FORMAT_H__
	12	#define __COMPACT_DECIMAL_FORMAT_H__
	13
	14	#include "unicode/utypes.h"
	15	/**
	16	* \file
	17	* \brief C++ API: Formats decimal numbers in compact form.
	18	*/
	19
	20	#if !UCONFIG_NO_FORMATTING
51004dcb A	21
	22	#include "unicode/decimfmt.h"
	23
	24	struct UHashtable;
	25
	26	U_NAMESPACE_BEGIN
	27
	28	class PluralRules;
	29
	30	/**
	31	* The CompactDecimalFormat produces abbreviated numbers, suitable for display in
	32	* environments will limited real estate. For example, 'Hits: 1.2B' instead of
	33	* 'Hits: 1,200,000,000'. The format will be appropriate for the given language,
	34	* such as "1,2 Mrd." for German.
	35	* <p>
	36	* For numbers under 1000 trillion (under 10^15, such as 123,456,789,012,345),
	37	* the result will be short for supported languages. However, the result may
	38	* sometimes exceed 7 characters, such as when there are combining marks or thin
	39	* characters. In such cases, the visual width in fonts should still be short.
	40	* <p>
	41	* By default, there are 3 significant digits. After creation, if more than
	42	* three significant digits are set (with setMaximumSignificantDigits), or if a
	43	* fixed number of digits are set (with setMaximumIntegerDigits or
	44	* setMaximumFractionDigits), then result may be wider.
	45	* <p>
	46	* At this time, parsing is not supported, and will produce a U_UNSUPPORTED_ERROR.
	47	* Resetting the pattern prefixes or suffixes is not supported; the method calls
	48	* are ignored.
	49	* <p>
57a6839d	50	* @stable ICU 51
51004dcb A	51	*/
	52	class U_I18N_API CompactDecimalFormat : public DecimalFormat {
	53	public:
	54
	55	/**
	56	* Returns a compact decimal instance for specified locale.
	57	* @param inLocale the given locale.
	58	* @param style whether to use short or long style.
	59	* @param status error code returned here.
57a6839d	60	* @stable ICU 51
51004dcb A	61	*/
	62	static CompactDecimalFormat* U_EXPORT2 createInstance(
	63	const Locale& inLocale, UNumberCompactStyle style, UErrorCode& status);
	64
	65	/**
	66	* Copy constructor.
	67	*
	68	* @param source the DecimalFormat object to be copied from.
57a6839d	69	* @stable ICU 51
51004dcb A	70	*/
	71	CompactDecimalFormat(const CompactDecimalFormat& source);
	72
	73	/**
	74	* Destructor.
57a6839d	75	* @stable ICU 51
51004dcb A	76	*/
	77	virtual ~CompactDecimalFormat();
	78
	79	/**
	80	* Assignment operator.
	81	*
	82	* @param rhs the DecimalFormat object to be copied.
57a6839d	83	* @stable ICU 51
51004dcb A	84	*/
	85	CompactDecimalFormat& operator=(const CompactDecimalFormat& rhs);
	86
	87	/**
	88	* Clone this Format object polymorphically. The caller owns the
	89	* result and should delete it when done.
	90	*
	91	* @return a polymorphic copy of this CompactDecimalFormat.
57a6839d	92	* @stable ICU 51
51004dcb A	93	*/
	94	virtual Format* clone() const;
	95
	96	/**
	97	* Return TRUE if the given Format objects are semantically equal.
	98	* Objects of different subclasses are considered unequal.
	99	*
	100	* @param other the object to be compared with.
	101	* @return TRUE if the given Format objects are semantically equal.
57a6839d	102	* @stable ICU 51
51004dcb A	103	*/
	104	virtual UBool operator==(const Format& other) const;
	105
	106
	107	using DecimalFormat::format;
	108
	109	/**
	110	* Format a double or long number using base-10 representation.
	111	*
	112	* @param number The value to be formatted.
	113	* @param appendTo Output parameter to receive result.
	114	* Result is appended to existing contents.
	115	* @param pos On input: an alignment field, if desired.
	116	* On output: the offsets of the alignment field.
	117	* @return Reference to 'appendTo' parameter.
57a6839d	118	* @stable ICU 51
51004dcb A	119	*/
	120	virtual UnicodeString& format(double number,
	121	UnicodeString& appendTo,
	122	FieldPosition& pos) const;
	123
	124	/**
	125	* Format a double or long number using base-10 representation.
	126	* Currently sets status to U_UNSUPPORTED_ERROR.
	127	*
	128	* @param number The value to be formatted.
	129	* @param appendTo Output parameter to receive result.
	130	* Result is appended to existing contents.
	131	* @param posIter On return, can be used to iterate over positions
	132	* of fields generated by this format call.
	133	* Can be NULL.
	134	* @param status Output param filled with success/failure status.
	135	* @return Reference to 'appendTo' parameter.
	136	* @internal
	137	*/
	138	virtual UnicodeString& format(double number,
	139	UnicodeString& appendTo,
	140	FieldPositionIterator* posIter,
	141	UErrorCode& status) const;
	142
	143	/**
	144	* Format an int64 number using base-10 representation.
	145	*
	146	* @param number The value to be formatted.
	147	* @param appendTo Output parameter to receive result.
	148	* Result is appended to existing contents.
	149	* @param pos On input: an alignment field, if desired.
	150	* On output: the offsets of the alignment field.
	151	* @return Reference to 'appendTo' parameter.
57a6839d	152	* @stable ICU 51
51004dcb A	153	*/
	154	virtual UnicodeString& format(int64_t number,
	155	UnicodeString& appendTo,
	156	FieldPosition& pos) const;
	157
	158	/**
	159	* Format an int64 number using base-10 representation.
	160	* Currently sets status to U_UNSUPPORTED_ERROR
	161	*
	162	* @param number The value to be formatted.
	163	* @param appendTo Output parameter to receive result.
	164	* Result is appended to existing contents.
	165	* @param posIter On return, can be used to iterate over positions
	166	* of fields generated by this format call.
	167	* Can be NULL.
	168	* @param status Output param filled with success/failure status.
	169	* @return Reference to 'appendTo' parameter.
	170	* @internal
	171	*/
	172	virtual UnicodeString& format(int64_t number,
	173	UnicodeString& appendTo,
	174	FieldPositionIterator* posIter,
	175	UErrorCode& status) const;
	176
	177	/**
	178	* Format a decimal number. Currently sets status to U_UNSUPPORTED_ERROR
	179	* The syntax of the unformatted number is a "numeric string"
	180	* as defined in the Decimal Arithmetic Specification, available at
	181	* http://speleotrove.com/decimal
	182	*
	183	* @param number The unformatted number, as a string.
	184	* @param appendTo Output parameter to receive result.
	185	* Result is appended to existing contents.
	186	* @param posIter On return, can be used to iterate over positions
	187	* of fields generated by this format call.
	188	* Can be NULL.
	189	* @param status Output param filled with success/failure status.
	190	* @return Reference to 'appendTo' parameter.
	191	* @internal
	192	*/
	193	virtual UnicodeString& format(const StringPiece &number,
	194	UnicodeString& appendTo,
	195	FieldPositionIterator* posIter,
	196	UErrorCode& status) const;
	197
	198	/**
	199	* Format a decimal number. Currently sets status to U_UNSUPPORTED_ERROR
	200	* The number is a DigitList wrapper onto a floating point decimal number.
	201	* The default implementation in NumberFormat converts the decimal number
	202	* to a double and formats that.
	203	*
	204	* @param number The number, a DigitList format Decimal Floating Point.
	205	* @param appendTo Output parameter to receive result.
	206	* Result is appended to existing contents.
	207	* @param posIter On return, can be used to iterate over positions
	208	* of fields generated by this format call.
	209	* @param status Output param filled with success/failure status.
	210	* @return Reference to 'appendTo' parameter.
	211	* @internal
	212	*/
	213	virtual UnicodeString& format(const DigitList &number,
	214	UnicodeString& appendTo,
	215	FieldPositionIterator* posIter,
	216	UErrorCode& status) const;
217
218	/**
219	* Format a decimal number. Currently sets status to U_UNSUPPORTED_ERROR.
220	* The number is a DigitList wrapper onto a floating point decimal number.
221	* The default implementation in NumberFormat converts the decimal number
222	* to a double and formats that.
223	*
224	* @param number The number, a DigitList format Decimal Floating Point.
225	* @param appendTo Output parameter to receive result.
226	* Result is appended to existing contents.
227	* @param pos On input: an alignment field, if desired.
228	* On output: the offsets of the alignment field.
229	* @param status Output param filled with success/failure status.
230	* @return Reference to 'appendTo' parameter.
231	* @internal
232	*/
233	virtual UnicodeString& format(const DigitList &number,
234	UnicodeString& appendTo,
235	FieldPosition& pos,
236	UErrorCode& status) const;
237
238	/**
239	* CompactDecimalFormat does not support parsing. This implementation
240	* does nothing.
241	* @param text Unused.
242	* @param result Does not change.
243	* @param parsePosition Does not change.
244	* @see Formattable
57a6839d	245	* @stable ICU 51
51004dcb A	246	*/
	247	virtual void parse(const UnicodeString& text,
	248	Formattable& result,
	249	ParsePosition& parsePosition) const;
	250
	251	/**
	252	* CompactDecimalFormat does not support parsing. This implementation
	253	* sets status to U_UNSUPPORTED_ERROR
	254	*
	255	* @param text Unused.
	256	* @param result Does not change.
	257	* @param status Always set to U_UNSUPPORTED_ERROR.
57a6839d	258	* @stable ICU 51
51004dcb A	259	*/
	260	virtual void parse(const UnicodeString& text,
	261	Formattable& result,
	262	UErrorCode& status) const;
	263
51004dcb A	264	/**
	265	* Parses text from the given string as a currency amount. Unlike
	266	* the parse() method, this method will attempt to parse a generic
	267	* currency name, searching for a match of this object's locale's
	268	* currency display names, or for a 3-letter ISO currency code.
	269	* This method will fail if this format is not a currency format,
	270	* that is, if it does not contain the currency pattern symbol
	271	* (U+00A4) in its prefix or suffix. This implementation always returns
	272	* NULL.
	273	*
	274	* @param text the string to parse
	275	* @param pos input-output position; on input, the position within text
	276	* to match; must have 0 <= pos.getIndex() < text.length();
	277	* on output, the position after the last matched character.
	278	* If the parse fails, the position in unchanged upon output.
	279	* @return if parse succeeds, a pointer to a newly-created CurrencyAmount
	280	* object (owned by the caller) containing information about
	281	* the parsed currency; if parse fails, this is NULL.
	282	* @internal
	283	*/
	284	virtual CurrencyAmount* parseCurrency(const UnicodeString& text,
	285	ParsePosition& pos) const;
	286
	287	/**
	288	* Return the class ID for this class. This is useful only for
	289	* comparing to a return value from getDynamicClassID(). For example:
	290	* <pre>
	291	* . Base* polymorphic_pointer = createPolymorphicObject();
	292	* . if (polymorphic_pointer->getDynamicClassID() ==
	293	* . Derived::getStaticClassID()) ...
	294	* </pre>
	295	* @return The class ID for all objects of this class.
57a6839d	296	* @stable ICU 51
51004dcb A	297	*/
	298	static UClassID U_EXPORT2 getStaticClassID();
	299
	300	/**
	301	* Returns a unique class ID POLYMORPHICALLY. Pure virtual override.
	302	* This method is to implement a simple version of RTTI, since not all
	303	* C++ compilers support genuine RTTI. Polymorphic operator==() and
	304	* clone() methods call this method.
	305	*
	306	* @return The class ID for this object. All objects of a
	307	* given class have the same class ID. Objects of
	308	* other classes have different class IDs.
57a6839d	309	* @stable ICU 51
51004dcb A	310	*/
	311	virtual UClassID getDynamicClassID() const;
	312
	313	private:
	314
	315	const UHashtable* _unitsByVariant;
	316	const double* _divisors;
	317	PluralRules* _pluralRules;
	318
	319	// Default constructor not implemented.
	320	CompactDecimalFormat(const DecimalFormat &, const UHashtable* unitsByVariant, const double* divisors, PluralRules* pluralRules);
	321
	322	UBool eqHelper(const CompactDecimalFormat& that) const;
	323	};
	324
	325	U_NAMESPACE_END
	326
51004dcb A	327	#endif /* #if !UCONFIG_NO_FORMATTING */
	328
	329	#endif // __COMPACT_DECIMAL_FORMAT_H__
	330	//eof