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

/*
********************************************************************************
*   Copyright (C) 2012-2013, 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
#ifndef U_HIDE_DRAFT_API

#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>
 * @draft 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.
      * @draft 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.
     * @draft ICU 51
      */
    CompactDecimalFormat(const CompactDecimalFormat& source);

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

    /**
     * Assignment operator.
     *
     * @param rhs    the DecimalFormat object to be copied.
     * @draft 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.
     * @draft 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.
     * @draft 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.
     * @draft 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.
     * @draft 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
    * @draft 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.
     * @draft ICU 51
     */
    virtual void parse(const UnicodeString& text,
                       Formattable& result,
                       UErrorCode& status) const;

/* Cannot use #ifndef U_HIDE_INTERNAL_API for the following draft method since it is virtual */
    /**
     * 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.
     * @draft 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.
     * @draft 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 /* U_HIDE_DRAFT_API */
#endif /* #if !UCONFIG_NO_FORMATTING */

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