xcodec-1.1.0.0: CHANGELOG.md

[`xcodec`](http://hackage.haskell.org/package/xcodec) change log:
=================================================================

Major release 1.0
-----------------

## Version 1.1.0.0 (07-08-2026)

This version revamps the class interface for `BinaryTranscoder`. Functions now
are named with octets in mind rather than bytes so that functions specific to
the `BinaryTranscoder` are easy to spot. Namely, the following functions got
renamed:

| Old              | New              |
|------------------|------------------|
| `lengthBytes`    | `totalOctets`    |
| `lengthBytes`    | `totalOctets`    |
| `serializeValue` | `unpackSerial`   |
| `packBytes`      | `packOctets`     |
| `unpackBytes`    | `unpackOctets`   |
| `pushByte`       | `pushOctetTop`   |
| `pushByteEnd`    | `pushOctetEnd`   |
| `takeBytes`      | `takeOctetsTop`  |
| `takeBytesEnd`   | `takeOctetsEnd`  |
| `dropBytes`      | `dropOctetsTop`  |
| `dropBytesEnd`   | `dropOctetsEnd`  |
| `splitAtByte`    | `splitOffset`    |
| `spanBytes`      | `spanOctetsTop`  |
| `spanBytesEnd`   | `spanOctetsEnd`  |
| `replicateByte`  | `replicateOctet` |
| `singleton`      | `fromOctet`      |

The `unpackValue` function was replaced with the `unpackValueCPU`,
`unpackValueBE`, and `unpackValueLE` functions, so endianness of the unpacked
value can be specified.

Also the `packValue` function got the same change. The functions `packValueBE`
and `packValueLE` replace it.

The function `swapOrder` is introduced so that the internal order of the
transcoder can be flipped without unpacking the value.

Unit tests for xcodec can now be found as part of [ipfshs](
https://git.sr.ht/~z0/ipfshs/).

## Version 1.0.0.0 (05-21-2026)

Introducing this package to hackage.org! This module provides instances of
`BinaryTranscoder`, a type-class for generically working on binary data formats,
and `StreamTranscoder` a type-class interface for designing encoders and
decoders on top of `BinaryTranscoder`.


### Module `Data.XCodec.BinaryTranscoder`

This module provides the type-class for the `BinaryTranscoder`. It also provides
default instances for `ByteString`, `LazyByteString`, and `ShortByteString` from
the GHC standard library. The minimal definition for a `BinaryTranscoder` is
currently with the following methods (where `bxc` is the type-parameter deriving
`BinaryTranscoder`):

```haskell
-- | Gives back the length in bytes of the Transcoder data.
lengthBytes :: bxc -> Int
-- | Unpacks transcoder data as BitSet, ie, an infinite bitarray.
unpackValue :: bxc -> BitSet
-- | Places the contents of the transcoder into a ByteString Builder.
serializeValue :: bxc -> Builder
-- | Packs Word8 values into transcoder data `bxc`.
packBytes :: [Word8] -> bxc
-- | Unpacks transcoder data into a list of bytes.
unpackBytes :: bxc -> [Word8]
-- | Prepends a byte value to the top of the transcoder data.
pushByte :: bxc -> Word8 -> bxc
-- | Appends the byte value to the end of the transcoder data.
pushByteEnd :: bxc -> Word8 -> bxc
-- | Takes a subsection of bytes from the beginning of the transcoder data.
takeBytes :: Int -> bxc -> bxc
-- | Removes bytes from the beginning of transcoder data.
dropBytes :: Int -> bxc -> bxc
-- | Removes bytes from the end of transcoder data.
takeBytesEnd :: Int -> bxc -> bxc
-- | Removes bytes from the end of transcoder data.
dropBytesEnd :: Int -> bxc -> bxc
-- | Parititions the binary data at the nth byte.
splitAtByte :: Int -> bxc -> (bxc, bxc)
-- | Repeats a byte value in binary data.
replicateByte :: Int -> Word8 -> bxc
-- | Splits byte values based on the first false result from the predicate.
spanBytes :: (Word8 -> Bool) -> bxc -> (bxc, bxc)
-- | Splits the list while the element predicate holds staring from the left
-- side.
spanBytesEnd :: (Word8 -> Bool) -> bxc -> (bxc, bxc)
```

### Module `Data.XCodec.StreamTranscoder`

This module exports the type-class and methods for `StreamTranscoder`. It
provides no default instances, and is a way for the programmer to implement
generic decoders and decoders on streams of data from deriving from
the `BinaryTranscoder` class of types. It defines the follwing method
signatures:

```haskell
-- | Generic Encoder signature
type Encoder xtype ytype = xtype -> ytype

-- | Generic Decoder signature
type Decoder xtype ytype = ytype -> Maybe xtype

-- | StreamTranscoder give a way to make a generic codec methods.
class (BinaryTranscoder xtype) => StreamTranscoder codec xtype ytype where
  streamEncoder :: codec -> Encoder xtype ytype
  streamDecoder :: codec -> Decoder xtype ytype
```