@@ -1,156 +1,397 @@
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.
4−-- |
5−-- | Writing to an `ArrayBuffer` is an `Effect`ful activity, so most
6−-- | functions in this module must be run in a `MonadEffect` context.
1+-- | `ArrayBuffer` serialization in the “builder monoid” style.
72-- |
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__.
3+-- | This module provides a `Builder` monoid and a `PutM` monad
4+-- | for building `ArrayBuffer`s. See the package README for usage examples.
125module 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
6+( PutM
7+, Put
8+, execPutM
9+, execPut
10+, putArrayBuffer
11+, putUint8
12+, putInt8
13+, putUint16be
14+, putUint16le
15+, putInt16be
16+, putInt16le
17+, putUint32be
18+, putUint32le
19+, putInt32be
20+, putInt32le
21+, putFloat32be
22+, putFloat32le
23+, putFloat64be
24+, putFloat64le
25+, Builder
26+, (<>>)
27+, execBuilder
28+, singleton
29+, snoc
30+, encodeUint8
31+, encodeInt8
32+, encodeUint16be
33+, encodeUint16le
34+, encodeInt16be
35+, encodeInt16le
36+, encodeUint32be
37+, encodeUint32le
38+, encodeInt32be
39+, encodeInt32le
40+, encodeFloat32be
41+, encodeFloat32le
42+, encodeFloat64be
43+, encodeFloat64le
44+)
45+where
3746
3847import Prelude
3948
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)
49+import Control.Monad.Writer.Trans (WriterT, execWriterT, tell)
50+import Data.ArrayBuffer.ArrayBuffer as AB
51+import Data.ArrayBuffer.DataView as DV
52+import Data.ArrayBuffer.Typed as AT
53+import Data.ArrayBuffer.Types (ArrayBuffer, Uint8Array)
4554import Data.Float32 (Float32)
55+import Data.Maybe (Maybe(..))
4656import Data.UInt (UInt)
4757import Effect (Effect)
48−import Effect.Class (class MonadEffect)
58+import Effect.Class (class MonadEffect, liftEffect)
4959
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.
60+-- | The `PutM` monad is a Writer transformer monad which
61+-- | [gives us access to do-notation](https://wiki.haskell.org/Do_notation_considered_harmful#Library_design)
62+-- | for building `ArrayBuffer`s.
5663type PutM = WriterT Builder
5764
58−-- | The `PutM` type reified to `Effect`, in other words `WriterT Builder Effect`.
65+-- | `Put` monad is the non-transformer version of `PutM`.
5966type Put = PutM Effect
6067
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.
68+-- | Monoidal builder for `ArrayBuffer`s.
7069-- |
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.
70+-- | ### Left-associative `<>>` append operator
7571-- |
76−-- | In a `PutM` monad do-block, we can
72+-- | __TL;DR__ You probably don't want to use the `Builder` monoid directly
73+-- | in your code, it’s better to use the `PutM` monad with do-notation instead.
7774-- |
78−-- | ```
79−-- | do
80−-- | messageBuilder <- subBuilder $ do
81−-- | putField1
82−-- | putField2
75+-- | The `Builder` monoid in this library is efficient when we `snoc` single
76+-- | items onto the end of it, or when we only `cons` single items to the
77+-- | beginning, but it can be less efficient when we are mixing `cons` and
78+-- | `snoc`.
79+-- | This matters when we're appending three or more `Builder`s
80+-- | in one associative expression, because the
81+-- | `Semigroup` append operator `<>` is right-associative.
8382-- |
84−-- | putInt32be $ length messageBuilder
85−-- | tell messageBuilder
83+-- | To solve this, we provide an operator `<>>` for appending `Builders`.
84+-- | `<>>` is exactly the same as `<>`, but left-associative.
85+-- | This only matters when we're chaining together three
86+-- | or more `Builder`s in a single associative expression.
87+-- | Instead of
88+-- | ```
89+-- | builder₁ <> builder₂ <> builder₃
90+-- | ```
91+-- | we should always prefer to
92+-- | write
8693-- | ```
87−subBuilder :: forall m. Monad m => PutM m Unit -> PutM m Builder
88−subBuilder = lift <<< execWriterT
94+-- | builder₁ <>> builder₂ <>> builder₃
95+-- | ```
96+-- | so that we get the efficient
97+-- | `snoc`ing of `Builder`s.
98+-- |
99+-- | If we build our `ArrayBuffer`s with the `PutM` monad instead of appending by
100+-- | using the `Semigroup` instance of `Builder`, then we always get the efficient
101+-- | `snoc` case.
102+-- |
103+data Builder
104+ = Node Builder ArrayBuffer Builder
105+ | Null
89106
90−-- | Append an `ArrayBuffer` to the builder.
91−putArrayBuffer :: forall m. Monad m => ArrayBuffer -> PutM m Unit
92−putArrayBuffer = tell <<< Internal.singleton <<< Internal.Buff
107+instance semigroupBuilder :: Semigroup Builder where
108+ append Null Null = Null
109+ append l Null = l
110+ append Null r = r
111+ append l (Node Null rx rr) = Node l rx rr -- this is the snoc case
112+ append (Node ll lx Null) r = Node ll lx r -- found the rightmost Null
113+ -- of the left tree
114+ append (Node ll lx lr) r = Node ll lx $ append lr r -- search down the right
115+ -- side of the left tree
116+ -- to find the rightmost
117+ -- Null
118+
119+infixl 5 append as <>>
120+
121+instance monoidBuilder :: Monoid Builder where
122+ mempty = Null
123+
124+-- | `Builder` is not an instance of `Foldable` because `Builder` is monomorphic.
125+foldl :: forall b. (b -> ArrayBuffer -> b) -> b -> Builder -> b
126+foldl f a Null = a
127+foldl f a (Node l x r) = foldl f (f (foldl f a l) x) r
128+
129+-- | Monomorphic foldM copied from
130+-- | [`Data.Foldable.foldM`](https://pursuit.purescript.org/packages/purescript-foldable-traversable/4.1.1/docs/Data.Foldable#v:foldM)
131+foldM :: forall b m. (Monad m) => (b -> ArrayBuffer -> m b) -> b -> Builder -> m b
132+foldM f a0 = foldl (\ma b -> ma >>= flip f b) (pure a0)
133+
134+-- | Construct a `Builder` with a single `ArrayBuffer`. *O(1)*
135+singleton :: ArrayBuffer -> Builder
136+singleton buf = Node Null buf Null
137+
138+-- | Add an `ArrayBuffer` to the end of the `Builder`. *O(1)*
139+snoc :: Builder -> ArrayBuffer -> Builder
140+snoc bs x = Node bs x Null
93141
94−-- | Append a `DataView` to the builder.
95−putDataView :: forall m. Monad m => DataView -> PutM m Unit
96−putDataView = tell <<< Internal.singleton <<< Internal.View
142+-- | Build a single `ArrayBuffer` from a `Builder`. *O(n)*
143+execBuilder :: forall m. (MonadEffect m) => Builder -> m ArrayBuffer
144+execBuilder bldr = do
145+ let buflen = foldl (\b a -> b + AB.byteLength a) 0 bldr
146+ -- Allocate the final ArrayBuffer
147+ buf <- liftEffect $ AB.empty buflen
148+ -- Then copy each ArrayBuffer into the final ArrayBuffer.
149+ -- To memcpy from one ArrayBuffer to another, apparently we have to first view
150+ -- both ArrayBuffers as ArrayView (Typed Array).
151+ newview <- liftEffect (AT.whole buf :: Effect Uint8Array)
152+ _ <- foldM
153+ ( \offset a -> do
154+ let offset' = offset + AB.byteLength a
155+ aview <- liftEffect (AT.whole a :: Effect Uint8Array)
156+ _ <- liftEffect $ AT.setTyped newview (Just offset') aview
157+ pure offset'
158+ ) 0 bldr
159+ pure buf
97160
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
161+-- | Build an `ArrayBuffer` with do-notation in any `MonadEffect`. *O(n)*
162+execPutM :: forall m. (MonadEffect m) => PutM m Unit -> m ArrayBuffer
163+execPutM = execBuilder <=< execWriterT
164+
165+-- | Build an `ArrayBuffer` with do-notation. *O(n)*
166+execPut :: Put Unit -> Effect ArrayBuffer
167+execPut = execPutM
168+
169+-- | Append an `ArrayBuffer` to the builder.
170+putArrayBuffer :: forall m. (MonadEffect m) => ArrayBuffer -> PutM m Unit
171+putArrayBuffer = tell <<< singleton
172+
173+-- | Serialize an 8-bit unsigned integer (byte) into a new `ArrayBuffer`.
174+encodeUint8 :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
175+encodeUint8 x = do
176+ buf <- liftEffect $ AB.empty 1
177+ _ <- liftEffect $ DV.setUint8 (DV.whole buf) 0 x
178+ pure buf
101179
102180-- | 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
181+putUint8 :: forall m. (MonadEffect m) => UInt -> PutM m Unit
182+putUint8 = putArrayBuffer <=< encodeUint8
183+
184+-- | Serialize an 8-bit two’s-complement signed integer (char) into a new `ArrayBuffer`.
185+encodeInt8 :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
186+encodeInt8 x = do
187+ buf <- liftEffect $ AB.empty 1
188+ _ <- liftEffect $ DV.setInt8 (DV.whole buf) 0 x
189+ pure buf
105190
106191-- | 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
192+putInt8 :: forall m. (MonadEffect m) => Int -> PutM m Unit
193+putInt8 = putArrayBuffer <=< encodeInt8
194+
195+-- | Serialize a 16-bit big-endian unsigned integer into a new `ArrayBuffer`.
196+encodeUint16be :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
197+encodeUint16be x = do
198+ buf <- liftEffect $ AB.empty 2
199+ _ <- liftEffect $ DV.setUint16be (DV.whole buf) 0 x
200+ pure buf
109201
110202-- | 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
203+putUint16be :: forall m. (MonadEffect m) => UInt -> PutM m Unit
204+putUint16be = putArrayBuffer <=< encodeUint16be
205+
206+-- | Serialize a 16-bit little-endian unsigned integer into a new `ArrayBuffer`.
207+encodeUint16le :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
208+encodeUint16le x = do
209+ buf <- liftEffect $ AB.empty 2
210+ _ <- liftEffect $ DV.setUint16le (DV.whole buf) 0 x
211+ pure buf
113212
114213-- | 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
214+putUint16le :: forall m. (MonadEffect m) => UInt -> PutM m Unit
215+putUint16le = putArrayBuffer <=< encodeUint16le
216+
217+-- | Serialize a 16-bit big-endian two’s-complement signed integer into a new `ArrayBuffer`.
218+encodeInt16be :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
219+encodeInt16be x = do
220+ buf <- liftEffect $ AB.empty 2
221+ _ <- liftEffect $ DV.setInt16be (DV.whole buf) 0 x
222+ pure buf
117223
118224-- | 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
225+putInt16be :: forall m. (MonadEffect m) => Int -> PutM m Unit
226+putInt16be = putArrayBuffer <=< encodeInt16be
227+
228+-- | Serialize a 16-bit little-endian two’s-complement signed integer into a new `ArrayBuffer`.
229+encodeInt16le :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
230+encodeInt16le x = do
231+ buf <- liftEffect $ AB.empty 2
232+ _ <- liftEffect $ DV.setInt16le (DV.whole buf) 0 x
233+ pure buf
121234
122235-- | 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
236+putInt16le :: forall m. (MonadEffect m) => Int -> PutM m Unit
237+putInt16le = putArrayBuffer <=< encodeInt16le
238+
239+-- | Serialize a 32-bit big-endian unsigned integer into a new `ArrayBuffer`.
240+encodeUint32be :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
241+encodeUint32be x = do
242+ buf <- liftEffect $ AB.empty 4
243+ _ <- liftEffect $ DV.setUint32be (DV.whole buf) 0 x
244+ pure buf
125245
126246-- | 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
247+putUint32be :: forall m. (MonadEffect m) => UInt -> PutM m Unit
248+putUint32be = putArrayBuffer <=< encodeUint32be
249+
250+-- | Serialize a 32-bit little-endian unsigned integer into a new `ArrayBuffer`.
251+encodeUint32le :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
252+encodeUint32le x = do
253+ buf <- liftEffect $ AB.empty 4
254+ _ <- liftEffect $ DV.setUint32le (DV.whole buf) 0 x
255+ pure buf
129256
130257-- | 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
258+putUint32le :: forall m. (MonadEffect m) => UInt -> PutM m Unit
259+putUint32le = putArrayBuffer <=< encodeUint32le
260+
261+-- | Serialize a 32-bit big-endian two’s-complement signed integer into a new `ArrayBuffer`.
262+encodeInt32be :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
263+encodeInt32be x = do
264+ buf <- liftEffect $ AB.empty 4
265+ _ <- liftEffect $ DV.setInt32be (DV.whole buf) 0 x
266+ pure buf
133267
134268-- | 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
269+putInt32be :: forall m. (MonadEffect m) => Int -> PutM m Unit
270+putInt32be = putArrayBuffer <=< encodeInt32be
271+
272+-- | Serialize a 32-bit little-endian two’s-complement signed integer into a new `ArrayBuffer`.
273+encodeInt32le :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
274+encodeInt32le x = do
275+ buf <- liftEffect $ AB.empty 4
276+ _ <- liftEffect $ DV.setInt32le (DV.whole buf) 0 x
277+ pure buf
137278
138279-- | 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
280+putInt32le :: forall m. (MonadEffect m) => Int -> PutM m Unit
281+putInt32le = putArrayBuffer <=< encodeInt32le
282+
283+-- | Serialize a 32-bit big-endian IEEE single-precision float into a new `ArrayBuffer`.
284+encodeFloat32be :: forall m. (MonadEffect m) => Float32 -> m ArrayBuffer
285+encodeFloat32be x = do
286+ buf <- liftEffect $ AB.empty 4
287+ _ <- liftEffect $ DV.setFloat32be (DV.whole buf) 0 x
288+ pure buf
141289
142290-- | 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
291+putFloat32be :: forall m. (MonadEffect m) => Float32 -> PutM m Unit
292+putFloat32be = putArrayBuffer <=< encodeFloat32be
293+
294+-- | Serialize a 32-bit little-endian IEEE single-precision float into a new `ArrayBuffer`.
295+encodeFloat32le :: forall m. (MonadEffect m) => Float32 -> m ArrayBuffer
296+encodeFloat32le x = do
297+ buf <- liftEffect $ AB.empty 4
298+ _ <- liftEffect $ DV.setFloat32le (DV.whole buf) 0 x
299+ pure buf
145300
146301-- | 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
302+putFloat32le :: forall m. (MonadEffect m) => Float32 -> PutM m Unit
303+putFloat32le = putArrayBuffer <=< encodeFloat32le
304+
305+-- | Serialize a 64-bit big-endian IEEE double-precision float into a new `ArrayBuffer`.
306+encodeFloat64be :: forall m. (MonadEffect m) => Number -> m ArrayBuffer
307+encodeFloat64be x = do
308+ buf <- liftEffect $ AB.empty 8
309+ _ <- liftEffect $ DV.setFloat64be (DV.whole buf) 0 x
310+ pure buf
149311
150312-- | 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
313+putFloat64be :: forall m. (MonadEffect m) => Number -> PutM m Unit
314+putFloat64be = putArrayBuffer <=< encodeFloat64be
315+
316+-- | Serialize a 64-bit little-endian IEEE double-precision float into a new `ArrayBuffer`.
317+encodeFloat64le :: forall m. (MonadEffect m) => Number -> m ArrayBuffer
318+encodeFloat64le x = do
319+ buf <- liftEffect $ AB.empty 8
320+ _ <- liftEffect $ DV.setFloat64le (DV.whole buf) 0 x
321+ pure buf
153322
154323-- | 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
324+putFloat64le :: forall m. (MonadEffect m) => Number -> PutM m Unit
325+putFloat64le = putArrayBuffer <=< encodeFloat64le
326+
327+
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.