1 /* GENERATED SOURCE. DO NOT MODIFY. */ 2 // © 2017 and later: Unicode, Inc. and others. 3 // License & terms of use: http://www.unicode.org/copyright.html#License 4 package ohos.global.icu.number; 5 6 import java.util.Locale; 7 8 import ohos.global.icu.impl.number.DecimalFormatProperties; 9 import ohos.global.icu.text.DecimalFormatSymbols; 10 import ohos.global.icu.util.ULocale; 11 12 /** 13 * The main entrypoint to the localized number formatting library introduced in ICU 60. Basic usage 14 * examples: 15 * 16 * <pre> 17 * // Most basic usage: 18 * NumberFormatter.withLocale(...).format(123).toString(); // 1,234 in en-US 19 * 20 * // Custom notation, unit, and rounding strategy: 21 * NumberFormatter.with() 22 * .notation(Notation.compactShort()) 23 * .unit(Currency.getInstance("EUR")) 24 * .precision(Precision.maxDigits(2)) 25 * .locale(...) 26 * .format(1234) 27 * .toString(); // €1.2K in en-US 28 * 29 * // Create a formatter in a private static final field: 30 * private static final LocalizedNumberFormatter formatter = NumberFormatter.withLocale(...) 31 * .unit(NoUnit.PERCENT) 32 * .precision(Precision.fixedFraction(3)); 33 * formatter.format(5.9831).toString(); // 5.983% in en-US 34 * 35 * // Create a "template" in a private static final field but without setting a locale until the call site: 36 * private static final UnlocalizedNumberFormatter template = NumberFormatter.with() 37 * .sign(SignDisplay.ALWAYS) 38 * .unitWidth(UnitWidth.FULL_NAME); 39 * template.locale(...).format(new Measure(1234, MeasureUnit.METER)).toString(); // +1,234 meters in en-US 40 * </pre> 41 * 42 * <p> 43 * This API offers more features than {@link ohos.global.icu.text.DecimalFormat} and is geared toward new 44 * users of ICU. 45 * 46 * <p> 47 * NumberFormatter instances (i.e., LocalizedNumberFormatter and UnlocalizedNumberFormatter) 48 * are immutable and thread safe. This means that invoking a configuration 49 * method has no effect on the receiving instance; you must store and use the new number formatter 50 * instance it returns instead. 51 * 52 * <pre> 53 * UnlocalizedNumberFormatter formatter = UnlocalizedNumberFormatter.with() 54 * .notation(Notation.scientific()); 55 * formatter.precision(Precision.maxFraction(2)); // does nothing! 56 * formatter.locale(ULocale.ENGLISH).format(9.8765).toString(); // prints "9.8765E0", not "9.88E0" 57 * </pre> 58 * 59 * <p> 60 * This API is based on the <em>fluent</em> design pattern popularized by libraries such as Google's 61 * Guava. For extensive details on the design of this API, read <a href="https://goo.gl/szi5VB">the 62 * design doc</a>. 63 * 64 * @author Shane Carr 65 * @hide exposed on OHOS 66 */ 67 public final class NumberFormatter { 68 69 private static final UnlocalizedNumberFormatter BASE = new UnlocalizedNumberFormatter(); 70 71 /** 72 * An enum declaring how to render units, including currencies. Example outputs when formatting 123 73 * USD and 123 meters in <em>en-CA</em>: 74 * 75 * <ul> 76 * <li>NARROW: "$123.00" and "123 m" 77 * <li>SHORT: "US$ 123.00" and "123 m" 78 * <li>FULL_NAME: "123.00 US dollars" and "123 meters" 79 * <li>ISO_CODE: "USD 123.00" and undefined behavior 80 * <li>HIDDEN: "123.00" and "123" 81 * </ul> 82 * 83 * <p> 84 * This enum is similar to {@link ohos.global.icu.text.MeasureFormat.FormatWidth}. 85 * 86 * @see NumberFormatter 87 * @hide exposed on OHOS 88 */ 89 public static enum UnitWidth { 90 /** 91 * Print an abbreviated version of the unit name. Similar to SHORT, but always use the shortest 92 * available abbreviation or symbol. This option can be used when the context hints at the 93 * identity of the unit. For more information on the difference between NARROW and SHORT, see 94 * SHORT. 95 * 96 * <p> 97 * In CLDR, this option corresponds to the "Narrow" format for measure units and the "¤¤¤¤¤" 98 * placeholder for currencies. 99 * 100 * @see NumberFormatter 101 */ 102 NARROW, 103 104 /** 105 * Print an abbreviated version of the unit name. Similar to NARROW, but use a slightly wider 106 * abbreviation or symbol when there may be ambiguity. This is the default behavior. 107 * 108 * <p> 109 * For example, in <em>es-US</em>, the SHORT form for Fahrenheit is "{0} °F", but the NARROW form 110 * is "{0}°", since Fahrenheit is the customary unit for temperature in that locale. 111 * 112 * <p> 113 * In CLDR, this option corresponds to the "Short" format for measure units and the "¤" 114 * placeholder for currencies. 115 * 116 * @see NumberFormatter 117 */ 118 SHORT, 119 120 /** 121 * Print the full name of the unit, without any abbreviations. 122 * 123 * <p> 124 * In CLDR, this option corresponds to the default format for measure units and the "¤¤¤" 125 * placeholder for currencies. 126 * 127 * @see NumberFormatter 128 */ 129 FULL_NAME, 130 131 /** 132 * Use the three-digit ISO XXX code in place of the symbol for displaying currencies. 133 * 134 * <p> 135 * Behavior of this option with non-currency units is not defined at this time. 136 * 137 * <p> 138 * In CLDR, this option corresponds to the "¤¤" placeholder for currencies. 139 * 140 * @see NumberFormatter 141 */ 142 ISO_CODE, 143 144 /** 145 * Use the formal variant of the currency symbol; for example, "NT$" for the New Taiwan 146 * dollar in zh-TW. 147 * 148 * <p> 149 * Behavior of this option with non-currency units is not defined at this time. 150 * 151 * @see NumberFormatter 152 * @hide draft / provisional / internal are hidden on OHOS 153 */ 154 FORMAL, 155 156 /** 157 * Use the alternate variant of the currency symbol; for example, "TL" for the Turkish 158 * lira (TRY). 159 * 160 * <p> 161 * Behavior of this option with non-currency units is not defined at this time. 162 * 163 * @see NumberFormatter 164 * @hide draft / provisional / internal are hidden on OHOS 165 */ 166 VARIANT, 167 168 /** 169 * Format the number according to the specified unit, but do not display the unit. For 170 * currencies, apply monetary symbols and formats as with SHORT, but omit the currency symbol. 171 * For measure units, the behavior is equivalent to not specifying the unit at all. 172 * 173 * @see NumberFormatter 174 */ 175 HIDDEN, 176 } 177 178 /** 179 * An enum declaring the strategy for when and how to display grouping separators (i.e., the 180 * separator, often a comma or period, after every 2-3 powers of ten). The choices are several 181 * pre-built strategies for different use cases that employ locale data whenever possible. Example 182 * outputs for 1234 and 1234567 in <em>en-IN</em>: 183 * 184 * <ul> 185 * <li>OFF: 1234 and 12345 186 * <li>MIN2: 1234 and 12,34,567 187 * <li>AUTO: 1,234 and 12,34,567 188 * <li>ON_ALIGNED: 1,234 and 12,34,567 189 * <li>THOUSANDS: 1,234 and 1,234,567 190 * </ul> 191 * 192 * <p> 193 * The default is AUTO, which displays grouping separators unless the locale data says that grouping 194 * is not customary. To force grouping for all numbers greater than 1000 consistently across locales, 195 * use ON_ALIGNED. On the other hand, to display grouping less frequently than the default, use MIN2 196 * or OFF. See the docs of each option for details. 197 * 198 * <p> 199 * Note: This enum specifies the strategy for grouping sizes. To set which character to use as the 200 * grouping separator, use the "symbols" setter. 201 * 202 * @see NumberFormatter 203 * @hide exposed on OHOS 204 */ 205 public static enum GroupingStrategy { 206 /** 207 * Do not display grouping separators in any locale. 208 * 209 * @see NumberFormatter 210 */ 211 OFF, 212 213 /** 214 * Display grouping using locale defaults, except do not show grouping on values smaller than 215 * 10000 (such that there is a <em>minimum of two digits</em> before the first separator). 216 * 217 * <p> 218 * Note that locales may restrict grouping separators to be displayed only on 1 million or 219 * greater (for example, ee and hu) or disable grouping altogether (for example, bg currency). 220 * 221 * <p> 222 * Locale data is used to determine whether to separate larger numbers into groups of 2 223 * (customary in South Asia) or groups of 3 (customary in Europe and the Americas). 224 * 225 * @see NumberFormatter 226 */ 227 MIN2, 228 229 /** 230 * Display grouping using the default strategy for all locales. This is the default behavior. 231 * 232 * <p> 233 * Note that locales may restrict grouping separators to be displayed only on 1 million or 234 * greater (for example, ee and hu) or disable grouping altogether (for example, bg currency). 235 * 236 * <p> 237 * Locale data is used to determine whether to separate larger numbers into groups of 2 238 * (customary in South Asia) or groups of 3 (customary in Europe and the Americas). 239 * 240 * @see NumberFormatter 241 */ 242 AUTO, 243 244 /** 245 * Always display the grouping separator on values of at least 1000. 246 * 247 * <p> 248 * This option ignores the locale data that restricts or disables grouping, described in MIN2 and 249 * AUTO. This option may be useful to normalize the alignment of numbers, such as in a 250 * spreadsheet. 251 * 252 * <p> 253 * Locale data is used to determine whether to separate larger numbers into groups of 2 254 * (customary in South Asia) or groups of 3 (customary in Europe and the Americas). 255 * 256 * @see NumberFormatter 257 */ 258 ON_ALIGNED, 259 260 /** 261 * Use the Western defaults: groups of 3 and enabled for all numbers 1000 or greater. Do not use 262 * locale data for determining the grouping strategy. 263 * 264 * @see NumberFormatter 265 */ 266 THOUSANDS 267 } 268 269 /** 270 * An enum declaring how to denote positive and negative numbers. Example outputs when formatting 271 * 123, 0, and -123 in <em>en-US</em>: 272 * 273 * <ul> 274 * <li>AUTO: "123", "0", and "-123" 275 * <li>ALWAYS: "+123", "+0", and "-123" 276 * <li>NEVER: "123", "0", and "123" 277 * <li>ACCOUNTING: "$123", "$0", and "($123)" 278 * <li>ACCOUNTING_ALWAYS: "+$123", "+$0", and "($123)" 279 * <li>EXCEPT_ZERO: "+123", "0", and "-123" 280 * <li>ACCOUNTING_EXCEPT_ZERO: "+$123", "$0", and "($123)" 281 * </ul> 282 * 283 * <p> 284 * The exact format, including the position and the code point of the sign, differ by locale. 285 * 286 * @see NumberFormatter 287 * @hide exposed on OHOS 288 */ 289 public static enum SignDisplay { 290 /** 291 * Show the minus sign on negative numbers, and do not show the sign on positive numbers. This is 292 * the default behavior. 293 * 294 * @see NumberFormatter 295 */ 296 AUTO, 297 298 /** 299 * Show the minus sign on negative numbers and the plus sign on positive numbers, including zero. 300 * To hide the sign on zero, see {@link #EXCEPT_ZERO}. 301 * 302 * @see NumberFormatter 303 */ 304 ALWAYS, 305 306 /** 307 * Do not show the sign on positive or negative numbers. 308 * 309 * @see NumberFormatter 310 */ 311 NEVER, 312 313 /** 314 * Use the locale-dependent accounting format on negative numbers, and do not show the sign on 315 * positive numbers. 316 * 317 * <p> 318 * The accounting format is defined in CLDR and varies by locale; in many Western locales, the 319 * format is a pair of parentheses around the number. 320 * 321 * <p> 322 * Note: Since CLDR defines the accounting format in the monetary context only, this option falls 323 * back to the AUTO sign display strategy when formatting without a currency unit. This 324 * limitation may be lifted in the future. 325 * 326 * @see NumberFormatter 327 */ 328 ACCOUNTING, 329 330 /** 331 * Use the locale-dependent accounting format on negative numbers, and show the plus sign on 332 * positive numbers, including zero. For more information on the accounting format, see the 333 * ACCOUNTING sign display strategy. To hide the sign on zero, see 334 * {@link #ACCOUNTING_EXCEPT_ZERO}. 335 * 336 * @see NumberFormatter 337 */ 338 ACCOUNTING_ALWAYS, 339 340 /** 341 * Show the minus sign on negative numbers and the plus sign on positive numbers. Do not show a 342 * sign on zero, numbers that round to zero, or NaN. 343 * 344 * @see NumberFormatter 345 */ 346 EXCEPT_ZERO, 347 348 /** 349 * Use the locale-dependent accounting format on negative numbers, and show the plus sign on 350 * positive numbers. Do not show a sign on zero, numbers that round to zero, or NaN. For more 351 * information on the accounting format, see the ACCOUNTING sign display strategy. 352 * 353 * @see NumberFormatter 354 */ 355 ACCOUNTING_EXCEPT_ZERO, 356 } 357 358 /** 359 * An enum declaring how to render the decimal separator. Example outputs when formatting 1 and 1.1 360 * in <em>en-US</em>: 361 * 362 * <ul> 363 * <li>AUTO: "1" and "1.1" 364 * <li>ALWAYS: "1." and "1.1" 365 * </ul> 366 * 367 * @see NumberFormatter 368 * @hide exposed on OHOS 369 */ 370 public static enum DecimalSeparatorDisplay { 371 /** 372 * Show the decimal separator when there are one or more digits to display after the separator, 373 * and do not show it otherwise. This is the default behavior. 374 * 375 * @see NumberFormatter 376 */ 377 AUTO, 378 379 /** 380 * Always show the decimal separator, even if there are no digits to display after the separator. 381 * 382 * @see NumberFormatter 383 */ 384 ALWAYS, 385 } 386 387 /** 388 * Use a default threshold of 3. This means that the third time .format() is called, the data 389 * structures get built using the "safe" code path. The first two calls to .format() will trigger the 390 * unsafe code path. 391 */ 392 static final long DEFAULT_THRESHOLD = 3; 393 394 /** 395 * Private constructor, not designed for instantiation. 396 */ NumberFormatter()397 private NumberFormatter() { 398 } 399 400 /** 401 * Call this method at the beginning of a NumberFormatter fluent chain in which the locale is not 402 * currently known at the call site. 403 * 404 * @return An {@link UnlocalizedNumberFormatter}, to be used for chaining. 405 */ with()406 public static UnlocalizedNumberFormatter with() { 407 return BASE; 408 } 409 410 /** 411 * Call this method at the beginning of a NumberFormatter fluent chain in which the locale is known 412 * at the call site. 413 * 414 * @param locale 415 * The locale from which to load formats and symbols for number formatting. 416 * @return A {@link LocalizedNumberFormatter}, to be used for chaining. 417 */ withLocale(Locale locale)418 public static LocalizedNumberFormatter withLocale(Locale locale) { 419 return BASE.locale(locale); 420 } 421 422 /** 423 * Call this method at the beginning of a NumberFormatter fluent chain in which the locale is known 424 * at the call site. 425 * 426 * @param locale 427 * The locale from which to load formats and symbols for number formatting. 428 * @return A {@link LocalizedNumberFormatter}, to be used for chaining. 429 */ withLocale(ULocale locale)430 public static LocalizedNumberFormatter withLocale(ULocale locale) { 431 return BASE.locale(locale); 432 } 433 434 /** 435 * Call this method at the beginning of a NumberFormatter fluent chain to create an instance based 436 * on a given number skeleton string. 437 * 438 * @param skeleton 439 * The skeleton string off of which to base this NumberFormatter. 440 * @return An {@link UnlocalizedNumberFormatter}, to be used for chaining. 441 * @throws SkeletonSyntaxException If the given string is not a valid number formatting skeleton. 442 */ forSkeleton(String skeleton)443 public static UnlocalizedNumberFormatter forSkeleton(String skeleton) { 444 return NumberSkeletonImpl.getOrCreate(skeleton); 445 } 446 447 /** 448 * Note: In Java, since NumberPropertyMapper is package-private, this method is here so that it is 449 * accessible to tests. 450 * 451 * @deprecated ICU 60 This API is ICU internal only. 452 * @hide draft / provisional / internal are hidden on OHOS 453 */ 454 @Deprecated fromDecimalFormat( DecimalFormatProperties properties, DecimalFormatSymbols symbols, DecimalFormatProperties exportedProperties)455 public static UnlocalizedNumberFormatter fromDecimalFormat( 456 DecimalFormatProperties properties, 457 DecimalFormatSymbols symbols, 458 DecimalFormatProperties exportedProperties) { 459 return NumberPropertyMapper.create(properties, symbols, exportedProperties); 460 } 461 } 462