@@ -19,7 +19,9 @@ the name.
1919* Unfolds are named as "read" or with a "read" prefix (e.g. readChunks).
2020* Folds are named as "write" or with a "write" prefix (e.g. writeChunks).
2121
22−## From and Put
22+## To and from Stream
23+
24+### From and Put
2325
2426* Immutable construction from some external source is named with a "from"
2527 prefix (e.g. fromList).
@@ -31,7 +33,7 @@ the name.
3133 lock as it assumes immutability. "put" may create a new object or overwrite
3234 an existing one, it may take a lock for writing as it assumes mutability.
3335
34−## To and Get
36+### To and Get
3537
3638* Converting the complete object to an external representation is prefixed with
3739 "to" (e.g. toBytes).
@@ -39,18 +41,47 @@ the name.
3941* "to" vs "get": "to" assumes immutable object so does not have to take a lock.
4042 "get" assumes mutable object so may take a lock.
4143
42−## Append
44+### Append
4345
4446* Use "append" prefix for appending data at the end of a mutable container
4547
48+## With additional config
49+
50+Sometimes we need to modify the behavior of a combinator using some additional
51+config. For example, combinators to read/write using a specified size of
52+buffer. For such cases we apply the "With" suffix to standard combinator names:
53+
54+* readWith
55+* readChunksWith
56+* toBytesWith
57+* getBytesWith
58+
4659## Random Access (Arrays)
4760
61+### Single elements
62+
4863* getIndex (for arrays)
49−* getSlice/getRange/getIndices
5064* putIndex (for mutable arrays)
65+
66+### Ranges
67+
68+* ...FromTo (e.g. readFromTo, readChunksFromTo, toBytesFromTo, getBytesFromTo)
69+* ...FromThenTo
70+* ...Indices
71+
72+We could use FromThenTo or FromStepN style for stepwise enumeration. We chose
73+FromThenTo style for the following reasons:
74+
75+* It is the style used in base lists, and we are already using it in Enumerable
76+ type class.
77+* Both have their pros and cons. It may be non-intuitive whether To is
78+ inclusive in one, we have to compute the correct count in the other one.
79+
80+### Appending
81+
5182* append (for mutable arrays)
5283
53−## Key Access (Maps)
84+## Key-Value Store Access (Maps)
5485
5586* getKey
5687* findKey (test existence)