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