1--- 2layout: default 3title: RuleBasedNumberFormat 4nav_order: 5 5grand_parent: Formatting 6parent: Formatting Numbers 7--- 8<!-- 9© 2020 and later: Unicode, Inc. and others. 10License & terms of use: http://www.unicode.org/copyright.html 11--> 12 13# RuleBasedNumberFormat 14{: .no_toc } 15 16## Contents 17{: .no_toc .text-delta } 18 191. TOC 20{:toc} 21 22--- 23 24# Overview 25 26[RuleBasedNumberFormat](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classRuleBasedNumberFormat.html) 27can format and parse numbers in spelled-out format, e.g. "one hundred and 28thirty-four". For example: 29 30``` 31"one hundred and thirty-four" // 134 using en_US spellout 32"one hundred and thirty-fourth" // 134 using en_US ordinal 33"hundertvierunddreissig" // 134 using de_DE spellout 34"MCMLVIII" // custom, 1958 in roman numerals 35``` 36 37RuleBasedNumberFormat is based on rules describing how to format a number. The 38rule syntax is designed primarily for formatting and parsing numbers as 39spelled-out text, though other kinds of formatting are possible. As a 40convenience, custom API is provided to allow selection from three predefined 41rule definitions, when available: SPELLOUT, ORDINAL, and DURATION. Users can 42request formatters either by providing a locale and one of these predefined rule 43selectors, or by specifying the rule definitions directly. 44 45> :point_right: **Note**: ICU provides number spellout rules for several locales, but not for all of the 46locales that ICU supports, and not all of the predefined rule types. Also, as of 47release 2.6, some of the provided rules are known to be incomplete. 48 49## Instantiation 50 51Unlike the other standard number formats, there is no corresponding factory 52method on NumberFormat. Instead, RuleBasedNumberFormat objects are instantiated 53via constructors. Constructors come in two flavors, ones that take rule text, 54and ones that take one of the predefined selectors. Constructors that do not 55take a Locale parameter use the current default locale. 56 57The following constructors are available: 58 591. **RuleBasedNumberFormat(int)** 60 Returns a format using predefined rules of the selected type from the 61 current locale. 62 632. **RuleBasedNumberFormat(Locale, int)** 64 As above, but specifies locale. 65 663. **RuleBasedNumberFormat(String)** 67 Returns a format using the provided rules, and symbols (if required) from 68 the current locale. 69 704. **RuleBasedNumberFormat(String, Locale)** 71 As above, but specifies locale. 72 73## Usage 74 75RuleBasedNumberFormat can be used like other NumberFormats. For example, in 76Java: 77 78```java 79double num = 2718.28; 80NumberFormat formatter = 81 new RuleBasedNumberFormat(RuleBasedNumberFormat.SPELLOUT); 82String result = formatter.format(num); 83System.out.println(result); 84 85// output (in en_US locale): 86// two thousand seven hundred and eighteen point two eight 87``` 88 89## Rule Sets 90 91Rule descriptions can provide multiple named rule sets, for example, the rules 92for en_US spellout provides a '%simplified' rule set that displays text without 93commas or the word 'and'. Rule sets can be queried and set on a 94RuleBasedNumberFormat. This lets you customize a RuleBasedNumberFormat for use 95through its inherited NumberFormat API. For example, in Java: 96 97You can also format a number specifying the ruleset directly, using an 98additional overload of format provided by RuleBasedNumberFormat. For example, in 99Java: 100 101> :point_right: **Note**: There is no standardization of rule set names, so you must either query the 102names, as in the first example above, or know the names that are defined in the 103rules for that formatter. 104 105## Rules 106 107The following example provides a quick look at the RuleBasedNumberFormat rule 108syntax. 109 110These rules format a number using standard decimal place-value notation, but 111using words instead of digits, e.g. 123.4 formats as 'one two three point four': 112 113``` 114"-x: minus >>;\n" 115+ "x.x: << point >>;\n" 116+ "zero; one; two; three; four; five; six;\n" 117+ " seven; eight; nine;\n" 118+ "10: << >>;\n" 119+ "100: << >>>;\n" 120+ "1000: <<, >>>;\n" 121+ "1,000,000: <<, >>>;\n" 122+ "1,000,000,000: <<, >>>;\n" 123+ "1,000,000,000,000: <<, >>>;\n" 124+ "1,000,000,000,000,000: =#,##0=;\n"; 125``` 126 127Rulesets are invoked by first applying negative and fractional rules, and then 128using a recursive process. It starts by finding the rule whose range includes 129the current value and applying that rule. If the rule so directs, it emits text, 130including text obtained by recursing on new values as directed by the rule. As 131you can see, the rules are designed to accommodate recursive processing of 132numbers, and so are best suited for formatting numbers in ways that are 133inherently recursive. 134 135A full explanation of this example can be found in the [RuleBasedNumberFormat 136examples](rbnf-examples.md). A complete description of the rule syntax can be 137found in the [RuleBasedNumberFormat API 138Documentation](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classRuleBasedNumberFormat.html). 139