@@ -3,8 +3,7 @@
33`ArrayBuffer` serialization in the “builder monoid” and “builder monad” style.
44In this style, we build up serialized data structures by `append`ing to
55a monoid in a Writer monad with do-notation. This style of serialization
6−has been used for a long time and we [insist that it works really well]
7−(https://wiki.haskell.org/Do_notation_considered_harmful#Library_design).
6+has been used for a long time and we [insist that it works really well](https://wiki.haskell.org/Do_notation_considered_harmful#Library_design).
87
98This package provides a `Builder` monoid and a `PutM` monad which are roughly
109equivalent to types of the same name in the Haskell
@@ -31,15 +30,28 @@ All `ArrayBuffer` building must occur in `Effect`.
3130
3231### Serialize an integer
3332
34−Create a two-byte `arraybuffer :: ArrayBuffer` which contains the number *-2* encoded as big-endian 16-bit two’s-complement.
33+Create a two-byte `arraybuffer :: ArrayBuffer` which contains the number *-10* encoded as big-endian 16-bit two’s-complement.
3534```purescript
3635do
37− arraybuffer <- execPut $ putInt16be (-2)
36+ arraybuffer <- execPut $ putInt16be (-10)
37+```
38+
39+### Serialize three floats
40+
41+Create a 24-byte `arraybuffer :: ArrayBuffer` which contains three big-endian
42+IEEE-754 double-precision floats.
43+
44+```purescript
45+do
46+ arraybuffer <- execPut $ do
47+ putFloat64be 1.0
48+ putFloat64be 2.0
49+ putFloat64be 3.0
3850```
3951
4052### Serialize a `String` as UTF8
4153
42−A function which encodes a `String` as UTF8 with a length prefix in a
54+Encode a `String` as UTF8 with a length prefix in a
4355way that's compatible with the
4456[`Binary.Put.putStringUtf8`](https://hackage.haskell.org/package/binary/docs/Data-Binary-Put.html#v:putStringUtf8)
4557function from the Haskell
@@ -49,18 +61,19 @@ Uses [`Data.TextEncoding.encodeUtf8`](https://pursuit.purescript.org/packages/pu
4961```purescript
5062putStringUtf8 :: forall m. (MonadEffect m) => String -> PutM m Unit
5163putStringUtf8 s = do
52− let stringbuf = Data.ArrayBuffer.Typed.buffer $
53− Data.TextEncoding.encodeUtf8 s
54− -- Put a 64-bit big-endian length prefix for the length of the utf8
55− -- string, in bytes.
56− putUint32be 0
57− putUint32be $ Data.Uint.fromInt $ Data.ArrayBuffer.byteLength stringbuf
58− putArrayBuffer stringbuf
64+ let stringbuf = Data.ArrayBuffer.Typed.buffer $ Data.TextEncoding.encodeUtf8 s
65+ -- Put a 64-bit big-endian length prefix for the length of the utf8 string, in bytes.
66+ putUint32be 0
67+ putUint32be $ Data.Uint.fromInt $ Data.ArrayBuffer.byteLength stringbuf
68+ putArrayBuffer stringbuf
69+
70+do
71+ arraybuffer <- execPut $ putStringUtf8 "ACAB"
5972```
6073
6174### Serialize an `Array Int`
6275
63−A function which encodes an `Array Int` with a length prefix in a
76+Encode an `Array Int` with a length prefix in a
6477way that's compatible with the
6578[`Binary` instance for `[Int32]`](https://hackage.haskell.org/package/binary/docs/Data-Binary.html#t:Binary)
6679from the Haskell
@@ -69,9 +82,11 @@ library.
6982```purescript
7083putArrayInt32 :: forall m. (MonadEffect m) => Array Int -> PutM m Unit
7184putArrayInt32 xs = do
72− -- Put a 64-bit big-endian length prefix for the length of the
73− -- array, in bytes.
85+ -- Put a 64-bit big-endian length prefix for the length of the array.
7486 putUint32be 0
7587 putUint32be $ Data.Uint.fromInt $ Data.Array.length xs
7688 traverse_ putInt32be xs
89+
90+do
91+ arraybuffer <- execPut $ putArrayInt32 [1,2,3]
7792```