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 <= 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 <= 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