1 // 2017 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html#License 3 package com.ibm.icu.number; 4 5 import com.ibm.icu.number.NumberFormatter.SignDisplay; 6 import com.ibm.icu.text.CompactDecimalFormat.CompactStyle; 7 8 /** 9 * A class that defines the notation style to be used when formatting numbers in NumberFormatter. 10 * 11 * @draft ICU 60 12 * @provisional This API might change or be removed in a future release. 13 * @see NumberFormatter 14 */ 15 public class Notation { 16 17 // TODO: Support engineering intervals other than 3? 18 private static final ScientificNotation SCIENTIFIC = new ScientificNotation(1, false, 1, SignDisplay.AUTO); 19 private static final ScientificNotation ENGINEERING = new ScientificNotation(3, false, 1, SignDisplay.AUTO); 20 private static final CompactNotation COMPACT_SHORT = new CompactNotation(CompactStyle.SHORT); 21 private static final CompactNotation COMPACT_LONG = new CompactNotation(CompactStyle.LONG); 22 private static final SimpleNotation SIMPLE = new SimpleNotation(); 23 24 /* package-private */ Notation() { 25 } 26 27 /** 28 * Print the number using scientific notation (also known as scientific form, standard index form, or standard form 29 * in the UK). The format for scientific notation varies by locale; for example, many Western locales display the 30 * number in the form "#E0", where the number is displayed with one digit before the decimal separator, zero or more 31 * digits after the decimal separator, and the corresponding power of 10 displayed after the "E". 32 * 33 * <p> 34 * Example outputs in <em>en-US</em> when printing 8.765E4 through 8.765E-3: 35 * 36 * <pre> 37 * 8.765E4 38 * 8.765E3 39 * 8.765E2 40 * 8.765E1 41 * 8.765E0 42 * 8.765E-1 43 * 8.765E-2 44 * 8.765E-3 45 * 0E0 46 * </pre> 47 * 48 * @return A ScientificNotation for chaining or passing to the NumberFormatter notation() setter. 49 * @draft ICU 60 50 * @provisional This API might change or be removed in a future release. 51 * @see NumberFormatter 52 */ 53 public static ScientificNotation scientific() { 54 return SCIENTIFIC; 55 } 56 57 /** 58 * Print the number using engineering notation, a variant of scientific notation in which the exponent must be 59 * divisible by 3. 60 * 61 * <p> 62 * Example outputs in <em>en-US</em> when printing 8.765E4 through 8.765E-3: 63 * 64 * <pre> 65 * 87.65E3 66 * 8.765E3 67 * 876.5E0 68 * 87.65E0 69 * 8.765E0 70 * 876.5E-3 71 * 87.65E-3 72 * 8.765E-3 73 * 0E0 74 * </pre> 75 * 76 * @return A ScientificNotation for chaining or passing to the NumberFormatter notation() setter. 77 * @draft ICU 60 78 * @provisional This API might change or be removed in a future release. 79 * @see NumberFormatter 80 */ 81 public static ScientificNotation engineering() { 82 return ENGINEERING; 83 } 84 85 /** 86 * Print the number using short-form compact notation. 87 * 88 * <p> 89 * <em>Compact notation</em>, defined in Unicode Technical Standard #35 Part 3 Section 2.4.1, prints numbers with 90 * localized prefixes or suffixes corresponding to different powers of ten. Compact notation is similar to 91 * engineering notation in how it scales numbers. 92 * 93 * <p> 94 * Compact notation is ideal for displaying large numbers (over ~1000) to humans while at the same time minimizing 95 * screen real estate. 96 * 97 * <p> 98 * In short form, the powers of ten are abbreviated. In <em>en-US</em>, the abbreviations are "K" for thousands, "M" 99 * for millions, "B" for billions, and "T" for trillions. Example outputs in <em>en-US</em> when printing 8.765E7 100 * through 8.765E0: 101 * 102 * <pre> 103 * 88M 104 * 8.8M 105 * 876K 106 * 88K 107 * 8.8K 108 * 876 109 * 88 110 * 8.8 111 * </pre> 112 * 113 * <p> 114 * When compact notation is specified without an explicit rounding strategy, numbers are rounded off to the closest 115 * integer after scaling the number by the corresponding power of 10, but with a digit shown after the decimal 116 * separator if there is only one digit before the decimal separator. The default compact notation rounding strategy 117 * is equivalent to: 118 * 119 * <pre> 120 * Rounder.integer().withMinDigits(2) 121 * </pre> 122 * 123 * @return A CompactNotation for passing to the NumberFormatter notation() setter. 124 * @draft ICU 60 125 * @provisional This API might change or be removed in a future release. 126 * @see NumberFormatter 127 */ 128 public static CompactNotation compactShort() { 129 return COMPACT_SHORT; 130 } 131 132 /** 133 * Print the number using long-form compact notation. For more information on compact notation, see 134 * {@link #compactShort}. 135 * 136 * <p> 137 * In long form, the powers of ten are spelled out fully. Example outputs in <em>en-US</em> when printing 8.765E7 138 * through 8.765E0: 139 * 140 * <pre> 141 * 88 million 142 * 8.8 million 143 * 876 thousand 144 * 88 thousand 145 * 8.8 thousand 146 * 876 147 * 88 148 * 8.8 149 * </pre> 150 * 151 * @return A CompactNotation for passing to the NumberFormatter notation() setter. 152 * @draft ICU 60 153 * @provisional This API might change or be removed in a future release. 154 * @see NumberFormatter 155 */ 156 public static CompactNotation compactLong() { 157 return COMPACT_LONG; 158 } 159 160 /** 161 * Print the number using simple notation without any scaling by powers of ten. This is the default behavior. 162 * 163 * <p> 164 * Since this is the default behavior, this method needs to be called only when it is necessary to override a 165 * previous setting. 166 * 167 * <p> 168 * Example outputs in <em>en-US</em> when printing 8.765E7 through 8.765E0: 169 * 170 * <pre> 171 * 87,650,000 172 * 8,765,000 173 * 876,500 174 * 87,650 175 * 8,765 176 * 876.5 177 * 87.65 178 * 8.765 179 * </pre> 180 * 181 * @return A SimpleNotation for passing to the NumberFormatter notation() setter. 182 * @draft ICU 60 183 * @provisional This API might change or be removed in a future release. 184 * @see NumberFormatter 185 */ 186 public static SimpleNotation simple() { 187 return SIMPLE; 188 } 189 }
