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