1 /* GENERATED SOURCE. DO NOT MODIFY. */ 2 // © 2018 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.util.ULocale; 9 10 /** 11 * The main entrypoint to the formatting of ranges of numbers, including currencies and other units of measurement. 12 * <p> 13 * Usage example: 14 * <pre> 15 * NumberRangeFormatter.with() 16 * .identityFallback(RangeIdentityFallback.APPROXIMATELY_OR_SINGLE_VALUE) 17 * .numberFormatterFirst(NumberFormatter.with().unit(MeasureUnit.METER)) 18 * .numberFormatterSecond(NumberFormatter.with().unit(MeasureUnit.KILOMETER)) 19 * .locale(ULocale.UK) 20 * .formatRange(750, 1.2) 21 * .toString(); 22 * // => "750 m - 1.2 km" 23 * </pre> 24 * <p> 25 * Like NumberFormatter, NumberRangeFormatter instances (i.e., LocalizedNumberRangeFormatter 26 * and UnlocalizedNumberRangeFormatter) are immutable and thread-safe. This API is based on the 27 * <em>fluent</em> design pattern popularized by libraries such as Google's Guava. 28 * 29 * @author sffc 30 * @see NumberFormatter 31 * @hide exposed on OHOS 32 */ 33 public abstract class NumberRangeFormatter { 34 35 /** 36 * Defines how to merge fields that are identical across the range sign. 37 * 38 * @see NumberRangeFormatter 39 * @hide exposed on OHOS 40 */ 41 public enum RangeCollapse { 42 /** 43 * Use locale data and heuristics to determine how much of the string to collapse. Could end up collapsing none, 44 * some, or all repeated pieces in a locale-sensitive way. 45 * <p> 46 * The heuristics used for this option are subject to change over time. 47 * 48 * @see NumberRangeFormatter 49 */ 50 AUTO, 51 52 /** 53 * Do not collapse any part of the number. Example: "3.2 thousand kilograms – 5.3 thousand kilograms" 54 * 55 * @see NumberRangeFormatter 56 */ 57 NONE, 58 59 /** 60 * Collapse the unit part of the number, but not the notation, if present. Example: "3.2 thousand – 5.3 thousand 61 * kilograms" 62 * 63 * @see NumberRangeFormatter 64 */ 65 UNIT, 66 67 /** 68 * Collapse any field that is equal across the range sign. May introduce ambiguity on the magnitude of the 69 * number. Example: "3.2 – 5.3 thousand kilograms" 70 * 71 * @see NumberRangeFormatter 72 */ 73 ALL 74 } 75 76 /** 77 * Defines the behavior when the two numbers in the range are identical after rounding. To programmatically detect 78 * when the identity fallback is used, compare the lower and upper BigDecimals via FormattedNumber. 79 * 80 * @see NumberRangeFormatter 81 * @hide exposed on OHOS 82 */ 83 public static enum RangeIdentityFallback { 84 /** 85 * Show the number as a single value rather than a range. Example: "$5" 86 * 87 * @see NumberRangeFormatter 88 */ 89 SINGLE_VALUE, 90 91 /** 92 * Show the number using a locale-sensitive approximation pattern. If the numbers were the same before rounding, 93 * show the single value. Example: "~$5" or "$5" 94 * 95 * @see NumberRangeFormatter 96 */ 97 APPROXIMATELY_OR_SINGLE_VALUE, 98 99 /** 100 * Show the number using a locale-sensitive approximation pattern. Use the range pattern always, even if the 101 * inputs are the same. Example: "~$5" 102 * 103 * @see NumberRangeFormatter 104 */ 105 APPROXIMATELY, 106 107 /** 108 * Show the number as the range of two equal values. Use the range pattern always, even if the inputs are the 109 * same. Example (with RangeCollapse.NONE): "$5 – $5" 110 * 111 * @see NumberRangeFormatter 112 */ 113 RANGE 114 } 115 116 /** 117 * Used in the result class FormattedNumberRange to indicate to the user whether the numbers formatted in the range 118 * were equal or not, and whether or not the identity fallback was applied. 119 * 120 * @see NumberRangeFormatter 121 * @hide exposed on OHOS 122 */ 123 public static enum RangeIdentityResult { 124 /** 125 * Used to indicate that the two numbers in the range were equal, even before any rounding rules were applied. 126 * 127 * @see NumberRangeFormatter 128 */ 129 EQUAL_BEFORE_ROUNDING, 130 131 /** 132 * Used to indicate that the two numbers in the range were equal, but only after rounding rules were applied. 133 * 134 * @see NumberRangeFormatter 135 */ 136 EQUAL_AFTER_ROUNDING, 137 138 /** 139 * Used to indicate that the two numbers in the range were not equal, even after rounding rules were applied. 140 * 141 * @see NumberRangeFormatter 142 */ 143 NOT_EQUAL 144 } 145 146 private static final UnlocalizedNumberRangeFormatter BASE = new UnlocalizedNumberRangeFormatter(); 147 148 /** 149 * Call this method at the beginning of a NumberRangeFormatter fluent chain in which the locale is not currently 150 * known at the call site. 151 * 152 * @return An {@link UnlocalizedNumberRangeFormatter}, to be used for chaining. 153 */ with()154 public static UnlocalizedNumberRangeFormatter with() { 155 return BASE; 156 } 157 158 /** 159 * Call this method at the beginning of a NumberRangeFormatter fluent chain in which the locale is known at the call 160 * site. 161 * 162 * @param locale 163 * The locale from which to load formats and symbols for number range formatting. 164 * @return A {@link LocalizedNumberRangeFormatter}, to be used for chaining. 165 */ withLocale(Locale locale)166 public static LocalizedNumberRangeFormatter withLocale(Locale locale) { 167 return BASE.locale(locale); 168 } 169 170 /** 171 * Call this method at the beginning of a NumberRangeFormatter fluent chain in which the locale is known at the call 172 * site. 173 * 174 * @param locale 175 * The locale from which to load formats and symbols for number range formatting. 176 * @return A {@link LocalizedNumberRangeFormatter}, to be used for chaining. 177 */ withLocale(ULocale locale)178 public static LocalizedNumberRangeFormatter withLocale(ULocale locale) { 179 return BASE.locale(locale); 180 } 181 182 /** 183 * Private constructor - this class is not designed for instantiation 184 */ NumberRangeFormatter()185 private NumberRangeFormatter() { 186 } 187 } 188