Add runOntoLength

CHANGELOG.md

@@ -5,6 +5,10 @@ Note: Prior to version 0.3.4.0, this library was named
 `small-bytearray-builder` is now just a compatibility shim
 to ease the migration process.
 
+## 0.3.14.0 -- 2023-??-??
+
+* Add `runOntoLength`.
+
 ## 0.3.13.0 -- 2023-05-01
 
 * Add VLQ builders for Word32 and Word64.

bytebuild.cabal

@@ -1,6 +1,6 @@
 cabal-version: 2.2
 name: bytebuild
-version: 0.3.13.0
+version: 0.3.14.0
 synopsis: Build byte arrays
 description:
   This is similar to the builder facilities provided by
@@ -57,7 +57,7 @@ library
     , natural-arithmetic >=0.1 && <0.2
     , primitive-offset >=0.2 && <0.3
     , primitive-unlifted >=0.1.2 && <0.2
-    , run-st >=0.1 && <0.2
+    , run-st >=0.1.2 && <0.2
     , template-haskell >=2.16
     , text >=1.2 && <2.2
     , text-short >=0.1.3 && <0.2

src/Data/Bytes/Builder.hs

@@ -17,6 +17,7 @@ module Data.Bytes.Builder
     -- * Evaluation
   , run
   , runOnto
+  , runOntoLength
   , reversedOnto
   , putMany
   , putManyConsLength
@@ -211,7 +212,7 @@ run !hint bldr = runOnto hint bldr ChunksNil
 runOnto ::
      Int -- ^ Size of initial chunk (use 4080 if uncertain)
   -> Builder -- ^ Builder
-  -> Chunks
+  -> Chunks -- ^ Suffix
   -> Chunks
 runOnto hint@(I# hint# ) (Builder f) cs0 = runST $ do
   MutableByteArray buf0 <- PM.newByteArray hint
@@ -220,6 +221,22 @@ runOnto hint@(I# hint# ) (Builder f) cs0 = runST $ do
       (# s1, Mutable bufX offX csX #)
   reverseCommitsOntoChunks cs0 cs
 
+-- | Variant of 'runOnto' that additionally returns the number of bytes
+-- consed onto the suffix.
+runOntoLength ::
+     Int -- ^ Size of initial chunk (use 4080 if uncertain)
+  -> Builder -- ^ Builder
+  -> Chunks -- ^ Suffix
+  -> (Int,Chunks)
+runOntoLength hint@(I# hint# ) (Builder f) cs0 = runST $ do
+  MutableByteArray buf0 <- PM.newByteArray hint
+  cs <- ST $ \s0 -> case f buf0 0# hint# Initial s0 of
+    (# s1, bufX, offX, _, csX #) ->
+      (# s1, Mutable bufX offX csX #)
+  let !n = addCommitsLength 0 cs
+  ch <- reverseCommitsOntoChunks cs0 cs
+  pure (n,ch)
+
 -- | Variant of 'runOnto' that conses the additional chunks
 -- in reverse order.
 reversedOnto ::