@@ -325,77 +325,73 @@ putFloat64le :: forall m. (MonadEffect m) => Number -> PutM m Unit
325325putFloat64le = putArrayBuffer <=< encodeFloat64le
326326
327327
328−-- | ## Implementation Details
329−-- |
330−-- | We want our `Builder` to be a data structure with
331−-- | * *O(1)* monoid append
332−-- | * *O(n)* fold
333−-- |
334−-- | Our `Builder` implementation is an unbalanced binary tree.
335−-- |
336−-- | For monoid `append`, what we actually get is *O(1)* when either the
337−-- | left or right tree is a singleton. If that's not true, then in the
338−-- | unlikely worst case `append` might be *O(n)*.
339−-- |
340−-- | `Builder` is optimized what we consider to be normal usage, that is,
341−-- | `snoc`ing singleton elements to the end of the `Builder`.
342−-- |
343−-- | If a Builder is built entirely by `snoc`ing, it will look like a
344−-- | left-only binary tree, a.k.a. a linked list.
345−-- |
346−-- | ```
347−-- | ④
348−-- | ╱
349−-- | ③
350−-- | ╱
351−-- | ②
352−-- | ╱
353−-- | ①
354−-- | ```
355−-- |
356−-- | If two of these `snoc`-built trees are `append`ed, then the new tree
357−-- | will look like
358−-- |
359−-- | ```
360−-- | ④
361−-- | ╱ ╲
362−-- | ③ ⑧
363−-- | ╱ ╱
364−-- | ② ⑦
365−-- | ╱ ╱
366−-- | ① ⑥
367−-- | ╱
368−-- | ⑤
369−-- | ```
370−-- |
371−-- | This is all similar to
372−-- | [__bytestring-tree-builder__](https://hackage.haskell.org/package/bytestring-tree-builder)
373−-- | , except that the
374−-- | [`Tree`](https://hackage.haskell.org/package/bytestring-tree-builder-0.2.7.3/docs/src/ByteString.TreeBuilder.Tree.html#Tree)
375−-- | structure in __bytestring-tree-builder__ only carries values in its
376−-- | leaves, which is how it achieves *O(1)* appending, at the cost of
377−-- | a higher coefficient time factor on the fold.
378−-- |
379−-- | We hope that this implementation is fairly fast, but we
380−-- | haven't chosen this implementation because it's fast, we've chosen
381−-- | this implementation because it's simple.
382−-- | If someone wants to create a fast Purescript ArrayBuffer serialization
383−-- | library, then they can benchmark against this one to prove that the new
384−-- | one is fast.
385−-- |
386−-- | One relatively cheap and simple performance improvement for this library would be to
387−-- | remove the Null constructor of `Builder` and instead use Javascript nulls.
388−-- |
389−-- | In the longer term, it might make sense to try to change the Builder so
390−-- | that it works like the
391−-- | https://hackage.haskell.org/package/bytestring/docs/Data-ByteString-Builder.html
392−-- |
393−-- | Here are some benchmarks of different Haskell ByteString builders
394−-- | https://github.com/haskell-perf/strict-bytestring-builders
395−-- |
396−-- | We've tried to design the API for this library with minimal assumptions,
397−-- | so that if we want to change the Builder implementation later then we can.
398−-- |
399−-- | Alternatives
400−-- | https://pursuit.purescript.org/packages/purescript-node-buffer
401−-- | https://pursuit.purescript.org/packages/purescript-arraybuffer-class
328+-- ## Implementation Details
329+--
330+-- We want our `Builder` to be a data structure with
331+-- * *O(1)* monoid append
332+-- * *O(n)* fold
333+--
334+-- Our `Builder` implementation is an unbalanced binary tree.
335+--
336+-- For monoid `append`, what we actually get is *O(1)* when either the
337+-- left or right tree is a singleton. If that's not true, then in the
338+-- unlikely worst case `append` might be *O(n)*.
339+--
340+-- `Builder` is optimized what we consider to be normal usage, that is,
341+-- `snoc`ing singleton elements to the end of the `Builder`.
342+--
343+-- If a Builder is built entirely by `snoc`ing, it will look like a
344+-- left-only binary tree, a.k.a. a linked list.
345+--
346+-- ```
347+-- ④
348+-- ╱
349+-- ③
350+-- ╱
351+-- ②
352+-- ╱
353+-- ①
354+-- ```
355+--
356+-- If two of these `snoc`-built trees are `append`ed, then the new tree
357+-- will look like
358+--
359+-- ```
360+-- ④
361+-- ╱ ╲
362+-- ③ ⑧
363+-- ╱ ╱
364+-- ② ⑦
365+-- ╱ ╱
366+-- ① ⑥
367+-- ╱
368+-- ⑤
369+-- ```
370+--
371+-- This is all similar to
372+-- [__bytestring-tree-builder__](https://hackage.haskell.org/package/bytestring-tree-builder)
373+-- , except that the
374+-- [`Tree`](https://hackage.haskell.org/package/bytestring-tree-builder-0.2.7.3/docs/src/ByteString.TreeBuilder.Tree.html#Tree)
375+-- structure in __bytestring-tree-builder__ only carries values in its
376+-- leaves, which is how it achieves *O(1)* appending, at the cost of
377+-- a higher coefficient time factor on the fold.
378+--
379+-- We hope that this implementation is fairly fast, but we
380+-- haven't chosen this implementation because it's fast, we've chosen
381+-- this implementation because it's simple.
382+-- If someone wants to create a fast Purescript ArrayBuffer serialization
383+-- library, then they can benchmark against this one to prove that the new
384+-- one is fast.
385+--
386+-- One relatively cheap and simple performance improvement for this library would be to
387+-- remove the Null constructor of `Builder` and instead use Javascript nulls.
388+--
389+-- In the longer term, it might make sense to try to change the Builder so
390+-- that it works like the
391+-- https://hackage.haskell.org/package/bytestring/docs/Data-ByteString-Builder.html
392+--
393+-- Here are some benchmarks of different Haskell ByteString builders
394+-- https://github.com/haskell-perf/strict-bytestring-builders
395+--
396+-- We've tried to design the API for this library with minimal assumptions,
397+-- so that if we want to change the Builder implementation later then we can.