@@ -1,468 +1,156 @@
1−-- | `ArrayBuffer` serialization in the “builder monoid” style.
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.
24-- |
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.
5+-- | Writing to an `ArrayBuffer` is an `Effect`ful activity, so most
6+-- | functions in this module must be run in a `MonadEffect` context.
77-- |
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−-- | ```
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__.
7212module Data.ArrayBuffer.Builder
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
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
11337
11438import Prelude
11539
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)
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)
12145import Data.Float32 (Float32)
122−import Data.Maybe (Maybe(..))
12346import Data.UInt (UInt)
12447import Effect (Effect)
125−import Effect.Class (class MonadEffect, liftEffect)
48+import Effect.Class (class MonadEffect)
12649
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.
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.
13056type PutM = WriterT Builder
13157
132−-- | `Put` monad is the non-transformer version of `PutM`.
58+-- | The `PutM` type reified to `Effect`, in other words `WriterT Builder Effect`.
13359type Put = PutM Effect
13460
135−-- | Monoidal builder for `ArrayBuffer`s.
136−-- |
137−-- | ### Left-associative `<>>` append operator
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.
13870-- |
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.
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.
14175-- |
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.
76+-- | In a `PutM` monad do-block, we can
14977-- |
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
16078-- | ```
161−-- | builder₁ <>> builder₂ <>> builder₃
162−-- | ```
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.
79+-- | do
80+-- | messageBuilder <- subBuilder $ do
81+-- | putField1
82+-- | putField2
16983-- |
170−data Builder
171− = Node Builder ArrayBuffer Builder
172− | Null
173−
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 <>>
187−
188−instance monoidBuilder :: Monoid Builder where
189− mempty = Null
190−
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
84+-- | putInt32be $ length messageBuilder
85+-- | tell messageBuilder
86+-- | ```
87+subBuilder :: forall m. Monad m => PutM m Unit -> PutM m Builder
88+subBuilder = lift <<< execWriterT
23589
23690-- | Append an `ArrayBuffer` to the builder.
237−putArrayBuffer :: forall m. (MonadEffect m) => ArrayBuffer -> PutM m Unit
238−putArrayBuffer = tell <<< singleton
91+putArrayBuffer :: forall m. Monad m => ArrayBuffer -> PutM m Unit
92+putArrayBuffer = tell <<< Internal.singleton <<< Internal.Buff
23993
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
94+-- | Append a `DataView` to the builder.
95+putDataView :: forall m. Monad m => DataView -> PutM m Unit
96+putDataView = tell <<< Internal.singleton <<< Internal.View
24697
247−-- | Append an 8-bit unsigned integer (byte) to the builder.
248−putUint8 :: forall m. (MonadEffect m) => UInt -> PutM m Unit
249−putUint8 = putArrayBuffer <=< encodeUint8
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
250101
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
102+-- | 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
257105
258106-- | Append an 8-bit two’s-complement signed integer (char) to the builder.
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
107+putInt8 :: forall m. MonadEffect m => Int -> PutM m Unit
108+putInt8 = putArrayBuffer <=< Internal.encodeInt8
268109
269110-- | Append a 16-bit big-endian unsigned integer to the builder.
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
111+putUint16be :: forall m. MonadEffect m => UInt -> PutM m Unit
112+putUint16be = putArrayBuffer <=< Internal.encodeUint16be
279113
280114-- | Append a 16-bit little-endian unsigned integer to the builder.
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
115+putUint16le :: forall m. MonadEffect m => UInt -> PutM m Unit
116+putUint16le = putArrayBuffer <=< Internal.encodeUint16le
290117
291118-- | Append a 16-bit big-endian two’s-complement signed integer to the builder.
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
119+putInt16be :: forall m. MonadEffect m => Int -> PutM m Unit
120+putInt16be = putArrayBuffer <=< Internal.encodeInt16be
301121
302122-- | Append a 16-bit little-endian two’s-complement signed integer to the builder.
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
123+putInt16le :: forall m. MonadEffect m => Int -> PutM m Unit
124+putInt16le = putArrayBuffer <=< Internal.encodeInt16le
312125
313126-- | Append a 32-bit big-endian unsigned integer to the builder.
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
127+putUint32be :: forall m. MonadEffect m => UInt -> PutM m Unit
128+putUint32be = putArrayBuffer <=< Internal.encodeUint32be
323129
324130-- | Append a 32-bit little-endian unsigned integer to the builder.
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
131+putUint32le :: forall m. MonadEffect m => UInt -> PutM m Unit
132+putUint32le = putArrayBuffer <=< Internal.encodeUint32le
334133
335134-- | Append a 32-bit big-endian two’s-complement signed integer to the builder.
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
135+putInt32be :: forall m. MonadEffect m => Int -> PutM m Unit
136+putInt32be = putArrayBuffer <=< Internal.encodeInt32be
345137
346138-- | Append a 32-bit little-endian two’s-complement signed integer to the builder.
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
139+putInt32le :: forall m. MonadEffect m => Int -> PutM m Unit
140+putInt32le = putArrayBuffer <=< Internal.encodeInt32le
356141
357142-- | Append a 32-bit big-endian IEEE single-precision float to the builder.
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
143+putFloat32be :: forall m. MonadEffect m => Float32 -> PutM m Unit
144+putFloat32be = putArrayBuffer <=< Internal.encodeFloat32be
367145
368146-- | Append a 32-bit little-endian IEEE single-precision float to the builder.
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
147+putFloat32le :: forall m. MonadEffect m => Float32 -> PutM m Unit
148+putFloat32le = putArrayBuffer <=< Internal.encodeFloat32le
378149
379150-- | Append a 64-bit big-endian IEEE double-precision float to the builder.
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
151+putFloat64be :: forall m. MonadEffect m => Number -> PutM m Unit
152+putFloat64be = putArrayBuffer <=< Internal.encodeFloat64be
389153
390154-- | Append a 64-bit little-endian IEEE double-precision float to the builder.
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
155+putFloat64le :: forall m. MonadEffect m => Number -> PutM m Unit
156+putFloat64le = putArrayBuffer <=< Internal.encodeFloat64le