public FormattedNumberRange formatRange(int first, int second) {
DecimalQuantity dq1 = new DecimalQuantity_DualStorageBCD(first);
DecimalQuantity dq2 = new DecimalQuantity_DualStorageBCD(second);
- return formatImpl(dq1, dq2);
+ return formatImpl(dq1, dq2, first == second);
}
/**
public FormattedNumberRange formatRange(double first, double second) {
DecimalQuantity dq1 = new DecimalQuantity_DualStorageBCD(first);
DecimalQuantity dq2 = new DecimalQuantity_DualStorageBCD(second);
- return formatImpl(dq1, dq2);
+ // Note: double equality could be changed to epsilon equality later if there is demand.
+ // The epsilon should be set via an API method.
+ return formatImpl(dq1, dq2, first == second);
}
/**
* @see NumberRangeFormatter
*/
public FormattedNumberRange formatRange(Number first, Number second) {
+ if (first == null || second == null) {
+ throw new IllegalArgumentException("Cannot format null values in range");
+ }
DecimalQuantity dq1 = new DecimalQuantity_DualStorageBCD(first);
DecimalQuantity dq2 = new DecimalQuantity_DualStorageBCD(second);
- return formatImpl(dq1, dq2);
+ return formatImpl(dq1, dq2, first.equals(second));
}
- FormattedNumberRange formatImpl(DecimalQuantity first, DecimalQuantity second) {
+ FormattedNumberRange formatImpl(DecimalQuantity first, DecimalQuantity second, boolean equalBeforeRounding) {
// TODO: This is a placeholder implementation.
RangeMacroProps macros = resolve();
LocalizedNumberFormatter f1 , f2;
nsb.append(r1.nsb);
nsb.append(" --- ", null);
nsb.append(r2.nsb);
- RangeIdentityType identityType = (first == second) ? RangeIdentityType.EQUAL_BEFORE_ROUNDING
+ RangeIdentityType identityType = equalBeforeRounding ? RangeIdentityType.EQUAL_BEFORE_ROUNDING
: RangeIdentityType.NOT_EQUAL;
return new FormattedNumberRange(nsb, first, second, identityType);
}
*/
public abstract class NumberRangeFormatter {
- public static enum RangeCollapse {}
+ /**
+ * Defines how to merge fields that are identical across the range sign.
+ *
+ * @draft ICU 63
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberRangeFormatter
+ */
+ public enum RangeCollapse {
+ /**
+ * Use locale data and heuristics to determine how much of the string to collapse. Could end up collapsing none,
+ * some, or all repeated pieces in a locale-sensitive way.
+ *
+ * @draft ICU 63
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberRangeFormatter
+ */
+ AUTO,
- public static enum RangeIdentityFallback {}
+ /**
+ * Do not collapse any part of the number. Example: "3.2 thousand kilograms – 5.3 thousand kilograms"
+ *
+ * @draft ICU 63
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberRangeFormatter
+ */
+ NONE,
+
+ /**
+ * Collapse the unit part of the number, but not the notation, if present. Example: "3.2 thousand – 5.3 thousand
+ * kilograms"
+ *
+ * @draft ICU 63
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberRangeFormatter
+ */
+ UNIT,
+
+ /**
+ * Collapse any field that is equal across the range sign. May introduce ambiguity on the magnitude of the
+ * number. Example: "3.2 – 5.3 thousand kilograms"
+ *
+ * @draft ICU 63
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberRangeFormatter
+ */
+ ALL
+ }
+
+ /**
+ * Defines the behavior when the two numbers in the range are identical after rounding. To programmatically detect
+ * when the identity fallback is used, compare the lower and upper BigDecimals via FormattedNumber.
+ *
+ * @draft ICU 63
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberRangeFormatter
+ */
+ public enum IdentityFallback {
+ /**
+ * Show the number as a single value rather than a range. Example: "$5"
+ *
+ * @draft ICU 63
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberRangeFormatter
+ */
+ SINGLE_VALUE,
+
+ /**
+ * Show the number using a locale-sensitive approximation pattern. If the numbers were the same before rounding,
+ * show the single value. Example: "~$5" or "$5"
+ *
+ * @draft ICU 63
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberRangeFormatter
+ */
+ APPROXIMATELY_OR_SINGLE_VALUE,
+
+ /**
+ * Show the number using a locale-sensitive approximation pattern. Use the range pattern always, even if the
+ * inputs are the same. Example: "~$5"
+ *
+ * @draft ICU 63
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberRangeFormatter
+ */
+ APPROXIMATELY,
+
+ /**
+ * Show the number as the range of two equal values. Use the range pattern always, even if the inputs are the
+ * same. Example (with RangeCollapse.NONE): "$5 – $5"
+ *
+ * @draft ICU 63
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberRangeFormatter
+ */
+ RANGE
+ }
+
+ /**
+ * Defines the behavior when the two numbers in the range are identical after rounding. To programmatically detect
+ * when the identity fallback is used, compare the lower and upper BigDecimals via FormattedNumber.
+ */
+
+ public static enum RangeIdentityFallback {
+ /**
+ * Show the number as a single value rather than a range. Example: "$5"
+ */
+ SINGLE_VALUE,
+
+ /**
+ * Show the number using a locale-sensitive approximation pattern. If the numbers were the same before rounding,
+ * show the single value. Example: "~$5" or "$5"
+ */
+ APPROXIMATELY_OR_SINGLE_VALUE,
+
+ /**
+ * Show the number using a locale-sensitive approximation pattern. Use the range pattern always, even if the
+ * inputs are the same. Example: "~$5"
+ */
+ APPROXIMATELY,
+
+ /**
+ * Show the number as the range of two equal values. Use the range pattern always, even if the inputs are the
+ * same. Example (with RangeCollapse.NONE): "$5 – $5"
+ */
+ RANGE
+ }
private static final UnlocalizedNumberRangeFormatter BASE = new UnlocalizedNumberRangeFormatter();
this.value = value;
}
+ /**
+ * Sets the NumberFormatter instance to use for the numbers in the range. The same formatter is applied to both
+ * sides of the range.
+ * <p>
+ * The NumberFormatter instances must not have a locale applied yet; the locale specified on the
+ * NumberRangeFormatter will be used.
+ *
+ * @param formatter
+ * The formatter to use for both numbers in the range.
+ * @return The fluent chain.
+ * @draft ICU 63
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberFormatter
+ * @see NumberRangeFormatter
+ */
public T numberFormatter(UnlocalizedNumberFormatter formatter) {
return numberFormatters(formatter, formatter);
}
+ /**
+ * Sets the NumberFormatter instances to use for the numbers in the range. This method allows you to set a different
+ * formatter for the first and second numbers.
+ * <p>
+ * The NumberFormatter instances must not have a locale applied yet; the locale specified on the
+ * NumberRangeFormatter will be used.
+ *
+ * @param formatterFirst
+ * The formatter to use for the first number in the range.
+ * @param formatterSecond
+ * The formatter to use for the second number in the range.
+ * @return The fluent chain.
+ * @draft ICU 63
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberFormatter
+ * @see NumberRangeFormatter
+ */
public T numberFormatters(UnlocalizedNumberFormatter formatterFirst, UnlocalizedNumberFormatter formatterSecond) {
T intermediate = create(KEY_FORMATTER_1, formatterFirst);
return (T) intermediate.create(KEY_FORMATTER_2, formatterSecond);
}
+ /**
+ * Sets the aggressiveness of "collapsing" fields across the range separator. Possible values:
+ * <p>
+ * <ul>
+ * <li>ALL: "3-5K miles"</li>
+ * <li>UNIT: "3K - 5K miles"</li>
+ * <li>NONE: "3K miles - 5K miles"</li>
+ * <li>AUTO: usually UNIT or NONE, depending on the locale and formatter settings</li>
+ * <p>
+ * The default value is AUTO.
+ *
+ * @param collapse
+ * The collapsing strategy to use for this range.
+ * @return The fluent chain.
+ * @draft ICU 63
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberRangeFormatter
+ */
public T collapse(RangeCollapse collapse) {
return create(KEY_COLLAPSE, collapse);
}
+ /**
+ * Sets the behavior when the two sides of the range are the same. This could happen if the same two numbers are
+ * passed to the formatRange function, or if different numbers are passed to the function but they become the same
+ * after rounding rules are applied. Possible values:
+ * <p>
+ * <ul>
+ * <li>SINGLE_VALUE: "5 miles"</li>
+ * <li>APPROXIMATELY_OR_SINGLE_VALUE: "~5 miles" or "5 miles", depending on whether the number was the same before
+ * rounding was applied</li>
+ * <li>APPROXIMATELY: "~5 miles"</li>
+ * <li>RANGE: "5-5 miles" (with collapse=UNIT)</li>
+ * <p>
+ * The default value is AUTO.
+ *
+ * @param identityFallback
+ * The strategy to use when formatting two numbers that end up being the same.
+ * @return The fluent chain.
+ * @draft ICU 63
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberRangeFormatter
+ */
public T identityFallback(RangeIdentityFallback identityFallback) {
return create(KEY_IDENTITY_FALLBACK, identityFallback);
}
projects / icu / commitdiff