git.iko.soy/streamly
on 7b5bc73 help sign in
streamly/dev/container-api.md
72 lines 2.6 kB history raw
1# Data Containers
3Containers are persistent containers of data e.g. files, arrays, maps. For
4consistency we use similar API for all such containers where possible. Usually
5the API names are relative to the current module e.g. toBytes in an array
6module means converting the array to bytes, it sounds intuitive if read
7qualified with the module name e.g. Array.toBytes. This doc lists some
8conventions and guidelines to be followed.
10## Bytes and Chunks
12APIs that deal with streams of Word8 may have "bytes" in their names
13while the ones dealing with "Array Word8" have "chunks" in their
14names. Usually the default is bytes when there is no explicit mention in
15the name.
17## Unfolds and Folds
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).
22## From and Put
24* Immutable construction from some external source is named with a "from"
25 prefix (e.g. fromList).
26* Mutation of an existing container uses a "put" prefix instead of "from". When
27 an API uses an existing container to write to and does not return a newly
28 constructed container then use "put".
29* "from" vs "put": "from" assumes creation of a new object, it may fail if the
30 object being created already exists (e.g. the file exists), it may not take a
31 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## To and Get
36* Converting the complete object to an external representation is prefixed with
37 "to" (e.g. toBytes).
38* For mutable objects "get" APIs may be used instead of "to" APIs.
39* "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## Append
44* Use "append" prefix for appending data at the end of a mutable container
46## Random Access (Arrays)
48* getIndex (for arrays)
49* getSlice/getRange/getIndices
50* putIndex (for mutable arrays)
51* append (for mutable arrays)
53## Key Access (Maps)
55* getKey
56* findKey (test existence)
57* createKey (insert new key for mutable maps)
58* putKey (insert or update for mutable maps)
59* updateKey (update existing or fail)
60* deleteKey (delete existing or fail)
61* destroyKey (delete existing or not)
63## Points to Consider
65The fold and unfold APIs can be used to express the to/from stream APIs. So we
66may not need both, it may just add to more APIs being proliferated.
68We may need an "append" style fold as well? What would "stream" append
69operations be called then?
71We may need locked version of "write" folds for mutable containers for
72concurrent access.