git.iko.soy/rowtype-yoga/purescript-arraybuffer-builder
on master help sign in
second draft
d7f705dJames Brock
src/Data/ArrayBuffer/Builder.purs+269−157
compare with master
unifiedsplit
@@ -1,28 +1,33 @@
1−-- | `ArrayBuffer` serialization primitives in the “builder monad” style.
1+-- | `ArrayBuffer` serialization in the “builder monoid” style.
2−-- | An API on top of
2+-- |
3−-- | [`Data.ArrayBuffer.ArrayBuffer`](https://pursuit.purescript.org/packages/purescript-arraybuffer/docs/Data.ArrayBuffer.ArrayBuffer)
4−-- | which provides a `Builder` monoid and a `PutM` monad which are roughly
3+-- | This module provides a `Builder` monoid and a `PutM` monad which are roughly
5−-- | equivalent to the Haskell
4+-- | equivalent to types of the same name in the Haskell
6-- | [`Data.Binary.Put`](https://hackage.haskell.org/package/binary/docs/Data-Binary-Put.html)
5-- | [`Data.Binary.Put`](https://hackage.haskell.org/package/binary/docs/Data-Binary-Put.html)
7-- | module.
6-- | module.
7+-- |
8-- | This library defines no typeclasses.
8-- | This library defines no typeclasses.
9-- |
9-- |
10−-- | See purescript-parsing-dataview for deserialization.
10+-- | ## Deserialization
11+-- |
12+-- | See
13+-- | [__purescript-parsing-dataview__](https://pursuit.purescript.org/packages/purescript-parsing-dataview/)
14+-- | for a way to deserialize from `ArrayBuffer` back to Purescript data.
11-- |
15-- |
12−-- | # Usage Examples
16+-- | ## Usage Examples
13-- |
17-- |
14-- | All `ArrayBuffer` building must occur in `Effect`.
18-- | All `ArrayBuffer` building must occur in `Effect`.
15-- |
19-- |
16−-- | ## Serialize an integer
20+-- | ### Serialize an integer
17-- |
21-- |
18−-- | Create a two-byte `buf :: ArrayBuffer` which contains the number *-2* encoded as big-endian 16-bit two’s-complement.
22+-- | Create a two-byte `arraybuffer :: ArrayBuffer` which contains the number *-2* encoded as big-endian 16-bit two’s-complement.
19-- | ```purescript
23-- | ```purescript
20−-- | buf <- execPut $ putInt32be (-2)
24+-- | do
25+-- | arraybuffer <- execPut $ putInt16be (-2)
21-- | ```
26-- | ```
22-- |
27-- |
23−-- | ## Serialize a `String` as UTF8
28+-- | ### Serialize a `String` as UTF8
24-- |
29-- |
25−-- | Create a `buf :: ArrayBuffer` which contains a `String` encoded as UTF8 with a length prefix in a
30+-- | A function which encodes a `String` as UTF8 with a length prefix in a
26-- | way that's compatible with the
31-- | way that's compatible with the
27-- | [`Binary.Put.putStringUtf8`](https://hackage.haskell.org/package/binary/docs/Data-Binary-Put.html#v:putStringUtf8)
32-- | [`Binary.Put.putStringUtf8`](https://hackage.haskell.org/package/binary/docs/Data-Binary-Put.html#v:putStringUtf8)
28-- | function from the Haskell
33-- | function from the Haskell
@@ -30,35 +35,37 @@
30-- | library.
35-- | library.
31-- | Uses [`Data.TextEncoding.encodeUtf8`](https://pursuit.purescript.org/packages/purescript-text-encoding/docs/Data.TextEncoding#v:encodeUtf8).
36-- | Uses [`Data.TextEncoding.encodeUtf8`](https://pursuit.purescript.org/packages/purescript-text-encoding/docs/Data.TextEncoding#v:encodeUtf8).
32-- | ```purescript
37-- | ```purescript
33−-- | buf <- execPut $ do
38+-- | putStringUtf8 :: forall m. (MonadEffect m) => String -> PutM m Unit
39+-- | putStringUtf8 s = do
34−-- | let stringbuf = Data.ArrayBuffer.Typed.buffer $ Data.TextEncoding.encodeUtf8 "Black Lives Matter"
40+-- | let stringbuf = Data.ArrayBuffer.Typed.buffer $
41+-- | Data.TextEncoding.encodeUtf8 s
35−-- | -- Put a 64-bit big-endian length prefix for the length of the utf8 string, in bytes.
42+-- | -- Put a 64-bit big-endian length prefix for the length of the utf8
43+-- | -- string, in bytes.
36−-- | putUint32be 0
44+-- | putUint32be 0
37−-- | putUint32be $ Data.Uint.fromInt $ Data.ArrayBuffer.byteLength stringbuf
45+-- | putUint32be $ Data.Uint.fromInt $ Data.ArrayBuffer.byteLength stringbuf
38−-- | putArrayBuffer stringbuf
46+-- | putArrayBuffer stringbuf
39-- | ```
47-- | ```
40-- |
48-- |
41−-- | ## Serialize an `Array Int`
49+-- | ### Serialize an `Array Int`
42-- |
50-- |
43−-- | Create a `buf :: ArrayBuffer` which encodes an `Array Int` with a length prefix in a
51+-- | A function which encodes an `Array Int` with a length prefix in a
44-- | way that's compatible with the
52-- | way that's compatible with the
45-- | [`Binary` instance for `[Int32]`](https://hackage.haskell.org/package/binary/docs/Data-Binary.html#t:Binary)
53-- | [`Binary` instance for `[Int32]`](https://hackage.haskell.org/package/binary/docs/Data-Binary.html#t:Binary)
46-- | from the Haskell
54-- | from the Haskell
47-- | [__binary__](https://hackage.haskell.org/package/binary)
55-- | [__binary__](https://hackage.haskell.org/package/binary)
48-- | library.
56-- | library.
49-- | ```purescript
57-- | ```purescript
50−-- | let x = [1,2,3] :: Array Int
58+-- | putArrayInt32 :: forall m. (MonadEffect m) => Array Int -> PutM m Unit
51−-- | buf <- execPut $
59+-- | putArrayInt32 xs = do
52−-- | -- Put a 64-bit big-endian length prefix for the length of the array, in bytes.
60+-- | -- Put a 64-bit big-endian length prefix for the length of the
61+-- | -- array, in bytes.
53−-- | putUint32be 0
62+-- | putUint32be 0
54−-- | putUint32be $ Data.Uint.fromInt $ Data.Array.length x
63+-- | putUint32be $ Data.Uint.fromInt $ Data.Array.length xs
55−-- | traverse_ putInt32be x
64+-- | traverse_ putInt32be xs
56-- | ```
65-- | ```
57−module Build
58−( Builder
66+module Data.ArrayBuffer.Builder
59−, PutM
67+( PutM
60, Put
68, Put
61−, execBuilder
62, execPutM
69, execPutM
63, execPut
70, execPut
64, putArrayBuffer
71, putArrayBuffer
@@ -76,106 +83,84 @@ module Build
76, putFloat32le
83, putFloat32le
77, putFloat64be
84, putFloat64be
78, putFloat64le
85, putFloat64le
86+, Builder
87+, (<>>)
88+, execBuilder
89+, singleton
90+, snoc
91+, encodeUint8
92+, encodeInt8
93+, encodeUint16be
94+, encodeUint16le
95+, encodeInt16be
96+, encodeInt16le
97+, encodeUint32be
98+, encodeUint32le
99+, encodeInt32be
100+, encodeInt32le
101+, encodeFloat32be
102+, encodeFloat32le
103+, encodeFloat64be
104+, encodeFloat64le
79)
105)
80where
106where
81
107
82import Prelude
108import Prelude
83−import Effect (Effect)
84−import Effect.Class (class MonadEffect, liftEffect)
85−import Data.UInt (UInt)
86−import Data.Float32 (Float32)
87−import Data.Maybe (Maybe(..))
88−import Control.Monad.Writer.Trans (WriterT, execWriterT, tell)
89
109
90−import Data.ArrayBuffer.Types (ArrayBuffer, Uint8Array)
110+import Control.Monad.Writer.Trans (WriterT, execWriterT, tell)
91import Data.ArrayBuffer.ArrayBuffer as AB
111import Data.ArrayBuffer.ArrayBuffer as AB
92import Data.ArrayBuffer.DataView as DV
112import Data.ArrayBuffer.DataView as DV
93import Data.ArrayBuffer.Typed as AT
113import Data.ArrayBuffer.Typed as AT
114+import Data.ArrayBuffer.Types (ArrayBuffer, Uint8Array)
115+import Data.Float32 (Float32)
116+import Data.Maybe (Maybe(..))
117+import Data.UInt (UInt)
118+import Effect (Effect)
119+import Effect.Class (class MonadEffect, liftEffect)
94
120
95−-- | Writer monad transformer for `Builder`.
121+-- | The `PutM` monad is a Writer transformer monad which
122+-- | [gives us access to do-notation](https://wiki.haskell.org/Do_notation_considered_harmful#Library_design)
123+-- | for building `ArrayBuffer`s.
96type PutM = WriterT Builder
124type PutM = WriterT Builder
97
125
98-- | `Put` monad is the non-transformer version of `PutM`.
126-- | `Put` monad is the non-transformer version of `PutM`.
99type Put = PutM Effect
127type Put = PutM Effect
100
128
101− -- Note: use liftEffect to call the ArrayBuffer Effect functions
102−
103−-- | Builder for `ArrayBuffer`s.
129+-- | Monoidal builder for `ArrayBuffer`s.
104−-- |
105−-- | It is common to build an `ArrayBuffer` by issuing a sequence of `put`
106−-- | commands in a `Put` monad, and this is the case which the Builder monoid
107−-- | is optimized for.
108-- |
130-- |
109−-- | # Implementation Details
131+-- | ### Left-associative `<>>` append operator
110-- |
132-- |
111−-- | Implements an unbalanced binary tree to get
133+-- | __TL;DR;__ Don't use the `Builder` monoid directly in your code, use the
112−-- | * *O(1)* `snoc` (add element to end)
134+-- | `PutM` monad with do-notation instead.
113−-- | * *O(1)* monoid `append` (concatenation)
114−-- | * *O(n)* `fold`
115-- |
135-- |
116−-- | For monoid `append`, what we actually get is *O(k)* where *k* is
136+-- | The `Builder` monoid in this library is efficient when we `snoc` single
117−-- | proportional to the number of `append`s which have already been performed.
137+-- | items onto the end of it, or when we only `cons` single items to the
118−-- |
138+-- | beginning, but it can be less efficient when we are mixing `cons` and
119−-- | `append`ing a singleton `Builder` to the right is treated as a `snoc`.
139+-- | `snoc`.
120−-- | Specifically, the special case of `append l r` where `r` has a `Null`
140+-- | This matters when we're appending three or more `Builder`s
121−-- | left subtree doesn't increase *k*. So as long as we're right-appending
141+-- | in one associative expression, because the
122−-- | singleton `Builder`s, then we still get *O(1)* `append`.
142+-- | `Semigroup` append operator `<>` is right-associative.
123−-- |
124−-- | `append` is O(n), in the worst case, if the `Builder` has been built
125−-- | entirely by `append`ing. If the Builder has been built mostly by
126−-- | `snoc`ing, then `append` approaches *O(1)*.
127−-- |
128−-- |
129−-- | If a Builder is built entirely by `snoc`ing, it will look like a
130−-- | left-only binary tree, a.k.a. a linked list.
131-- |
143-- |
144+-- | To solve this, we provide an operator `<>>` for appending `Builders`.
145+-- | `<>>` is exactly the same as `<>`, but left-associative.
146+-- | This only matters when we're chaining together three
147+-- | or more `Builder`s in a single associative expression.
148+-- | Instead of
132-- | ```
149-- | ```
133−-- | ⬤
150+-- | builder₁ <> builder₂ <> builder₃
134−-- | ╱
135−-- | ⬤
136−-- | ╱
137−-- | ⬤
138−-- | ╱
139−-- | ⬤
140-- | ```
151-- | ```
141−-- |
152+-- | we should always prefer to
142−-- | If two of these `snoc`-built trees are `append`ed, then the new tree
153+-- | write
143−-- | will look like
144−-- |
145-- | ```
154-- | ```
146−-- | ⬤
155+-- | builder₁ <>> builder₂ <>> builder₃
147−-- | ╱ ╲
148−-- | ⬤ ⬤
149−-- | ╱ ╱
150−-- | ⬤ ⬤
151−-- | ╱ ╱
152−-- | ⬤ ⬤
153−-- | ╱
154−-- | ⬤
155-- | ```
156-- | ```
157+-- | so that we get the efficient
158+-- | `snoc`ing of `Builder`s.
156-- |
159-- |
157−-- | This is all similar to
160+-- | If we build our `ArrayBuffer`s with the `PutM` monad instead of appending by
158−-- | https://hackage.haskell.org/package/bytestring-tree-builder
161+-- | using the `Semigroup` instance of `Builder`, then we always get the efficient
159−-- | , except that the `Tree` https://hackage.haskell.org/package/bytestring-tree-builder-0.2.7.3/docs/src/ByteString.TreeBuilder.Tree.html#Tree
162+-- | `snoc` case.
160−-- | structure in __bytestring-tree-builder__ only carries values in its
161−-- | leaves, and therefore I think has an *O(n log(n))* fold. This `Builder`
162−-- | has an *O(n)* fold.
163-- |
163-- |
164−-- | We hope that this implementation is fairly fast, but we
165−-- | haven't chosen this implementation because it's fast, we've chosen
166−-- | this implementation because it's simple. This library provides basic
167−-- | ArrayBuffer serialization with the familar “put monad” style.
168−-- | The only currently existing Purescript libary which does ArrayBuffer
169−-- | serialization is
170−-- | https://pursuit.purescript.org/packages/purescript-arraybuffer-class
171−-- | , and that library is heavily typeclass-based and designed
172−-- | for compatibility with the Haskell cereal library.
173−-- | If someone wants to create a fast Purescript ArrayBuffer serialization
174−-- | library, then they can benchmark against this one to prove that the new
175−-- | one is fast.
176−-- |
177−-- | One relatively cheap and simple performance improvement for this library would be to
178−-- | remove the Null constructor of Builder and instead use Javascript nulls.
179data Builder
164data Builder
180 = Node Builder ArrayBuffer Builder
165 = Node Builder ArrayBuffer Builder
181 | Null
166 | Null
@@ -192,6 +177,8 @@ instance semigroupBuilder :: Semigroup Builder where
192 -- to find the rightmost
177 -- to find the rightmost
193 -- Null
178 -- Null
194
179
180+infixl 5 append as <>>
181+
195instance monoidBuilder :: Monoid Builder where
182instance monoidBuilder :: Monoid Builder where
196 mempty = Null
183 mempty = Null
197
184
@@ -201,18 +188,19 @@ foldl f a Null = a
201foldl f a (Node l x r) = foldl f (f (foldl f a l) x) r
188foldl f a (Node l x r) = foldl f (f (foldl f a l) x) r
202
189
203-- | Monomorphic foldM copied from
190-- | Monomorphic foldM copied from
204−-- | https://pursuit.purescript.org/packages/purescript-foldable-traversable/4.1.1/docs/Data.Foldable#v:foldM
191+-- | [`Data.Foldable.foldM`](https://pursuit.purescript.org/packages/purescript-foldable-traversable/4.1.1/docs/Data.Foldable#v:foldM)
205foldM :: forall b m. (Monad m) => (b -> ArrayBuffer -> m b) -> b -> Builder -> m b
192foldM :: forall b m. (Monad m) => (b -> ArrayBuffer -> m b) -> b -> Builder -> m b
206foldM f a0 = foldl (\ma b -> ma >>= flip f b) (pure a0)
193foldM f a0 = foldl (\ma b -> ma >>= flip f b) (pure a0)
207
194
195+-- | Construct a `Builder` with a single `ArrayBuffer`. *O(1)*
208singleton :: ArrayBuffer -> Builder
196singleton :: ArrayBuffer -> Builder
209singleton buf = Node Null buf Null
197singleton buf = Node Null buf Null
210
198
211−-- | Add an ArrayBuffer to the end of the Builder.
199+-- | Add an `ArrayBuffer` to the end of the `Builder`. *O(1)*
212snoc :: Builder -> ArrayBuffer -> Builder
200snoc :: Builder -> ArrayBuffer -> Builder
213snoc bs x = Node bs x Null
201snoc bs x = Node bs x Null
214
202
215−-- | Build a single `ArrayBuffer` from a `Builder`.
203+-- | Build a single `ArrayBuffer` from a `Builder`. *O(n)*
216execBuilder :: forall m. (MonadEffect m) => Builder -> m ArrayBuffer
204execBuilder :: forall m. (MonadEffect m) => Builder -> m ArrayBuffer
217execBuilder bldr = do
205execBuilder bldr = do
218 let buflen = foldl (\b a -> b + AB.byteLength a) 0 bldr
206 let buflen = foldl (\b a -> b + AB.byteLength a) 0 bldr
@@ -231,11 +219,11 @@ execBuilder bldr = do
231 ) 0 bldr
219 ) 0 bldr
232 pure buf
220 pure buf
233
221
234−-- | Monad computation to build an `ArrayBuffer` in any `MonadEffect`.
222+-- | Build an `ArrayBuffer` with do-notation in any `MonadEffect`. *O(n)*
235execPutM :: forall m. (MonadEffect m) => PutM m Unit -> m ArrayBuffer
223execPutM :: forall m. (MonadEffect m) => PutM m Unit -> m ArrayBuffer
236execPutM = execBuilder <=< execWriterT
224execPutM = execBuilder <=< execWriterT
237
225
238−-- | Monad computation to build an `ArrayBuffer` in the `Effect` monad.
226+-- | Build an `ArrayBuffer` with do-notation. *O(n)*
239execPut :: Put Unit -> Effect ArrayBuffer
227execPut :: Put Unit -> Effect ArrayBuffer
240execPut = execPutM
228execPut = execPutM
241
229
@@ -243,100 +231,224 @@ execPut = execPutM
243putArrayBuffer :: forall m. (MonadEffect m) => ArrayBuffer -> PutM m Unit
231putArrayBuffer :: forall m. (MonadEffect m) => ArrayBuffer -> PutM m Unit
244putArrayBuffer = tell <<< singleton
232putArrayBuffer = tell <<< singleton
245
233
234+-- | Serialize an 8-bit unsigned integer (byte) into a new `ArrayBuffer`.
235+encodeUint8 :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
236+encodeUint8 x = do
237+ buf <- liftEffect $ AB.empty 1
238+ _ <- liftEffect $ DV.setUint8 (DV.whole buf) 0 x
239+ pure buf
240+
246-- | Append an 8-bit unsigned integer (byte) to the builder.
241-- | Append an 8-bit unsigned integer (byte) to the builder.
247putUint8 :: forall m. (MonadEffect m) => UInt -> PutM m Unit
242putUint8 :: forall m. (MonadEffect m) => UInt -> PutM m Unit
248−putUint8 x = do
243+putUint8 = putArrayBuffer <=< encodeUint8
244+
245+-- | Serialize an 8-bit two’s-complement signed integer (char) into a new `ArrayBuffer`.
246+encodeInt8 :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
247+encodeInt8 x = do
249 buf <- liftEffect $ AB.empty 1
248 buf <- liftEffect $ AB.empty 1
250− _ <- liftEffect $ DV.setUint8 (DV.whole buf) 0 x
249+ _ <- liftEffect $ DV.setInt8 (DV.whole buf) 0 x
251− tell $ singleton buf
250+ pure buf
252
251
253-- | Append an 8-bit two’s-complement signed integer (char) to the builder.
252-- | Append an 8-bit two’s-complement signed integer (char) to the builder.
254putInt8 :: forall m. (MonadEffect m) => Int -> PutM m Unit
253putInt8 :: forall m. (MonadEffect m) => Int -> PutM m Unit
255−putInt8 x = do
254+putInt8 = putArrayBuffer <=< encodeInt8
255+
256+-- | Serialize a 16-bit big-endian unsigned integer into a new `ArrayBuffer`.
257+encodeUint16be :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
258+encodeUint16be x = do
256− buf <- liftEffect $ AB.empty 1
259+ buf <- liftEffect $ AB.empty 2
257− _ <- liftEffect $ DV.setInt8 (DV.whole buf) 0 x
260+ _ <- liftEffect $ DV.setUint16be (DV.whole buf) 0 x
258− tell $ singleton buf
261+ pure buf
259
262
260-- | Append a 16-bit big-endian unsigned integer to the builder.
263-- | Append a 16-bit big-endian unsigned integer to the builder.
261putUint16be :: forall m. (MonadEffect m) => UInt -> PutM m Unit
264putUint16be :: forall m. (MonadEffect m) => UInt -> PutM m Unit
262−putUint16be x = do
265+putUint16be = putArrayBuffer <=< encodeUint16be
266+
267+-- | Serialize a 16-bit little-endian unsigned integer into a new `ArrayBuffer`.
268+encodeUint16le :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
269+encodeUint16le x = do
263 buf <- liftEffect $ AB.empty 2
270 buf <- liftEffect $ AB.empty 2
264− _ <- liftEffect $ DV.setUint16be (DV.whole buf) 0 x
271+ _ <- liftEffect $ DV.setUint16le (DV.whole buf) 0 x
265− tell $ singleton buf
272+ pure buf
266
273
267-- | Append a 16-bit little-endian unsigned integer to the builder.
274-- | Append a 16-bit little-endian unsigned integer to the builder.
268putUint16le :: forall m. (MonadEffect m) => UInt -> PutM m Unit
275putUint16le :: forall m. (MonadEffect m) => UInt -> PutM m Unit
269−putUint16le x = do
276+putUint16le = putArrayBuffer <=< encodeUint16le
277+
278+-- | Serialize a 16-bit big-endian two’s-complement signed integer into a new `ArrayBuffer`.
279+encodeInt16be :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
280+encodeInt16be x = do
270 buf <- liftEffect $ AB.empty 2
281 buf <- liftEffect $ AB.empty 2
271− _ <- liftEffect $ DV.setUint16le (DV.whole buf) 0 x
282+ _ <- liftEffect $ DV.setInt16be (DV.whole buf) 0 x
272− tell $ singleton buf
283+ pure buf
273
284
274-- | Append a 16-bit big-endian two’s-complement signed integer to the builder.
285-- | Append a 16-bit big-endian two’s-complement signed integer to the builder.
275putInt16be :: forall m. (MonadEffect m) => Int -> PutM m Unit
286putInt16be :: forall m. (MonadEffect m) => Int -> PutM m Unit
276−putInt16be x = do
287+putInt16be = putArrayBuffer <=< encodeInt16be
288+
289+-- | Serialize a 16-bit little-endian two’s-complement signed integer into a new `ArrayBuffer`.
290+encodeInt16le :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
291+encodeInt16le x = do
277 buf <- liftEffect $ AB.empty 2
292 buf <- liftEffect $ AB.empty 2
278− _ <- liftEffect $ DV.setInt16be (DV.whole buf) 0 x
293+ _ <- liftEffect $ DV.setInt16le (DV.whole buf) 0 x
279− tell $ singleton buf
294+ pure buf
280
295
281-- | Append a 16-bit little-endian two’s-complement signed integer to the builder.
296-- | Append a 16-bit little-endian two’s-complement signed integer to the builder.
282putInt16le :: forall m. (MonadEffect m) => Int -> PutM m Unit
297putInt16le :: forall m. (MonadEffect m) => Int -> PutM m Unit
283−putInt16le x = do
298+putInt16le = putArrayBuffer <=< encodeInt16le
299+
300+-- | Serialize a 32-bit big-endian unsigned integer into a new `ArrayBuffer`.
301+encodeUint32be :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
302+encodeUint32be x = do
284− buf <- liftEffect $ AB.empty 2
303+ buf <- liftEffect $ AB.empty 4
285− _ <- liftEffect $ DV.setInt16le (DV.whole buf) 0 x
304+ _ <- liftEffect $ DV.setUint32be (DV.whole buf) 0 x
286− tell $ singleton buf
305+ pure buf
287
306
288-- | Append a 32-bit big-endian unsigned integer to the builder.
307-- | Append a 32-bit big-endian unsigned integer to the builder.
289putUint32be :: forall m. (MonadEffect m) => UInt -> PutM m Unit
308putUint32be :: forall m. (MonadEffect m) => UInt -> PutM m Unit
290−putUint32be x = do
309+putUint32be = putArrayBuffer <=< encodeUint32be
310+
311+-- | Serialize a 32-bit little-endian unsigned integer into a new `ArrayBuffer`.
312+encodeUint32le :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
313+encodeUint32le x = do
291 buf <- liftEffect $ AB.empty 4
314 buf <- liftEffect $ AB.empty 4
292− _ <- liftEffect $ DV.setUint32be (DV.whole buf) 0 x
315+ _ <- liftEffect $ DV.setUint32le (DV.whole buf) 0 x
293− tell $ singleton buf
316+ pure buf
294
317
295-- | Append a 32-bit little-endian unsigned integer to the builder.
318-- | Append a 32-bit little-endian unsigned integer to the builder.
296putUint32le :: forall m. (MonadEffect m) => UInt -> PutM m Unit
319putUint32le :: forall m. (MonadEffect m) => UInt -> PutM m Unit
297−putUint32le x = do
320+putUint32le = putArrayBuffer <=< encodeUint32le
321+
322+-- | Serialize a 32-bit big-endian two’s-complement signed integer into a new `ArrayBuffer`.
323+encodeInt32be :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
324+encodeInt32be x = do
298 buf <- liftEffect $ AB.empty 4
325 buf <- liftEffect $ AB.empty 4
299− _ <- liftEffect $ DV.setUint32le (DV.whole buf) 0 x
326+ _ <- liftEffect $ DV.setInt32be (DV.whole buf) 0 x
300− tell $ singleton buf
327+ pure buf
301
328
302-- | Append a 32-bit big-endian two’s-complement signed integer to the builder.
329-- | Append a 32-bit big-endian two’s-complement signed integer to the builder.
303putInt32be :: forall m. (MonadEffect m) => Int -> PutM m Unit
330putInt32be :: forall m. (MonadEffect m) => Int -> PutM m Unit
304−putInt32be x = do
331+putInt32be = putArrayBuffer <=< encodeInt32be
332+
333+-- | Serialize a 32-bit little-endian two’s-complement signed integer into a new `ArrayBuffer`.
334+encodeInt32le :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
335+encodeInt32le x = do
305 buf <- liftEffect $ AB.empty 4
336 buf <- liftEffect $ AB.empty 4
306− _ <- liftEffect $ DV.setInt32be (DV.whole buf) 0 x
337+ _ <- liftEffect $ DV.setInt32le (DV.whole buf) 0 x
307− tell $ singleton buf
338+ pure buf
308
339
309-- | Append a 32-bit little-endian two’s-complement signed integer to the builder.
340-- | Append a 32-bit little-endian two’s-complement signed integer to the builder.
310putInt32le :: forall m. (MonadEffect m) => Int -> PutM m Unit
341putInt32le :: forall m. (MonadEffect m) => Int -> PutM m Unit
311−putInt32le x = do
342+putInt32le = putArrayBuffer <=< encodeInt32le
343+
344+-- | Serialize a 32-bit big-endian IEEE single-precision float into a new `ArrayBuffer`.
345+encodeFloat32be :: forall m. (MonadEffect m) => Float32 -> m ArrayBuffer
346+encodeFloat32be x = do
312 buf <- liftEffect $ AB.empty 4
347 buf <- liftEffect $ AB.empty 4
313− _ <- liftEffect $ DV.setInt32le (DV.whole buf) 0 x
348+ _ <- liftEffect $ DV.setFloat32be (DV.whole buf) 0 x
314− tell $ singleton buf
349+ pure buf
315
350
316-- | Append a 32-bit big-endian IEEE single-precision float to the builder.
351-- | Append a 32-bit big-endian IEEE single-precision float to the builder.
317putFloat32be :: forall m. (MonadEffect m) => Float32 -> PutM m Unit
352putFloat32be :: forall m. (MonadEffect m) => Float32 -> PutM m Unit
318−putFloat32be x = do
353+putFloat32be = putArrayBuffer <=< encodeFloat32be
354+
355+-- | Serialize a 32-bit little-endian IEEE single-precision float into a new `ArrayBuffer`.
356+encodeFloat32le :: forall m. (MonadEffect m) => Float32 -> m ArrayBuffer
357+encodeFloat32le x = do
319 buf <- liftEffect $ AB.empty 4
358 buf <- liftEffect $ AB.empty 4
320− _ <- liftEffect $ DV.setFloat32be (DV.whole buf) 0 x
359+ _ <- liftEffect $ DV.setFloat32le (DV.whole buf) 0 x
321− tell $ singleton buf
360+ pure buf
322
361
323-- | Append a 32-bit little-endian IEEE single-precision float to the builder.
362-- | Append a 32-bit little-endian IEEE single-precision float to the builder.
324putFloat32le :: forall m. (MonadEffect m) => Float32 -> PutM m Unit
363putFloat32le :: forall m. (MonadEffect m) => Float32 -> PutM m Unit
325−putFloat32le x = do
364+putFloat32le = putArrayBuffer <=< encodeFloat32le
365+
366+-- | Serialize a 64-bit big-endian IEEE double-precision float into a new `ArrayBuffer`.
367+encodeFloat64be :: forall m. (MonadEffect m) => Number -> m ArrayBuffer
368+encodeFloat64be x = do
326− buf <- liftEffect $ AB.empty 4
369+ buf <- liftEffect $ AB.empty 8
327− _ <- liftEffect $ DV.setFloat32le (DV.whole buf) 0 x
370+ _ <- liftEffect $ DV.setFloat64be (DV.whole buf) 0 x
328− tell $ singleton buf
371+ pure buf
329
372
330-- | Append a 64-bit big-endian IEEE double-precision float to the builder.
373-- | Append a 64-bit big-endian IEEE double-precision float to the builder.
331putFloat64be :: forall m. (MonadEffect m) => Number -> PutM m Unit
374putFloat64be :: forall m. (MonadEffect m) => Number -> PutM m Unit
332−putFloat64be x = do
375+putFloat64be = putArrayBuffer <=< encodeFloat64be
376+
377+-- | Serialize a 64-bit little-endian IEEE double-precision float into a new `ArrayBuffer`.
378+encodeFloat64le :: forall m. (MonadEffect m) => Number -> m ArrayBuffer
379+encodeFloat64le x = do
333 buf <- liftEffect $ AB.empty 8
380 buf <- liftEffect $ AB.empty 8
334− _ <- liftEffect $ DV.setFloat64be (DV.whole buf) 0 x
381+ _ <- liftEffect $ DV.setFloat64le (DV.whole buf) 0 x
335− tell $ singleton buf
382+ pure buf
336
383
337-- | Append a 64-bit little-endian IEEE double-precision float to the builder.
384-- | Append a 64-bit little-endian IEEE double-precision float to the builder.
338putFloat64le :: forall m. (MonadEffect m) => Number -> PutM m Unit
385putFloat64le :: forall m. (MonadEffect m) => Number -> PutM m Unit
339−putFloat64le x = do
386+putFloat64le = putArrayBuffer <=< encodeFloat64le
340− buf <- liftEffect $ AB.empty 8
387+
341− _ <- liftEffect $ DV.setFloat64le (DV.whole buf) 0 x
388+
342− tell $ singleton buf
389+-- | ## Implementation Details
390+-- |
391+-- | We want our `Builder` to be a data structure with
392+-- | * *O(1)* monoid append
393+-- | * *O(n)* fold
394+-- |
395+-- | Our `Builder` monoid implementation is an unbalanced binary tree.
396+-- |
397+-- | For monoid `append`, what we actually get is *O(1)* when either the
398+-- | left or right tree is a singleton. If that's not true, then in the
399+-- | unlikely worst case `append` might be *O(n)*.
400+-- |
401+-- | `Builder` is optimized what we consider to be normal usage, that is,
402+-- | `snoc`ing singleton elements to the end of the `Builder`.
403+-- |
404+-- | If a Builder is built entirely by `snoc`ing, it will look like a
405+-- | left-only binary tree, a.k.a. a linked list.
406+-- |
407+-- | ```
408+-- | ④
409+-- | ╱
410+-- | ③
411+-- | ╱
412+-- | ②
413+-- | ╱
414+-- | ①
415+-- | ```
416+-- |
417+-- | If two of these `snoc`-built trees are `append`ed, then the new tree
418+-- | will look like
419+-- |
420+-- | ```
421+-- | ④
422+-- | ╱ ╲
423+-- | ③ ⑧
424+-- | ╱ ╱
425+-- | ② ⑦
426+-- | ╱ ╱
427+-- | ① ⑥
428+-- | ╱
429+-- | ⑤
430+-- | ```
431+-- |
432+-- | This is all similar to
433+-- | [__bytestring-tree-builder__](https://hackage.haskell.org/package/bytestring-tree-builder)
434+-- | , except that the
435+-- | [`Tree`](https://hackage.haskell.org/package/bytestring-tree-builder-0.2.7.3/docs/src/ByteString.TreeBuilder.Tree.html#Tree)
436+-- | structure in __bytestring-tree-builder__ only carries values in its
437+-- | leaves, which is how it achieves *O(1)* appending, at the cost of
438+-- | a higher coefficient time factor on the fold.
439+-- |
440+-- | We hope that this implementation is fairly fast, but we
441+-- | haven't chosen this implementation because it's fast, we've chosen
442+-- | this implementation because it's simple. This library provides basic
443+-- | ArrayBuffer serialization with the familar “put monad” style.
444+-- | The only currently existing Purescript libary which does ArrayBuffer
445+-- | serialization is
446+-- | https://pursuit.purescript.org/packages/purescript-arraybuffer-class
447+-- | , and that library is heavily typeclass-based and designed
448+-- | for compatibility with the Haskell cereal library.
449+-- | If someone wants to create a fast Purescript ArrayBuffer serialization
450+-- | library, then they can benchmark against this one to prove that the new
451+-- | one is fast.
452+-- |
453+-- | One relatively cheap and simple performance improvement for this library would be to
454+-- | remove the Null constructor of `Builder` and instead use Javascript nulls.