Stay organized with collections
Save and categorize content based on your preferences.
abstract class NumberRangeFormatter
The main entrypoint to the formatting of ranges of numbers, including currencies and other units of measurement.
Usage example:
NumberRangeFormatter.with()
.identityFallback(RangeIdentityFallback.APPROXIMATELY_OR_SINGLE_VALUE)
.numberFormatterFirst(NumberFormatter.with().unit(MeasureUnit.METER))
.numberFormatterSecond(NumberFormatter.with().unit(MeasureUnit.KILOMETER))
.locale(ULocale.UK)
.formatRange(750, 1.2)
.toString();
// => "750 m - 1.2 km"
Like NumberFormatter, NumberRangeFormatter instances (i.e., LocalizedNumberRangeFormatter and UnlocalizedNumberRangeFormatter) are immutable and thread-safe. This API is based on the fluent design pattern popularized by libraries such as Google's Guava.
Summary
| Nested classes |
|
Defines how to merge fields that are identical across the range sign.
|
|
Defines the behavior when the two numbers in the range are identical after rounding.
|
|
Used in the result class FormattedNumberRange to indicate to the user whether the numbers formatted in the range were equal or not, and whether or not the identity fallback was applied.
|
| Public methods |
| open static UnlocalizedNumberRangeFormatter! |
Call this method at the beginning of a NumberRangeFormatter fluent chain in which the locale is not currently known at the call site.
|
| open static LocalizedNumberRangeFormatter! |
Call this method at the beginning of a NumberRangeFormatter fluent chain in which the locale is known at the call site.
|
| open static LocalizedNumberRangeFormatter! |
Call this method at the beginning of a NumberRangeFormatter fluent chain in which the locale is known at the call site.
|
Public methods
with
open static fun with(): UnlocalizedNumberRangeFormatter!
Call this method at the beginning of a NumberRangeFormatter fluent chain in which the locale is not currently known at the call site.
withLocale
open static fun withLocale(locale: ULocale!): LocalizedNumberRangeFormatter!
Call this method at the beginning of a NumberRangeFormatter fluent chain in which the locale is known at the call site.
| Parameters |
locale |
ULocale!: The locale from which to load formats and symbols for number range formatting. |
withLocale
open static fun withLocale(locale: Locale!): LocalizedNumberRangeFormatter!
Call this method at the beginning of a NumberRangeFormatter fluent chain in which the locale is known at the call site.
| Parameters |
locale |
Locale!: The locale from which to load formats and symbols for number range formatting. |
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2025-02-10 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-02-10 UTC."],[],[],null,["# NumberRangeFormatter\n\nAdded in [API level 30](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)\n\nNumberRangeFormatter\n====================\n\n*** ** * ** ***\n\nKotlin \\|[Java](/reference/android/icu/number/NumberRangeFormatter \"View this page in Java\") \n\n```\nabstract class NumberRangeFormatter\n```\n\n|---|----------------------------------------------|\n| [kotlin.Any](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-any/index.html) ||\n| ↳ | [android.icu.number.NumberRangeFormatter](#) |\n\nThe main entrypoint to the formatting of ranges of numbers, including currencies and other units of measurement.\n\nUsage example: \n\n```kotlin\nNumberRangeFormatter.with()\n .identityFallback(RangeIdentityFallback.APPROXIMATELY_OR_SINGLE_VALUE)\n .numberFormatterFirst(NumberFormatter.with().unit(MeasureUnit.METER))\n .numberFormatterSecond(NumberFormatter.with().unit(MeasureUnit.KILOMETER))\n .locale(ULocale.UK)\n .formatRange(750, 1.2)\n .toString();\n // =\u003e \"750 m - 1.2 km\"\n \n```\n\nLike NumberFormatter, NumberRangeFormatter instances (i.e., LocalizedNumberRangeFormatter and UnlocalizedNumberRangeFormatter) are immutable and thread-safe. This API is based on the *fluent* design pattern popularized by libraries such as Google's Guava.\n\nSummary\n-------\n\n| Nested classes ||\n|---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| | [RangeCollapse](/reference/kotlin/android/icu/number/NumberRangeFormatter.RangeCollapse) Defines how to merge fields that are identical across the range sign. |\n| | [RangeIdentityFallback](/reference/kotlin/android/icu/number/NumberRangeFormatter.RangeIdentityFallback) Defines the behavior when the two numbers in the range are identical after rounding. |\n| | [RangeIdentityResult](/reference/kotlin/android/icu/number/NumberRangeFormatter.RangeIdentityResult) Used in the result class FormattedNumberRange to indicate to the user whether the numbers formatted in the range were equal or not, and whether or not the identity fallback was applied. |\n\n| Public methods ||\n|----------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| open static [UnlocalizedNumberRangeFormatter](/reference/kotlin/android/icu/number/UnlocalizedNumberRangeFormatter)! | [with](#with())`()` Call this method at the beginning of a NumberRangeFormatter fluent chain in which the locale is not currently known at the call site. |\n| open static [LocalizedNumberRangeFormatter](/reference/kotlin/android/icu/number/LocalizedNumberRangeFormatter)! | [withLocale](#withLocale(android.icu.util.ULocale))`(`locale:` `[ULocale](../util/ULocale.html#)!`)` Call this method at the beginning of a NumberRangeFormatter fluent chain in which the locale is known at the call site. |\n| open static [LocalizedNumberRangeFormatter](/reference/kotlin/android/icu/number/LocalizedNumberRangeFormatter)! | [withLocale](#withLocale(java.util.Locale))`(`locale:` `[Locale](../../../java/util/Locale.html#)!`)` Call this method at the beginning of a NumberRangeFormatter fluent chain in which the locale is known at the call site. |\n\nPublic methods\n--------------\n\n### with\n\nAdded in [API level 30](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) \n\n```\nopen static fun with(): UnlocalizedNumberRangeFormatter!\n```\n\nCall this method at the beginning of a NumberRangeFormatter fluent chain in which the locale is not currently known at the call site.\n\n| Return ||\n|----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|\n| [UnlocalizedNumberRangeFormatter](/reference/kotlin/android/icu/number/UnlocalizedNumberRangeFormatter)! | An [UnlocalizedNumberRangeFormatter](/reference/kotlin/android/icu/number/UnlocalizedNumberRangeFormatter), to be used for chaining. |\n\n### withLocale\n\nAdded in [API level 30](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) \n\n```\nopen static fun withLocale(locale: ULocale!): LocalizedNumberRangeFormatter!\n```\n\nCall this method at the beginning of a NumberRangeFormatter fluent chain in which the locale is known at the call site.\n\n| Parameters ||\n|----------|-------------------------------------------------------------------------------------------------------------------|\n| `locale` | [ULocale](../util/ULocale.html#)!: The locale from which to load formats and symbols for number range formatting. |\n\n| Return ||\n|------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|\n| [LocalizedNumberRangeFormatter](/reference/kotlin/android/icu/number/LocalizedNumberRangeFormatter)! | A [LocalizedNumberRangeFormatter](/reference/kotlin/android/icu/number/LocalizedNumberRangeFormatter), to be used for chaining. |\n\n### withLocale\n\nAdded in [API level 30](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) \n\n```\nopen static fun withLocale(locale: Locale!): LocalizedNumberRangeFormatter!\n```\n\nCall this method at the beginning of a NumberRangeFormatter fluent chain in which the locale is known at the call site.\n\n| Parameters ||\n|----------|----------------------------------------------------------------------------------------------------------------------------|\n| `locale` | [Locale](../../../java/util/Locale.html#)!: The locale from which to load formats and symbols for number range formatting. |\n\n| Return ||\n|------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|\n| [LocalizedNumberRangeFormatter](/reference/kotlin/android/icu/number/LocalizedNumberRangeFormatter)! | A [LocalizedNumberRangeFormatter](/reference/kotlin/android/icu/number/LocalizedNumberRangeFormatter), to be used for chaining. |"]]
