You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/style-guide.md
+23-1
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,7 @@ This document is an evolving list of recommendations for the ECMA-402 specificat
4
4
5
5
This document contains background on how the style decisions were reached. The actual recommendations are highlighted with a :star2: emoji.
6
6
7
+
7
8
## Table of Contents
8
9
9
10
-[Casing Conventions](#casing-conventions)
@@ -27,7 +28,9 @@ This document contains background on how the style decisions were reached. The
27
28
-[Pros](#pros-3)
28
29
-[Cons](#cons-3)
29
30
-[Decision](#decision-3)
30
-
31
+
-[Element Ordering](#element-ordering)
32
+
- [General Guidelines](#general-guidelines)
33
+
- [resolvedOptions](#resolvedoptions)
31
34
32
35
*Table of Contents generated using https://magnetikonline.github.io/markdown-toc-generate/*
33
36
@@ -199,3 +202,22 @@ We could enforce a camel case convention on these strings, such as the following
199
202
##### Decision
200
203
201
204
- Defer the decision on the syntax for identifiers to the other specification when possible.
205
+
206
+
## Element Ordering
207
+
208
+
This section concerns the observable order for elements of arrays and properties of objects.
209
+
210
+
### General Guidelines
211
+
212
+
:star2:*ECMA-402 must provide a deterministic order for the elements of all arrays and the properties of all objects. This order should be lexicographic except in cases for which there is a clearly preferable semantic ordering. :star2:*
213
+
214
+
For example, an array holding the time zone identifiers "Asia/Tokyo", "Asia/Ho_Chi_Minh", and "Asia/Dubai" should use the order `["Asia/Dubai", "Asia/Ho_Chi_Minh", "Asia/Tokyo"]`
215
+
216
+
For an example of when *not* to use lexicographic order, consider an array holding calendar time scale units. This array could be ordered by descending magnitude as `["years", "months", "weeks", "days"]` or its reverse ascending magnitude as `["days", "weeks", "months", "years"]`, but should not use the lexicographic `["days", "months", "weeks", "years"]` order.
217
+
218
+
### `resolvedOptions`
219
+
:star2:*Properties in the output from `resolvedOptions()` of an Intl object should start with `locale` and otherwise use lexicographic order. Deviations (such as those motivated by semantic order involving a subset of properties) must be documented.*:star2:
220
+
221
+
Spec changes that add properties should do so in accordance with this recommendation, rather than automatically placing them at the end—relative enumeration order of properties should remain stable over time, but there is no such expectation regarding adjacency.
222
+
#### Examples
223
+
`Object.keys(new Intl.Segmenter().resolvedOptions())` returns `[ 'locale', 'granularity' ]`. If support for the [Unicode BCP 47 U Extension "dx" key](https://unicode.org/reports/tr35/#UnicodeDictionaryBreakExclusionIdentifier) were added and exposed as `dictionaryBreakExcludedScripts`, that property would belong before `granularity`.
0 commit comments