git.iko.soy/rowtype-yoga/purescript-arraybuffer-builder
on master help sign in
docs
8a03343James Brock
README.md+30−15
compare with master
unifiedsplit
@@ -3,8 +3,7 @@
3`ArrayBuffer` serialization in the “builder monoid” and “builder monad” style.
3`ArrayBuffer` serialization in the “builder monoid” and “builder monad” style.
4In this style, we build up serialized data structures by `append`ing to
4In this style, we build up serialized data structures by `append`ing to
5a monoid in a Writer monad with do-notation. This style of serialization
5a 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).
8
7
9This package provides a `Builder` monoid and a `PutM` monad which are roughly
8This package provides a `Builder` monoid and a `PutM` monad which are roughly
10equivalent to types of the same name in the Haskell
9equivalent to types of the same name in the Haskell
@@ -31,15 +30,28 @@ All `ArrayBuffer` building must occur in `Effect`.
31
30
32### Serialize an integer
31### Serialize an integer
33
32
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.
35```purescript
34```purescript
36do
35do
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
38```
50```
39
51
40### Serialize a `String` as UTF8
52### Serialize a `String` as UTF8
41
53
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
43way that's compatible with the
55way that's compatible with the
44[`Binary.Put.putStringUtf8`](https://hackage.haskell.org/package/binary/docs/Data-Binary-Put.html#v:putStringUtf8)
56[`Binary.Put.putStringUtf8`](https://hackage.haskell.org/package/binary/docs/Data-Binary-Put.html#v:putStringUtf8)
45function from the Haskell
57function from the Haskell
@@ -49,18 +61,19 @@ Uses [`Data.TextEncoding.encodeUtf8`](https://pursuit.purescript.org/packages/pu
49```purescript
61```purescript
50putStringUtf8 :: forall m. (MonadEffect m) => String -> PutM m Unit
62putStringUtf8 :: forall m. (MonadEffect m) => String -> PutM m Unit
51putStringUtf8 s = do
63putStringUtf8 s = do
52− let stringbuf = Data.ArrayBuffer.Typed.buffer $
64+ let stringbuf = Data.ArrayBuffer.Typed.buffer $ Data.TextEncoding.encodeUtf8 s
53− Data.TextEncoding.encodeUtf8 s
54− -- Put a 64-bit big-endian length prefix for the length of the utf8
65+ -- Put a 64-bit big-endian length prefix for the length of the utf8 string, in bytes.
55− -- string, in bytes.
56− putUint32be 0
66+ putUint32be 0
57− putUint32be $ Data.Uint.fromInt $ Data.ArrayBuffer.byteLength stringbuf
67+ putUint32be $ Data.Uint.fromInt $ Data.ArrayBuffer.byteLength stringbuf
58− putArrayBuffer stringbuf
68+ putArrayBuffer stringbuf
69+
70+do
71+ arraybuffer <- execPut $ putStringUtf8 "ACAB"
59```
72```
60
73
61### Serialize an `Array Int`
74### Serialize an `Array Int`
62
75
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
64way that's compatible with the
77way that's compatible with the
65[`Binary` instance for `[Int32]`](https://hackage.haskell.org/package/binary/docs/Data-Binary.html#t:Binary)
78[`Binary` instance for `[Int32]`](https://hackage.haskell.org/package/binary/docs/Data-Binary.html#t:Binary)
66from the Haskell
79from the Haskell
@@ -69,9 +82,11 @@ library.
69```purescript
82```purescript
70putArrayInt32 :: forall m. (MonadEffect m) => Array Int -> PutM m Unit
83putArrayInt32 :: forall m. (MonadEffect m) => Array Int -> PutM m Unit
71putArrayInt32 xs = do
84putArrayInt32 xs = do
72− -- Put a 64-bit big-endian length prefix for the length of the
85+ -- Put a 64-bit big-endian length prefix for the length of the array.
73− -- array, in bytes.
74 putUint32be 0
86 putUint32be 0
75 putUint32be $ Data.Uint.fromInt $ Data.Array.length xs
87 putUint32be $ Data.Uint.fromInt $ Data.Array.length xs
76 traverse_ putInt32be xs
88 traverse_ putInt32be xs
89+
90+do
91+ arraybuffer <- execPut $ putArrayInt32 [1,2,3]
77```
92```