@@ -19,7 +19,9 @@ the name.
19* Unfolds are named as "read" or with a "read" prefix (e.g. readChunks).
19* Unfolds are named as "read" or with a "read" prefix (e.g. readChunks).
20* Folds are named as "write" or with a "write" prefix (e.g. writeChunks).
20* Folds are named as "write" or with a "write" prefix (e.g. writeChunks).
22−## From and Put
24+### From and Put
24* Immutable construction from some external source is named with a "from"
26* Immutable construction from some external source is named with a "from"
25 prefix (e.g. fromList).
27 prefix (e.g. fromList).
@@ -31,7 +33,7 @@ the name.
31 lock as it assumes immutability. "put" may create a new object or overwrite
33 lock as it assumes immutability. "put" may create a new object or overwrite
32 an existing one, it may take a lock for writing as it assumes mutability.
34 an existing one, it may take a lock for writing as it assumes mutability.
34−## To and Get
36+### To and Get
36* Converting the complete object to an external representation is prefixed with
38* Converting the complete object to an external representation is prefixed with
37 "to" (e.g. toBytes).
39 "to" (e.g. toBytes).
@@ -39,18 +41,47 @@ the name.
39* "to" vs "get": "to" assumes immutable object so does not have to take a lock.
41* "to" vs "get": "to" assumes immutable object so does not have to take a lock.
40 "get" assumes mutable object so may take a lock.
42 "get" assumes mutable object so may take a lock.
42−## Append
44+### Append
44* Use "append" prefix for appending data at the end of a mutable container
46* Use "append" prefix for appending data at the end of a mutable container
48+## With additional config
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:
46## Random Access (Arrays)
59## Random Access (Arrays)
48* getIndex (for arrays)
63* getIndex (for arrays)
49−* getSlice/getRange/getIndices
50* putIndex (for mutable arrays)
64* putIndex (for mutable arrays)
68+* ...FromTo (e.g. readFromTo, readChunksFromTo, toBytesFromTo, getBytesFromTo)
72+We could use FromThenTo or FromStepN style for stepwise enumeration. We chose
73+FromThenTo style for the following reasons:
75+* It is the style used in base lists, and we are already using it in Enumerable
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.
51* append (for mutable arrays)
82* append (for mutable arrays)
53−## Key Access (Maps)
84+## Key-Value Store Access (Maps)
56* findKey (test existence)
87* findKey (test existence)