Skip to content

Commit 40feac2

Browse files
committed
Make preserving order a normative recommendation and make terms definitions
1 parent 778df52 commit 40feac2

File tree

1 file changed

+17
-15
lines changed

1 file changed

+17
-15
lines changed

spec/Appendix A -- Notation Conventions.md

+17-15
Original file line numberDiff line numberDiff line change
@@ -224,32 +224,34 @@ types like "list", "set" and "map". These describe observable data collections
224224
such as the result of applying a grammar and the inputs and outputs of
225225
algorithms. They also describe unobservable data collections such as temporary
226226
data internal to an algorithm. Each data collection type defines the operations
227-
available, and whether values unique or ordered.
227+
available, and whether values are unique or ordered.
228228

229229
**List**
230230

231-
The term "list" describes a sequence of values which may not be unique. A list
232-
is ordered unless explicitly stated otherwise (as an "unordered list"). For
231+
:: The term _list_ describes a sequence of values which may not be unique. A
232+
list is ordered unless explicitly stated otherwise (as an "unordered list"). For
233233
clarity the term "ordered list" may be used when an order is semantically
234234
important.
235235

236236
**Set**
237237

238-
The term "set" describes a unique collection of values, where each value is
238+
:: The term _set_ describes a unique collection of values, where each value is
239239
considered a "member" of that set. A set is unordered unless explicitly stated
240240
otherwise (as an "ordered set"). For clarity the term "unordered set" may be
241241
used when the lack of an order is semantically important.
242242

243243
**Map**
244244

245-
The term "map" describes a collection of "entry" key and value pairs, where the
246-
set of keys across all entries is unique but the values across all entries may
247-
repeat. A map is unordered unless explicitly stated otherwise (as an "ordered
248-
map"). For clarity the term "unordered map" may be used when the lack of an
249-
order is semantically important.
250-
251-
Note: To improve legibility, when possible implementations should preserve
252-
observable order for unordered data collections. For example, if an applied
253-
grammar to an input string results in an unordered set, serializing that set (to
254-
a string or other observable output) should produce the same order found in the
255-
original input string.
245+
:: The term _map_ describes a collection of "entry" key and value pairs, where
246+
the set of keys across all entries is unique but the values across all entries
247+
may repeat. A map is unordered unless explicitly stated otherwise (as an
248+
"ordered map"). For clarity the term "unordered map" may be used when the lack
249+
of an order is semantically important.
250+
251+
**Preserving order**
252+
253+
To improve legibility, when possible implementations should preserve observable
254+
order for unordered data collections. For example, if applying a grammar to an
255+
input string produces an unordered set, serializing that set (to a string or
256+
other observable output) should produce the same order found in the original
257+
input string.

0 commit comments

Comments
 (0)