Skip to content

Commit 1e7cdbb

Browse files
authored
Change :math to :offset and remove draft status (#1073)
In the 2025-05-12 teleconference, the group agreed to make the name of this function less generic. A number of alternative names were proposed in the call. The name `:offset` was used here, partially as a placeholder while we seek consensus. We agreed that the new function would be limited to adjusting the value of the operand by small integer values. _Digit Size Option_, used here, would make that from `0` to `999`. It has been proposed that this be restricted to `1` to `99`. In this pull request, note that I added the function name to subsections. The current spec doesn't link properly to subsections because all functions use the same section ID. I did not change the other functions to match, pending discussion.
1 parent 70b6d32 commit 1e7cdbb

File tree

1 file changed

+21
-20
lines changed

1 file changed

+21
-20
lines changed

spec/functions/number.md

Lines changed: 21 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -159,40 +159,41 @@ together with the resolved options' values.
159159
160160
The _function_ `:integer` performs selection as described in [Number Selection](#number-selection) below.
161161
162-
#### The `:math` function
162+
#### The `:offset` function
163163
164-
> [!IMPORTANT]
165-
> The _function_ `:math` has a status of **Draft**.
166-
> It is proposed for inclusion in a future release of this specification and is not Stable.
167-
168-
The _function_ `:math` is proposed as a _selector_ and _formatter_ for matching or formatting
169-
numeric values to which a mathematical operation has been applied.
164+
The _function_ `:offset` is a _selector_ and _formatter_ for matching or formatting
165+
numeric values to which an offset has been applied.
166+
The "offset" is a small integer adjustment of the _operand_'s value.
170167
171168
> This function is useful for selection and formatting of values that
172169
> differ from the input value by a specified amount.
173-
> For example, it can be used in a message such as this:
170+
> For example, it can be used in a _message_ such as this:
174171
>
175172
> ```
176173
> .input {$like_count :integer}
177-
> .local $others_count = {$like_count :math subtract=1}
174+
> .local $others_count = {$like_count :offset subtract=1}
178175
> .match $like_count $others_count
179176
> 0 * {{Your post has no likes.}}
180177
> 1 * {{{$name} liked your post.}}
181178
> * one {{{$name} and {$others_count} other user liked your post.}}
182179
> * * {{{$name} and {$others_count} other users liked your post.}}
183180
> ```
184181
185-
##### Operands
182+
> [!NOTE]
183+
> The purpose of this _function_ is to supply compatibility with
184+
> ICU's `PluralFormat` and its `offset` feature, also found in ICU MessageFormat.
186185
187-
The function `:math` requires a [Number Operand](#number-operands) as its _operand_.
186+
##### `:offset` Operands
188187
189-
##### Options
188+
The function `:offset` requires a [Number Operand](#number-operands) as its _operand_.
189+
190+
##### `:offset` Options
190191
191-
The _options_ on `:math` are exclusive with each other,
192+
The _options_ on `:offset` are exclusive with each other,
192193
and exactly one _option_ is always required.
193194
The _options_ do not have default values.
194195
195-
The following _options_ are REQUIRED to be available on the function `:math`:
196+
The following _options_ are REQUIRED to be available on the function `:offset`:
196197
197198
- `add`
198199
- _digit size option_
@@ -204,9 +205,9 @@ or if an _option value_ is not a _digit size option_,
204205
a _Bad Option_ error is emitted
205206
and a _fallback value_ used as the _resolved value_ of the _expression_.
206207
207-
##### Resolved Value
208+
##### `:offset` Resolved Value
208209
209-
The _resolved value_ of an _expression_ with a `:math` _function_
210+
The _resolved value_ of an _expression_ with a `:offset` _function_
210211
contains the implementation-defined numeric value
211212
of the _operand_ of the annotated _expression_.
212213
@@ -222,18 +223,18 @@ If the _operand_ of the _expression_ is an implementation-defined numeric type,
222223
such as the _resolved value_ of an _expression_ with a `:number` or `:integer` _annotation_,
223224
it can include option values.
224225
These are included in the resolved option values of the _expression_.
225-
The `:math` _options_ are not included in the resolved option values.
226+
The `:offset` _options_ are not included in the resolved option values.
226227
227228
> [!NOTE]
228-
> Implementations can encounter practical limits with `:math` _expressions_,
229+
> Implementations can encounter practical limits with `:offset` _expressions_,
229230
> such as the result of adding two integers exceeding
230231
> the storage or precision of some implementation-defined number type.
231232
> In such cases, implementations can emit an _Unsupported Operation_ error
232233
> or they might just silently overflow the underlying data value.
233234
234-
##### Selection
235+
##### `:offset` Selection
235236
236-
The _function_ `:math` performs selection as described in [Number Selection](#number-selection) below.
237+
The _function_ `:offset` performs selection as described in [Number Selection](#number-selection) below.
237238
238239
#### The `:currency` function
239240

0 commit comments

Comments
 (0)