Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Change :math to :offset and remove draft status #1073

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 19, 2025
+21 −20
Merged

Change :math to :offset and remove draft status #1073

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 21 additions & 20 deletions spec/functions/number.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,40 +159,41 @@ together with the resolved options' values.

The _function_ `:integer` performs selection as described in [Number Selection](#number-selection) below.

#### The `:math` function
#### The `:offset` function

> [!IMPORTANT]
> The _function_ `:math` has a status of **Draft**.
> It is proposed for inclusion in a future release of this specification and is not Stable.

The _function_ `:math` is proposed as a _selector_ and _formatter_ for matching or formatting
numeric values to which a mathematical operation has been applied.
The _function_ `:offset` is a _selector_ and _formatter_ for matching or formatting
numeric values to which an offset has been applied.
The "offset" is a small integer adjustment of the _operand_'s value.

> This function is useful for selection and formatting of values that
> differ from the input value by a specified amount.
> For example, it can be used in a message such as this:
> For example, it can be used in a _message_ such as this:
>
> ```
> .input {$like_count :integer}
> .local $others_count = {$like_count :math subtract=1}
> .local $others_count = {$like_count :offset subtract=1}
> .match $like_count $others_count
> 0 * {{Your post has no likes.}}
> 1 * {{{$name} liked your post.}}
> * one {{{$name} and {$others_count} other user liked your post.}}
> * * {{{$name} and {$others_count} other users liked your post.}}
> ```

##### Operands
> [!NOTE]
> The purpose of this _function_ is to supply compatibility with
> ICU's `PluralFormat` and its `offset` feature, also found in ICU MessageFormat.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> ICU's `PluralFormat` and its `offset` feature, also found in ICU MessageFormat.
> ICU's `PluralFormat` and its `offset` feature, also found in ICU MessageFormat.
> It is needed for migration, because it is commonly used for messages
> that need to convey the first few items of a list plus the count of the remainder,
> such as in the example above.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we're inverting things a bit here. As I see it, the primary purpose of this function is the same as that of plural offset in MF1, to enable the expression of messages with plural variance that depends on an offset count. Supporting migration from MF1 arises from that; it ought not be presented as "the purpose" of the function as a whole.


The function `:math` requires a [Number Operand](#number-operands) as its _operand_.
##### `:offset` Operands

##### Options
The function `:offset` requires a [Number Operand](#number-operands) as its _operand_.

##### `:offset` Options

The _options_ on `:math` are exclusive with each other,
The _options_ on `:offset` are exclusive with each other,
and exactly one _option_ is always required.
The _options_ do not have default values.
Comment on lines +192 to 194
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The _options_ on `:offset` are exclusive with each other,
and exactly one _option_ is always required.
The _options_ do not have default values.

Delete, there is only one, and it is required below.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But this PR is not changing the inclusion of both add and subtract options?


The following _options_ are REQUIRED to be available on the function `:math`:
The following _options_ are REQUIRED to be available on the function `:offset`:

- `add`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's actually a subtract, since it is the remaining count.

- _digit size option_
Expand All @@ -204,9 +205,9 @@ or if an _option value_ is not a _digit size option_,
a _Bad Option_ error is emitted
and a _fallback value_ used as the _resolved value_ of the _expression_.

##### Resolved Value
##### `:offset` Resolved Value

The _resolved value_ of an _expression_ with a `:math` _function_
The _resolved value_ of an _expression_ with a `:offset` _function_
contains the implementation-defined numeric value
of the _operand_ of the annotated _expression_.

Expand All @@ -222,18 +223,18 @@ If the _operand_ of the _expression_ is an implementation-defined numeric type,
such as the _resolved value_ of an _expression_ with a `:number` or `:integer` _annotation_,
it can include option values.
These are included in the resolved option values of the _expression_.
The `:math` _options_ are not included in the resolved option values.
The `:offset` _options_ are not included in the resolved option values.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At least two reasons:

  1. Clarity; the function processes and "consumes" the option, as its resolved value includes the offset. This also allows for an implementation to present the resolved value of an :offset and a :number using the same representation.
  2. We've not identified any use cases that would benefit from a consumer of an :offset value to know that an offset was applied to the value, or what that offset was.


> [!NOTE]
> Implementations can encounter practical limits with `:math` _expressions_,
> Implementations can encounter practical limits with `:offset` _expressions_,
> such as the result of adding two integers exceeding
> the storage or precision of some implementation-defined number type.
> In such cases, implementations can emit an _Unsupported Operation_ error
> or they might just silently overflow the underlying data value.

##### Selection
##### `:offset` Selection

The _function_ `:math` performs selection as described in [Number Selection](#number-selection) below.
The _function_ `:offset` performs selection as described in [Number Selection](#number-selection) below.

#### The `:currency` function

Expand Down