• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2 ********************************************************************************
3 * Copyright (C) 1997-2010, International Business Machines Corporation and others.
4 * All Rights Reserved.
5 ********************************************************************************
6 *
7 * File NUMFMT.H
8 *
9 * Modification History:
10 *
11 *   Date        Name        Description
12 *   02/19/97    aliu        Converted from java.
13 *   03/18/97    clhuang     Updated per C++ implementation.
14 *   04/17/97    aliu        Changed DigitCount to int per code review.
15 *    07/20/98    stephen        JDK 1.2 sync up. Added scientific support.
16 *                            Changed naming conventions to match C++ guidelines
17 *                            Derecated Java style constants (eg, INTEGER_FIELD)
18 ********************************************************************************
19 */
20 
21 #ifndef NUMFMT_H
22 #define NUMFMT_H
23 
24 
25 #include "unicode/utypes.h"
26 
27 /**
28  * \file
29  * \brief C++ API: Abstract base class for all number formats.
30  */
31 
32 #if !UCONFIG_NO_FORMATTING
33 
34 #include "unicode/unistr.h"
35 #include "unicode/format.h"
36 #include "unicode/unum.h" // UNumberFormatStyle
37 #include "unicode/locid.h"
38 #include "unicode/stringpiece.h"
39 
40 U_NAMESPACE_BEGIN
41 
42 #if !UCONFIG_NO_SERVICE
43 class NumberFormatFactory;
44 class StringEnumeration;
45 #endif
46 
47 /**
48  *
49  * Abstract base class for all number formats.  Provides interface for
50  * formatting and parsing a number.  Also provides methods for
51  * determining which locales have number formats, and what their names
52  * are.
53  * <P>
54  * NumberFormat helps you to format and parse numbers for any locale.
55  * Your code can be completely independent of the locale conventions
56  * for decimal points, thousands-separators, or even the particular
57  * decimal digits used, or whether the number format is even decimal.
58  * <P>
59  * To format a number for the current Locale, use one of the static
60  * factory methods:
61  * <pre>
62  * \code
63  *    double myNumber = 7.0;
64  *    UnicodeString myString;
65  *    UErrorCode success = U_ZERO_ERROR;
66  *    NumberFormat* nf = NumberFormat::createInstance(success)
67  *    nf->format(myNumber, myString);
68  *    cout << " Example 1: " << myString << endl;
69  * \endcode
70  * </pre>
71  * If you are formatting multiple numbers, it is more efficient to get
72  * the format and use it multiple times so that the system doesn't
73  * have to fetch the information about the local language and country
74  * conventions multiple times.
75  * <pre>
76  * \code
77  *     UnicodeString myString;
78  *     UErrorCode success = U_ZERO_ERROR;
79  *     nf = NumberFormat::createInstance( success );
80  *     int32_t a[] = { 123, 3333, -1234567 };
81  *     const int32_t a_len = sizeof(a) / sizeof(a[0]);
82  *     myString.remove();
83  *     for (int32_t i = 0; i < a_len; i++) {
84  *         nf->format(a[i], myString);
85  *         myString += " ; ";
86  *     }
87  *     cout << " Example 2: " << myString << endl;
88  * \endcode
89  * </pre>
90  * To format a number for a different Locale, specify it in the
91  * call to createInstance().
92  * <pre>
93  * \code
94  *     nf = NumberFormat::createInstance( Locale::FRENCH, success );
95  * \endcode
96  * </pre>
97  * You can use a NumberFormat to parse also.
98  * <pre>
99  * \code
100  *    UErrorCode success;
101  *    Formattable result(-999);  // initialized with error code
102  *    nf->parse(myString, result, success);
103  * \endcode
104  * </pre>
105  * Use createInstance to get the normal number format for that country.
106  * There are other static factory methods available.  Use getCurrency
107  * to get the currency number format for that country.  Use getPercent
108  * to get a format for displaying percentages. With this format, a
109  * fraction from 0.53 is displayed as 53%.
110  * <P>
111  * Starting from ICU 4.2, you can use createInstance() by passing in a 'style'
112  * as parameter to get the correct instance.
113  * For example,
114  * use createInstance(...kNumberStyle...) to get the normal number format,
115  * createInstance(...kPercentStyle...) to get a format for displaying
116  * percentage,
117  * createInstance(...kScientificStyle...) to get a format for displaying
118  * scientific number,
119  * createInstance(...kCurrencyStyle...) to get the currency number format,
120  * in which the currency is represented by its symbol, for example, "$3.00".
121  * createInstance(...kIsoCurrencyStyle...)  to get the currency number format,
122  * in which the currency is represented by its ISO code, for example "USD3.00".
123  * createInstance(...kPluralCurrencyStyle...) to get the currency number format,
124  * in which the currency is represented by its full name in plural format,
125  * for example, "3.00 US dollars" or "1.00 US dollar".
126  * <P>
127  * You can also control the display of numbers with such methods as
128  * getMinimumFractionDigits.  If you want even more control over the
129  * format or parsing, or want to give your users more control, you can
130  * try casting the NumberFormat you get from the factory methods to a
131  * DecimalNumberFormat. This will work for the vast majority of
132  * countries; just remember to put it in a try block in case you
133  * encounter an unusual one.
134  * <P>
135  * You can also use forms of the parse and format methods with
136  * ParsePosition and FieldPosition to allow you to:
137  * <ul type=round>
138  *   <li>(a) progressively parse through pieces of a string.
139  *   <li>(b) align the decimal point and other areas.
140  * </ul>
141  * For example, you can align numbers in two ways.
142  * <P>
143  * If you are using a monospaced font with spacing for alignment, you
144  * can pass the FieldPosition in your format call, with field =
145  * INTEGER_FIELD. On output, getEndIndex will be set to the offset
146  * between the last character of the integer and the decimal. Add
147  * (desiredSpaceCount - getEndIndex) spaces at the front of the
148  * string.
149  * <P>
150  * If you are using proportional fonts, instead of padding with
151  * spaces, measure the width of the string in pixels from the start to
152  * getEndIndex.  Then move the pen by (desiredPixelWidth -
153  * widthToAlignmentPoint) before drawing the text.  It also works
154  * where there is no decimal, but possibly additional characters at
155  * the end, e.g. with parentheses in negative numbers: "(12)" for -12.
156  * <p>
157  * <em>User subclasses are not supported.</em> While clients may write
158  * subclasses, such code will not necessarily work and will not be
159  * guaranteed to work stably from release to release.
160  *
161  * @stable ICU 2.0
162  */
163 class U_I18N_API NumberFormat : public Format {
164 public:
165 
166     /**
167      * Constants for various number format styles.
168      * kNumberStyle specifies a normal number style of format.
169      * kCurrencyStyle specifies a currency format using currency symbol name,
170      * such as in "$1.00".
171      * kPercentStyle specifies a style of format to display percent.
172      * kScientificStyle specifies a style of format to display scientific number.
173      * kISOCurrencyStyle specifies a currency format using ISO currency code,
174      * such as in "USD1.00".
175      * kPluralCurrencyStyle specifies a currency format using currency plural
176      * names, such as in "1.00 US dollar" and "3.00 US dollars".
177      * @draft ICU 4.2
178      */
179     enum EStyles {
180         kNumberStyle,
181         kCurrencyStyle,
182         kPercentStyle,
183         kScientificStyle,
184         kIsoCurrencyStyle,
185         kPluralCurrencyStyle,
186         kStyleCount // ALWAYS LAST ENUM: number of styles
187     };
188 
189     /**
190      * Alignment Field constants used to construct a FieldPosition object.
191      * Signifies that the position of the integer part or fraction part of
192      * a formatted number should be returned.
193      *
194      * Note: as of ICU 4.4, the values in this enum have been extended to
195      * support identification of all number format fields, not just those
196      * pertaining to alignment.
197      *
198      * @see FieldPosition
199      * @stable ICU 2.0
200      */
201     enum EAlignmentFields {
202         kIntegerField,
203         kFractionField,
204         kDecimalSeparatorField,
205         kExponentSymbolField,
206         kExponentSignField,
207         kExponentField,
208         kGroupingSeparatorField,
209         kCurrencyField,
210         kPercentField,
211         kPermillField,
212         kSignField,
213 
214     /**
215      * These constants are provided for backwards compatibility only.
216      * Please use the C++ style constants defined above.
217      * @stable ICU 2.0
218      */
219         INTEGER_FIELD        = kIntegerField,
220         FRACTION_FIELD        = kFractionField
221     };
222 
223     /**
224      * Destructor.
225      * @stable ICU 2.0
226      */
227     virtual ~NumberFormat();
228 
229     /**
230      * Return true if the given Format objects are semantically equal.
231      * Objects of different subclasses are considered unequal.
232      * @return    true if the given Format objects are semantically equal.
233      * @stable ICU 2.0
234      */
235     virtual UBool operator==(const Format& other) const;
236 
237 
238     using Format::format;
239 
240     /**
241      * Format an object to produce a string.  This method handles
242      * Formattable objects with numeric types. If the Formattable
243      * object type is not a numeric type, then it returns a failing
244      * UErrorCode.
245      *
246      * @param obj       The object to format.
247      * @param appendTo  Output parameter to receive result.
248      *                  Result is appended to existing contents.
249      * @param pos       On input: an alignment field, if desired.
250      *                  On output: the offsets of the alignment field.
251      * @param status    Output param filled with success/failure status.
252      * @return          Reference to 'appendTo' parameter.
253      * @stable ICU 2.0
254      */
255     virtual UnicodeString& format(const Formattable& obj,
256                                   UnicodeString& appendTo,
257                                   FieldPosition& pos,
258                                   UErrorCode& status) const;
259 
260     /**
261      * Format an object to produce a string.  This method handles
262      * Formattable objects with numeric types. If the Formattable
263      * object type is not a numeric type, then it returns a failing
264      * UErrorCode.
265      *
266      * @param obj       The object to format.
267      * @param appendTo  Output parameter to receive result.
268      *                  Result is appended to existing contents.
269      * @param posIter   On return, can be used to iterate over positions
270      *                  of fields generated by this format call.  Can be
271      *                  NULL.
272      * @param status    Output param filled with success/failure status.
273      * @return          Reference to 'appendTo' parameter.
274      * @stable 4.4
275      */
276     virtual UnicodeString& format(const Formattable& obj,
277                                   UnicodeString& appendTo,
278                                   FieldPositionIterator* posIter,
279                                   UErrorCode& status) const;
280 
281     /**
282      * Parse a string to produce an object.  This methods handles
283      * parsing of numeric strings into Formattable objects with numeric
284      * types.
285      * <P>
286      * Before calling, set parse_pos.index to the offset you want to
287      * start parsing at in the source. After calling, parse_pos.index
288      * indicates the position after the successfully parsed text.  If
289      * an error occurs, parse_pos.index is unchanged.
290      * <P>
291      * When parsing, leading whitespace is discarded (with successful
292      * parse), while trailing whitespace is left as is.
293      * <P>
294      * See Format::parseObject() for more.
295      *
296      * @param source    The string to be parsed into an object.
297      * @param result    Formattable to be set to the parse result.
298      *                  If parse fails, return contents are undefined.
299      * @param parse_pos The position to start parsing at. Upon return
300      *                  this param is set to the position after the
301      *                  last character successfully parsed. If the
302      *                  source is not parsed successfully, this param
303      *                  will remain unchanged.
304      * @return          A newly created Formattable* object, or NULL
305      *                  on failure.  The caller owns this and should
306      *                  delete it when done.
307      * @stable ICU 2.0
308      */
309     virtual void parseObject(const UnicodeString& source,
310                              Formattable& result,
311                              ParsePosition& parse_pos) const;
312 
313     /**
314      * Format a double number. These methods call the NumberFormat
315      * pure virtual format() methods with the default FieldPosition.
316      *
317      * @param number    The value to be formatted.
318      * @param appendTo  Output parameter to receive result.
319      *                  Result is appended to existing contents.
320      * @return          Reference to 'appendTo' parameter.
321      * @stable ICU 2.0
322      */
323     UnicodeString& format(  double number,
324                             UnicodeString& appendTo) const;
325 
326     /**
327      * Format a long number. These methods call the NumberFormat
328      * pure virtual format() methods with the default FieldPosition.
329      *
330      * @param number    The value to be formatted.
331      * @param appendTo  Output parameter to receive result.
332      *                  Result is appended to existing contents.
333      * @return          Reference to 'appendTo' parameter.
334      * @stable ICU 2.0
335      */
336     UnicodeString& format(  int32_t number,
337                             UnicodeString& appendTo) const;
338 
339     /**
340      * Format an int64 number. These methods call the NumberFormat
341      * pure virtual format() methods with the default FieldPosition.
342      *
343      * @param number    The value to be formatted.
344      * @param appendTo  Output parameter to receive result.
345      *                  Result is appended to existing contents.
346      * @return          Reference to 'appendTo' parameter.
347      * @stable ICU 2.8
348      */
349     UnicodeString& format(  int64_t number,
350                             UnicodeString& appendTo) const;
351 
352     /**
353      * Format a double number. Concrete subclasses must implement
354      * these pure virtual methods.
355      *
356      * @param number    The value to be formatted.
357      * @param appendTo  Output parameter to receive result.
358      *                  Result is appended to existing contents.
359      * @param pos       On input: an alignment field, if desired.
360      *                  On output: the offsets of the alignment field.
361      * @return          Reference to 'appendTo' parameter.
362      * @stable ICU 2.0
363      */
364     virtual UnicodeString& format(double number,
365                                   UnicodeString& appendTo,
366                                   FieldPosition& pos) const = 0;
367     /**
368      * Format a double number. Subclasses must implement
369      * this method.
370      *
371      * @param number    The value to be formatted.
372      * @param appendTo  Output parameter to receive result.
373      *                  Result is appended to existing contents.
374      * @param posIter   On return, can be used to iterate over positions
375      *                  of fields generated by this format call.
376      *                  Can be NULL.
377      * @param status    Output param filled with success/failure status.
378      * @return          Reference to 'appendTo' parameter.
379      * @stable 4.4
380      */
381     virtual UnicodeString& format(double number,
382                                   UnicodeString& appendTo,
383                                   FieldPositionIterator* posIter,
384                                   UErrorCode& status) const;
385     /**
386      * Format a long number. Concrete subclasses must implement
387      * these pure virtual methods.
388      *
389      * @param number    The value to be formatted.
390      * @param appendTo  Output parameter to receive result.
391      *                  Result is appended to existing contents.
392      * @param pos       On input: an alignment field, if desired.
393      *                  On output: the offsets of the alignment field.
394      * @return          Reference to 'appendTo' parameter.
395      * @stable ICU 2.0
396     */
397     virtual UnicodeString& format(int32_t number,
398                                   UnicodeString& appendTo,
399                                   FieldPosition& pos) const = 0;
400 
401     /**
402      * Format an int32 number. Subclasses must implement
403      * this method.
404      *
405      * @param number    The value to be formatted.
406      * @param appendTo  Output parameter to receive result.
407      *                  Result is appended to existing contents.
408      * @param posIter   On return, can be used to iterate over positions
409      *                  of fields generated by this format call.
410      *                  Can be NULL.
411      * @param status    Output param filled with success/failure status.
412      * @return          Reference to 'appendTo' parameter.
413      * @stable 4.4
414      */
415     virtual UnicodeString& format(int32_t number,
416                                   UnicodeString& appendTo,
417                                   FieldPositionIterator* posIter,
418                                   UErrorCode& status) const;
419     /**
420      * Format an int64 number. (Not abstract to retain compatibility
421      * with earlier releases, however subclasses should override this
422      * method as it just delegates to format(int32_t number...);
423      *
424      * @param number    The value to be formatted.
425      * @param appendTo  Output parameter to receive result.
426      *                  Result is appended to existing contents.
427      * @param pos       On input: an alignment field, if desired.
428      *                  On output: the offsets of the alignment field.
429      * @return          Reference to 'appendTo' parameter.
430      * @stable ICU 2.8
431     */
432     virtual UnicodeString& format(int64_t number,
433                                   UnicodeString& appendTo,
434                                   FieldPosition& pos) const;
435     /**
436      * Format an int64 number. Subclasses must implement
437      * this method.
438      *
439      * @param number    The value to be formatted.
440      * @param appendTo  Output parameter to receive result.
441      *                  Result is appended to existing contents.
442      * @param posIter   On return, can be used to iterate over positions
443      *                  of fields generated by this format call.
444      *                  Can be NULL.
445      * @param status    Output param filled with success/failure status.
446      * @return          Reference to 'appendTo' parameter.
447      * @stable 4.4
448      */
449     virtual UnicodeString& format(int64_t number,
450                                   UnicodeString& appendTo,
451                                   FieldPositionIterator* posIter,
452                                   UErrorCode& status) const;
453 
454     /**
455      * Format a decimal number. Subclasses must implement
456      * this method.  The syntax of the unformatted number is a "numeric string"
457      * as defined in the Decimal Arithmetic Specification, available at
458      * http://speleotrove.com/decimal
459      *
460      * @param number    The unformatted number, as a string, to be formatted.
461      * @param appendTo  Output parameter to receive result.
462      *                  Result is appended to existing contents.
463      * @param posIter   On return, can be used to iterate over positions
464      *                  of fields generated by this format call.
465      *                  Can be NULL.
466      * @param status    Output param filled with success/failure status.
467      * @return          Reference to 'appendTo' parameter.
468      * @stable 4.4
469      */
470     virtual UnicodeString& format(const StringPiece &number,
471                                   UnicodeString& appendTo,
472                                   FieldPositionIterator* posIter,
473                                   UErrorCode& status) const;
474 public:
475     /**
476      * Format a decimal number.
477      * The number is a DigitList wrapper onto a floating point decimal number.
478      * The default implementation in NumberFormat converts the decimal number
479      * to a double and formats that.  Subclasses of NumberFormat that want
480      * to specifically handle big decimal numbers must override this method.
481      * class DecimalFormat does so.
482      *
483      * @param number    The number, a DigitList format Decimal Floating Point.
484      * @param appendTo  Output parameter to receive result.
485      *                  Result is appended to existing contents.
486      * @param posIter   On return, can be used to iterate over positions
487      *                  of fields generated by this format call.
488      * @param status    Output param filled with success/failure status.
489      * @return          Reference to 'appendTo' parameter.
490      * @internal
491      */
492     virtual UnicodeString& format(const DigitList &number,
493                                   UnicodeString& appendTo,
494                                   FieldPositionIterator* posIter,
495                                   UErrorCode& status) const;
496 
497     /**
498      * Format a decimal number.
499      * The number is a DigitList wrapper onto a floating point decimal number.
500      * The default implementation in NumberFormat converts the decimal number
501      * to a double and formats that.  Subclasses of NumberFormat that want
502      * to specifically handle big decimal numbers must override this method.
503      * class DecimalFormat does so.
504      *
505      * @param number    The number, a DigitList format Decimal Floating Point.
506      * @param appendTo  Output parameter to receive result.
507      *                  Result is appended to existing contents.
508      * @param pos       On input: an alignment field, if desired.
509      *                  On output: the offsets of the alignment field.
510      * @param status    Output param filled with success/failure status.
511      * @return          Reference to 'appendTo' parameter.
512      * @internal
513      */
514     virtual UnicodeString& format(const DigitList &number,
515                                   UnicodeString& appendTo,
516                                   FieldPosition& pos,
517                                   UErrorCode& status) const;
518 
519 public:
520 
521     /**
522      * Redeclared Format method.
523      * @param obj       The object to be formatted.
524      * @param appendTo  Output parameter to receive result.
525      *                  Result is appended to existing contents.
526      * @param status    Output parameter set to a failure error code
527      *                  when a failure occurs.
528      * @return          Reference to 'appendTo' parameter.
529      * @stable ICU 2.0
530      */
531     UnicodeString& format(const Formattable& obj,
532                           UnicodeString& appendTo,
533                           UErrorCode& status) const;
534 
535    /**
536     * Return a long if possible (e.g. within range LONG_MAX,
537     * LONG_MAX], and with no decimals), otherwise a double.  If
538     * IntegerOnly is set, will stop at a decimal point (or equivalent;
539     * e.g. for rational numbers "1 2/3", will stop after the 1).
540     * <P>
541     * If no object can be parsed, index is unchanged, and NULL is
542     * returned.
543     * <P>
544     * This is a pure virtual which concrete subclasses must implement.
545     *
546     * @param text           The text to be parsed.
547     * @param result         Formattable to be set to the parse result.
548     *                       If parse fails, return contents are undefined.
549     * @param parsePosition  The position to start parsing at on input.
550     *                       On output, moved to after the last successfully
551     *                       parse character. On parse failure, does not change.
552     * @return               A Formattable object of numeric type.  The caller
553     *                       owns this an must delete it.  NULL on failure.
554     * @stable ICU 2.0
555     */
556     virtual void parse(const UnicodeString& text,
557                        Formattable& result,
558                        ParsePosition& parsePosition) const = 0;
559 
560     /**
561      * Parse a string as a numeric value, and return a Formattable
562      * numeric object. This method parses integers only if IntegerOnly
563      * is set.
564      *
565      * @param text          The text to be parsed.
566      * @param result        Formattable to be set to the parse result.
567      *                      If parse fails, return contents are undefined.
568      * @param status        Output parameter set to a failure error code
569      *                      when a failure occurs.
570      * @return              A Formattable object of numeric type.  The caller
571      *                      owns this an must delete it.  NULL on failure.
572      * @see                 NumberFormat::isParseIntegerOnly
573      * @stable ICU 2.0
574      */
575     virtual void parse( const UnicodeString& text,
576                         Formattable& result,
577                         UErrorCode& status) const;
578 
579     /**
580      * Parses text from the given string as a currency amount.  Unlike
581      * the parse() method, this method will attempt to parse a generic
582      * currency name, searching for a match of this object's locale's
583      * currency display names, or for a 3-letter ISO currency code.
584      * This method will fail if this format is not a currency format,
585      * that is, if it does not contain the currency pattern symbol
586      * (U+00A4) in its prefix or suffix.
587      *
588      * @param text the string to parse
589      * @param result output parameter to receive result. This will have
590      * its currency set to the parsed ISO currency code.
591      * @param pos input-output position; on input, the position within
592      * text to match; must have 0 <= pos.getIndex() < text.length();
593      * on output, the position after the last matched character. If
594      * the parse fails, the position in unchanged upon output.
595      * @return a reference to result
596      * @internal
597      */
598     virtual Formattable& parseCurrency(const UnicodeString& text,
599                                        Formattable& result,
600                                        ParsePosition& pos) const;
601 
602     /**
603      * Return true if this format will parse numbers as integers
604      * only.  For example in the English locale, with ParseIntegerOnly
605      * true, the string "1234." would be parsed as the integer value
606      * 1234 and parsing would stop at the "." character.  Of course,
607      * the exact format accepted by the parse operation is locale
608      * dependant and determined by sub-classes of NumberFormat.
609      * @return    true if this format will parse numbers as integers
610      *            only.
611      * @stable ICU 2.0
612      */
613     UBool isParseIntegerOnly(void) const;
614 
615     /**
616      * Sets whether or not numbers should be parsed as integers only.
617      * @param value    set True, this format will parse numbers as integers
618      *                 only.
619      * @see isParseIntegerOnly
620      * @stable ICU 2.0
621      */
622     virtual void setParseIntegerOnly(UBool value);
623 
624     /**
625      * Returns the default number format for the current default
626      * locale.  The default format is one of the styles provided by
627      * the other factory methods: getNumberInstance,
628      * getCurrencyInstance or getPercentInstance.  Exactly which one
629      * is locale dependant.
630      * @stable ICU 2.0
631      */
632     static NumberFormat* U_EXPORT2 createInstance(UErrorCode&);
633 
634     /**
635      * Returns the default number format for the specified locale.
636      * The default format is one of the styles provided by the other
637      * factory methods: getNumberInstance, getCurrencyInstance or
638      * getPercentInstance.  Exactly which one is locale dependant.
639      * @param inLocale    the given locale.
640      * @stable ICU 2.0
641      */
642     static NumberFormat* U_EXPORT2 createInstance(const Locale& inLocale,
643                                         UErrorCode&);
644 
645     /**
646      * Creates the specified decimal format style of the desired locale.
647      * @param desiredLocale    the given locale.
648      * @param choice           the given style.
649      * @param success          Output param filled with success/failure status.
650      * @return                 A new NumberFormat instance.
651      * @draft ICU 4.2
652      */
653     static NumberFormat* U_EXPORT2 createInstance(const Locale& desiredLocale, EStyles choice, UErrorCode& success);
654 
655 
656     /**
657      * Returns a currency format for the current default locale.
658      * @stable ICU 2.0
659      */
660     static NumberFormat* U_EXPORT2 createCurrencyInstance(UErrorCode&);
661 
662     /**
663      * Returns a currency format for the specified locale.
664      * @param inLocale    the given locale.
665      * @stable ICU 2.0
666      */
667     static NumberFormat* U_EXPORT2 createCurrencyInstance(const Locale& inLocale,
668                                                 UErrorCode&);
669 
670     /**
671      * Returns a percentage format for the current default locale.
672      * @stable ICU 2.0
673      */
674     static NumberFormat* U_EXPORT2 createPercentInstance(UErrorCode&);
675 
676     /**
677      * Returns a percentage format for the specified locale.
678      * @param inLocale    the given locale.
679      * @stable ICU 2.0
680      */
681     static NumberFormat* U_EXPORT2 createPercentInstance(const Locale& inLocale,
682                                                UErrorCode&);
683 
684     /**
685      * Returns a scientific format for the current default locale.
686      * @stable ICU 2.0
687      */
688     static NumberFormat* U_EXPORT2 createScientificInstance(UErrorCode&);
689 
690     /**
691      * Returns a scientific format for the specified locale.
692      * @param inLocale    the given locale.
693      * @stable ICU 2.0
694      */
695     static NumberFormat* U_EXPORT2 createScientificInstance(const Locale& inLocale,
696                                                 UErrorCode&);
697 
698     /**
699      * Get the set of Locales for which NumberFormats are installed.
700      * @param count    Output param to receive the size of the locales
701      * @stable ICU 2.0
702      */
703     static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
704 
705 #if !UCONFIG_NO_SERVICE
706     /**
707      * Register a new NumberFormatFactory.  The factory will be adopted.
708      * @param toAdopt the NumberFormatFactory instance to be adopted
709      * @param status the in/out status code, no special meanings are assigned
710      * @return a registry key that can be used to unregister this factory
711      * @stable ICU 2.6
712      */
713     static URegistryKey U_EXPORT2 registerFactory(NumberFormatFactory* toAdopt, UErrorCode& status);
714 
715     /**
716      * Unregister a previously-registered NumberFormatFactory using the key returned from the
717      * register call.  Key becomes invalid after a successful call and should not be used again.
718      * The NumberFormatFactory corresponding to the key will be deleted.
719      * @param key the registry key returned by a previous call to registerFactory
720      * @param status the in/out status code, no special meanings are assigned
721      * @return TRUE if the factory for the key was successfully unregistered
722      * @stable ICU 2.6
723      */
724     static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status);
725 
726     /**
727      * Return a StringEnumeration over the locales available at the time of the call,
728      * including registered locales.
729      * @return a StringEnumeration over the locales available at the time of the call
730      * @stable ICU 2.6
731      */
732     static StringEnumeration* U_EXPORT2 getAvailableLocales(void);
733 #endif /* UCONFIG_NO_SERVICE */
734 
735     /**
736      * Returns true if grouping is used in this format. For example,
737      * in the English locale, with grouping on, the number 1234567
738      * might be formatted as "1,234,567". The grouping separator as
739      * well as the size of each group is locale dependant and is
740      * determined by sub-classes of NumberFormat.
741      * @see setGroupingUsed
742      * @stable ICU 2.0
743      */
744     UBool isGroupingUsed(void) const;
745 
746     /**
747      * Set whether or not grouping will be used in this format.
748      * @param newValue    True, grouping will be used in this format.
749      * @see getGroupingUsed
750      * @stable ICU 2.0
751      */
752     virtual void setGroupingUsed(UBool newValue);
753 
754     /**
755      * Returns the maximum number of digits allowed in the integer portion of a
756      * number.
757      * @return     the maximum number of digits allowed in the integer portion of a
758      *             number.
759      * @see setMaximumIntegerDigits
760      * @stable ICU 2.0
761      */
762     int32_t getMaximumIntegerDigits(void) const;
763 
764     /**
765      * Sets the maximum number of digits allowed in the integer portion of a
766      * number. maximumIntegerDigits must be >= minimumIntegerDigits.  If the
767      * new value for maximumIntegerDigits is less than the current value
768      * of minimumIntegerDigits, then minimumIntegerDigits will also be set to
769      * the new value.
770      *
771      * @param newValue    the new value for the maximum number of digits
772      *                    allowed in the integer portion of a number.
773      * @see getMaximumIntegerDigits
774      * @stable ICU 2.0
775      */
776     virtual void setMaximumIntegerDigits(int32_t newValue);
777 
778     /**
779      * Returns the minimum number of digits allowed in the integer portion of a
780      * number.
781      * @return    the minimum number of digits allowed in the integer portion of a
782      *            number.
783      * @see setMinimumIntegerDigits
784      * @stable ICU 2.0
785      */
786     int32_t getMinimumIntegerDigits(void) const;
787 
788     /**
789      * Sets the minimum number of digits allowed in the integer portion of a
790      * number. minimumIntegerDigits must be &lt;= maximumIntegerDigits.  If the
791      * new value for minimumIntegerDigits exceeds the current value
792      * of maximumIntegerDigits, then maximumIntegerDigits will also be set to
793      * the new value.
794      * @param newValue    the new value to be set.
795      * @see getMinimumIntegerDigits
796      * @stable ICU 2.0
797      */
798     virtual void setMinimumIntegerDigits(int32_t newValue);
799 
800     /**
801      * Returns the maximum number of digits allowed in the fraction portion of a
802      * number.
803      * @return    the maximum number of digits allowed in the fraction portion of a
804      *            number.
805      * @see setMaximumFractionDigits
806      * @stable ICU 2.0
807      */
808     int32_t getMaximumFractionDigits(void) const;
809 
810     /**
811      * Sets the maximum number of digits allowed in the fraction portion of a
812      * number. maximumFractionDigits must be >= minimumFractionDigits.  If the
813      * new value for maximumFractionDigits is less than the current value
814      * of minimumFractionDigits, then minimumFractionDigits will also be set to
815      * the new value.
816      * @param newValue    the new value to be set.
817      * @see getMaximumFractionDigits
818      * @stable ICU 2.0
819      */
820     virtual void setMaximumFractionDigits(int32_t newValue);
821 
822     /**
823      * Returns the minimum number of digits allowed in the fraction portion of a
824      * number.
825      * @return    the minimum number of digits allowed in the fraction portion of a
826      *            number.
827      * @see setMinimumFractionDigits
828      * @stable ICU 2.0
829      */
830     int32_t getMinimumFractionDigits(void) const;
831 
832     /**
833      * Sets the minimum number of digits allowed in the fraction portion of a
834      * number. minimumFractionDigits must be &lt;= maximumFractionDigits.   If the
835      * new value for minimumFractionDigits exceeds the current value
836      * of maximumFractionDigits, then maximumIntegerDigits will also be set to
837      * the new value
838      * @param newValue    the new value to be set.
839      * @see getMinimumFractionDigits
840      * @stable ICU 2.0
841      */
842     virtual void setMinimumFractionDigits(int32_t newValue);
843 
844     /**
845      * Sets the currency used to display currency
846      * amounts.  This takes effect immediately, if this format is a
847      * currency format.  If this format is not a currency format, then
848      * the currency is used if and when this object becomes a
849      * currency format.
850      * @param theCurrency a 3-letter ISO code indicating new currency
851      * to use.  It need not be null-terminated.  May be the empty
852      * string or NULL to indicate no currency.
853      * @param ec input-output error code
854      * @stable ICU 3.0
855      */
856     virtual void setCurrency(const UChar* theCurrency, UErrorCode& ec);
857 
858     /**
859      * Gets the currency used to display currency
860      * amounts.  This may be an empty string for some subclasses.
861      * @return a 3-letter null-terminated ISO code indicating
862      * the currency in use, or a pointer to the empty string.
863      * @stable ICU 2.6
864      */
865     const UChar* getCurrency() const;
866 
867 public:
868 
869     /**
870      * Return the class ID for this class.  This is useful for
871      * comparing to a return value from getDynamicClassID(). Note that,
872      * because NumberFormat is an abstract base class, no fully constructed object
873      * will have the class ID returned by NumberFormat::getStaticClassID().
874      * @return The class ID for all objects of this class.
875      * @stable ICU 2.0
876      */
877     static UClassID U_EXPORT2 getStaticClassID(void);
878 
879     /**
880      * Returns a unique class ID POLYMORPHICALLY.  Pure virtual override.
881      * This method is to implement a simple version of RTTI, since not all
882      * C++ compilers support genuine RTTI.  Polymorphic operator==() and
883      * clone() methods call this method.
884      * <P>
885      * @return The class ID for this object. All objects of a
886      * given class have the same class ID.  Objects of
887      * other classes have different class IDs.
888      * @stable ICU 2.0
889      */
890     virtual UClassID getDynamicClassID(void) const = 0;
891 
892 protected:
893 
894     /**
895      * Default constructor for subclass use only.
896      * @stable ICU 2.0
897      */
898     NumberFormat();
899 
900     /**
901      * Copy constructor.
902      * @stable ICU 2.0
903      */
904     NumberFormat(const NumberFormat&);
905 
906     /**
907      * Assignment operator.
908      * @stable ICU 2.0
909      */
910     NumberFormat& operator=(const NumberFormat&);
911 
912     /**
913      * Returns the currency in effect for this formatter.  Subclasses
914      * should override this method as needed.  Unlike getCurrency(),
915      * this method should never return "".
916      * @result output parameter for null-terminated result, which must
917      * have a capacity of at least 4
918      * @internal
919      */
920     virtual void getEffectiveCurrency(UChar* result, UErrorCode& ec) const;
921 
922 private:
923 
924     /**
925      * Creates the specified decimal format style of the desired locale.
926      * @param desiredLocale    the given locale.
927      * @param choice           the given style.
928      * @param success          Output param filled with success/failure status.
929      * @return                 A new NumberFormat instance.
930      */
931     static NumberFormat* makeInstance(const Locale& desiredLocale, EStyles choice, UErrorCode& success);
932 
933     UBool      fGroupingUsed;
934     int32_t     fMaxIntegerDigits;
935     int32_t     fMinIntegerDigits;
936     int32_t     fMaxFractionDigits;
937     int32_t     fMinFractionDigits;
938     UBool      fParseIntegerOnly;
939 
940     // ISO currency code
941     UChar      fCurrency[4];
942 
943     friend class ICUNumberFormatFactory; // access to makeInstance, EStyles
944     friend class ICUNumberFormatService;
945 };
946 
947 #if !UCONFIG_NO_SERVICE
948 /**
949  * A NumberFormatFactory is used to register new number formats.  The factory
950  * should be able to create any of the predefined formats for each locale it
951  * supports.  When registered, the locales it supports extend or override the
952  * locale already supported by ICU.
953  *
954  * @stable ICU 2.6
955  */
956 class U_I18N_API NumberFormatFactory : public UObject {
957 public:
958 
959     /**
960      * Destructor
961      * @stable ICU 3.0
962      */
963     virtual ~NumberFormatFactory();
964 
965     /**
966      * Return true if this factory will be visible.  Default is true.
967      * If not visible, the locales supported by this factory will not
968      * be listed by getAvailableLocales.
969      * @stable ICU 2.6
970      */
971     virtual UBool visible(void) const = 0;
972 
973     /**
974      * Return the locale names directly supported by this factory.  The number of names
975      * is returned in count;
976      * @stable ICU 2.6
977      */
978     virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const = 0;
979 
980     /**
981      * Return a number format of the appropriate type.  If the locale
982      * is not supported, return null.  If the locale is supported, but
983      * the type is not provided by this service, return null.  Otherwise
984      * return an appropriate instance of NumberFormat.
985      * @stable ICU 2.6
986      */
987     virtual NumberFormat* createFormat(const Locale& loc, UNumberFormatStyle formatType) = 0;
988 };
989 
990 /**
991  * A NumberFormatFactory that supports a single locale.  It can be visible or invisible.
992  * @stable ICU 2.6
993  */
994 class U_I18N_API SimpleNumberFormatFactory : public NumberFormatFactory {
995 protected:
996     /**
997      * True if the locale supported by this factory is visible.
998      * @stable ICU 2.6
999      */
1000     const UBool _visible;
1001 
1002     /**
1003      * The locale supported by this factory, as a UnicodeString.
1004      * @stable ICU 2.6
1005      */
1006     UnicodeString _id;
1007 
1008 public:
1009     /**
1010      * @stable ICU 2.6
1011      */
1012     SimpleNumberFormatFactory(const Locale& locale, UBool visible = TRUE);
1013 
1014     /**
1015      * @stable ICU 3.0
1016      */
1017     virtual ~SimpleNumberFormatFactory();
1018 
1019     /**
1020      * @stable ICU 2.6
1021      */
1022     virtual UBool visible(void) const;
1023 
1024     /**
1025      * @stable ICU 2.6
1026      */
1027     virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const;
1028 };
1029 #endif /* #if !UCONFIG_NO_SERVICE */
1030 
1031 // -------------------------------------
1032 
1033 inline UBool
isParseIntegerOnly()1034 NumberFormat::isParseIntegerOnly() const
1035 {
1036     return fParseIntegerOnly;
1037 }
1038 
1039 inline UnicodeString&
format(const Formattable & obj,UnicodeString & appendTo,UErrorCode & status)1040 NumberFormat::format(const Formattable& obj,
1041                      UnicodeString& appendTo,
1042                      UErrorCode& status) const {
1043     return Format::format(obj, appendTo, status);
1044 }
1045 
1046 U_NAMESPACE_END
1047 
1048 #endif /* #if !UCONFIG_NO_FORMATTING */
1049 
1050 #endif // _NUMFMT
1051 //eof
1052