Release 0.3.16.0 with Avro module and a few minor additions

CHANGELOG.md

@@ -5,6 +5,13 @@ 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.16.0 -- 2024-01-29
+
+* Add `wordPaddedDec3`.
+* Add `Data.Bytes.Builder.Avro`.
+* Add `word16LEB128`.
+* Stop accepting versions of text lower than 2.0.
+
 ## 0.3.15.0 -- 2024-01-05
 
 * Add `Data.Bytes.Builder.Unsafe.pasteUtf8TextJson#` for users who need

bytebuild.cabal

@@ -1,6 +1,6 @@
 cabal-version: 2.2
 name: bytebuild
-version: 0.3.15.0
+version: 0.3.16.0
 synopsis: Build byte arrays
 description:
  This is similar to the builder facilities provided by
@@ -37,6 +37,7 @@ flag checked
 library
  exposed-modules:
  Data.Bytes.Builder
+ Data.Bytes.Builder.Avro
  Data.Bytes.Builder.Class
  Data.Bytes.Builder.Template
  Data.Bytes.Builder.Unsafe
@@ -58,7 +59,7 @@ library
  , primitive-offset >=0.2 && <0.3
  , run-st >=0.1.2 && <0.2
  , template-haskell >=2.16
- , text >=1.2 && <2.2
+ , text >=2.0 && <2.2
  , text-short >=0.1.3 && <0.2
  , wide-word >=0.1.0.9 && <0.2
  , zigzag

src/Data/Bytes/Builder.hs

@@ -105,6 +105,7 @@ module Data.Bytes.Builder
  , int32LEB128
  , int64LEB128
  , wordLEB128
+ , word16LEB128
  , word32LEB128
  , word64LEB128
  -- **** VLQ
@@ -1219,6 +1220,11 @@ wordLEB128 :: Word -> Builder
 {-# inline wordLEB128 #-}
 wordLEB128 w = fromBounded Nat.constant (Bounded.wordLEB128 w)
 
+-- | Encode a 16-bit word with LEB-128.
+word16LEB128 :: Word16 -> Builder
+{-# inline word16LEB128 #-}
+word16LEB128 w = fromBounded Nat.constant (Bounded.word16LEB128 w)
+
 -- | Encode a 32-bit word with LEB-128.
 word32LEB128 :: Word32 -> Builder
 {-# inline word32LEB128 #-}

src/Data/Bytes/Builder/Avro.hs

@@ -0,0 +1,77 @@
+{-# language BangPatterns #-}
+
+-- | Builders for encoding data with Apache Avro. Most functions in this
+-- module are just aliases for other functions. Avro uses zig-zag LEB128
+-- for all integral types.
+module Data.Bytes.Builder.Avro
+ ( int
+ , int32
+ , int64
+ , word16
+ , word32
+ , word128
+ , bytes
+ , chunks
+ , text
+ -- * Maps
+ , map2
+ ) where
+
+import Data.Int
+import Data.Word
+import Data.Bytes.Builder (Builder)
+import Data.Text (Text)
+import Data.Bytes (Bytes)
+import Data.WideWord (Word128)
+import Data.Bytes.Chunks (Chunks)
+
+import qualified Data.Bytes as Bytes
+import qualified Data.Bytes.Chunks as Chunks
+import qualified Data.Bytes.Builder as B
+import qualified Data.Bytes.Text.Utf8 as Utf8
+
+int32 :: Int32 -> Builder
+int32 = B.int32LEB128
+
+int64 :: Int64 -> Builder
+int64 = B.int64LEB128
+
+int :: Int -> Builder
+int = B.intLEB128
+
+-- | Note: This results in a zigzag encoded number. Avro does not have
+-- unsigned types.
+word16 :: Word16 -> Builder
+word16 = B.int32LEB128 . fromIntegral
+
+-- | Note: This results in a zigzag encoded number. Avro does not have
+-- unsigned types.
+word32 :: Word32 -> Builder
+word32 = B.int64LEB128 . fromIntegral
+
+-- | Note: This results in a @fixed@ encoded value of length 16. In the
+-- schema, the type must be @{"type": "fixed", "name": "...", "size": 16}@.
+-- A big-endian encoding is used.
+word128 :: Word128 -> Builder
+word128 = B.word128BE
+
+bytes :: Bytes -> Builder
+bytes !b = int (Bytes.length b) <> B.bytes b
+
+chunks :: Chunks -> Builder
+chunks !b = int (Chunks.length b) <> B.chunks b
+
+text :: Text -> Builder
+text = bytes . Utf8.fromText
+
+-- | Encode a map with exactly two key-value pairs. The keys are text.
+-- This is commonly used to encode the header in an avro file, which has
+-- a map with two keys: @avro.schema@ and @avro.codec@.
+map2 ::
+ Text -- ^ First key
+ -> Builder -- ^ First value (already encoded)
+ -> Text -- ^ Second key
+ -> Builder -- ^ Second value (already encoded)
+ -> Builder
+{-# inline map2 #-}
+map2 k1 v1 k2 v2 = B.word8 0x04 <> text k1 <> v1 <> text k2 <> v2 <> B.word8 0x00

src/Data/Bytes/Builder/Bounded.hs

@@ -74,6 +74,7 @@ module Data.Bytes.Builder.Bounded
  , char
  -- ** Native
  , wordPaddedDec2
+ , wordPaddedDec3
  , wordPaddedDec4
  , wordPaddedDec9
  -- ** Machine-Readable
@@ -102,6 +103,7 @@ module Data.Bytes.Builder.Bounded
  -- with the high bit of each output byte set to 1 in all bytes except for
  -- the final byte.
  , wordLEB128
+ , word16LEB128
  , word32LEB128
  , word64LEB128
  -- **** VLQ
@@ -788,6 +790,14 @@ wordPaddedDec4 !w = Unsafe.construct $ \arr off -> do
  ) arr (off + 3) w
  pure (off + 4)
 
+wordPaddedDec3 :: Word -> Builder 3
+wordPaddedDec3 !w = Unsafe.construct $ \arr off -> do
+ putRem10
+ (putRem10 $ putRem10
+ (\_ _ _ -> pure ())
+ ) arr (off + 2) w
+ pure (off + 3)
+
 -- | Encode a number less than 1e9 as a decimal number, zero-padding it to
 -- nine digits. For example: 0 is encoded as @000000000@ and 5 is encoded as
 -- @000000005@.
@@ -923,6 +933,11 @@ wordLEB128 :: Word -> Builder 10
 {-# inline wordLEB128 #-}
 wordLEB128 (W# w) = lebCommon (W# w)
 
+-- | Encode a 32-bit word with LEB-128.
+word16LEB128 :: Word16 -> Builder 3
+{-# inline word16LEB128 #-}
+word16LEB128 (W16# w) = lebCommon (W# (C.word16ToWord# w))
+
 -- | Encode a 32-bit word with LEB-128.
 word32LEB128 :: Word32 -> Builder 5
 {-# inline word32LEB128 #-}