@@ -57,19 +57,20 @@
57-- | __bytestring-tree-builder__
57-- | __bytestring-tree-builder__
58-- | which “according to the benchmarks … beats all the alternatives.”
58-- | which “according to the benchmarks … beats all the alternatives.”
59-- | However, we
59-- | However, we
60−-- | haven't chosen this implementation because it's fast, we've chosen
60+-- | haven’t chosen this implementation because it’s fast, we've chosen
61−-- | this implementation because it's simple.
61+-- | this implementation because it’s simple.
62−-- | If someone wants to create a fast PureScript ArrayBuffer serialization
62+-- | If someone wants to create a fast PureScript `ArrayBuffer` serialization
63-- | library, then they can benchmark against this one to prove that the new
63-- | library, then they can benchmark against this one to prove that the new
64-- | one is fast.
64-- | one is fast.
66-- | One relatively cheap and simple performance improvement for this library would be to
66-- | One relatively cheap and simple performance improvement for this library would be to
67−-- | remove the Null constructor of `Builder` and instead use Javascript nulls.
67+-- | remove the `Null` constructor of `Builder` and instead use Javascript nulls?
68−-- | __UPDATE__ Actually no, we need the Null constructor for the Monoid instance.
70-- | In the longer term, it might make sense to try to change the `Builder` so
69-- | In the longer term, it might make sense to try to change the `Builder` so
71-- | that it works like the
70-- | that it works like the
72−-- | https://hackage.haskell.org/package/bytestring/docs/Data-ByteString-Builder.html
71+-- | https://hackage.haskell.org/package/bytestring/docs/Data-ByteString-Builder.html .
72+-- | That’s the approach taken by
73+-- | https://pursuit.purescript.org/packages/purescript-dynamic-buffers .
74-- | Here are some benchmarks of different Haskell ByteString builders
75-- | Here are some benchmarks of different Haskell ByteString builders
75-- | https://github.com/haskell-perf/strict-bytestring-builders
76-- | https://github.com/haskell-perf/strict-bytestring-builders
@@ -77,27 +78,18 @@
77-- | We've tried to design the API for this library with minimal assumptions,
78-- | We've tried to design the API for this library with minimal assumptions,
78-- | so that if we want to change the `Builder` implementation later then we can.
79-- | so that if we want to change the `Builder` implementation later then we can.
80−-- | Another way this could go:
81−-- | https://kodimensional.dev/posts/2019-03-25-comonadic-builders
83−-- | Our convention is that functions which add `DataView`s to
84−-- | the `Builder` are suffixed with underscore (`_`).
86module Data.ArrayBuffer.Builder.Internal
81module Data.ArrayBuffer.Builder.Internal
87( Builder(..)
82( Builder(..)
89−, Bytes(..)
84+, DataBuff(..)
91, execBuilder
86, execBuilder
95, singleton
90, singleton
101, encodeUint8
93, encodeUint8
102, encodeInt8
94, encodeInt8
103, encodeUint16be
95, encodeUint16be
@@ -127,6 +119,19 @@ import Data.UInt (UInt)
127import Effect (Effect)
119import Effect (Effect)
128import Effect.Class (class MonadEffect, liftEffect)
120import Effect.Class (class MonadEffect, liftEffect)
122+-- | For distinguishing between `ArrayBuffer` and `DataView`.
127+-- Concerning DataViews.
128+-- https://v8.dev/blog/dataview
130+ -- | View the contents of `DataBuff` as a `DataView`.
131+toView :: DataBuff -> DataView
132+toView (Buff ab) = DV.whole ab
133+toView (View dv) = dv
130-- | Monoidal builder for `ArrayBuffer`s.
135-- | Monoidal builder for `ArrayBuffer`s.
132-- | We can add two types of things to the `Builder`:
137-- | We can add two types of things to the `Builder`:
@@ -138,7 +143,7 @@ import Effect.Class (class MonadEffect, liftEffect)
138-- | from some other `ArrayBuffer`, so that we don’t
143-- | from some other `ArrayBuffer`, so that we don’t
139-- | need an extra intermediate copy of the slice.
144-- | need an extra intermediate copy of the slice.
140data Builder
145data Builder
141− = Node Builder Bytes Builder
146+ = Node Builder DataBuff Builder
144-- | ### Left-associative `<>>` append operator
149-- | ### Left-associative `<>>` append operator
@@ -193,57 +198,35 @@ infixl 5 append as <>>
193instance monoidBuilder :: Monoid Builder where
198instance monoidBuilder :: Monoid Builder where
194 mempty = Null
199 mempty = Null
196−-- | For distinguishing between `ArrayBuffer` and `DataView`.
198− = ByteBuff ArrayBuffer
201-- | `Builder` is not an instance of `Foldable` because `Builder` is monomorphic.
201-- | `Builder` is not an instance of `Foldable` because `Builder` is monomorphic.
202−foldl :: forall b. (b -> Bytes -> b) -> b -> Builder -> b
202+foldl :: forall b. (b -> DataBuff -> b) -> b -> Builder -> b
203foldl _ a Null = a
203foldl _ a Null = a
204foldl f a (Node l x r) = foldl f (f (foldl f a l) x) r
204foldl f a (Node l x r) = foldl f (f (foldl f a l) x) r
206-- | Monomorphic foldM copied from
206-- | Monomorphic foldM copied from
207-- | [`Data.Foldable.foldM`](https://pursuit.purescript.org/packages/purescript-foldable-traversable/4.1.1/docs/Data.Foldable#v:foldM)
207-- | [`Data.Foldable.foldM`](https://pursuit.purescript.org/packages/purescript-foldable-traversable/4.1.1/docs/Data.Foldable#v:foldM)
208−foldM :: forall b m. (Monad m) => (b -> Bytes -> m b) -> b -> Builder -> m b
208+foldM :: forall b m. (Monad m) => (b -> DataBuff -> m b) -> b -> Builder -> m b
209foldM f a0 = foldl (\ma b -> ma >>= flip f b) (pure a0)
209foldM f a0 = foldl (\ma b -> ma >>= flip f b) (pure a0)
211−-- | Construct a `Builder` with a single `ArrayBuffer`. *O(1)*
211+-- | Construct a `Builder` with a single `DataBuff`. *O(1)*
212−singleton :: ArrayBuffer -> Builder
212+singleton :: DataBuff -> Builder
213−singleton buf = Node Null (ByteBuff buf) Null
213+singleton buf = Node Null buf Null
215−-- | Construct a `Builder` with a single `DataView`. *O(1)*
216−singleton_ :: DataView -> Builder
217−singleton_ buf = Node Null (ByteView buf) Null
219-- | Calculate the total byte length of the `Builder`, without actually
215-- | Calculate the total byte length of the `Builder`, without actually
220-- | building it yet. *O(n)*
216-- | building it yet. *O(n)*
221length :: Builder -> ByteLength
217length :: Builder -> ByteLength
222length bldr = foldl (\b a -> b + len a) 0 bldr
218length bldr = foldl (\b a -> b + len a) 0 bldr
224− len (ByteBuff ab) = AB.byteLength ab
220+ len (Buff ab) = AB.byteLength ab
225− len (ByteView dv) = DV.byteLength dv
221+ len (View dv) = DV.byteLength dv
227− -- | View the contents of `Bytes` as a `DataView`.
228−toView :: Bytes -> DataView
229−toView (ByteBuff ab) = DV.whole ab
230−toView (ByteView dv) = dv
232−-- | Prepend an `ArrayBuffer` to the beginning of the `Builder`. *O(1)*
233−cons :: ArrayBuffer -> Builder -> Builder
234−cons x bs = Node Null (ByteBuff x) bs
236−-- | Prepend a `DataView` to the beginning of the `Builder`. *O(1)*
237−cons_ :: DataView -> Builder -> Builder
238−cons_ x bs = Node Null (ByteView x) bs
240−-- | Append an `ArrayBuffer` to the end of the `Builder`. *O(1)*
223+-- | Prepend a `DataBuff` to the beginning of the `Builder`. *O(1)*
241−snoc :: Builder -> ArrayBuffer -> Builder
224+cons :: DataBuff -> Builder -> Builder
242−snoc bs x = Node bs (ByteBuff x) Null
225+cons x bs = Node Null x bs
244−-- | Append a `DataView` to the end of the `Builder`. *O(1)*
227+-- | Append a `DataBuff` to the end of the `Builder`. *O(1)*
245−snoc_ :: Builder -> DataView -> Builder
228+snoc :: Builder -> DataBuff -> Builder
246−snoc_ bs x = Node bs (ByteView x) Null
229+snoc bs x = Node bs x Null
248-- | Build a single `ArrayBuffer` from a `Builder`. *O(n)*
231-- | Build a single `ArrayBuffer` from a `Builder`. *O(n)*
249execBuilder :: forall m. (MonadEffect m) => Builder -> m ArrayBuffer
232execBuilder :: forall m. (MonadEffect m) => Builder -> m ArrayBuffer
@@ -263,9 +246,9 @@ execBuilder bldr = do
266− toUint8Array :: Bytes -> Effect Uint8Array
249+ toUint8Array :: DataBuff -> Effect Uint8Array
267− toUint8Array (ByteBuff ab) = AT.whole ab
250+ toUint8Array (Buff ab) = AT.whole ab
268− toUint8Array (ByteView dv) =
251+ toUint8Array (View dv) =
269 AT.part (DV.buffer dv) (DV.byteOffset dv) (DV.byteLength dv)
252 AT.part (DV.buffer dv) (DV.byteOffset dv) (DV.byteLength dv)
271-- | Serialize an 8-bit unsigned integer (byte) into a new `ArrayBuffer`.
254-- | Serialize an 8-bit unsigned integer (byte) into a new `ArrayBuffer`.