@@ -1,156 +1,468 @@
1−-- | This module provides a `Builder` monoid and a `PutM` monad
2−-- | for serializing `Data.ArrayBuffer.Types.ArrayBuffer`s.
3−-- | See the package README for usage examples.
1+-- | `ArrayBuffer` serialization in the “builder monoid” style.
42-- |
5−-- | Writing to an `ArrayBuffer` is an `Effect`ful activity, so most
6−-- | functions in this module must be run in a `MonadEffect` context.
3+-- | This module provides a `Builder` monoid and a `PutM` monad which are roughly
4+-- | equivalent to types of the same name in the Haskell
5+-- | [`Data.Binary.Put`](https://hackage.haskell.org/package/binary/docs/Data-Binary-Put.html)
6+-- | module.
77-- |
8−-- | For other operations for working with `ArrayBuffer`, see
9−-- | module
10−-- | [`Data.ArrayBuffer.ArrayBuffer`](https://pursuit.purescript.org/packages/purescript-arraybuffer/docs/Data.ArrayBuffer.ArrayBuffer)
11−-- | in package __arraybuffer__.
8+-- | This library defines no typeclasses. Typeclass-based
9+-- | serialization/deserialization generally assumes that we are round-tripping
10+-- | some data structures out to storage and then back into our program.
11+-- | This library is designed for the case that we are serializing some data
12+-- | to be sent to another program which expects a certain serialization format
13+-- | that we don't control.
14+-- |
15+-- | ## Deserialization
16+-- |
17+-- | This module is only for writing `ArrayBuffer`s, not reading them.
18+-- | See
19+-- | [__purescript-parsing-dataview__](https://pursuit.purescript.org/packages/purescript-parsing-dataview/)
20+-- | for a way to deserialize from `ArrayBuffer` back to Purescript data.
21+-- |
22+-- | ## Usage Examples
23+-- |
24+-- | All `ArrayBuffer` building must occur in `Effect`.
25+-- |
26+-- | ### Serialize an integer
27+-- |
28+-- | Create a two-byte `arraybuffer :: ArrayBuffer` which contains the number *-2* encoded as big-endian 16-bit two’s-complement.
29+-- | ```purescript
30+-- | do
31+-- | arraybuffer <- execPut $ putInt16be (-2)
32+-- | ```
33+-- |
34+-- | ### Serialize a `String` as UTF8
35+-- |
36+-- | A function which encodes a `String` as UTF8 with a length prefix in a
37+-- | way that's compatible with the
38+-- | [`Binary.Put.putStringUtf8`](https://hackage.haskell.org/package/binary/docs/Data-Binary-Put.html#v:putStringUtf8)
39+-- | function from the Haskell
40+-- | [__binary__](https://hackage.haskell.org/package/binary)
41+-- | library.
42+-- | Uses [`Data.TextEncoding.encodeUtf8`](https://pursuit.purescript.org/packages/purescript-text-encoding/docs/Data.TextEncoding#v:encodeUtf8).
43+-- | ```purescript
44+-- | putStringUtf8 :: forall m. (MonadEffect m) => String -> PutM m Unit
45+-- | putStringUtf8 s = do
46+-- | let stringbuf = Data.ArrayBuffer.Typed.buffer $
47+-- | Data.TextEncoding.encodeUtf8 s
48+-- | -- Put a 64-bit big-endian length prefix for the length of the utf8
49+-- | -- string, in bytes.
50+-- | putUint32be 0
51+-- | putUint32be $ Data.Uint.fromInt $ Data.ArrayBuffer.byteLength stringbuf
52+-- | putArrayBuffer stringbuf
53+-- | ```
54+-- |
55+-- | ### Serialize an `Array Int`
56+-- |
57+-- | A function which encodes an `Array Int` with a length prefix in a
58+-- | way that's compatible with the
59+-- | [`Binary` instance for `[Int32]`](https://hackage.haskell.org/package/binary/docs/Data-Binary.html#t:Binary)
60+-- | from the Haskell
61+-- | [__binary__](https://hackage.haskell.org/package/binary)
62+-- | library.
63+-- | ```purescript
64+-- | putArrayInt32 :: forall m. (MonadEffect m) => Array Int -> PutM m Unit
65+-- | putArrayInt32 xs = do
66+-- | -- Put a 64-bit big-endian length prefix for the length of the
67+-- | -- array, in bytes.
68+-- | putUint32be 0
69+-- | putUint32be $ Data.Uint.fromInt $ Data.Array.length xs
70+-- | traverse_ putInt32be xs
71+-- | ```
1272module Data.ArrayBuffer.Builder
13− ( PutM
14− , Put
15− , execPutM
16− , execPut
17− , subBuilder
18− , putArrayBuffer
19− , putDataView
20− , putDataBuff
21− , putUint8
22− , putInt8
23− , putUint16be
24− , putUint16le
25− , putInt16be
26− , putInt16le
27− , putUint32be
28− , putUint32le
29− , putInt32be
30− , putInt32le
31− , putFloat32be
32− , putFloat32le
33− , putFloat64be
34− , putFloat64le
35− , module Data.ArrayBuffer.Builder.Internal
36− ) where
73+( PutM
74+, Put
75+, execPutM
76+, execPut
77+, putArrayBuffer
78+, putUint8
79+, putInt8
80+, putUint16be
81+, putUint16le
82+, putInt16be
83+, putInt16le
84+, putUint32be
85+, putUint32le
86+, putInt32be
87+, putInt32le
88+, putFloat32be
89+, putFloat32le
90+, putFloat64be
91+, putFloat64le
92+, Builder
93+, (<>>)
94+, execBuilder
95+, singleton
96+, snoc
97+, encodeUint8
98+, encodeInt8
99+, encodeUint16be
100+, encodeUint16le
101+, encodeInt16be
102+, encodeInt16le
103+, encodeUint32be
104+, encodeUint32le
105+, encodeInt32be
106+, encodeInt32le
107+, encodeFloat32be
108+, encodeFloat32le
109+, encodeFloat64be
110+, encodeFloat64le
111+)
112+where
37113
38114import Prelude
39115
40−import Control.Monad.Rec.Class (class MonadRec)
41−import Control.Monad.Writer.Trans (WriterT, execWriterT, tell, lift)
42−import Data.ArrayBuffer.Builder.Internal (Builder, DataBuff(..), length, toView, (<>>))
43−import Data.ArrayBuffer.Builder.Internal as Internal
44−import Data.ArrayBuffer.Types (ArrayBuffer, DataView)
116+import Control.Monad.Writer.Trans (WriterT, execWriterT, tell)
117+import Data.ArrayBuffer.ArrayBuffer as AB
118+import Data.ArrayBuffer.DataView as DV
119+import Data.ArrayBuffer.Typed as AT
120+import Data.ArrayBuffer.Types (ArrayBuffer, Uint8Array)
45121import Data.Float32 (Float32)
122+import Data.Maybe (Maybe(..))
46123import Data.UInt (UInt)
47124import Effect (Effect)
48−import Effect.Class (class MonadEffect)
125+import Effect.Class (class MonadEffect, liftEffect)
49126
50−-- | The `PutM` monad is a `WriterT Builder` transformer monad which
51−-- | gives us do-notation for the `Builder` monoid. The base monad must be
52−-- | a `MonadEffect`.
53−-- |
54−-- | To append `Builder`s in this monad call `tell`, or any of the `put*`
55−-- | functions in this module.
127+-- | The `PutM` monad is a Writer transformer monad which
128+-- | [gives us access to do-notation](https://wiki.haskell.org/Do_notation_considered_harmful#Library_design)
129+-- | for building `ArrayBuffer`s.
56130type PutM = WriterT Builder
57131
58−-- | The `PutM` type reified to `Effect`, in other words `WriterT Builder Effect`.
132+-- | `Put` monad is the non-transformer version of `PutM`.
59133type Put = PutM Effect
60134
61−-- | Build an `ArrayBuffer` with do-notation in any `MonadEffect`. *O(n)* Stack-safe.
62−execPutM :: forall m. MonadEffect m => MonadRec m => PutM m Unit -> m ArrayBuffer
63−execPutM = Internal.execBuilder <=< execWriterT
64−
65−-- | Build an `ArrayBuffer` with do-notation in `Effect`. *O(n)* Stack-safe.
66−execPut :: Put Unit -> Effect ArrayBuffer
67−execPut = execPutM
68−
69−-- | Build up a sub-`Builder` without `tell`ing it to the `Writer` yet.
135+-- | Monoidal builder for `ArrayBuffer`s.
70136-- |
71−-- | One case where we might want to call a `subBuilder` is when
72−-- | serializing length-prefixed messages in some protocol. In that case,
73−-- | we must serialize the message first, calculate the message length,
74−-- | append the message length, and then append the message.
137+-- | ### Left-associative `<>>` append operator
75138-- |
76−-- | In a `PutM` monad do-block, we can
139+-- | __TL;DR__ You probably don't want to use the `Builder` monoid directly
140+-- | in your code, it’s better to use the `PutM` monad with do-notation instead.
77141-- |
78−-- | ```
79−-- | do
80−-- | messageBuilder <- subBuilder $ do
81−-- | putField1
82−-- | putField2
142+-- | The `Builder` monoid in this library is efficient when we `snoc` single
143+-- | items onto the end of it, or when we only `cons` single items to the
144+-- | beginning, but it can be less efficient when we are mixing `cons` and
145+-- | `snoc`.
146+-- | This matters when we're appending three or more `Builder`s
147+-- | in one associative expression, because the
148+-- | `Semigroup` append operator `<>` is right-associative.
83149-- |
84−-- | putInt32be $ length messageBuilder
85−-- | tell messageBuilder
150+-- | To solve this, we provide an operator `<>>` for appending `Builders`.
151+-- | `<>>` is exactly the same as `<>`, but left-associative.
152+-- | This only matters when we're chaining together three
153+-- | or more `Builder`s in a single associative expression.
154+-- | Instead of
155+-- | ```
156+-- | builder₁ <> builder₂ <> builder₃
157+-- | ```
158+-- | we should always prefer to
159+-- | write
160+-- | ```
161+-- | builder₁ <>> builder₂ <>> builder₃
86162-- | ```
87−subBuilder :: forall m. Monad m => PutM m Unit -> PutM m Builder
88−subBuilder = lift <<< execWriterT
163+-- | so that we get the efficient
164+-- | `snoc`ing of `Builder`s.
165+-- |
166+-- | If we build our `ArrayBuffer`s with the `PutM` monad instead of appending by
167+-- | using the `Semigroup` instance of `Builder`, then we always get the efficient
168+-- | `snoc` case.
169+-- |
170+data Builder
171+ = Node Builder ArrayBuffer Builder
172+ | Null
89173
90−-- | Append an `ArrayBuffer` to the builder.
91−putArrayBuffer :: forall m. Monad m => ArrayBuffer -> PutM m Unit
92−putArrayBuffer = tell <<< Internal.singleton <<< Internal.Buff
174+instance semigroupBuilder :: Semigroup Builder where
175+ append Null Null = Null
176+ append l Null = l
177+ append Null r = r
178+ append l (Node Null rx rr) = Node l rx rr -- this is the snoc case
179+ append (Node ll lx Null) r = Node ll lx r -- found the rightmost Null
180+ -- of the left tree
181+ append (Node ll lx lr) r = Node ll lx $ append lr r -- search down the right
182+ -- side of the left tree
183+ -- to find the rightmost
184+ -- Null
185+
186+infixl 5 append as <>>
93187
94−-- | Append a `DataView` to the builder.
95−putDataView :: forall m. Monad m => DataView -> PutM m Unit
96−putDataView = tell <<< Internal.singleton <<< Internal.View
188+instance monoidBuilder :: Monoid Builder where
189+ mempty = Null
97190
98−-- | Append either an `ArrayBuffer` or a `DataView` to the builder.
99−putDataBuff :: forall m. Monad m => DataBuff -> PutM m Unit
100−putDataBuff = tell <<< Internal.singleton
191+-- | `Builder` is not an instance of `Foldable` because `Builder` is monomorphic.
192+foldl :: forall b. (b -> ArrayBuffer -> b) -> b -> Builder -> b
193+foldl f a Null = a
194+foldl f a (Node l x r) = foldl f (f (foldl f a l) x) r
195+
196+-- | Monomorphic foldM copied from
197+-- | [`Data.Foldable.foldM`](https://pursuit.purescript.org/packages/purescript-foldable-traversable/4.1.1/docs/Data.Foldable#v:foldM)
198+foldM :: forall b m. (Monad m) => (b -> ArrayBuffer -> m b) -> b -> Builder -> m b
199+foldM f a0 = foldl (\ma b -> ma >>= flip f b) (pure a0)
200+
201+-- | Construct a `Builder` with a single `ArrayBuffer`. *O(1)*
202+singleton :: ArrayBuffer -> Builder
203+singleton buf = Node Null buf Null
204+
205+-- | Add an `ArrayBuffer` to the end of the `Builder`. *O(1)*
206+snoc :: Builder -> ArrayBuffer -> Builder
207+snoc bs x = Node bs x Null
208+
209+-- | Build a single `ArrayBuffer` from a `Builder`. *O(n)*
210+execBuilder :: forall m. (MonadEffect m) => Builder -> m ArrayBuffer
211+execBuilder bldr = do
212+ let buflen = foldl (\b a -> b + AB.byteLength a) 0 bldr
213+ -- Allocate the final ArrayBuffer
214+ buf <- liftEffect $ AB.empty buflen
215+ -- Then copy each ArrayBuffer into the final ArrayBuffer.
216+ -- To memcpy from one ArrayBuffer to another, apparently we have to first view
217+ -- both ArrayBuffers as ArrayView (Typed Array).
218+ newview <- liftEffect (AT.whole buf :: Effect Uint8Array)
219+ _ <- foldM
220+ ( \offset a -> do
221+ let offset' = offset + AB.byteLength a
222+ aview <- liftEffect (AT.whole a :: Effect Uint8Array)
223+ _ <- liftEffect $ AT.setTyped newview (Just offset') aview
224+ pure offset'
225+ ) 0 bldr
226+ pure buf
227+
228+-- | Build an `ArrayBuffer` with do-notation in any `MonadEffect`. *O(n)*
229+execPutM :: forall m. (MonadEffect m) => PutM m Unit -> m ArrayBuffer
230+execPutM = execBuilder <=< execWriterT
231+
232+-- | Build an `ArrayBuffer` with do-notation. *O(n)*
233+execPut :: Put Unit -> Effect ArrayBuffer
234+execPut = execPutM
235+
236+-- | Append an `ArrayBuffer` to the builder.
237+putArrayBuffer :: forall m. (MonadEffect m) => ArrayBuffer -> PutM m Unit
238+putArrayBuffer = tell <<< singleton
239+
240+-- | Serialize an 8-bit unsigned integer (byte) into a new `ArrayBuffer`.
241+encodeUint8 :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
242+encodeUint8 x = do
243+ buf <- liftEffect $ AB.empty 1
244+ _ <- liftEffect $ DV.setUint8 (DV.whole buf) 0 x
245+ pure buf
101246
102247-- | Append an 8-bit unsigned integer (byte) to the builder.
103−putUint8 :: forall m. MonadEffect m => UInt -> PutM m Unit
104−putUint8 = putArrayBuffer <=< Internal.encodeUint8
248+putUint8 :: forall m. (MonadEffect m) => UInt -> PutM m Unit
249+putUint8 = putArrayBuffer <=< encodeUint8
250+
251+-- | Serialize an 8-bit two’s-complement signed integer (char) into a new `ArrayBuffer`.
252+encodeInt8 :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
253+encodeInt8 x = do
254+ buf <- liftEffect $ AB.empty 1
255+ _ <- liftEffect $ DV.setInt8 (DV.whole buf) 0 x
256+ pure buf
105257
106258-- | Append an 8-bit two’s-complement signed integer (char) to the builder.
107−putInt8 :: forall m. MonadEffect m => Int -> PutM m Unit
108−putInt8 = putArrayBuffer <=< Internal.encodeInt8
259+putInt8 :: forall m. (MonadEffect m) => Int -> PutM m Unit
260+putInt8 = putArrayBuffer <=< encodeInt8
261+
262+-- | Serialize a 16-bit big-endian unsigned integer into a new `ArrayBuffer`.
263+encodeUint16be :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
264+encodeUint16be x = do
265+ buf <- liftEffect $ AB.empty 2
266+ _ <- liftEffect $ DV.setUint16be (DV.whole buf) 0 x
267+ pure buf
109268
110269-- | Append a 16-bit big-endian unsigned integer to the builder.
111−putUint16be :: forall m. MonadEffect m => UInt -> PutM m Unit
112−putUint16be = putArrayBuffer <=< Internal.encodeUint16be
270+putUint16be :: forall m. (MonadEffect m) => UInt -> PutM m Unit
271+putUint16be = putArrayBuffer <=< encodeUint16be
272+
273+-- | Serialize a 16-bit little-endian unsigned integer into a new `ArrayBuffer`.
274+encodeUint16le :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
275+encodeUint16le x = do
276+ buf <- liftEffect $ AB.empty 2
277+ _ <- liftEffect $ DV.setUint16le (DV.whole buf) 0 x
278+ pure buf
113279
114280-- | Append a 16-bit little-endian unsigned integer to the builder.
115−putUint16le :: forall m. MonadEffect m => UInt -> PutM m Unit
116−putUint16le = putArrayBuffer <=< Internal.encodeUint16le
281+putUint16le :: forall m. (MonadEffect m) => UInt -> PutM m Unit
282+putUint16le = putArrayBuffer <=< encodeUint16le
283+
284+-- | Serialize a 16-bit big-endian two’s-complement signed integer into a new `ArrayBuffer`.
285+encodeInt16be :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
286+encodeInt16be x = do
287+ buf <- liftEffect $ AB.empty 2
288+ _ <- liftEffect $ DV.setInt16be (DV.whole buf) 0 x
289+ pure buf
117290
118291-- | Append a 16-bit big-endian two’s-complement signed integer to the builder.
119−putInt16be :: forall m. MonadEffect m => Int -> PutM m Unit
120−putInt16be = putArrayBuffer <=< Internal.encodeInt16be
292+putInt16be :: forall m. (MonadEffect m) => Int -> PutM m Unit
293+putInt16be = putArrayBuffer <=< encodeInt16be
294+
295+-- | Serialize a 16-bit little-endian two’s-complement signed integer into a new `ArrayBuffer`.
296+encodeInt16le :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
297+encodeInt16le x = do
298+ buf <- liftEffect $ AB.empty 2
299+ _ <- liftEffect $ DV.setInt16le (DV.whole buf) 0 x
300+ pure buf
121301
122302-- | Append a 16-bit little-endian two’s-complement signed integer to the builder.
123−putInt16le :: forall m. MonadEffect m => Int -> PutM m Unit
124−putInt16le = putArrayBuffer <=< Internal.encodeInt16le
303+putInt16le :: forall m. (MonadEffect m) => Int -> PutM m Unit
304+putInt16le = putArrayBuffer <=< encodeInt16le
305+
306+-- | Serialize a 32-bit big-endian unsigned integer into a new `ArrayBuffer`.
307+encodeUint32be :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
308+encodeUint32be x = do
309+ buf <- liftEffect $ AB.empty 4
310+ _ <- liftEffect $ DV.setUint32be (DV.whole buf) 0 x
311+ pure buf
125312
126313-- | Append a 32-bit big-endian unsigned integer to the builder.
127−putUint32be :: forall m. MonadEffect m => UInt -> PutM m Unit
128−putUint32be = putArrayBuffer <=< Internal.encodeUint32be
314+putUint32be :: forall m. (MonadEffect m) => UInt -> PutM m Unit
315+putUint32be = putArrayBuffer <=< encodeUint32be
316+
317+-- | Serialize a 32-bit little-endian unsigned integer into a new `ArrayBuffer`.
318+encodeUint32le :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
319+encodeUint32le x = do
320+ buf <- liftEffect $ AB.empty 4
321+ _ <- liftEffect $ DV.setUint32le (DV.whole buf) 0 x
322+ pure buf
129323
130324-- | Append a 32-bit little-endian unsigned integer to the builder.
131−putUint32le :: forall m. MonadEffect m => UInt -> PutM m Unit
132−putUint32le = putArrayBuffer <=< Internal.encodeUint32le
325+putUint32le :: forall m. (MonadEffect m) => UInt -> PutM m Unit
326+putUint32le = putArrayBuffer <=< encodeUint32le
327+
328+-- | Serialize a 32-bit big-endian two’s-complement signed integer into a new `ArrayBuffer`.
329+encodeInt32be :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
330+encodeInt32be x = do
331+ buf <- liftEffect $ AB.empty 4
332+ _ <- liftEffect $ DV.setInt32be (DV.whole buf) 0 x
333+ pure buf
133334
134335-- | Append a 32-bit big-endian two’s-complement signed integer to the builder.
135−putInt32be :: forall m. MonadEffect m => Int -> PutM m Unit
136−putInt32be = putArrayBuffer <=< Internal.encodeInt32be
336+putInt32be :: forall m. (MonadEffect m) => Int -> PutM m Unit
337+putInt32be = putArrayBuffer <=< encodeInt32be
338+
339+-- | Serialize a 32-bit little-endian two’s-complement signed integer into a new `ArrayBuffer`.
340+encodeInt32le :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
341+encodeInt32le x = do
342+ buf <- liftEffect $ AB.empty 4
343+ _ <- liftEffect $ DV.setInt32le (DV.whole buf) 0 x
344+ pure buf
137345
138346-- | Append a 32-bit little-endian two’s-complement signed integer to the builder.
139−putInt32le :: forall m. MonadEffect m => Int -> PutM m Unit
140−putInt32le = putArrayBuffer <=< Internal.encodeInt32le
347+putInt32le :: forall m. (MonadEffect m) => Int -> PutM m Unit
348+putInt32le = putArrayBuffer <=< encodeInt32le
349+
350+-- | Serialize a 32-bit big-endian IEEE single-precision float into a new `ArrayBuffer`.
351+encodeFloat32be :: forall m. (MonadEffect m) => Float32 -> m ArrayBuffer
352+encodeFloat32be x = do
353+ buf <- liftEffect $ AB.empty 4
354+ _ <- liftEffect $ DV.setFloat32be (DV.whole buf) 0 x
355+ pure buf
141356
142357-- | Append a 32-bit big-endian IEEE single-precision float to the builder.
143−putFloat32be :: forall m. MonadEffect m => Float32 -> PutM m Unit
144−putFloat32be = putArrayBuffer <=< Internal.encodeFloat32be
358+putFloat32be :: forall m. (MonadEffect m) => Float32 -> PutM m Unit
359+putFloat32be = putArrayBuffer <=< encodeFloat32be
360+
361+-- | Serialize a 32-bit little-endian IEEE single-precision float into a new `ArrayBuffer`.
362+encodeFloat32le :: forall m. (MonadEffect m) => Float32 -> m ArrayBuffer
363+encodeFloat32le x = do
364+ buf <- liftEffect $ AB.empty 4
365+ _ <- liftEffect $ DV.setFloat32le (DV.whole buf) 0 x
366+ pure buf
145367
146368-- | Append a 32-bit little-endian IEEE single-precision float to the builder.
147−putFloat32le :: forall m. MonadEffect m => Float32 -> PutM m Unit
148−putFloat32le = putArrayBuffer <=< Internal.encodeFloat32le
369+putFloat32le :: forall m. (MonadEffect m) => Float32 -> PutM m Unit
370+putFloat32le = putArrayBuffer <=< encodeFloat32le
371+
372+-- | Serialize a 64-bit big-endian IEEE double-precision float into a new `ArrayBuffer`.
373+encodeFloat64be :: forall m. (MonadEffect m) => Number -> m ArrayBuffer
374+encodeFloat64be x = do
375+ buf <- liftEffect $ AB.empty 8
376+ _ <- liftEffect $ DV.setFloat64be (DV.whole buf) 0 x
377+ pure buf
149378
150379-- | Append a 64-bit big-endian IEEE double-precision float to the builder.
151−putFloat64be :: forall m. MonadEffect m => Number -> PutM m Unit
152−putFloat64be = putArrayBuffer <=< Internal.encodeFloat64be
380+putFloat64be :: forall m. (MonadEffect m) => Number -> PutM m Unit
381+putFloat64be = putArrayBuffer <=< encodeFloat64be
382+
383+-- | Serialize a 64-bit little-endian IEEE double-precision float into a new `ArrayBuffer`.
384+encodeFloat64le :: forall m. (MonadEffect m) => Number -> m ArrayBuffer
385+encodeFloat64le x = do
386+ buf <- liftEffect $ AB.empty 8
387+ _ <- liftEffect $ DV.setFloat64le (DV.whole buf) 0 x
388+ pure buf
153389
154390-- | Append a 64-bit little-endian IEEE double-precision float to the builder.
155−putFloat64le :: forall m. MonadEffect m => Number -> PutM m Unit
156−putFloat64le = putArrayBuffer <=< Internal.encodeFloat64le
391+putFloat64le :: forall m. (MonadEffect m) => Number -> PutM m Unit
392+putFloat64le = putArrayBuffer <=< encodeFloat64le
393+
394+
395+-- | ## Implementation Details
396+-- |
397+-- | We want our `Builder` to be a data structure with
398+-- | * *O(1)* monoid append
399+-- | * *O(n)* fold
400+-- |
401+-- | Our `Builder` implementation is an unbalanced binary tree.
402+-- |
403+-- | For monoid `append`, what we actually get is *O(1)* when either the
404+-- | left or right tree is a singleton. If that's not true, then in the
405+-- | unlikely worst case `append` might be *O(n)*.
406+-- |
407+-- | `Builder` is optimized what we consider to be normal usage, that is,
408+-- | `snoc`ing singleton elements to the end of the `Builder`.
409+-- |
410+-- | If a Builder is built entirely by `snoc`ing, it will look like a
411+-- | left-only binary tree, a.k.a. a linked list.
412+-- |
413+-- | ```
414+-- | ④
415+-- | ╱
416+-- | ③
417+-- | ╱
418+-- | ②
419+-- | ╱
420+-- | ①
421+-- | ```
422+-- |
423+-- | If two of these `snoc`-built trees are `append`ed, then the new tree
424+-- | will look like
425+-- |
426+-- | ```
427+-- | ④
428+-- | ╱ ╲
429+-- | ③ ⑧
430+-- | ╱ ╱
431+-- | ② ⑦
432+-- | ╱ ╱
433+-- | ① ⑥
434+-- | ╱
435+-- | ⑤
436+-- | ```
437+-- |
438+-- | This is all similar to
439+-- | [__bytestring-tree-builder__](https://hackage.haskell.org/package/bytestring-tree-builder)
440+-- | , except that the
441+-- | [`Tree`](https://hackage.haskell.org/package/bytestring-tree-builder-0.2.7.3/docs/src/ByteString.TreeBuilder.Tree.html#Tree)
442+-- | structure in __bytestring-tree-builder__ only carries values in its
443+-- | leaves, which is how it achieves *O(1)* appending, at the cost of
444+-- | a higher coefficient time factor on the fold.
445+-- |
446+-- | We hope that this implementation is fairly fast, but we
447+-- | haven't chosen this implementation because it's fast, we've chosen
448+-- | this implementation because it's simple.
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.
455+-- |
456+-- | In the longer term, it might make sense to try to change the Builder so
457+-- | that it works like the
458+-- | https://hackage.haskell.org/package/bytestring/docs/Data-ByteString-Builder.html
459+-- |
460+-- | Here are some benchmarks of different Haskell ByteString builders
461+-- | https://github.com/haskell-perf/strict-bytestring-builders
462+-- |
463+-- | We've tried to design the API for this library with minimal assumptions,
464+-- | so that if we want to change the Builder implementation later then we can.
465+-- |
466+-- | Alternatives
467+-- | https://pursuit.purescript.org/packages/purescript-node-buffer
468+-- | https://pursuit.purescript.org/packages/purescript-arraybuffer-class