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-2015, International Business Machines Corporation and others.
6* All Rights Reserved.
7*******************************************************************************
8*/
9
10#ifndef RBNF_H
11#define RBNF_H
12
13#include "unicode/utypes.h"
14
15#if U_SHOW_CPLUSPLUS_API
16
17/**
18 * \file
19 * \brief C++ API: Rule Based Number Format
20 */
21
22/**
23 * \def U_HAVE_RBNF
24 * This will be 0 if RBNF support is not included in ICU
25 * and 1 if it is.
26 *
27 * @stable ICU 2.4
28 */
29#if UCONFIG_NO_FORMATTING
30#define U_HAVE_RBNF 0
31#else
32#define U_HAVE_RBNF 1
33
34#include "unicode/dcfmtsym.h"
35#include "unicode/fmtable.h"
36#include "unicode/locid.h"
37#include "unicode/numfmt.h"
38#include "unicode/unistr.h"
39#include "unicode/strenum.h"
40#include "unicode/brkiter.h"
41#include "unicode/upluralrules.h"
42
43U_NAMESPACE_BEGIN
44
45class NFRule;
46class NFRuleSet;
47class LocalizationInfo;
48class PluralFormat;
49class RuleBasedCollator;
50
51/**
52 * Tags for the predefined rulesets.
53 *
54 * @stable ICU 2.2
55 */
56enum URBNFRuleSetTag {
57 URBNF_SPELLOUT,
58 URBNF_ORDINAL,
59 URBNF_DURATION,
60 URBNF_NUMBERING_SYSTEM,
61#ifndef U_HIDE_DEPRECATED_API
62 /**
63 * One more than the highest normal URBNFRuleSetTag value.
64 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
65 */
66 URBNF_COUNT
67#endif // U_HIDE_DEPRECATED_API
68};
69
70/**
71 * The RuleBasedNumberFormat class formats numbers according to a set of rules. This number formatter is
72 * typically used for spelling out numeric values in words (e.g., 25,3476 as
73 * "twenty-five thousand three hundred seventy-six" or "vingt-cinq mille trois
74 * cents soixante-seize" or
75 * "fünfundzwanzigtausenddreihundertsechsundsiebzig"), but can also be used for
76 * other complicated formatting tasks, such as formatting a number of seconds as hours,
77 * minutes and seconds (e.g., 3,730 as "1:02:10").
78 *
79 * <p>The resources contain three predefined formatters for each locale: spellout, which
80 * spells out a value in words (123 is &quot;one hundred twenty-three&quot;); ordinal, which
81 * appends an ordinal suffix to the end of a numeral (123 is &quot;123rd&quot;); and
82 * duration, which shows a duration in seconds as hours, minutes, and seconds (123 is
83 * &quot;2:03&quot;).&nbsp; The client can also define more specialized <tt>RuleBasedNumberFormat</tt>s
84 * by supplying programmer-defined rule sets.</p>
85 *
86 * <p>The behavior of a <tt>RuleBasedNumberFormat</tt> is specified by a textual description
87 * that is either passed to the constructor as a <tt>String</tt> or loaded from a resource
88 * bundle. In its simplest form, the description consists of a semicolon-delimited list of <em>rules.</em>
89 * Each rule has a string of output text and a value or range of values it is applicable to.
90 * In a typical spellout rule set, the first twenty rules are the words for the numbers from
91 * 0 to 19:</p>
92 *
93 * <pre>zero; one; two; three; four; five; six; seven; eight; nine;
94 * ten; eleven; twelve; thirteen; fourteen; fifteen; sixteen; seventeen; eighteen; nineteen;</pre>
95 *
96 * <p>For larger numbers, we can use the preceding set of rules to format the ones place, and
97 * we only have to supply the words for the multiples of 10:</p>
98 *
99 * <pre> 20: twenty[-&gt;&gt;];
100 * 30: thirty[-&gt;&gt;];
101 * 40: forty[-&gt;&gt;];
102 * 50: fifty[-&gt;&gt;];
103 * 60: sixty[-&gt;&gt;];
104 * 70: seventy[-&gt;&gt;];
105 * 80: eighty[-&gt;&gt;];
106 * 90: ninety[-&gt;&gt;];</pre>
107 *
108 * <p>In these rules, the <em>base value</em> is spelled out explicitly and set off from the
109 * rule's output text with a colon. The rules are in a sorted list, and a rule is applicable
110 * to all numbers from its own base value to one less than the next rule's base value. The
111 * &quot;&gt;&gt;&quot; token is called a <em>substitution</em> and tells the fomatter to
112 * isolate the number's ones digit, format it using this same set of rules, and place the
113 * result at the position of the &quot;&gt;&gt;&quot; token. Text in brackets is omitted if
114 * the number being formatted is an even multiple of 10 (the hyphen is a literal hyphen; 24
115 * is &quot;twenty-four,&quot; not &quot;twenty four&quot;).</p>
116 *
117 * <p>For even larger numbers, we can actually look up several parts of the number in the
118 * list:</p>
119 *
120 * <pre>100: &lt;&lt; hundred[ &gt;&gt;];</pre>
121 *
122 * <p>The &quot;&lt;&lt;&quot; represents a new kind of substitution. The &lt;&lt; isolates
123 * the hundreds digit (and any digits to its left), formats it using this same rule set, and
124 * places the result where the &quot;&lt;&lt;&quot; was. Notice also that the meaning of
125 * &gt;&gt; has changed: it now refers to both the tens and the ones digits. The meaning of
126 * both substitutions depends on the rule's base value. The base value determines the rule's <em>divisor,</em>
127 * which is the highest power of 10 that is less than or equal to the base value (the user
128 * can change this). To fill in the substitutions, the formatter divides the number being
129 * formatted by the divisor. The integral quotient is used to fill in the &lt;&lt;
130 * substitution, and the remainder is used to fill in the &gt;&gt; substitution. The meaning
131 * of the brackets changes similarly: text in brackets is omitted if the value being
132 * formatted is an even multiple of the rule's divisor. The rules are applied recursively, so
133 * if a substitution is filled in with text that includes another substitution, that
134 * substitution is also filled in.</p>
135 *
136 * <p>This rule covers values up to 999, at which point we add another rule:</p>
137 *
138 * <pre>1000: &lt;&lt; thousand[ &gt;&gt;];</pre>
139 *
140 * <p>Again, the meanings of the brackets and substitution tokens shift because the rule's
141 * base value is a higher power of 10, changing the rule's divisor. This rule can actually be
142 * used all the way up to 999,999. This allows us to finish out the rules as follows:</p>
143 *
144 * <pre> 1,000,000: &lt;&lt; million[ &gt;&gt;];
145 * 1,000,000,000: &lt;&lt; billion[ &gt;&gt;];
146 * 1,000,000,000,000: &lt;&lt; trillion[ &gt;&gt;];
147 * 1,000,000,000,000,000: OUT OF RANGE!;</pre>
148 *
149 * <p>Commas, periods, and spaces can be used in the base values to improve legibility and
150 * are ignored by the rule parser. The last rule in the list is customarily treated as an
151 * &quot;overflow rule,&quot; applying to everything from its base value on up, and often (as
152 * in this example) being used to print out an error message or default representation.
153 * Notice also that the size of the major groupings in large numbers is controlled by the
154 * spacing of the rules: because in English we group numbers by thousand, the higher rules
155 * are separated from each other by a factor of 1,000.</p>
156 *
157 * <p>To see how these rules actually work in practice, consider the following example:
158 * Formatting 25,430 with this rule set would work like this:</p>
159 *
160 * <table border="0" width="100%">
161 * <tr>
162 * <td><strong>&lt;&lt; thousand &gt;&gt;</strong></td>
163 * <td>[the rule whose base value is 1,000 is applicable to 25,340]</td>
164 * </tr>
165 * <tr>
166 * <td><strong>twenty-&gt;&gt;</strong> thousand &gt;&gt;</td>
167 * <td>[25,340 over 1,000 is 25. The rule for 20 applies.]</td>
168 * </tr>
169 * <tr>
170 * <td>twenty-<strong>five</strong> thousand &gt;&gt;</td>
171 * <td>[25 mod 10 is 5. The rule for 5 is &quot;five.&quot;</td>
172 * </tr>
173 * <tr>
174 * <td>twenty-five thousand <strong>&lt;&lt; hundred &gt;&gt;</strong></td>
175 * <td>[25,340 mod 1,000 is 340. The rule for 100 applies.]</td>
176 * </tr>
177 * <tr>
178 * <td>twenty-five thousand <strong>three</strong> hundred &gt;&gt;</td>
179 * <td>[340 over 100 is 3. The rule for 3 is &quot;three.&quot;]</td>
180 * </tr>
181 * <tr>
182 * <td>twenty-five thousand three hundred <strong>forty</strong></td>
183 * <td>[340 mod 100 is 40. The rule for 40 applies. Since 40 divides
184 * evenly by 10, the hyphen and substitution in the brackets are omitted.]</td>
185 * </tr>
186 * </table>
187 *
188 * <p>The above syntax suffices only to format positive integers. To format negative numbers,
189 * we add a special rule:</p>
190 *
191 * <pre>-x: minus &gt;&gt;;</pre>
192 *
193 * <p>This is called a <em>negative-number rule,</em> and is identified by &quot;-x&quot;
194 * where the base value would be. This rule is used to format all negative numbers. the
195 * &gt;&gt; token here means &quot;find the number's absolute value, format it with these
196 * rules, and put the result here.&quot;</p>
197 *
198 * <p>We also add a special rule called a <em>fraction rule </em>for numbers with fractional
199 * parts:</p>
200 *
201 * <pre>x.x: &lt;&lt; point &gt;&gt;;</pre>
202 *
203 * <p>This rule is used for all positive non-integers (negative non-integers pass through the
204 * negative-number rule first and then through this rule). Here, the &lt;&lt; token refers to
205 * the number's integral part, and the &gt;&gt; to the number's fractional part. The
206 * fractional part is formatted as a series of single-digit numbers (e.g., 123.456 would be
207 * formatted as &quot;one hundred twenty-three point four five six&quot;).</p>
208 *
209 * <p>To see how this rule syntax is applied to various languages, examine the resource data.</p>
210 *
211 * <p>There is actually much more flexibility built into the rule language than the
212 * description above shows. A formatter may own multiple rule sets, which can be selected by
213 * the caller, and which can use each other to fill in their substitutions. Substitutions can
214 * also be filled in with digits, using a DecimalFormat object. There is syntax that can be
215 * used to alter a rule's divisor in various ways. And there is provision for much more
216 * flexible fraction handling. A complete description of the rule syntax follows:</p>
217 *
218 * <hr>
219 *
220 * <p>The description of a <tt>RuleBasedNumberFormat</tt>'s behavior consists of one or more <em>rule
221 * sets.</em> Each rule set consists of a name, a colon, and a list of <em>rules.</em> A rule
222 * set name must begin with a % sign. Rule sets with names that begin with a single % sign
223 * are <em>public:</em> the caller can specify that they be used to format and parse numbers.
224 * Rule sets with names that begin with %% are <em>private:</em> they exist only for the use
225 * of other rule sets. If a formatter only has one rule set, the name may be omitted.</p>
226 *
227 * <p>The user can also specify a special &quot;rule set&quot; named <tt>%%lenient-parse</tt>.
228 * The body of <tt>%%lenient-parse</tt> isn't a set of number-formatting rules, but a <tt>RuleBasedCollator</tt>
229 * description which is used to define equivalences for lenient parsing. For more information
230 * on the syntax, see <tt>RuleBasedCollator</tt>. For more information on lenient parsing,
231 * see <tt>setLenientParse()</tt>. <em>Note:</em> symbols that have syntactic meaning
232 * in collation rules, such as '&amp;', have no particular meaning when appearing outside
233 * of the <tt>lenient-parse</tt> rule set.</p>
234 *
235 * <p>The body of a rule set consists of an ordered, semicolon-delimited list of <em>rules.</em>
236 * Internally, every rule has a base value, a divisor, rule text, and zero, one, or two <em>substitutions.</em>
237 * These parameters are controlled by the description syntax, which consists of a <em>rule
238 * descriptor,</em> a colon, and a <em>rule body.</em></p>
239 *
240 * <p>A rule descriptor can take one of the following forms (text in <em>italics</em> is the
241 * name of a token):</p>
242 *
243 * <table border="0" width="100%">
244 * <tr>
245 * <td><em>bv</em>:</td>
246 * <td><em>bv</em> specifies the rule's base value. <em>bv</em> is a decimal
247 * number expressed using ASCII digits. <em>bv</em> may contain spaces, period, and commas,
248 * which are ignored. The rule's divisor is the highest power of 10 less than or equal to
249 * the base value.</td>
250 * </tr>
251 * <tr>
252 * <td><em>bv</em>/<em>rad</em>:</td>
253 * <td><em>bv</em> specifies the rule's base value. The rule's divisor is the
254 * highest power of <em>rad</em> less than or equal to the base value.</td>
255 * </tr>
256 * <tr>
257 * <td><em>bv</em>&gt;:</td>
258 * <td><em>bv</em> specifies the rule's base value. To calculate the divisor,
259 * let the radix be 10, and the exponent be the highest exponent of the radix that yields a
260 * result less than or equal to the base value. Every &gt; character after the base value
261 * decreases the exponent by 1. If the exponent is positive or 0, the divisor is the radix
262 * raised to the power of the exponent; otherwise, the divisor is 1.</td>
263 * </tr>
264 * <tr>
265 * <td><em>bv</em>/<em>rad</em>&gt;:</td>
266 * <td><em>bv</em> specifies the rule's base value. To calculate the divisor,
267 * let the radix be <em>rad</em>, and the exponent be the highest exponent of the radix that
268 * yields a result less than or equal to the base value. Every &gt; character after the radix
269 * decreases the exponent by 1. If the exponent is positive or 0, the divisor is the radix
270 * raised to the power of the exponent; otherwise, the divisor is 1.</td>
271 * </tr>
272 * <tr>
273 * <td>-x:</td>
274 * <td>The rule is a negative-number rule.</td>
275 * </tr>
276 * <tr>
277 * <td>x.x:</td>
278 * <td>The rule is an <em>improper fraction rule</em>. If the full stop in
279 * the middle of the rule name is replaced with the decimal point
280 * that is used in the language or DecimalFormatSymbols, then that rule will
281 * have precedence when formatting and parsing this rule. For example, some
282 * languages use the comma, and can thus be written as x,x instead. For example,
283 * you can use "x.x: &lt;&lt; point &gt;&gt;;x,x: &lt;&lt; comma &gt;&gt;;" to
284 * handle the decimal point that matches the language's natural spelling of
285 * the punctuation of either the full stop or comma.</td>
286 * </tr>
287 * <tr>
288 * <td>0.x:</td>
289 * <td>The rule is a <em>proper fraction rule</em>. If the full stop in
290 * the middle of the rule name is replaced with the decimal point
291 * that is used in the language or DecimalFormatSymbols, then that rule will
292 * have precedence when formatting and parsing this rule. For example, some
293 * languages use the comma, and can thus be written as 0,x instead. For example,
294 * you can use "0.x: point &gt;&gt;;0,x: comma &gt;&gt;;" to
295 * handle the decimal point that matches the language's natural spelling of
296 * the punctuation of either the full stop or comma.</td>
297 * </tr>
298 * <tr>
299 * <td>x.0:</td>
300 * <td>The rule is a <em>master rule</em>. If the full stop in
301 * the middle of the rule name is replaced with the decimal point
302 * that is used in the language or DecimalFormatSymbols, then that rule will
303 * have precedence when formatting and parsing this rule. For example, some
304 * languages use the comma, and can thus be written as x,0 instead. For example,
305 * you can use "x.0: &lt;&lt; point;x,0: &lt;&lt; comma;" to
306 * handle the decimal point that matches the language's natural spelling of
307 * the punctuation of either the full stop or comma.</td>
308 * </tr>
309 * <tr>
310 * <td>Inf:</td>
311 * <td>The rule for infinity.</td>
312 * </tr>
313 * <tr>
314 * <td>NaN:</td>
315 * <td>The rule for an IEEE 754 NaN (not a number).</td>
316 * </tr>
317 * <tr>
318 * <td><em>nothing</em></td>
319 * <td>If the rule's rule descriptor is left out, the base value is one plus the
320 * preceding rule's base value (or zero if this is the first rule in the list) in a normal
321 * rule set.&nbsp; In a fraction rule set, the base value is the same as the preceding rule's
322 * base value.</td>
323 * </tr>
324 * </table>
325 *
326 * <p>A rule set may be either a regular rule set or a <em>fraction rule set,</em> depending
327 * on whether it is used to format a number's integral part (or the whole number) or a
328 * number's fractional part. Using a rule set to format a rule's fractional part makes it a
329 * fraction rule set.</p>
330 *
331 * <p>Which rule is used to format a number is defined according to one of the following
332 * algorithms: If the rule set is a regular rule set, do the following:
333 *
334 * <ul>
335 * <li>If the rule set includes a master rule (and the number was passed in as a <tt>double</tt>),
336 * use the master rule.&nbsp; (If the number being formatted was passed in as a <tt>long</tt>,
337 * the master rule is ignored.)</li>
338 * <li>If the number is negative, use the negative-number rule.</li>
339 * <li>If the number has a fractional part and is greater than 1, use the improper fraction
340 * rule.</li>
341 * <li>If the number has a fractional part and is between 0 and 1, use the proper fraction
342 * rule.</li>
343 * <li>Binary-search the rule list for the rule with the highest base value less than or equal
344 * to the number. If that rule has two substitutions, its base value is not an even multiple
345 * of its divisor, and the number <em>is</em> an even multiple of the rule's divisor, use the
346 * rule that precedes it in the rule list. Otherwise, use the rule itself.</li>
347 * </ul>
348 *
349 * <p>If the rule set is a fraction rule set, do the following:
350 *
351 * <ul>
352 * <li>Ignore negative-number and fraction rules.</li>
353 * <li>For each rule in the list, multiply the number being formatted (which will always be
354 * between 0 and 1) by the rule's base value. Keep track of the distance between the result
355 * the nearest integer.</li>
356 * <li>Use the rule that produced the result closest to zero in the above calculation. In the
357 * event of a tie or a direct hit, use the first matching rule encountered. (The idea here is
358 * to try each rule's base value as a possible denominator of a fraction. Whichever
359 * denominator produces the fraction closest in value to the number being formatted wins.) If
360 * the rule following the matching rule has the same base value, use it if the numerator of
361 * the fraction is anything other than 1; if the numerator is 1, use the original matching
362 * rule. (This is to allow singular and plural forms of the rule text without a lot of extra
363 * hassle.)</li>
364 * </ul>
365 *
366 * <p>A rule's body consists of a string of characters terminated by a semicolon. The rule
367 * may include zero, one, or two <em>substitution tokens,</em> and a range of text in
368 * brackets. The brackets denote optional text (and may also include one or both
369 * substitutions). The exact meanings of the substitution tokens, and under what conditions
370 * optional text is omitted, depend on the syntax of the substitution token and the context.
371 * The rest of the text in a rule body is literal text that is output when the rule matches
372 * the number being formatted.</p>
373 *
374 * <p>A substitution token begins and ends with a <em>token character.</em> The token
375 * character and the context together specify a mathematical operation to be performed on the
376 * number being formatted. An optional <em>substitution descriptor </em>specifies how the
377 * value resulting from that operation is used to fill in the substitution. The position of
378 * the substitution token in the rule body specifies the location of the resultant text in
379 * the original rule text.</p>
380 *
381 * <p>The meanings of the substitution token characters are as follows:</p>
382 *
383 * <table border="0" width="100%">
384 * <tr>
385 * <td>&gt;&gt;</td>
386 * <td>in normal rule</td>
387 * <td>Divide the number by the rule's divisor and format the remainder</td>
388 * </tr>
389 * <tr>
390 * <td></td>
391 * <td>in negative-number rule</td>
392 * <td>Find the absolute value of the number and format the result</td>
393 * </tr>
394 * <tr>
395 * <td></td>
396 * <td>in fraction or master rule</td>
397 * <td>Isolate the number's fractional part and format it.</td>
398 * </tr>
399 * <tr>
400 * <td></td>
401 * <td>in rule in fraction rule set</td>
402 * <td>Not allowed.</td>
403 * </tr>
404 * <tr>
405 * <td>&gt;&gt;&gt;</td>
406 * <td>in normal rule</td>
407 * <td>Divide the number by the rule's divisor and format the remainder,
408 * but bypass the normal rule-selection process and just use the
409 * rule that precedes this one in this rule list.</td>
410 * </tr>
411 * <tr>
412 * <td></td>
413 * <td>in all other rules</td>
414 * <td>Not allowed.</td>
415 * </tr>
416 * <tr>
417 * <td>&lt;&lt;</td>
418 * <td>in normal rule</td>
419 * <td>Divide the number by the rule's divisor and format the quotient</td>
420 * </tr>
421 * <tr>
422 * <td></td>
423 * <td>in negative-number rule</td>
424 * <td>Not allowed.</td>
425 * </tr>
426 * <tr>
427 * <td></td>
428 * <td>in fraction or master rule</td>
429 * <td>Isolate the number's integral part and format it.</td>
430 * </tr>
431 * <tr>
432 * <td></td>
433 * <td>in rule in fraction rule set</td>
434 * <td>Multiply the number by the rule's base value and format the result.</td>
435 * </tr>
436 * <tr>
437 * <td>==</td>
438 * <td>in all rule sets</td>
439 * <td>Format the number unchanged</td>
440 * </tr>
441 * <tr>
442 * <td>[]</td>
443 * <td>in normal rule</td>
444 * <td>Omit the optional text if the number is an even multiple of the rule's divisor</td>
445 * </tr>
446 * <tr>
447 * <td></td>
448 * <td>in negative-number rule</td>
449 * <td>Not allowed.</td>
450 * </tr>
451 * <tr>
452 * <td></td>
453 * <td>in improper-fraction rule</td>
454 * <td>Omit the optional text if the number is between 0 and 1 (same as specifying both an
455 * x.x rule and a 0.x rule)</td>
456 * </tr>
457 * <tr>
458 * <td></td>
459 * <td>in master rule</td>
460 * <td>Omit the optional text if the number is an integer (same as specifying both an x.x
461 * rule and an x.0 rule)</td>
462 * </tr>
463 * <tr>
464 * <td></td>
465 * <td>in proper-fraction rule</td>
466 * <td>Not allowed.</td>
467 * </tr>
468 * <tr>
469 * <td></td>
470 * <td>in rule in fraction rule set</td>
471 * <td>Omit the optional text if multiplying the number by the rule's base value yields 1.</td>
472 * </tr>
473 * <tr>
474 * <td width="37">$(cardinal,<i>plural syntax</i>)$</td>
475 * <td width="23"></td>
476 * <td width="165" valign="top">in all rule sets</td>
477 * <td>This provides the ability to choose a word based on the number divided by the radix to the power of the
478 * exponent of the base value for the specified locale, which is normally equivalent to the &lt;&lt; value.
479 * This uses the cardinal plural rules from PluralFormat. All strings used in the plural format are treated
480 * as the same base value for parsing.</td>
481 * </tr>
482 * <tr>
483 * <td width="37">$(ordinal,<i>plural syntax</i>)$</td>
484 * <td width="23"></td>
485 * <td width="165" valign="top">in all rule sets</td>
486 * <td>This provides the ability to choose a word based on the number divided by the radix to the power of the
487 * exponent of the base value for the specified locale, which is normally equivalent to the &lt;&lt; value.
488 * This uses the ordinal plural rules from PluralFormat. All strings used in the plural format are treated
489 * as the same base value for parsing.</td>
490 * </tr>
491 * </table>
492 *
493 * <p>The substitution descriptor (i.e., the text between the token characters) may take one
494 * of three forms:</p>
495 *
496 * <table border="0" width="100%">
497 * <tr>
498 * <td>a rule set name</td>
499 * <td>Perform the mathematical operation on the number, and format the result using the
500 * named rule set.</td>
501 * </tr>
502 * <tr>
503 * <td>a DecimalFormat pattern</td>
504 * <td>Perform the mathematical operation on the number, and format the result using a
505 * DecimalFormat with the specified pattern.&nbsp; The pattern must begin with 0 or #.</td>
506 * </tr>
507 * <tr>
508 * <td>nothing</td>
509 * <td>Perform the mathematical operation on the number, and format the result using the rule
510 * set containing the current rule, except:
511 * <ul>
512 * <li>You can't have an empty substitution descriptor with a == substitution.</li>
513 * <li>If you omit the substitution descriptor in a &gt;&gt; substitution in a fraction rule,
514 * format the result one digit at a time using the rule set containing the current rule.</li>
515 * <li>If you omit the substitution descriptor in a &lt;&lt; substitution in a rule in a
516 * fraction rule set, format the result using the default rule set for this formatter.</li>
517 * </ul>
518 * </td>
519 * </tr>
520 * </table>
521 *
522 * <p>Whitespace is ignored between a rule set name and a rule set body, between a rule
523 * descriptor and a rule body, or between rules. If a rule body begins with an apostrophe,
524 * the apostrophe is ignored, but all text after it becomes significant (this is how you can
525 * have a rule's rule text begin with whitespace). There is no escape function: the semicolon
526 * is not allowed in rule set names or in rule text, and the colon is not allowed in rule set
527 * names. The characters beginning a substitution token are always treated as the beginning
528 * of a substitution token.</p>
529 *
530 * <p>See the resource data and the demo program for annotated examples of real rule sets
531 * using these features.</p>
532 *
533 * <p><em>User subclasses are not supported.</em> While clients may write
534 * subclasses, such code will not necessarily work and will not be
535 * guaranteed to work stably from release to release.
536 *
537 * <p><b>Localizations</b></p>
538 * <p>Constructors are available that allow the specification of localizations for the
539 * public rule sets (and also allow more control over what public rule sets are available).
540 * Localization data is represented as a textual description. The description represents
541 * an array of arrays of string. The first element is an array of the public rule set names,
542 * each of these must be one of the public rule set names that appear in the rules. Only
543 * names in this array will be treated as public rule set names by the API. Each subsequent
544 * element is an array of localizations of these names. The first element of one of these
545 * subarrays is the locale name, and the remaining elements are localizations of the
546 * public rule set names, in the same order as they were listed in the first arrray.</p>
547 * <p>In the syntax, angle brackets '<', '>' are used to delimit the arrays, and comma ',' is used
548 * to separate elements of an array. Whitespace is ignored, unless quoted.</p>
549 * <p>For example:<pre>
550 * < < %foo, %bar, %baz >,
551 * < en, Foo, Bar, Baz >,
552 * < fr, 'le Foo', 'le Bar', 'le Baz' >
553 * < zh, \\u7532, \\u4e59, \\u4e19 > >
554 * </pre></p>
555 * @author Richard Gillam
556 * @see NumberFormat
557 * @see DecimalFormat
558 * @see PluralFormat
559 * @see PluralRules
560 * @stable ICU 2.0
561 */
562class U_I18N_API RuleBasedNumberFormat : public NumberFormat {
563public:
564
565 //-----------------------------------------------------------------------
566 // constructors
567 //-----------------------------------------------------------------------
568
569 /**
570 * Creates a RuleBasedNumberFormat that behaves according to the description
571 * passed in. The formatter uses the default locale.
572 * @param rules A description of the formatter's desired behavior.
573 * See the class documentation for a complete explanation of the description
574 * syntax.
575 * @param perror The parse error if an error was encountered.
576 * @param status The status indicating whether the constructor succeeded.
577 * @stable ICU 3.2
578 */
579 RuleBasedNumberFormat(const UnicodeString& rules, UParseError& perror, UErrorCode& status);
580
581 /**
582 * Creates a RuleBasedNumberFormat that behaves according to the description
583 * passed in. The formatter uses the default locale.
584 * <p>
585 * The localizations data provides information about the public
586 * rule sets and their localized display names for different
587 * locales. The first element in the list is an array of the names
588 * of the public rule sets. The first element in this array is
589 * the initial default ruleset. The remaining elements in the
590 * list are arrays of localizations of the names of the public
591 * rule sets. Each of these is one longer than the initial array,
592 * with the first String being the ULocale ID, and the remaining
593 * Strings being the localizations of the rule set names, in the
594 * same order as the initial array. Arrays are NULL-terminated.
595 * @param rules A description of the formatter's desired behavior.
596 * See the class documentation for a complete explanation of the description
597 * syntax.
598 * @param localizations the localization information.
599 * names in the description. These will be copied by the constructor.
600 * @param perror The parse error if an error was encountered.
601 * @param status The status indicating whether the constructor succeeded.
602 * @stable ICU 3.2
603 */
604 RuleBasedNumberFormat(const UnicodeString& rules, const UnicodeString& localizations,
605 UParseError& perror, UErrorCode& status);
606
607 /**
608 * Creates a RuleBasedNumberFormat that behaves according to the rules
609 * passed in. The formatter uses the specified locale to determine the
610 * characters to use when formatting numerals, and to define equivalences
611 * for lenient parsing.
612 * @param rules The formatter rules.
613 * See the class documentation for a complete explanation of the rule
614 * syntax.
615 * @param locale A locale that governs which characters are used for
616 * formatting values in numerals and which characters are equivalent in
617 * lenient parsing.
618 * @param perror The parse error if an error was encountered.
619 * @param status The status indicating whether the constructor succeeded.
620 * @stable ICU 2.0
621 */
622 RuleBasedNumberFormat(const UnicodeString& rules, const Locale& locale,
623 UParseError& perror, UErrorCode& status);
624
625 /**
626 * Creates a RuleBasedNumberFormat that behaves according to the description
627 * passed in. The formatter uses the default locale.
628 * <p>
629 * The localizations data provides information about the public
630 * rule sets and their localized display names for different
631 * locales. The first element in the list is an array of the names
632 * of the public rule sets. The first element in this array is
633 * the initial default ruleset. The remaining elements in the
634 * list are arrays of localizations of the names of the public
635 * rule sets. Each of these is one longer than the initial array,
636 * with the first String being the ULocale ID, and the remaining
637 * Strings being the localizations of the rule set names, in the
638 * same order as the initial array. Arrays are NULL-terminated.
639 * @param rules A description of the formatter's desired behavior.
640 * See the class documentation for a complete explanation of the description
641 * syntax.
642 * @param localizations a list of localizations for the rule set
643 * names in the description. These will be copied by the constructor.
644 * @param locale A locale that governs which characters are used for
645 * formatting values in numerals and which characters are equivalent in
646 * lenient parsing.
647 * @param perror The parse error if an error was encountered.
648 * @param status The status indicating whether the constructor succeeded.
649 * @stable ICU 3.2
650 */
651 RuleBasedNumberFormat(const UnicodeString& rules, const UnicodeString& localizations,
652 const Locale& locale, UParseError& perror, UErrorCode& status);
653
654 /**
655 * Creates a RuleBasedNumberFormat from a predefined ruleset. The selector
656 * code choosed among three possible predefined formats: spellout, ordinal,
657 * and duration.
658 * @param tag A selector code specifying which kind of formatter to create for that
659 * locale. There are four legal values: URBNF_SPELLOUT, which creates a formatter that
660 * spells out a value in words in the desired language, URBNF_ORDINAL, which attaches
661 * an ordinal suffix from the desired language to the end of a number (e.g. "123rd"),
662 * URBNF_DURATION, which formats a duration in seconds as hours, minutes, and seconds always rounding down,
663 * and URBNF_NUMBERING_SYSTEM, which is used to invoke rules for alternate numbering
664 * systems such as the Hebrew numbering system, or for Roman Numerals, etc.
665 * @param locale The locale for the formatter.
666 * @param status The status indicating whether the constructor succeeded.
667 * @stable ICU 2.0
668 */
669 RuleBasedNumberFormat(URBNFRuleSetTag tag, const Locale& locale, UErrorCode& status);
670
671 //-----------------------------------------------------------------------
672 // boilerplate
673 //-----------------------------------------------------------------------
674
675 /**
676 * Copy constructor
677 * @param rhs the object to be copied from.
678 * @stable ICU 2.6
679 */
680 RuleBasedNumberFormat(const RuleBasedNumberFormat& rhs);
681
682 /**
683 * Assignment operator
684 * @param rhs the object to be copied from.
685 * @stable ICU 2.6
686 */
687 RuleBasedNumberFormat& operator=(const RuleBasedNumberFormat& rhs);
688
689 /**
690 * Release memory allocated for a RuleBasedNumberFormat when you are finished with it.
691 * @stable ICU 2.6
692 */
693 virtual ~RuleBasedNumberFormat();
694
695 /**
696 * Clone this object polymorphically. The caller is responsible
697 * for deleting the result when done.
698 * @return A copy of the object.
699 * @stable ICU 2.6
700 */
701 virtual RuleBasedNumberFormat* clone() const;
702
703 /**
704 * Return true if the given Format objects are semantically equal.
705 * Objects of different subclasses are considered unequal.
706 * @param other the object to be compared with.
707 * @return true if the given Format objects are semantically equal.
708 * @stable ICU 2.6
709 */
710 virtual UBool operator==(const Format& other) const;
711
712//-----------------------------------------------------------------------
713// public API functions
714//-----------------------------------------------------------------------
715
716 /**
717 * return the rules that were provided to the RuleBasedNumberFormat.
718 * @return the result String that was passed in
719 * @stable ICU 2.0
720 */
721 virtual UnicodeString getRules() const;
722
723 /**
724 * Return the number of public rule set names.
725 * @return the number of public rule set names.
726 * @stable ICU 2.0
727 */
728 virtual int32_t getNumberOfRuleSetNames() const;
729
730 /**
731 * Return the name of the index'th public ruleSet. If index is not valid,
732 * the function returns null.
733 * @param index the index of the ruleset
734 * @return the name of the index'th public ruleSet.
735 * @stable ICU 2.0
736 */
737 virtual UnicodeString getRuleSetName(int32_t index) const;
738
739 /**
740 * Return the number of locales for which we have localized rule set display names.
741 * @return the number of locales for which we have localized rule set display names.
742 * @stable ICU 3.2
743 */
744 virtual int32_t getNumberOfRuleSetDisplayNameLocales(void) const;
745
746 /**
747 * Return the index'th display name locale.
748 * @param index the index of the locale
749 * @param status set to a failure code when this function fails
750 * @return the locale
751 * @see #getNumberOfRuleSetDisplayNameLocales
752 * @stable ICU 3.2
753 */
754 virtual Locale getRuleSetDisplayNameLocale(int32_t index, UErrorCode& status) const;
755
756 /**
757 * Return the rule set display names for the provided locale. These are in the same order
758 * as those returned by getRuleSetName. The locale is matched against the locales for
759 * which there is display name data, using normal fallback rules. If no locale matches,
760 * the default display names are returned. (These are the internal rule set names minus
761 * the leading '%'.)
762 * @param index the index of the rule set
763 * @param locale the locale (returned by getRuleSetDisplayNameLocales) for which the localized
764 * display name is desired
765 * @return the display name for the given index, which might be bogus if there is an error
766 * @see #getRuleSetName
767 * @stable ICU 3.2
768 */
769 virtual UnicodeString getRuleSetDisplayName(int32_t index,
770 const Locale& locale = Locale::getDefault());
771
772 /**
773 * Return the rule set display name for the provided rule set and locale.
774 * The locale is matched against the locales for which there is display name data, using
775 * normal fallback rules. If no locale matches, the default display name is returned.
776 * @return the display name for the rule set
777 * @stable ICU 3.2
778 * @see #getRuleSetDisplayName
779 */
780 virtual UnicodeString getRuleSetDisplayName(const UnicodeString& ruleSetName,
781 const Locale& locale = Locale::getDefault());
782
783
784 using NumberFormat::format;
785
786 /**
787 * Formats the specified 32-bit number using the default ruleset.
788 * @param number The number to format.
789 * @param toAppendTo the string that will hold the (appended) result
790 * @param pos the fieldposition
791 * @return A textual representation of the number.
792 * @stable ICU 2.0
793 */
794 virtual UnicodeString& format(int32_t number,
795 UnicodeString& toAppendTo,
796 FieldPosition& pos) const;
797
798 /**
799 * Formats the specified 64-bit number using the default ruleset.
800 * @param number The number to format.
801 * @param toAppendTo the string that will hold the (appended) result
802 * @param pos the fieldposition
803 * @return A textual representation of the number.
804 * @stable ICU 2.1
805 */
806 virtual UnicodeString& format(int64_t number,
807 UnicodeString& toAppendTo,
808 FieldPosition& pos) const;
809 /**
810 * Formats the specified number using the default ruleset.
811 * @param number The number to format.
812 * @param toAppendTo the string that will hold the (appended) result
813 * @param pos the fieldposition
814 * @return A textual representation of the number.
815 * @stable ICU 2.0
816 */
817 virtual UnicodeString& format(double number,
818 UnicodeString& toAppendTo,
819 FieldPosition& pos) const;
820
821 /**
822 * Formats the specified number using the named ruleset.
823 * @param number The number to format.
824 * @param ruleSetName The name of the rule set to format the number with.
825 * This must be the name of a valid public rule set for this formatter.
826 * @param toAppendTo the string that will hold the (appended) result
827 * @param pos the fieldposition
828 * @param status the status
829 * @return A textual representation of the number.
830 * @stable ICU 2.0
831 */
832 virtual UnicodeString& format(int32_t number,
833 const UnicodeString& ruleSetName,
834 UnicodeString& toAppendTo,
835 FieldPosition& pos,
836 UErrorCode& status) const;
837 /**
838 * Formats the specified 64-bit number using the named ruleset.
839 * @param number The number to format.
840 * @param ruleSetName The name of the rule set to format the number with.
841 * This must be the name of a valid public rule set for this formatter.
842 * @param toAppendTo the string that will hold the (appended) result
843 * @param pos the fieldposition
844 * @param status the status
845 * @return A textual representation of the number.
846 * @stable ICU 2.1
847 */
848 virtual UnicodeString& format(int64_t number,
849 const UnicodeString& ruleSetName,
850 UnicodeString& toAppendTo,
851 FieldPosition& pos,
852 UErrorCode& status) const;
853 /**
854 * Formats the specified number using the named ruleset.
855 * @param number The number to format.
856 * @param ruleSetName The name of the rule set to format the number with.
857 * This must be the name of a valid public rule set for this formatter.
858 * @param toAppendTo the string that will hold the (appended) result
859 * @param pos the fieldposition
860 * @param status the status
861 * @return A textual representation of the number.
862 * @stable ICU 2.0
863 */
864 virtual UnicodeString& format(double number,
865 const UnicodeString& ruleSetName,
866 UnicodeString& toAppendTo,
867 FieldPosition& pos,
868 UErrorCode& status) const;
869
870protected:
871 /**
872 * Format a decimal number.
873 * The number is a DigitList wrapper onto a floating point decimal number.
874 * The default implementation in NumberFormat converts the decimal number
875 * to a double and formats that. Subclasses of NumberFormat that want
876 * to specifically handle big decimal numbers must override this method.
877 * class DecimalFormat does so.
878 *
879 * @param number The number, a DigitList format Decimal Floating Point.
880 * @param appendTo Output parameter to receive result.
881 * Result is appended to existing contents.
882 * @param pos On input: an alignment field, if desired.
883 * On output: the offsets of the alignment field.
884 * @param status Output param filled with success/failure status.
885 * @return Reference to 'appendTo' parameter.
886 * @internal
887 */
888 virtual UnicodeString& format(const number::impl::DecimalQuantity &number,
889 UnicodeString& appendTo,
890 FieldPosition& pos,
891 UErrorCode& status) const;
892public:
893
894 using NumberFormat::parse;
895
896 /**
897 * Parses the specfied string, beginning at the specified position, according
898 * to this formatter's rules. This will match the string against all of the
899 * formatter's public rule sets and return the value corresponding to the longest
900 * parseable substring. This function's behavior is affected by the lenient
901 * parse mode.
902 * @param text The string to parse
903 * @param result the result of the parse, either a double or a long.
904 * @param parsePosition On entry, contains the position of the first character
905 * in "text" to examine. On exit, has been updated to contain the position
906 * of the first character in "text" that wasn't consumed by the parse.
907 * @see #setLenient
908 * @stable ICU 2.0
909 */
910 virtual void parse(const UnicodeString& text,
911 Formattable& result,
912 ParsePosition& parsePosition) const;
913
914#if !UCONFIG_NO_COLLATION
915
916 /**
917 * Turns lenient parse mode on and off.
918 *
919 * When in lenient parse mode, the formatter uses a Collator for parsing the text.
920 * Only primary differences are treated as significant. This means that case
921 * differences, accent differences, alternate spellings of the same letter
922 * (e.g., ae and a-umlaut in German), ignorable characters, etc. are ignored in
923 * matching the text. In many cases, numerals will be accepted in place of words
924 * or phrases as well.
925 *
926 * For example, all of the following will correctly parse as 255 in English in
927 * lenient-parse mode:
928 * <br>"two hundred fifty-five"
929 * <br>"two hundred fifty five"
930 * <br>"TWO HUNDRED FIFTY-FIVE"
931 * <br>"twohundredfiftyfive"
932 * <br>"2 hundred fifty-5"
933 *
934 * The Collator used is determined by the locale that was
935 * passed to this object on construction. The description passed to this object
936 * on construction may supply additional collation rules that are appended to the
937 * end of the default collator for the locale, enabling additional equivalences
938 * (such as adding more ignorable characters or permitting spelled-out version of
939 * symbols; see the demo program for examples).
940 *
941 * It's important to emphasize that even strict parsing is relatively lenient: it
942 * will accept some text that it won't produce as output. In English, for example,
943 * it will correctly parse "two hundred zero" and "fifteen hundred".
944 *
945 * @param enabled If true, turns lenient-parse mode on; if false, turns it off.
946 * @see RuleBasedCollator
947 * @stable ICU 2.0
948 */
949 virtual void setLenient(UBool enabled);
950
951 /**
952 * Returns true if lenient-parse mode is turned on. Lenient parsing is off
953 * by default.
954 * @return true if lenient-parse mode is turned on.
955 * @see #setLenient
956 * @stable ICU 2.0
957 */
958 virtual inline UBool isLenient(void) const;
959
960#endif
961
962 /**
963 * Override the default rule set to use. If ruleSetName is null, reset
964 * to the initial default rule set. If the rule set is not a public rule set name,
965 * U_ILLEGAL_ARGUMENT_ERROR is returned in status.
966 * @param ruleSetName the name of the rule set, or null to reset the initial default.
967 * @param status set to failure code when a problem occurs.
968 * @stable ICU 2.6
969 */
970 virtual void setDefaultRuleSet(const UnicodeString& ruleSetName, UErrorCode& status);
971
972 /**
973 * Return the name of the current default rule set. If the current rule set is
974 * not public, returns a bogus (and empty) UnicodeString.
975 * @return the name of the current default rule set
976 * @stable ICU 3.0
977 */
978 virtual UnicodeString getDefaultRuleSetName() const;
979
980 /**
981 * Set a particular UDisplayContext value in the formatter, such as
982 * UDISPCTX_CAPITALIZATION_FOR_STANDALONE. Note: For getContext, see
983 * NumberFormat.
984 * @param value The UDisplayContext value to set.
985 * @param status Input/output status. If at entry this indicates a failure
986 * status, the function will do nothing; otherwise this will be
987 * updated with any new status from the function.
988 * @stable ICU 53
989 */
990 virtual void setContext(UDisplayContext value, UErrorCode& status);
991
992 /**
993 * Get the rounding mode.
994 * @return A rounding mode
995 * @stable ICU 60
996 */
997 virtual ERoundingMode getRoundingMode(void) const;
998
999 /**
1000 * Set the rounding mode.
1001 * @param roundingMode A rounding mode
1002 * @stable ICU 60
1003 */
1004 virtual void setRoundingMode(ERoundingMode roundingMode);
1005
1006public:
1007 /**
1008 * ICU "poor man's RTTI", returns a UClassID for this class.
1009 *
1010 * @stable ICU 2.8
1011 */
1012 static UClassID U_EXPORT2 getStaticClassID(void);
1013
1014 /**
1015 * ICU "poor man's RTTI", returns a UClassID for the actual class.
1016 *
1017 * @stable ICU 2.8
1018 */
1019 virtual UClassID getDynamicClassID(void) const;
1020
1021 /**
1022 * Sets the decimal format symbols, which is generally not changed
1023 * by the programmer or user. The formatter takes ownership of
1024 * symbolsToAdopt; the client must not delete it.
1025 *
1026 * @param symbolsToAdopt DecimalFormatSymbols to be adopted.
1027 * @stable ICU 49
1028 */
1029 virtual void adoptDecimalFormatSymbols(DecimalFormatSymbols* symbolsToAdopt);
1030
1031 /**
1032 * Sets the decimal format symbols, which is generally not changed
1033 * by the programmer or user. A clone of the symbols is created and
1034 * the symbols is _not_ adopted; the client is still responsible for
1035 * deleting it.
1036 *
1037 * @param symbols DecimalFormatSymbols.
1038 * @stable ICU 49
1039 */
1040 virtual void setDecimalFormatSymbols(const DecimalFormatSymbols& symbols);
1041
1042private:
1043 RuleBasedNumberFormat(); // default constructor not implemented
1044
1045 // this will ref the localizations if they are not NULL
1046 // caller must deref to get adoption
1047 RuleBasedNumberFormat(const UnicodeString& description, LocalizationInfo* localizations,
1048 const Locale& locale, UParseError& perror, UErrorCode& status);
1049
1050 void init(const UnicodeString& rules, LocalizationInfo* localizations, UParseError& perror, UErrorCode& status);
1051 void initCapitalizationContextInfo(const Locale& thelocale);
1052 void dispose();
1053 void stripWhitespace(UnicodeString& src);
1054 void initDefaultRuleSet();
1055 NFRuleSet* findRuleSet(const UnicodeString& name, UErrorCode& status) const;
1056
1057 /* friend access */
1058 friend class NFSubstitution;
1059 friend class NFRule;
1060 friend class NFRuleSet;
1061 friend class FractionalPartSubstitution;
1062
1063 inline NFRuleSet * getDefaultRuleSet() const;
1064 const RuleBasedCollator * getCollator() const;
1065 DecimalFormatSymbols * initializeDecimalFormatSymbols(UErrorCode &status);
1066 const DecimalFormatSymbols * getDecimalFormatSymbols() const;
1067 NFRule * initializeDefaultInfinityRule(UErrorCode &status);
1068 const NFRule * getDefaultInfinityRule() const;
1069 NFRule * initializeDefaultNaNRule(UErrorCode &status);
1070 const NFRule * getDefaultNaNRule() const;
1071 PluralFormat *createPluralFormat(UPluralType pluralType, const UnicodeString &pattern, UErrorCode& status) const;
1072 UnicodeString& adjustForCapitalizationContext(int32_t startPos, UnicodeString& currentResult, UErrorCode& status) const;
1073 UnicodeString& format(int64_t number, NFRuleSet *ruleSet, UnicodeString& toAppendTo, UErrorCode& status) const;
1074 void format(double number, NFRuleSet& rs, UnicodeString& toAppendTo, UErrorCode& status) const;
1075
1076private:
1077 NFRuleSet **fRuleSets;
1078 UnicodeString* ruleSetDescriptions;
1079 int32_t numRuleSets;
1080 NFRuleSet *defaultRuleSet;
1081 Locale locale;
1082 RuleBasedCollator* collator;
1083 DecimalFormatSymbols* decimalFormatSymbols;
1084 NFRule *defaultInfinityRule;
1085 NFRule *defaultNaNRule;
1086 ERoundingMode fRoundingMode;
1087 UBool lenient;
1088 UnicodeString* lenientParseRules;
1089 LocalizationInfo* localizations;
1090 UnicodeString originalDescription;
1091 UBool capitalizationInfoSet;
1092 UBool capitalizationForUIListMenu;
1093 UBool capitalizationForStandAlone;
1094 BreakIterator* capitalizationBrkIter;
1095};
1096
1097// ---------------
1098
1099#if !UCONFIG_NO_COLLATION
1100
1101inline UBool
1102RuleBasedNumberFormat::isLenient(void) const {
1103 return lenient;
1104}
1105
1106#endif
1107
1108inline NFRuleSet*
1109RuleBasedNumberFormat::getDefaultRuleSet() const {
1110 return defaultRuleSet;
1111}
1112
1113U_NAMESPACE_END
1114
1115/* U_HAVE_RBNF */
1116#endif
1117
1118#endif /* U_SHOW_CPLUSPLUS_API */
1119
1120/* RBNF_H */
1121#endif
1122