8000 Describe date/time formatting functions and options (#623) · unicode-org/message-format-wg@9d25057 · GitHub
[go: up one dir, main page]
Skip to content

Commit 9d25057

Browse files
aphillipseemeli
aphillips
and
eemeli
authored
Describe date/time formatting functions and options (#623)
* Describe date/time formatting functions and options Based on the 2024-02-05 teleconference discussion, describe the date/time formatting functions in a manner similar to the number selection design document. * Improve operands * Update exploration/default-registry-and-mf1-compatibility.md Co-authored-by: Eemeli Aro <eemeli@mozilla.com> * Update exploration/default-registry-and-mf1-compatibility.md Co-authored-by: Eemeli Aro <eemeli@mozilla.com> * Address comments about date operands * Address @eemeli's comments Here I have tried to be more rigorous in describing the functions and their options. Note that we as a group still need to agree to this design. * Tweak operand section formatting --------- Co-authored-by: Eemeli Aro <eemeli@mozilla.com>
1 parent e588afb commit 9d25057

File tree

1 file changed

+170
-29
lines changed

1 file changed

+170
-29
lines changed

‎exploration/default-registry-and-mf1-compatibility.md

Lines changed: 170 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -63,37 +63,178 @@ Options:
6363

6464
(When no default is given, the default depends on the locale or implementation)
6565

66-
### Dates and Times
67-
68-
Function name: `:datetime`
69-
70-
Aliases:
71-
- `:date` (with `style=...` option corresponding to `:datetime dateStyle=...`)
72-
- `:time` (with `style=...` option corresponding to `:datetime timeStyle=...`)
66+
---
7367

74-
Operand: "iso8601"
75-
76-
Options:
77-
- `dateStyle` (`full` `long` `medium` `short`)
78-
- `timeStyle` (`full` `long` `medium` `short`)
79-
- `calendar` (buddhist chinese coptic dangi ethioaa ethiopic gregory hebrew indian islamic islamic-umalqura
80-
islamic-tbla islamic-civil islamic-rgsa iso8601 japanese persian roc)
81-
- `numberingSystem` (arab arabext bali beng deva fullwide gujr guru hanidec khmr knda laoo latn
82-
limb mlym mong mymr orya tamldec telu thai tibt)
83-
- `timezone` (tzid)
84-
- `hourCycle` (`h11` `h12` `h23` `h24`)
85-
- `weekday` (`long` `short` `narrow`)
86-
- `era` (`long` `short` `narrow`)
87-
- `year` (`numeric` `2-digit`)
88-
- `month` (`numeric` `2-digit` `long` `short` `narrow`)
89-
- `day` (`numeric` `2-digit`)
90-
- `hour` (`numeric` `2-digit`)
91-
- `minute` (`numeric` `2-digit`)
92-
- `second` (`numeric` `2-digit`)
93-
- `fractionalSecondDigits` (`1`, `2`, `3`)
94-
- `timeZoneName` (`long` `short` `shortOffset` `longOffset` `shortGeneric` `longGeneric`)
68+
### Dates and Times
9569

96-
(When no default is given, the default depends on the locale or implementation)
70+
This subsection describes the functions and options for date/time formatting.
71+
72+
#### Functions
73+
74+
Functions for formatting [date/time values](#operands) in the default registry are:
75+
76+
- `:datetime`
77+
- `:date`
78+
- `:time`
79+
80+
If no options are specified, each of the functions defaults to the following:
81+
- `{$d :datetime}` is the same as `{$d :datetime dateStyle=short timeStyle=short}`
82+
- `{$d :date}` is the same as `{$d :date style=short}`
83+
- `{$t :time}` is the same as `{$t :time style=short}`
84+
85+
> [!NOTE]
86+
> Pattern selection based on date/time values is a complex topic and no support for this
87+
> is required in this release.
88+
89+
#### Operands
90+
91+
The _operand_ of a date/time function is either
92+
an implementation-defined date/time type (passed in as an argument)
93+
or a _date/time literal value_, as defined below.
94+
All other _operand_ values produce a _Selection Error_ when evaluated for selection
95+
or a _Formatting Error_ when formatting the value.
96+
97+
A **_<dfn>date/time literal value</dfn>_** is a non-empty string consisting of
98+
one of the following:
99+
- an XMLSchema 1.1 [dateTime](https://www.w3.org/TR/xmlschema11-2/#dateTime)
100+
- an XMLSchema 1.1 [time](https://www.w3.org/TR/xmlschema11-2/#time)
101+
- an XMLSchema 1.1 [date](https://www.w3.org/TR/xmlschema11-2/#date)
102+
103+
The `timezoneOffset` of each of these formats is optional.
104+
When the offset is not present, implementations should use a floating time type
105+
(such as Java's `java.time.LocalDateTime`) to represent the time value.
106+
For more information, see [Working with Timezones](https://w3c.github.io/timezone).
107+
108+
> [!IMPORTANT]
109+
> The [ABNF](/main/spec/message.abnf) and [syntax](/main/spec/syntax.md) of MFv2
110+
> do not formally define date/time literals.
111+
> This means that a _message_ can be syntactically valid but produce
112+
> runtime errors due to what amounts to a "type mismatch".
113+
114+
> [!NOTE]
115+
> String values passed as variables in the _formatting context_'s
116+
> _input mapping_ can be formatted as date/time values as long as their
117+
> contents are date/time literals.
118+
>
119+
> For example, if the value of the variable `now` were the string
120+
> `2024-02-06T16:40:00Z`, it would behave identically to the local
121+
> variable in this example:
122+
> ```
123+
> .local $example = {|2024-02-06T16:40:00Z| :datetime}
124+
> {{{$now :datetime} == {$example}}}
125+
> ```
126+
127+
> [!NOTE]
128+
> True time zone support in serializations is expected to coincide with the adoption
129+
> of Temporal in JavaScript.
130+
> The form of these serializations is known and is a de facto standard.
131+
> Support for these extensions is expected to be required in the post-tech preview.
132+
> See: https://datatracker.ietf.org/doc/draft-ietf-sedate-datetime-extended/
133+
134+
#### Options
< 10000 /td>135+
136+
All date/time functions support the following options, which
137+
provide high-level control over date/time formats:
138+
- `calendar` (default is locale-specific)
139+
- valid [Unicode Calendar Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeCalendarIdentifier)
140+
- `numberingSystem` (default is locale-specific)
141+
- valid [Unicode Number System Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeNumberSystemIdentifier)
142+
- `timeZone` (default is system default time zone or UTC)
143+
- valid identifier per [BCP175](https://www.rfc-editor.org/rfc/rfc6557)
144+
145+
In addition to the above high-level options, a function can use either the appropriate
146+
_style_ options for that function
147+
or can use a collection of _field options_ (but not both) to control the formatted
148+
output.
149+
150+
The function `:datetime` has these function-specific _style_ options.
151+
- `dateStyle`
152+
- `full`
153+
- `long`
154+
- `medium`
155+
- `short`
156+
- `timeStyle`
157+
- `full`
158+
- `long`
159+
- `medium`
160+
- `short`
161+
162+
The function `:date` has these function-specific _style_ options:
163+
- `style`
164+
- `full`
165+
- `long`
166+
- `medium`
167+
- `short`
168+
169+
The function `:time` has these function-specific _style_ options:
170+
- `style`
171+
- `full`
172+
- `long`
173+
- `medium`
174+
- `short`
175+
176+
The _field_ options are defined as follows:
177+
178+
All functions have the following option:
179+
- `timeZoneName`
180+
- `long`
181+
- `short`
182+
- `shortOffset`
183+
- `longOffset`
184+
- `shortGeneric`
185+
- `longGeneric`
186+
187+
The functions `:datetime` and `:date` have the following options:
188+
- `weekday`
189+
- `long`
190+
- `short`
191+
- `narrow`
192+
- `era`
193+
- `long`
194+
- `short`
195+
- `narrow`
196+
- `year`
197+
- `numeric`
198+
- `2-digit`
199+
- `month`
200+
- `numeric`
201+
- `2-digit`
202+
- `long`
203+
- `short`
204+
- `narrow`
205+
- `day`
206+
- `numeric`
207+
- `2-digit`
208+
209+
The functions `:datetime` and `:time` have the following options:
210+
- `hour`
211+
- `numeric`
212+
- `2-digit`
213+
- `minute`
214+
- `numeric`
215+
- `2-digit`
216+
- `second`
217+
- `numeric`
218+
- `2-digit`
219+
- `fractionalSecondDigits`
220+
- `1`
221+
- `2`
222+
- `3`
223+
- `hourCycle` (default is locale-specific)
224+
- `h11`
225+
- `h12`
226+
- `h23`
227+
- `h24`
228+
229+
230+
#### Selection
231+
232+
Selection based on date/time types is not required by MFv2.
233+
Implementations should use care when defining selectors based on date/time types.
234+
The types of queries found in implementations such as `java.time.TemporalAccessor`
235+
are complex and user expectations may be inconsistent with good I18N practices.
236+
237+
---
97238
98239
### Strings
99240

0 commit comments

Comments
 (0)
0