Skip to content

Commit 778df52

Browse files
committed
Add Lee's suggested data collections paragraph
1 parent 42a617b commit 778df52

File tree

1 file changed

+37
-0
lines changed

1 file changed

+37
-0
lines changed

spec/Appendix A -- Notation Conventions.md

+37
Original file line numberDiff line numberDiff line change
@@ -216,3 +216,40 @@ Fibonacci(number):
216216
Note: Algorithms described in this document are written to be easy to
217217
understand. Implementers are encouraged to include equivalent but optimized
218218
implementations.
219+
220+
## Data Collections
221+
222+
This specification describes the semantic properties of data collections using
223+
types like "list", "set" and "map". These describe observable data collections
224+
such as the result of applying a grammar and the inputs and outputs of
225+
algorithms. They also describe unobservable data collections such as temporary
226+
data internal to an algorithm. Each data collection type defines the operations
227+
available, and whether values unique or ordered.
228+
229+
**List**
230+
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
233+
clarity the term "ordered list" may be used when an order is semantically
234+
important.
235+
236+
**Set**
237+
238+
The term "set" describes a unique collection of values, where each value is
239+
considered a "member" of that set. A set is unordered unless explicitly stated
240+
otherwise (as an "ordered set"). For clarity the term "unordered set" may be
241+
used when the lack of an order is semantically important.
242+
243+
**Map**
244+
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.

0 commit comments

Comments
 (0)