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
25struct UHashtable;
26
27U_NAMESPACE_BEGIN
28
29class 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 */
53class U_I18N_API CompactDecimalFormat : public DecimalFormat {
54public:
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
315private:
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
327U_NAMESPACE_END
328
329#endif /* U_HIDE_DRAFT_API */
330#endif /* #if !UCONFIG_NO_FORMATTING */
331
332#endif // __COMPACT_DECIMAL_FORMAT_H__
333//eof
334