From f05d0ba36fbfec8666b9f35c7b97afa75674d25c Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 30 Oct 2024 15:48:37 -0700 Subject: [PATCH 01/17] Implement `:unit` as _OPTIONAL_ in the registry This introduces `:unit` as an optional function, per discussion elsewhere. --- spec/registry.md | 142 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) diff --git a/spec/registry.md b/spec/registry.md index eb8fb6297..58cd6f724 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -384,6 +384,148 @@ its _resolved value_ contains the implementation-defined integer value of the _operand_ of the annotated _expression_, together with the resolved options' values. +==== + +### `:unit` function + +The function `:unit` is a selector and formatter for unitized values, +that is, numeric values associated with a unit of measurement. +This is a specialized form of numeric selection and formatting. + +> [!IMPORTANT] +> Implementation of this function is **_OPTIONAL_**. +> Any implementation of this function is strongly encouraged to follow this specification. + +#### Operands + +The _operand_ of the `:unit` function can be one of any number of +implementation-defined types, +each of which contains a numerical `value` plus a `unit` and optionally a `perUnit`. +or it can be a [Number Operand](#number-operands), as long as at least the option +`unit` is provided. +The options `unit` and `perUnit` MAY be used to override the units of an implementation-defined type, +provided the units are compatible and the implementation supports conversion. + +The value of the _operand_'s `unit` SHOULD be either a string containing a +valid [Unit Identifier](https://www.unicode.org/reports/tr35/tr35-general.html#unit-identifiers) +or an implementation-defined unit type. + +A [Number Operand](#number-operands) without a `unit` _option_ results in a _Bad Operand_ error. + +> [!NOTE] +> For example, in ICU4J, the type `com.ibm.icu.util.Measure` can be used +> to set the `value` and `unit` (and optionally the `perUnit`). + +> [!NOTE] +> For runtime environments that do not provide a ready-made data structure, +> class, or type for currency values, the implementation ought to provide +> a data structure, convenience function, or documentation on how to encode +> the value, unit, and optionally per-unit for formatting. +> For example, such an implementation might define a "unit operand" +> to include a key-value structure with specific keys to be the +> local unit operand, which might look like the following: +> ```json +> { +> "value": 123.45, +> "unit": "kilometer", +> "perUnit": "hour" +> } +> ``` + +#### Options + +Some options do not have default values defined in this specification. +The defaults for these options are implementation-dependent. +In general, the default values for such options depend on the locale, +the unit, +the value of other options, or all of these. + +The following options and their values are required to be available on the function `:currency`: +- `select` + - `plural` (default) + - `ordinal` + - `exact` +- `unit` + - valid [Unit Identifier](https://www.unicode.org/reports/tr35/tr35-general.html#unit-identifiers) + (no default) +- `perUnit` + - valid [Unit Identifier](https://www.unicode.org/reports/tr35/tr35-general.html#unit-identifiers) + (no default) +- `compactDisplay` (this option only has meaning when combined with the option `notation=compact`) + - `short` (default) + - `long` +- `notation` + - `standard` (default) + - `compact` +- `numberingSystem` + - valid [Unicode Number System Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeNumberSystemIdentifier) + (default is locale-specific) +- `useGrouping` + - `auto` (default) + - `always` + - `never` + - `min2` +- `minimumIntegerDigits` + - ([digit size option](#digit-size-options), default: `1`) +- `minimumFractionDigits` + - ([digit size option](#digit-size-options)) +- `maximumFractionDigits` + - ([digit size option](#digit-size-options)) +- `minimumSignificantDigits` + - ([digit size option](#digit-size-options)) +- `maximumSignificantDigits` + - ([digit size option](#digit-size-options)) + +If the _operand_ of the _expression_ is an implementation-defined type, +such as the _resolved value_ of an _expression_ with a `:unit` _annotation_, +it can include option values. +These are included in the resolved option values of the _expression_, +with _options_ on the _expression_ taking priority over any option values of the _operand_. + +> For example, the _placeholder_ in this _message_: +> ``` +> .input {$n :unit unit=furlong minimumFractionDigits=2} +> {{{$n :unit minimumIntegerDigits=1}}} +> ``` +> would have the resolved options: +> `{ unit: 'furlong', minimumFractionDigits: '2', minimumIntegerDigits: '1' }`. + +Not all per-units are compatible with the primary unit. +Implementations will produce a _Bad Option_ error for units +or combinations of units and per-units that are not supported. + +#### Selection + +The _function_ `:unit` performs selection as described in [Number Selection](#number-selection) below. + +#### Composition + +When an _operand_ or an _option_ value uses a _variable_ annotated, +directly or indirectly, by a `:unit` _annotation_, +its _resolved value_ contains an implementation-defined unit value +of the _operand_ of the annotated _expression_, +together with the resolved options' values. + +> [!NOTE] +> Some implementations support conversation between compatible units. +> For example, consider the value: +> ``` +> { +> "value": 123.5, +> "unit": "meter" +> } +> ``` +> The following _message_ might convert the formatted result to U.S. customary units: +> ``` +> You have {$v :unit unit=foot} to go. +> ``` +> Care has to be excersized with this type of operation. +> Not all units support conversion +> (for example, trying to convert meters to gallons produced a _Bad Option_) +> nor will all implementations support conversion. + +==== + ### Number Operands The _operand_ of a number function is either an implementation-defined type or From 9a5b46a0d188ab32a0341d16be4fed39392e5a49 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 30 Oct 2024 15:52:43 -0700 Subject: [PATCH 02/17] Update registry.md --- spec/registry.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/spec/registry.md b/spec/registry.md index 58cd6f724..ee38922e6 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -384,7 +384,6 @@ its _resolved value_ contains the implementation-defined integer value of the _operand_ of the annotated _expression_, together with the resolved options' values. -==== ### `:unit` function @@ -424,7 +423,7 @@ A [Number Operand](#number-operands) without a `unit` _option_ results in a _Bad > For example, such an implementation might define a "unit operand" > to include a key-value structure with specific keys to be the > local unit operand, which might look like the following: -> ```json +> ``` > { > "value": 123.45, > "unit": "kilometer", @@ -451,6 +450,10 @@ The following options and their values are required to be available on the funct - `perUnit` - valid [Unit Identifier](https://www.unicode.org/reports/tr35/tr35-general.html#unit-identifiers) (no default) +- `unitDisplay` + - `short` (default) + - `narrow` + - `long` - `compactDisplay` (this option only has meaning when combined with the option `notation=compact`) - `short` (default) - `long` @@ -460,6 +463,12 @@ The following options and their values are required to be available on the funct - `numberingSystem` - valid [Unicode Number System Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeNumberSystemIdentifier) (default is locale-specific) +- `signDisplay` + - `auto` (default) + - `always` + - `exceptZero` + - `negative` + - `never` - `useGrouping` - `auto` (default) - `always` @@ -524,7 +533,6 @@ together with the resolved options' values. > (for example, trying to convert meters to gallons produced a _Bad Option_) > nor will all implementations support conversion. -==== ### Number Operands From 4a623f95d5e53b5e5366fe5cbe882a1afbbbb92c Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 30 Oct 2024 15:54:55 -0700 Subject: [PATCH 03/17] Remove stray mentions of "currency" --- spec/registry.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/registry.md b/spec/registry.md index ee38922e6..a77bab5f1 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -417,7 +417,7 @@ A [Number Operand](#number-operands) without a `unit` _option_ results in a _Bad > [!NOTE] > For runtime environments that do not provide a ready-made data structure, -> class, or type for currency values, the implementation ought to provide +> class, or type for unit values, the implementation ought to provide > a data structure, convenience function, or documentation on how to encode > the value, unit, and optionally per-unit for formatting. > For example, such an implementation might define a "unit operand" @@ -439,7 +439,7 @@ In general, the default values for such options depend on the locale, the unit, the value of other options, or all of these. -The following options and their values are required to be available on the function `:currency`: +The following options and their values are required to be available on the function `:unit`: - `select` - `plural` (default) - `ordinal` From aaba29279088a25743c80335b4974ad9140dee01 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Thu, 31 Oct 2024 07:19:51 -0700 Subject: [PATCH 04/17] Apply suggestions from code review Co-authored-by: Tim Chevalier --- spec/registry.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/registry.md b/spec/registry.md index a77bab5f1..487e1339f 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -516,7 +516,7 @@ of the _operand_ of the annotated _expression_, together with the resolved options' values. > [!NOTE] -> Some implementations support conversation between compatible units. +> Some implementations support conversion between compatible units. > For example, consider the value: > ``` > { @@ -528,7 +528,7 @@ together with the resolved options' values. > ``` > You have {$v :unit unit=foot} to go. > ``` -> Care has to be excersized with this type of operation. +> Care has to be exercised with this type of operation. > Not all units support conversion > (for example, trying to convert meters to gallons produced a _Bad Option_) > nor will all implementations support conversion. From 87869903ecefcd576c376ec31398c5a5f326b81f Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Thu, 31 Oct 2024 07:31:54 -0700 Subject: [PATCH 05/17] Better specify conversion conditions --- spec/registry.md | 40 +++++++++++++++++++++------------------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/spec/registry.md b/spec/registry.md index 487e1339f..1d8f66ad7 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -499,6 +499,27 @@ with _options_ on the _expression_ taking priority over any option values of the > would have the resolved options: > `{ unit: 'furlong', minimumFractionDigits: '2', minimumIntegerDigits: '1' }`. +Some implementations support conversion between compatible units. +Attempting to convert units (by specifying the `unit` option) +produces a _Bad Option_ error if conversion is unsupported +or if the specified units are incompatible. +For example, trying to convert meters to gallons produces a _Bad Option_. + +Implementations MUST NOT substitute the unit without performing the associated conversion. + +> For example, consider the value: +> ``` +> { +> "value": 123.5, +> "unit": "meter" +> } +> ``` +> The following _message_ might convert the formatted result to U.S. customary units: +> ``` +> You have {$v :unit unit=foot maximumFractionDigits=0} to go. +> ``` +> This can produce "You have 405 feet to go." + Not all per-units are compatible with the primary unit. Implementations will produce a _Bad Option_ error for units or combinations of units and per-units that are not supported. @@ -515,25 +536,6 @@ its _resolved value_ contains an implementation-defined unit value of the _operand_ of the annotated _expression_, together with the resolved options' values. -> [!NOTE] -> Some implementations support conversion between compatible units. -> For example, consider the value: -> ``` -> { -> "value": 123.5, -> "unit": "meter" -> } -> ``` -> The following _message_ might convert the formatted result to U.S. customary units: -> ``` -> You have {$v :unit unit=foot} to go. -> ``` -> Care has to be exercised with this type of operation. -> Not all units support conversion -> (for example, trying to convert meters to gallons produced a _Bad Option_) -> nor will all implementations support conversion. - - ### Number Operands The _operand_ of a number function is either an implementation-defined type or From b5ef04918eab7c9cc909ed2617a6b8f941d44a15 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Fri, 1 Nov 2024 06:46:54 -0700 Subject: [PATCH 06/17] Address per-unit comments --- spec/registry.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/spec/registry.md b/spec/registry.md index 1d8f66ad7..1e98e84b2 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -399,10 +399,10 @@ This is a specialized form of numeric selection and formatting. The _operand_ of the `:unit` function can be one of any number of implementation-defined types, -each of which contains a numerical `value` plus a `unit` and optionally a `perUnit`. -or it can be a [Number Operand](#number-operands), as long as at least the option +each of which contains a numerical `value` plus a `unit` +or it can be a [Number Operand](#number-operands), as long as the option `unit` is provided. -The options `unit` and `perUnit` MAY be used to override the units of an implementation-defined type, +The option `unit` MAY be used to override the units of an implementation-defined type, provided the units are compatible and the implementation supports conversion. The value of the _operand_'s `unit` SHOULD be either a string containing a @@ -412,22 +412,21 @@ or an implementation-defined unit type. A [Number Operand](#number-operands) without a `unit` _option_ results in a _Bad Operand_ error. > [!NOTE] -> For example, in ICU4J, the type `com.ibm.icu.util.Measure` can be used -> to set the `value` and `unit` (and optionally the `perUnit`). +> For example, in ICU4J, the type `com.ibm.icu.util.Measure` might be used +> as an _operand_ for `:unit` because it contains the `value` and `unit`. > [!NOTE] > For runtime environments that do not provide a ready-made data structure, > class, or type for unit values, the implementation ought to provide > a data structure, convenience function, or documentation on how to encode -> the value, unit, and optionally per-unit for formatting. +> the value and unit for formatting. > For example, such an implementation might define a "unit operand" > to include a key-value structure with specific keys to be the > local unit operand, which might look like the following: > ``` > { > "value": 123.45, -> "unit": "kilometer", -> "perUnit": "hour" +> "unit": "kilometer-per-hour" > } > ``` @@ -447,8 +446,8 @@ The following options and their values are required to be available on the funct - `unit` - valid [Unit Identifier](https://www.unicode.org/reports/tr35/tr35-general.html#unit-identifiers) (no default) -- `perUnit` - - valid [Unit Identifier](https://www.unicode.org/reports/tr35/tr35-general.html#unit-identifiers) +- `usage` + - valid usage identifier (TBD) (no default) - `unitDisplay` - `short` (default) @@ -500,7 +499,7 @@ with _options_ on the _expression_ taking priority over any option values of the > `{ unit: 'furlong', minimumFractionDigits: '2', minimumIntegerDigits: '1' }`. Some implementations support conversion between compatible units. -Attempting to convert units (by specifying the `unit` option) +Attempting to convert units (by specifying the `usage` option) produces a _Bad Option_ error if conversion is unsupported or if the specified units are incompatible. For example, trying to convert meters to gallons produces a _Bad Option_. @@ -520,9 +519,9 @@ Implementations MUST NOT substitute the unit without performing the associated c > ``` > This can produce "You have 405 feet to go." -Not all per-units are compatible with the primary unit. +Not all usages are compatible with the unit. Implementations will produce a _Bad Option_ error for units -or combinations of units and per-units that are not supported. +or combinations of units and usages that are not supported. #### Selection From 59ae65744f16453deb2bf0bdafa3373fad1635ae Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Sat, 2 Nov 2024 16:00:47 -0700 Subject: [PATCH 07/17] Update spec/registry.md Co-authored-by: Mark Davis --- spec/registry.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec/registry.md b/spec/registry.md index 1e98e84b2..ff13f261b 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -483,7 +483,8 @@ The following options and their values are required to be available on the funct - ([digit size option](#digit-size-options)) - `maximumSignificantDigits` - ([digit size option](#digit-size-options)) - +- `usage` + - Well-formed and valid usage identifiers are defined in [Unicode Preferences](https://www.unicode.org/reports/tr35/tr35-info.html#unit-preferences). If the _operand_ of the _expression_ is an implementation-defined type, such as the _resolved value_ of an _expression_ with a `:unit` _annotation_, it can include option values. From 8d83a8f63a1dc678cc6a9d9355ee55fb84be2d11 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Mon, 4 Nov 2024 14:24:41 -0800 Subject: [PATCH 08/17] Changes from 2024-11-04 teleconference - Cleanup the `usage` option (which appeared twice). - Remove `ordinal` selection and add a note to that effect. - Clean up text about conversion --- spec/registry.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/spec/registry.md b/spec/registry.md index ff13f261b..4cd399fd9 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -438,17 +438,20 @@ In general, the default values for such options depend on the locale, the unit, the value of other options, or all of these. +> [!NOTE] +> The option `select` does not accept the value `ordinal` because selecting +> unit values using ordinal rules makes no sense. + The following options and their values are required to be available on the function `:unit`: - `select` - `plural` (default) - - `ordinal` - `exact` - `unit` - valid [Unit Identifier](https://www.unicode.org/reports/tr35/tr35-general.html#unit-identifiers) (no default) - `usage` - - valid usage identifier (TBD) - (no default) + - Well-formed and valid usage identifiers are defined in [Unicode Preferences](https://www.unicode.org/reports/tr35/tr35-info.html#unit-preferences). + - (no default) - `unitDisplay` - `short` (default) - `narrow` @@ -483,8 +486,7 @@ The following options and their values are required to be available on the funct - ([digit size option](#digit-size-options)) - `maximumSignificantDigits` - ([digit size option](#digit-size-options)) -- `usage` - - Well-formed and valid usage identifiers are defined in [Unicode Preferences](https://www.unicode.org/reports/tr35/tr35-info.html#unit-preferences). + If the _operand_ of the _expression_ is an implementation-defined type, such as the _resolved value_ of an _expression_ with a `:unit` _annotation_, it can include option values. @@ -499,11 +501,10 @@ with _options_ on the _expression_ taking priority over any option values of the > would have the resolved options: > `{ unit: 'furlong', minimumFractionDigits: '2', minimumIntegerDigits: '1' }`. -Some implementations support conversion between compatible units. -Attempting to convert units (by specifying the `usage` option) -produces a _Bad Option_ error if conversion is unsupported +Some implementations support conversion to the locale's preferred units via the `usage` option. +Attempting to convert units produces a _Bad Option_ error if such conversion is unsupported or if the specified units are incompatible. -For example, trying to convert meters to gallons produces a _Bad Option_. +For example, trying to convert meters to a `volume` unit (such as "gallons") produces a _Bad Option_. Implementations MUST NOT substitute the unit without performing the associated conversion. From a76eedc8e67b18fb3dd9db0efced9f5eca8a39ed Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Mon, 4 Nov 2024 15:26:11 -0800 Subject: [PATCH 09/17] Make `usage` optional --- spec/registry.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/spec/registry.md b/spec/registry.md index 4cd399fd9..07efa0a25 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -387,7 +387,7 @@ together with the resolved options' values. ### `:unit` function -The function `:unit` is a selector and formatter for unitized values, +The _function_ `:unit` is a selector and formatter for unitized values, that is, numeric values associated with a unit of measurement. This is a specialized form of numeric selection and formatting. @@ -432,11 +432,11 @@ A [Number Operand](#number-operands) without a `unit` _option_ results in a _Bad #### Options -Some options do not have default values defined in this specification. -The defaults for these options are implementation-dependent. -In general, the default values for such options depend on the locale, +Some _options_ do not have default values defined in this specification. +The defaults for these _options_ are implementation-dependent. +In general, the default values for such _options_ depend on the locale, the unit, -the value of other options, or all of these. +the value of other _options_, or all of these. > [!NOTE] > The option `select` does not accept the value `ordinal` because selecting @@ -449,7 +449,7 @@ The following options and their values are required to be available on the funct - `unit` - valid [Unit Identifier](https://www.unicode.org/reports/tr35/tr35-general.html#unit-identifiers) (no default) -- `usage` +- `usage` \[OPTIONAL\] - Well-formed and valid usage identifiers are defined in [Unicode Preferences](https://www.unicode.org/reports/tr35/tr35-info.html#unit-preferences). - (no default) - `unitDisplay` @@ -501,7 +501,8 @@ with _options_ on the _expression_ taking priority over any option values of the > would have the resolved options: > `{ unit: 'furlong', minimumFractionDigits: '2', minimumIntegerDigits: '1' }`. -Some implementations support conversion to the locale's preferred units via the `usage` option. +Some implementations support conversion to the locale's preferred units via the `usage` _option_. +Implementing this _option_ is optional. Attempting to convert units produces a _Bad Option_ error if such conversion is unsupported or if the specified units are incompatible. For example, trying to convert meters to a `volume` unit (such as "gallons") produces a _Bad Option_. From d0eb3e38360d4020f9deba65563503cdc211c96c Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Thu, 7 Nov 2024 08:24:21 -0800 Subject: [PATCH 10/17] Add rounding to `:unit` --- spec/registry.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/spec/registry.md b/spec/registry.md index 07efa0a25..d59d88e44 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -486,6 +486,22 @@ The following options and their values are required to be available on the funct - ([digit size option](#digit-size-options)) - `maximumSignificantDigits` - ([digit size option](#digit-size-options)) +- `roundingPriority` + - `auto` (default) + - `morePrecision` + - `lessPrecision` +- `roundingIncrement` + - 1 (default), 2, 5, 10, 20, 25, 50, 100, 200, 250, 500, 1000, 2000, 2500, and 5000 +- `roundingMode` + - `ceil` + - `floor` + - `expand` + - `trunc` + - `halfCeil` + - `halfFloor` + - `halfExpand` (default) + - `halfTrunc` + - `halfEven` If the _operand_ of the _expression_ is an implementation-defined type, such as the _resolved value_ of an _expression_ with a `:unit` _annotation_, From 57582eeadcbe20d052511405a52fc7c0c6f4ecbe Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Thu, 14 Nov 2024 09:32:09 -0800 Subject: [PATCH 11/17] Make consistent with other functions - Replace `Composition` with `Resolved Value` - Match phrasing to other functions - Move `Resolved Value` before `Selection` like other functions --- spec/registry.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/spec/registry.md b/spec/registry.md index d59d88e44..7f5c7150a 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -542,18 +542,17 @@ Not all usages are compatible with the unit. Implementations will produce a _Bad Option_ error for units or combinations of units and usages that are not supported. -#### Selection - -The _function_ `:unit` performs selection as described in [Number Selection](#number-selection) below. - -#### Composition +#### Resolved Value -When an _operand_ or an _option_ value uses a _variable_ annotated, -directly or indirectly, by a `:unit` _annotation_, -its _resolved value_ contains an implementation-defined unit value +The _resolved value_ of an _expression_ with a `:unit` _function_ +consist of an implementation-defined unit value of the _operand_ of the annotated _expression_, together with the resolved options' values. +#### Selection + +The _function_ `:unit` performs selection as described in [Number Selection](#number-selection) below. + ### Number Operands The _operand_ of a number function is either an implementation-defined type or From 8fe64c9ca3fa7c32817cda9891ea4d8c0632bd8d Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Fri, 15 Nov 2024 07:33:47 -0800 Subject: [PATCH 12/17] Linkify some terms; add `Unsupported Operation` for one error --- spec/registry.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/spec/registry.md b/spec/registry.md index 3fa69099b..31dddcbb7 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -574,9 +574,9 @@ This is a specialized form of numeric selection and formatting. The _operand_ of the `:unit` function can be one of any number of implementation-defined types, each of which contains a numerical `value` plus a `unit` -or it can be a [Number Operand](#number-operands), as long as the option +or it can be a [Number Operand](#number-operands), as long as the _option_ `unit` is provided. -The option `unit` MAY be used to override the units of an implementation-defined type, +The _option_ `unit` MAY be used to override the units of an implementation-defined type, provided the units are compatible and the implementation supports conversion. The value of the _operand_'s `unit` SHOULD be either a string containing a @@ -679,9 +679,9 @@ The following options and their values are required to be available on the funct If the _operand_ of the _expression_ is an implementation-defined type, such as the _resolved value_ of an _expression_ with a `:unit` _annotation_, -it can include option values. -These are included in the resolved option values of the _expression_, -with _options_ on the _expression_ taking priority over any option values of the _operand_. +it can include _option_ values. +These are included in the resolved _option_ values of the _expression_, +with _options_ on the _expression_ taking priority over any _option_ values of the _operand_. > For example, the _placeholder_ in this _message_: > ``` @@ -693,9 +693,10 @@ with _options_ on the _expression_ taking priority over any option values of the Some implementations support conversion to the locale's preferred units via the `usage` _option_. Implementing this _option_ is optional. -Attempting to convert units produces a _Bad Option_ error if such conversion is unsupported -or if the specified units are incompatible. -For example, trying to convert meters to a `volume` unit (such as "gallons") produces a _Bad Option_. +Attempting to convert units produces an _Unsupported Operation_ error if such conversion is unsupported. +It produces a _Bad Option_ error if the specified units are incompatible. +> For example, trying to convert a `length` unit such as meters +> to a `volume` unit (such as "gallons") produces a _Bad Option_. Implementations MUST NOT substitute the unit without performing the associated conversion. @@ -712,7 +713,7 @@ Implementations MUST NOT substitute the unit without performing the associated c > ``` > This can produce "You have 405 feet to go." -Not all usages are compatible with the unit. +Not all `usage` values are compatible with a given unit. Implementations will produce a _Bad Option_ error for units or combinations of units and usages that are not supported. @@ -721,7 +722,7 @@ or combinations of units and usages that are not supported. The _resolved value_ of an _expression_ with a `:unit` _function_ consist of an implementation-defined unit value of the _operand_ of the annotated _expression_, -together with the resolved options' values. +together with the resolved _options_ and their resolved values. #### Selection From 0c7beb211aa022eba9f4998d3029829ed054ac14 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Fri, 15 Nov 2024 07:34:33 -0800 Subject: [PATCH 13/17] Make section title consistent with other sections --- spec/registry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/registry.md b/spec/registry.md index 31dddcbb7..fc7055980 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -559,7 +559,7 @@ together with the resolved options' values. The _function_ `:currency` performs selection as described in [Number Selection](#number-selection) below. -### `:unit` function +### The `:unit` function The _function_ `:unit` is a selector and formatter for unitized values, that is, numeric values associated with a unit of measurement. From b90a7206d1cf5b3b0ccf0932af8da01abf954d80 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 20 Nov 2024 11:16:12 -0800 Subject: [PATCH 14/17] Address comments - Change `:unit` to **Proposed** - Modify `usage` to use valid - Modify `usage` to be in its own subsection - Modify `usage` to SHOULD _Unsupported Operation_ when the conversion isn't supported --- spec/registry.md | 52 +++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 27 deletions(-) diff --git a/spec/registry.md b/spec/registry.md index fc7055980..0b379333c 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -561,14 +561,11 @@ The _function_ `:currency` performs selection as described in [Number Selection] ### The `:unit` function -The _function_ `:unit` is a selector and formatter for unitized values, -that is, numeric values associated with a unit of measurement. +The _function_ `:unit` is **Proposed** for inclusion in the next release of this specification but has not yet been finalized. +The _function_ `:unit` is proposed to be a **RECOMMENDED** selector and formatter for unitized values, +that is, for numeric values associated with a unit of measurement. This is a specialized form of numeric selection and formatting. -> [!IMPORTANT] -> Implementation of this function is **_OPTIONAL_**. -> Any implementation of this function is strongly encouraged to follow this specification. - #### Operands The _operand_ of the `:unit` function can be one of any number of @@ -622,10 +619,10 @@ The following options and their values are required to be available on the funct - `exact` - `unit` - valid [Unit Identifier](https://www.unicode.org/reports/tr35/tr35-general.html#unit-identifiers) - (no default) -- `usage` \[OPTIONAL\] - - Well-formed and valid usage identifiers are defined in [Unicode Preferences](https://www.unicode.org/reports/tr35/tr35-info.html#unit-preferences). - - (no default) + (no default, see [Unit Conversion](#unit-conversion) below) +- `usage` \[RECOMMENDED\] + - valid [Unicode Unit Preference](https://www.unicode.org/reports/tr35/tr35-info.html#unit-preferences) + (no default) - `unitDisplay` - `short` (default) - `narrow` @@ -691,12 +688,26 @@ with _options_ on the _expression_ taking priority over any _option_ values of t > would have the resolved options: > `{ unit: 'furlong', minimumFractionDigits: '2', minimumIntegerDigits: '1' }`. -Some implementations support conversion to the locale's preferred units via the `usage` _option_. +#### Resolved Value + +The _resolved value_ of an _expression_ with a `:unit` _function_ +consist of an implementation-defined unit value +of the _operand_ of the annotated _expression_, +together with the resolved _options_ and their resolved values. + +#### Selection + +The _function_ `:unit` performs selection as described in [Number Selection](#number-selection) below. + +#### Unit Conversion + +Implementations MAY support conversion to the locale's preferred units via the `usage` _option_. Implementing this _option_ is optional. -Attempting to convert units produces an _Unsupported Operation_ error if such conversion is unsupported. -It produces a _Bad Option_ error if the specified units are incompatible. +Not all `usage` values are compatible with a given unit. +Implementations SHOULD emit an _Unsupported Operation_ error if the requestion conversion is not supported. + > For example, trying to convert a `length` unit such as meters -> to a `volume` unit (such as "gallons") produces a _Bad Option_. +> to a `volume` unit (such as "gallons") could produce an _Unsupported Operation_ error. Implementations MUST NOT substitute the unit without performing the associated conversion. @@ -713,20 +724,7 @@ Implementations MUST NOT substitute the unit without performing the associated c > ``` > This can produce "You have 405 feet to go." -Not all `usage` values are compatible with a given unit. -Implementations will produce a _Bad Option_ error for units -or combinations of units and usages that are not supported. - -#### Resolved Value - -The _resolved value_ of an _expression_ with a `:unit` _function_ -consist of an implementation-defined unit value -of the _operand_ of the annotated _expression_, -together with the resolved _options_ and their resolved values. -#### Selection - -The _function_ `:unit` performs selection as described in [Number Selection](#number-selection) below. ### Number Operands From 13e33f08118fe8abcdecc7082ffe333983020c82 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 20 Nov 2024 11:34:49 -0800 Subject: [PATCH 15/17] Address comments --- spec/registry.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/spec/registry.md b/spec/registry.md index 0b379333c..eac185157 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -704,10 +704,11 @@ The _function_ `:unit` performs selection as described in [Number Selection](#nu Implementations MAY support conversion to the locale's preferred units via the `usage` _option_. Implementing this _option_ is optional. Not all `usage` values are compatible with a given unit. -Implementations SHOULD emit an _Unsupported Operation_ error if the requestion conversion is not supported. +Implementations SHOULD emit an _Unsupported Operation_ error if the requested conversion is not supported. -> For example, trying to convert a `length` unit such as meters -> to a `volume` unit (such as "gallons") could produce an _Unsupported Operation_ error. +> For example, trying to convert a `length` unit (such as "meters") +> to a `volume` usage (which might be a unit akin to "liters" or "gallons", depending on the locale) +> could produce an _Unsupported Operation_ error. Implementations MUST NOT substitute the unit without performing the associated conversion. From b5cf412683a7d5c99109218cf11c35161f116837 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 20 Nov 2024 17:06:07 -0800 Subject: [PATCH 16/17] Address comments, remove unit conversion --- spec/registry.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/spec/registry.md b/spec/registry.md index eac185157..cd150966a 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -573,8 +573,6 @@ implementation-defined types, each of which contains a numerical `value` plus a `unit` or it can be a [Number Operand](#number-operands), as long as the _option_ `unit` is provided. -The _option_ `unit` MAY be used to override the units of an implementation-defined type, -provided the units are compatible and the implementation supports conversion. The value of the _operand_'s `unit` SHOULD be either a string containing a valid [Unit Identifier](https://www.unicode.org/reports/tr35/tr35-general.html#unit-identifiers) @@ -719,9 +717,10 @@ Implementations MUST NOT substitute the unit without performing the associated c > "unit": "meter" > } > ``` -> The following _message_ might convert the formatted result to U.S. customary units: +> The following _message_ might convert the formatted result to U.S. customary units +> in the `en-US` locale: > ``` -> You have {$v :unit unit=foot maximumFractionDigits=0} to go. +> You have {$v :unit usage=road maximumFractionDigits=0} to go. > ``` > This can produce "You have 405 feet to go." From 94c0dec6d2eb809d1f56b0de53131af05d00718d Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 20 Nov 2024 17:08:40 -0800 Subject: [PATCH 17/17] Move link to unit conversion to correct option --- spec/registry.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/registry.md b/spec/registry.md index cd150966a..0d33b63e8 100644 --- a/spec/registry.md +++ b/spec/registry.md @@ -617,10 +617,10 @@ The following options and their values are required to be available on the funct - `exact` - `unit` - valid [Unit Identifier](https://www.unicode.org/reports/tr35/tr35-general.html#unit-identifiers) - (no default, see [Unit Conversion](#unit-conversion) below) + (no default) - `usage` \[RECOMMENDED\] - valid [Unicode Unit Preference](https://www.unicode.org/reports/tr35/tr35-info.html#unit-preferences) - (no default) + (no default, see [Unit Conversion](#unit-conversion) below) - `unitDisplay` - `short` (default) - `narrow`