Implement :currency function in the default registry
#915
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -171,37 +171,6 @@ with _options_ on the _expression_ taking priority over any option values of the | |
| > would be formatted with the resolved options | ||
| > `{ notation: 'scientific', minimumFractionDigits: '1' }`. | ||
|
|
||
| ##### Default Value of `select` Option | ||
|
|
||
| The value `plural` is the default for the option `select` | ||
|
|
@@ -308,37 +277,6 @@ Option values with the following names are however discarded if included in the | |
| - `maximumFractionDigits` | ||
| - `minimumSignificantDigits` | ||
|
|
||
| ##### Default Value of `select` Option | ||
|
|
||
| The value `plural` is the default for the option `select` | ||
|
|
@@ -384,6 +322,136 @@ its _resolved value_ contains the implementation-defined integer value | |
| of the _operand_ of the annotated _expression_, | ||
| together with the resolved options' values. | ||
|
|
||
| ### The `:currency` function | ||
|
|
||
| The function `:currency` is an OPTIONAL selector and formatter for currency values, | ||
| which are a specialized form of numeric selection and formatting. | ||
|
|
||
| #### Operands | ||
|
|
||
| The _operand_ of the `:currency` function can be one of any number of | ||
| implementation-defined types, | ||
| each of which contains a numerical `value` and a `currency`; | ||
| or it can be a [Number Operand](#number-operands), as long as the option | ||
| `currency` is provided. | ||
| The option `currency` MUST NOT be used to override the currency of an implementation-defined type. | ||
| Using this option in such a case results in a _Bad Option_ error. | ||
|
|
||
| The value of the _operand_'s `currency` MUST be either a string containing a | ||
| valid [Unicode Currency Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeCurrencyIdentifier) | ||
| or an implementation-defined currency type. | ||
|
|
||
| A [Number Operand](#number-operands) without a `currency` _option_ results in a _Bad Operand_ error. | ||
|
|
||
| > [!NOTE] | ||
| > For example, in ICU4J, the type `com.ibm.icu.util.CurrencyAmount` can be used | ||
| > to set the amount and currency. | ||
|
|
||
| > [!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 and currency code for formatting. | ||
| > For example, such an implementation might define a "currency operand" | ||
| > to include a key-value structure with specific keys to be the | ||
| > local currency operand, which might look like the following: | ||
| > ```json | ||
| > "operandName": { | ||
| > "value": 123.45, | ||
| > "currency": "EUR" | ||
| > } | ||
| > ``` | ||
|
|
||
| #### 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 currency, | ||
| the value of other options, or all of these. | ||
|
|
||
| Fraction digits for currency values behave differently than for other numeric formatters. | ||
| The number of fraction digits displayed is usually set by the currency used. | ||
| For example, USD uses 2 fraction digits, while JPY uses none. | ||
| Setting `fractionDigits` to `none` makes the display and selection work similar to `:integer`. | ||
aphillips marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| Setting some other number of `fractionDigits` allows greater precision display | ||
| (such as when performing currency conversions or other specialized operations) | ||
|
|
||
| > [!NOTE] | ||
| > Except where noted otherwise, the names of _options_ and their _values_ were derived from the | ||
| > [options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) | ||
| > in JavaScript's `Intl.NumberFormat`. | ||
|
|
||
| The following options and their values are required to be available on the function `:currency`: | ||
| - `select` | ||
| - `plural` (default) | ||
| - `ordinal` | ||
| - `exact` | ||
| - `currency` | ||
| - valid [Unicode Currency Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeCurrencyIdentifier) | ||
| (no default) | ||
aphillips marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - `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) | ||
| - `currencySign` | ||
| - `accounting` | ||
| - `standard` (default) | ||
| - `currencyDisplay` (this option's values are derived from those in ICU NumberFormatter) | ||
| - `auto` (default) | ||
| - `narrow` | ||
aphillips marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| - `short` | ||
| - `iso` | ||
| - `full` | ||
| - `formal` | ||
| - `variant` | ||
eemeli marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| - `useGrouping` | ||
| - `auto` (default) | ||
| - `always` | ||
| - `never` | ||
| - `min2` | ||
| - `minimumIntegerDigits` | ||
| - ([digit size option](#digit-size-options), default: `1`) | ||
| - `fractionDigits` (unlike number/integer formats, the fraction digits for currency formatting are fixed) | ||
| - `auto` (default) (the number of digits used by the currency) | ||
| - `none` | ||
| - ([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 `:currency` _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 :currency currency=USD fractionDigits=none} | ||
| > {{{$n :currency currencySign=accounting}}} | ||
| > ``` | ||
| > would be formatted with the resolved options | ||
| > `{ currencySign: 'accounting', fractionDigits: 'none', currency: 'USD' }`. | ||
|
|
||
| #### Selection | ||
|
|
||
| The _function_ `:currency` performs selection as described in [Number Selection](#number-selection) below. | ||
|
There was a problem hiding this comment. While considering #933, I realised that plural selection on currency values depends on being able to introspect the fraction digits which are by default locale-dependent. The ICU FormattedNumber might do that automatically, but in other APIs the operation can get a bit trickier. There was a problem hiding this comment. It's not locale-dependent. It's currency dependent. This is why fraction digits are different in this function! |
||
|
|
||
| #### Composition | ||
|
|
||
| When an _operand_ or an _option_ value uses a _variable_ annotated, | ||
| directly or indirectly, by a `:currency` _annotation_, | ||
| its _resolved value_ contains an implementation-defined currency value | ||
| of the _operand_ of the annotated _expression_, | ||
| together with the resolved options' values. | ||
|
|
||
| ### Number Operands | ||
|
|
||
| The _operand_ of a number function is either an implementation-defined type or | ||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.