codecs

object codecs

Provides codecs for common types and combinators for building larger codecs.

=== Bits and Bytes Codecs ===

The simplest of the provided codecs are those that encode/decode BitVectors and ByteVectors directly. These are provided by bits and bytes methods. These codecs encode all of the bits/bytes directly in to the result and decode all of the remaining bits/bytes in to the result value. That is, the result of decode always returns a empty bit vector for the remaining bits.

Similarly, fixed size alternatives are provided by the bits(size) and bytes(size) methods, which encode a fixed number of bits/bytes (or error if not provided the correct size) and decoded a fixed number of bits/bytes (or error if that many bits/bytes are not available).

There are more specialized codecs for working with bits, including ignore and constant.

=== Numeric Codecs ===

There are built-in codecs for Int, Long, Float, and Double.

There are a number of predefined integral codecs named using the form: {{{ [u]int$${size}[L] }}} where u stands for unsigned, size is replaced by one of 8, 16, 24, 32, 64, and L stands for little-endian. For each codec of that form, the type is Codec[Int] or Codec[Long] depending on the specified size. For example, int32 supports 32-bit big-endian 2s complement signed integers, and uint16L supports 16-bit little-endian unsigned integers. Note: uint64[L] are not provided because a 64-bit unsigned integer does not fit in to a Long.

Additionally, methods of the form [u]int[L](size: Int) and [u]long[L](size: Int) exist to build arbitrarily sized codecs, within the limitations of Int and Long.

IEEE 754 floating point values are supported by the float, floatL, double, and doubleL codecs.

=== Miscellaneous Value Codecs ===

In addition to the numeric codecs, there are built-in codecs for Boolean, String, and UUID.

Boolean values are supported by the bool codecs.

=== Combinators ===

There are a number of methods provided that create codecs out of other codecs. These include simple combinators such as fixedSizeBits and variableSizeBits and advanced combinators such as discriminated, which provides its own DSL for building a large codec out of many small codecs. For a list of all combinators, see the Combinators section below.

=== Cryptography Codecs ===

There are codecs that support working with encrypted data (encrypted), digital signatures and checksums (fixedSizeSignature and variableSizeSignature). Additionally, support for java.security.cert.Certificates is provided by certificate and x509Certificate.

class Object
trait Matchable
class Any

Document{}

val bits: Codec[BitVector]

Encodes by returning supplied bit vector; decodes by taking all remaining bits in the supplied bit vector.

def bits(size: Long): Codec[BitVector]

Encodes by returning the supplied bit vector if its length is size bits, padding with zeroes if smaller than size bits, returning error if greater; decodes by taking size bits from the supplied bit vector.

Value Params
size

number of bits to encode/decode

def bitsStrict(size: Long): Codec[BitVector]

Encodes by returning the supplied bit vector if its length is size bits, otherwise returning error; decodes by taking size bits from the supplied bit vector.

Value Params
size

number of bits to encode/decode

val bytes: Codec[ByteVector]

Encodes by returning supplied byte vector as a bit vector; decodes by taking all remaining bits in supplied bit vector and converting to a byte vector.

def bytes(size: Int): Codec[ByteVector]

Encodes by returning the supplied byte vector if its length is size bytes, padding with zeroes if smaller than size bytes, returning error if greater; decodes by taking size * 8 bits from the supplied bit vector and converting to a byte vector.

Value Params
size

number of bytes to encode/decode

def bytesStrict(size: Int): Codec[ByteVector]

Encodes by returning the supplied byte vector if its length is size bytes, otherwise returning error; decodes by taking size * 8 bits from the supplied bit vector and converting to a byte vector.

Value Params
size

number of bytes to encode/decode

val byte: Codec[Byte]

Codec for 8-bit 2s complement bytes.

val ushort8: Codec[Short]

Codec for 8-bit unsigned bytes.

val short16: Codec[Short]

Codec for 16-bit 2s complement big-endian shorts.

val int8: Codec[Int]

Codec for 8-bit 2s complement big-endian integers.

val int16: Codec[Int]

Codec for 16-bit 2s complement big-endian integers.

val int24: Codec[Int]

Codec for 24-bit 2s complement big-endian integers.

val int32: Codec[Int]

Codec for 32-bit 2s complement big-endian integers.

val int64: Codec[Long]

Codec for 64-bit 2s complement big-endian integers.

val uint2: Codec[Int]

Codec for 2-bit unsigned big-endian integers.

val uint4: Codec[Int]

Codec for 4-bit unsigned big-endian integers.

val uint8: Codec[Int]

Codec for 8-bit unsigned big-endian integers.

val uint16: Codec[Int]

Codec for 16-bit unsigned big-endian integers.

val uint24: Codec[Int]

Codec for 24-bit unsigned big-endian integers.

val uint32: Codec[Long]

Codec for 32-bit unsigned big-endian integers.

val short16L: Codec[Short]

Codec for 16-bit 2s complement little-endian shorts.

val int8L: Codec[Int]

Codec for 8-bit 2s complement little-endian integers.

val int16L: Codec[Int]

Codec for 16-bit 2s complement little-endian integers.

val int24L: Codec[Int]

Codec for 24-bit 2s complement little-endian integers.

val int32L: Codec[Int]

Codec for 32-bit 2s complement little-endian integers.

val int64L: Codec[Long]

Codec for 64-bit 2s complement little-endian integers.

val uint2L: Codec[Int]

Codec for 2-bit unsigned little-endian integers.

val uint4L: Codec[Int]

Codec for 4-bit unsigned little-endian integers.

val uint8L: Codec[Int]

Codec for 8-bit unsigned little-endian integers.

val uint16L: Codec[Int]

Codec for 16-bit unsigned little-endian integers.

val uint24L: Codec[Int]

Codec for 24-bit unsigned little-endian integers.

val uint32L: Codec[Long]

Codec for 32-bit unsigned little-endian integers.

val vint: Codec[Int]

Codec for variable-length big-endian integers. Encoding requires between 1 and 5 bytes, depending on the value. Smaller ints require less bytes. Negative values are always encoded with 5 bytes.

val vintL: Codec[Int]

Codec for variable-length little-endian integers. Encoding requires between 1 and 5 bytes, depending on the value. Smaller ints require less bytes. Negative values are always encoded with 5 bytes.

val vlong: Codec[Long]

Codec for variable-length big-endian longs. Encoding requires between 1 and 9 bytes, depending on the value. Smaller longs require less bytes. Negative values are not supported.

val vpbcd: Codec[Long]

Codec for variable-length packed decimal longs. Negative values are not supported.

val vlongL: Codec[Long]

Codec for variable-length little-endian longs. Encoding requires between 1 and 9 bytes, depending on the value. Smaller longs require less bytes. Negative values are not supported.

def byte(size: Int): Codec[Byte]

Codec for n-bit 2s complement bytes.

Value Params
size

number of bits (must be 0 < size <= 8)

def ubyte(size: Int): Codec[Byte]

Codec for n-bit unsigned bytes.

Value Params
size

number of bits (must be 0 < size <= 7)

def short(size: Int): Codec[Short]

Codec for n-bit 2s complement big-endian shorts.

Value Params
size

number of bits (must be 0 < size <= 16)

def ushort(size: Int): Codec[Short]

Codec for n-bit unsigned big-endian shorts.

Value Params
size

number of bits (must be 0 < size <= 15)

def int(size: Int): Codec[Int]

Codec for n-bit 2s complement big-endian integers that are represented with Int.

Value Params
size

number of bits (must be 0 < size <= 32)

def uint(bits: Int): Codec[Int]

Codec for n-bit unsigned big-endian integers that are represented with Int.

Value Params
bits

number of bits (must be 0 < size <= 31)

def long(bits: Int): Codec[Long]

Codec for n-bit 2s complement big-endian integers that are represented with Long.

Value Params
bits

number of bits (must be 0 < size <= 64)

def ulong(bits: Int): Codec[Long]

Codec for n-bit unsigned big-endian integers that are represented with Long.

Value Params
bits

number of bits (must be 0 < size <= 63)

def shortL(size: Int): Codec[Short]

Codec for n-bit 2s complement little-endian shorts.

Value Params
size

number of bits (must be 0 < size <= 16)

def ushortL(size: Int): Codec[Short]

Codec for n-bit unsigned little-endian shorts.

Value Params
size

number of bits (must be 0 < size <= 15)

def intL(bits: Int): Codec[Int]

Codec for n-bit 2s complement little-endian integers that are represented with Int.

Value Params
bits

number of bits (must be 0 < size <= 32)

def uintL(bits: Int): Codec[Int]

Codec for n-bit unsigned little-endian integers that are represented with Int.

Value Params
bits

number of bits (must be 0 < size <= 31)

def longL(bits: Int): Codec[Long]

Codec for n-bit 2s complement little-endian integers that are represented with Long.

Value Params
bits

number of bits (must be 0 < size <= 64)

def ulongL(bits: Int): Codec[Long]

Codec for n-bit unsigned little-endian integers that are represented with Long.

Value Params
bits

number of bits (must be 0 < size <= 63)

def pbcd(nibbles: Int): Codec[Long]

Codec for n-nibble packed decimal (BCD) integers that are represented with Long.

Value Params
nibbles

number of nibbles (4-bit chunks)

def lpbcd(nibbles: Int): Codec[Long]

Codec for n-nibble packed decimal (BCD) integers that are represented with Long. This codec, despite requiring the size in nibbles, is byte-size oriented. This means it expects to parse complete bytes (even if nibble size is odd). For encoding, this codec will pad 0s on the left while, for decoding, it will fetch the size in bytes round up.

Value Params
nibbles

number of nibbles (4-bit chunks)

val float: Codec[Float]

32-bit big endian IEEE 754 floating point number.

val floatL: Codec[Float]

32-bit little endian IEEE 754 floating point number.

val double: Codec[Double]

64-bit big endian IEEE 754 floating point number.

val doubleL: Codec[Double]

64-bit little endian IEEE 754 floating point number.

val bool: Codec[Boolean]

1-bit boolean codec, where false corresponds to bit value 0 and true corresponds to bit value 1.

def bool(n: Long): Codec[Boolean]

n-bit boolean codec, where false corresponds to bit vector of all 0s and true corresponds to all other vectors.

def string(charset: Charset): Codec[String]

String codec that uses the supplied Charset to perform encoding/decoding.

This codec does not encode the size of the string in to the output. Hence, decoding a vector that has additional data after the encoded string will result in unexpected output. Instead, it is common to use this codec along with either fixedSizeBits or variableSizeBits. For example, a common encoding is a size field, say 2 bytes, followed by the encoded string. This can be accomplished with: {{{ variableSizeBits(uint16, string) }}}

Value Params
charset

charset to use to convert strings to/from binary

val ascii: Codec[String]

String codec that uses the US-ASCII charset. See string for more information on String codecs.

val utf8: Codec[String]

String codec that uses the UTF-8 charset. See string for more information on String codecs.

val cstring: Codec[String]

String codec that uses the US-ASCII charset that encodes strings with a trailing NUL termination byte and decodes a string up to the next NUL termination byte. It fails to decode if the bit vector ends before a NUL termination byte can be found.

def string32(charset: Charset): Codec[String]

String codec that uses the given Charset and prefixes the encoded string by the byte size in a 32-bit 2s complement big endian field.

Value Params
charset

charset to use to convert strings to/from binary

def string32L(charset: Charset): Codec[String]

String codec that uses the given Charset and prefixes the encoded string by the byte size in a 32-bit 2s complement little endian field.

Value Params
charset

charset to use to convert strings to/from binary

val ascii32: Codec[String]

String codec that uses the US-ASCII charset and prefixes the encoded string by the byte size in a 32-bit 2s complement big endian field.

val ascii32L: Codec[String]

String codec that uses the US-ASCII charset and prefixes the encoded string by the byte size in a 32-bit 2s complement little endian field.

val utf8_32: Codec[String]

String codec that uses the UTF-8 charset and prefixes the encoded string by the byte size in a 32-bit 2s complement big endian field.

val utf8_32L: Codec[String]

String codec that uses the UTF-8 charset and prefixes the encoded string by the byte size in a 32-bit 2s complement little endian field.

val uuid: Codec[UUID]

Encodes/decodes UUIDs as 2 64-bit big-endian longs, first the high 64-bits then the low 64-bits.

def provide[A](value: A): Codec[A]

Codec that always returns an empty vector from encode and always returns (empty, value) from decode. This is often useful when combined with other codecs (e.g., the discriminated).

Value Params
value

value to return from decode

def ignore(size: Long): Codec[Unit]

Codec that always encodes size 0 bits and always decodes size bits and then discards them, returning () instead.

Value Params
size

number of bits to ignore

def constant(bits: BitVector): Codec[Unit]

Codec that always encodes the specified bits and always decodes the specified bits, returning () if the actual bits match the specified bits and returning an error otherwise.

Value Params
bits

constant bits

def constant(bytes: ByteVector): Codec[Unit]

Codec that always encodes the specified bytes and always decodes the specified bytes, returning () if the actual bytes match the specified bytes and returning an error otherwise.

Value Params
bytes

constant bytes

def constant[A](bits: A*)(using `evidence$1`: Integral[A]): Codec[Unit]

Codec that always encodes the specified bits and always decodes the specified bits, returning () if the actual bits match the specified bits and returning an error otherwise.

Value Params
bits

constant bits

def constantLenient(bits: BitVector): Codec[Unit]

Codec that always encodes the specified bits and always decodes n bits, returning (), where n is the length of the specified bits.

Value Params
bits

constant bits

def constantLenient(bytes: ByteVector): Codec[Unit]

Codec that always encodes the specified bytes and always decodes n bytes, returning (), where n is the length of the specified bytes.

Value Params
bytes

constant bytes

def constantLenient[A](bits: A*)(using `evidence$2`: Integral[A]): Codec[Unit]

Codec that always encodes the specified bits and always decodes n bits, returning (), where n is the length of the specified bits.

Value Params
bits

constant bits

def fixedSizeBits[A](size: Long, codec: Codec[A]): Codec[A]

Codec that limits the number of bits the specified codec works with.

When encoding, if encoding with the specified codec results in less than the specified size, the vector is right padded with 0 bits. If the result is larger than the specified size, an encoding error is returned.

When decoding, the specified codec is only given size bits. If the specified codec does not consume all the bits it was given, any remaining bits are discarded.

Value Params
codec

codec to limit

size

number of bits

def fixedSizeBytes[A](size: Long, codec: Codec[A]): Codec[A]

Byte equivalent of fixedSizeBits.

Value Params
codec

codec to limit

size

number of bytes

def paddedFixedSizeBits[A](size: Long, codec: Codec[A], padCodec: Codec[Unit]): Codec[A]

Codec that limits the number of bits the specified codec works with.

If the encoded result is larger than the specified size, an encoding error is returned.

If encoding with the specified codec results in less than the specified size, the vector is right padded by repeatedly encoding with padCodec. An encoding error is returned if the padCodec result does not precisely fill the remaining space.

When decoding, the specified codec is only given size bits. If the specified codec does not consume all the bits it was given, all remaining bits are repeatedly decoded by padCodec. A decoding error is returned if any padCodec decode returns an error.

Value Params
codec

codec to limit

padCodec

codec to use for padding

size

number of bits

def paddedFixedSizeBitsDependent[A](size: Long, codec: Codec[A], padCodec: Long => Codec[Unit]): Codec[A]

Codec that limits the number of bits the specified codec works with.

If the encoded result is larger than the specified size, an encoding error is returned.

If encoding with the specified codec results in less than the specified size, the vector is right padded by repeatedly encoding with the codec returned from padCodec(numberOfPaddingBits). An encoding error is returned if the padCodec result does not precisely fill the remaining space.

When decoding, the specified codec is only given size bits. If the specified codec does not consume all the bits it was given, all remaining bits are repeatedly decoded by the codec returned from padCodec(remainingBitCount). A decoding error is returned if any padding decode iteration returns an error.

Value Params
codec

codec to limit

padCodec

function that provides the codec to use for padding

size

number of bits

def paddedFixedSizeBytes[A](size: Long, codec: Codec[A], padCodec: Codec[Unit]): Codec[A]

Byte equivalent of paddedFixedSizeBits.

Value Params
codec

codec to limit

padCodec

codec to use for padding

size

number of bytes

def paddedFixedSizeBytesDependent[A](size: Long, codec: Codec[A], padCodec: Long => Codec[Unit]): Codec[A]

Byte equivalent of paddedFixedSizeBitsDependent.

The padCodec function is passed the number of bits of padding required -- not bytes.

Value Params
codec

codec to limit

padCodec

function that provides the codec to use for padding

size

number of bytes

def paddedVarAlignedBits[A](sizeCodec: Codec[Long], valueCodec: Codec[A], multipleForPadding: Int): PaddedVarAlignedCodec[A]

Codec that pads on a multiplier.

Similar to ByteAligendCodec, but instead of only padding to 8 bits, pads to a variable size

Value Params
multipleForPadding

multiple to align the value to with padding

sizeCodec

codec that determines the size

valueCodec

codec for encoding the payload

def paddedVarAlignedBytes[A](sizeCodec: Codec[Int], valueCodec: Codec[A], multipleForPadding: Int): Codec[A]

Byte equivalent of paddedVarAlignedBits.

Value Params
multipleForPadding

multiple of bytes to align the value to with padding

sizeCodec

codec that determines the size

valueCodec

coec for encoding the payload

def limitedSizeBits[A](limit: Long, codec: Codec[A]): Codec[A]

Codec that limits the number of bits the specified codec works with.

When encoding, if encoding with the specified codec results in less than the specified size, the vector is returned with no padding. If the result is larger than the specified size, an encoding error is returned. This differs from fixedSizeBits by not padding encoded vectors less than the specified size.

When decoding, the specified codec is only given size bits. If the specified codec does not consume all the bits it was given, any remaining bits are returned with the overall remainder.

Value Params
codec

codec to limit

size

number of bits

def limitedSizeBytes[A](limit: Long, codec: Codec[A]): Codec[A]

Byte equivalent of limitedSizeBits.

Value Params
codec

codec to limit

size

number of bytes

def variableSizeBits[A](size: Codec[Int], value: Codec[A], sizePadding: Int): Codec[A]

Codec that supports vectors of the form size ++ value where the size field decodes to the bit length of the value field.

For example, encoding the string "hello" with variableSizeBits(uint8, ascii) yields a vector of 6 bytes -- the first byte being 0x28 and the next 5 bytes being the US-ASCII encoding of "hello".

The size field can be any Int codec. An optional padding can be applied to the size field. The sizePadding is added to the calculated size before encoding, and subtracted from the decoded size before decoding the value.

For example, encoding "hello" with variableSizeBits(uint8, ascii, 1) yields a vector of 6 bytes -- the first byte being 0x29 and the next 5 bytes being the US-ASCII encoding of "hello".

Value Params
size

codec that encodes/decodes the size in bits

sizePadding

number of bits to add to the size before encoding (and subtract from the size before decoding)

value

codec the encodes/decodes the value

def variableSizeBytes[A](size: Codec[Int], value: Codec[A], sizePadding: Int): Codec[A]

Byte equivalent of variableSizeBits.

Value Params
size

codec that encodes/decodes the size in bytes

sizePadding

number of bytes to add to the size before encoding (and subtract from the size before decoding)

value

codec the encodes/decodes the value

def variableSizeBitsLong[A](size: Codec[Long], value: Codec[A], sizePadding: Long): Codec[A]

Codec that supports vectors of the form size ++ value where the size field decodes to the bit length of the value field.

For example, encoding the string "hello" with variableSizeBitsLong(uint32, ascii) yields a vector of 9 bytes -- the first four bytes being 0x00000028 and the next 5 bytes being the US-ASCII encoding of "hello".

The size field can be any Long codec. An optional padding can be applied to the size field. The sizePadding is added to the calculated size before encoding, and subtracted from the decoded size before decoding the value.

For example, encoding "hello" with variableSizeBitsLong(uint32, ascii, 1) yields a vector of 9 bytes -- the first 4 bytes being 0x00000029 and the next 5 bytes being the US-ASCII encoding of "hello".

Value Params
size

codec that encodes/decodes the size in bits

sizePadding

number of bits to add to the size before encoding (and subtract from the size before decoding)

value

codec the encodes/decodes the value

def variableSizeBytesLong[A](size: Codec[Long], value: Codec[A], sizePadding: Long): Codec[A]

Byte equivalent of variableSizeBitsLong.

Value Params
size

codec that encodes/decodes the size in bytes

sizePadding

number of bytes to add to the size before encoding (and subtract from the size before decoding)

value

codec the encodes/decodes the value

def variableSizeDelimited[A](delimiterCodec: Codec[Unit], value: Codec[A]): Codec[A]

Codec that supports vectors of the form value ++ delimiter where the delimiter marks the end of the value field.

Value Params
size

codec that encodes/decodes the delimiter

value

codec the encodes/decodes the value

def variableSizeDelimited[A](delimiterCodec: Codec[Unit], value: Codec[A], multipleValueSize: Long): Codec[A]

Codec that supports vectors of the form value ++ delimiter where the delimiter marks the end of the value field.

Value Params
multipleValueSize

the size or a mutiple size of the expected value

size

codec that encodes/decodes the delimiter

value

codec the encodes/decodes the value

def variableSizePrefixedBits[A, B](size: Codec[Int], prefix: Codec[A], value: Codec[B], sizePadding: Int): Codec[(A, B)]

Codec that supports vectors of the form size ++ prefix ++ value where the size field decodes to the bit length of the value field.

For example, encoding (3, "hello") with variableSizePrefixedBits(uint8, int32, ascii) yields a vector of 10 bytes -- the first byte being 0x28, the next 4 bytes being 0x00000003, and the last 5 bytes being the US-ASCII encoding of "hello".

The size field can be any Int codec. An optional padding can be applied to the size field. The sizePadding is added to the calculated size before encoding, and subtracted from the decoded size before decoding the value.

For example, encoding (3, "hello") with variableSizePrefixedBits(uint8, int32, ascii, 1) yields a vector of 10 bytes -- the first byte being 0x29, the next 4 bytes being 0x00000003, and the last 5 bytes being the US-ASCII encoding of "hello".

Value Params
prefix

codec that encodes/decodes the prefix

size

codec that encodes/decodes the size in bits

sizePadding

number of bits to add to the size before encoding (and subtract from the size before decoding)

value

codec the encodes/decodes the value

def variableSizePrefixedBytes[A, B](size: Codec[Int], prefix: Codec[A], value: Codec[B], sizePadding: Int): Codec[(A, B)]

Byte equivalent of variableSizePrefixedBits.

Value Params
prefix

codec that encodes/decodes the prefix

size

codec that encodes/decodes the size in bytes

sizePadding

number of bytes to add to the size before encoding (and subtract from the size before decoding)

value

codec the encodes/decodes the value

def variableSizePrefixedBitsLong[A, B](size: Codec[Long], prefix: Codec[A], value: Codec[B], sizePadding: Long): Codec[(A, B)]

Codec that supports vectors of the form size ++ prefix ++ value where the size field decodes to the bit length of the value field.

For example, encoding the string (3, "hello") with variableSizePrefixedBitsLong(uint32, int32, ascii) yields a vector of 13 bytes -- the first four bytes being 0x00000028, the next 4 bytes being 0x00000003, and the last 5 bytes being the US-ASCII encoding of "hello".

The size field can be any Long codec. An optional padding can be applied to the size field. The sizePadding is added to the calculated size before encoding, and subtracted from the decoded size before decoding the value.

For example, encoding (3, "hello") with variableSizePrefixedBitsLong(uint32, int32, ascii, 1) yields a vector of 13 bytes -- the first 4 bytes being 0x00000029, the next 4 bytes being 0x00000003, and the last 5 bytes being the US-ASCII encoding of "hello".

Value Params
prefix

codec that encodes/decodes the prefix

size

codec that encodes/decodes the size in bits

sizePadding

number of bits to add to the size before encoding (and subtract from the size before decoding)

value

codec the encodes/decodes the value

def variableSizePrefixedBytesLong[A, B](size: Codec[Long], prefix: Codec[A], value: Codec[B], sizePadding: Long): Codec[(A, B)]

Byte equivalent of variableSizePrefixedBitsLong.

Value Params
prefix

codec that encodes/decodes the prefix

size

codec that encodes/decodes the size in bytes

sizePadding

number of bytes to add to the size before encoding (and subtract from the size before decoding)

value

codec the encodes/decodes the value

def peek[A](target: Codec[A]): Codec[A]

Decodes using the specified codec but resets the remainder to the original vector. Encodes with the specified codec.

Value Params
target

codec that encodes/decodes the value

Returns

codec that behaves the same as target but resets remainder to the input vector after decoding

def byteAligned[A](codec: Codec[A]): Codec[A]

Codec that: - encodes using the specified codec but right-pads with 0 bits to the next largest byte when the size of the encoded bit vector is not divisible by 8 - decodes using the specified codec but drops any leading bits of the remainder when the number of bytes consumed by the specified codec is not divisible by 8

This combinator allows byte alignment without manually specifying ignore bits. For example, instead of writing (bool(1) :: bool(1) :: ignore(6)).dropUnits, this combinator allows byteAligned(bool(1) :: bool(1)).

Note that aligning large structures on byte boundaries can provide significant performance improvements when converting to/from data structures that are based on bytes -- e.g., Array[Byte] or ByteBuffer.

Value Params
codec

codec to align to next larger byte boundary

def conditional[A](included: Boolean, codec: => Codec[A]): Codec[Option[A]]

Codec of Option[A] that delegates to a Codec[A] when the included parameter is true.

When encoding, if included is true and the value to encode is a Some, the specified codec is used to encode the inner value. Otherwise, an empty bit vector is returned.

When decoding, if included is true, the specified codec is used and its result is wrapped in a Some. Otherwise, a None is returned.

Value Params
codec

codec to conditionally include

included

whether this codec is enabled (meaning it delegates to the specified codec) or disabled, in which case it encodes no bits and returns None from decode

def optional[A](guard: Codec[Boolean], target: Codec[A]): Codec[Option[A]]

Codec of Option[A] that delegates to a Codec[A] when the guard codec decodes a true.

When encoding, a Some results in guard encoding a true and target encoding the value. A None results in guard encoding a false and the target not encoding anything.

Various guard codecs and combinators are provided by this library -- e.g., bitsRemaining and recover.

Value Params
guard

codec that determines whether the target codec is included

target

codec to conditionally include

val bitsRemaining: Codec[Boolean]

Codec that decodes true when the input vector is non-empty and false when it is empty. Encodes to an empty bit vector.

def withDefault[A](opt: Codec[Option[A]], default: Codec[A]): Codec[A]

Creates a Codec[A] from a Codec[Option[A]] and a fallback Codec[A].

When encoding, the A is encoded with opt (by wrapping it in a Some). When decoding, opt is first used to decode the buffer. If it decodes a Some(a), that value is returned. If it decodes a None, default is used to decode the buffer.

Value Params
default

fallback codec used during decoding when opt decodes a None

opt

optional codec

def withDefaultValue[A](opt: Codec[Option[A]], default: A): Codec[A]

Creates a Codec[A] from a Codec[Option[A]] and a fallback value A.

When encoding, the A is encoded with opt (by wrapping it in a Some). When decoding, opt is first used to decode the buffer. If it decodes a Some(a), that value is returned. If it decodes a None, the default value is return.

Value Params
default

fallback value returned from decode when opt decodes a None

opt

optional codec

def recover(target: Codec[Unit]): Codec[Boolean]

Creates a codec that decodes true when the target codec decodes successfully and decodes false when the target codec decodes unsuccessfully. Upon a successful decode of the target codec, the remaining bits are returned, whereas upon an unsuccessful decode, the original input buffer is returned.

When encoding, a true results in the target codec encoding a unit whereas a false results in encoding of an empty vector.

Value Params
target

codec to recover errors from

def lookahead(target: Codec[Unit]): Codec[Boolean]

Lookahead version of recover -- i.e., upon successful decoding with the target codec, the original buffer is returned instead of the remaining buffer.

Value Params
target

codec to recover errors from

def choice[A](codecs: Codec[A]*): Codec[A]

Codec that encodes/decodes using the specified codecs by trying each codec in succession and using the first successful result.

def vector[A](codec: Codec[A]): Codec[Vector[A]]

Codec that encodes/decodes a Vector[A] from a Codec[A].

When encoding, each A in the vector is encoded and all of the resulting vectors are concatenated.

When decoding, codec.decode is called repeatedly until there are no more remaining bits and the value result of each decode is returned in the vector.

Value Params
codec

codec to encode/decode a single element of the sequence

def vectorOfN[A](countCodec: Codec[Int], valueCodec: Codec[A]): Codec[Vector[A]]

Codec that encodes/decodes a Vector[A] of N elements using a Codec[A].

When encoding, the number of elements in the vector is encoded using countCodec and the values are then each encoded using valueCodec.

When decoding, the number of elements is decoded using countCodec and then that number of elements are decoded using valueCodec. Any remaining bits are returned.

Note: when the count is known statically, use vectorOfN(provide(count), ...).

Value Params
codec

codec to encode/decode a single element of the sequence

def vectorMultiplexed[A](mux: (BitVector, BitVector) => BitVector, deMux: BitVector => (BitVector, BitVector), valueCodec: Codec[A]): Codec[Vector[A]]

Codec that encodes/decodes a Vector[A] from a Codec[A].

When encoding, each A in the vector is encoded and all of the resulting bits are combined using mux.

When decoding, deMux is called repeatedly to obtain the next bits (to decode using valueCodec) and the remaining bits (input to deMux on next iteration) until a decoding error is encountered or no more bits remain. The final return value is a vector of all decoded element values.

Note: For large vectors, it may be necessary to compact bits in deMux.

Type Params
A

element type

Value Params
deMux

element de-multiplexer (should return the next bits to decode and the remaining bits for next iteration)

mux

element multiplexer

valueCodec

element codec (used to decode next bits)

def vectorDelimited[A](delimiter: BitVector, valueCodec: Codec[A]): Codec[Vector[A]]

Codec that encodes/decodes a Vector[A] from a Codec[A].

When encoding, each A in the vector is encoded and all of the resulting bits are concatenated using delimiter.

When decoding, the input bits are first (logically) grouped into delimiter sized chunks and partitioned around delimiter chunks. Then, the individual partitions are (concatenated and) decoded using the valueCodec and the values collected are returned in a vector.

Note: This method applies specific semantics to the notion of a delimiter. An alternate (and faster) implementation could be to search for the delimiter using BitVector.indexOfSlice but this would work only if value bits do not contain the delimiter bits at any bit position.

Example: {{{ val codec = vectorDelimited(BitVector(' '), ascii) codec.decode(ascii.encode("i am delimited").require).require.value // Vector("i", "am", "delimited") }}}

Type Params
A

element type

Value Params
delimiter

the bits used to separate element bit values

valueCodec

element codec (used to decode next bits)

def list[A](codec: Codec[A]): Codec[List[A]]

Codec that encodes/decodes a List[A] from a Codec[A].

When encoding, each A in the list is encoded and all of the resulting vectors are concatenated.

When decoding, codec.decode is called repeatedly until there are no more remaining bits and the value result of each decode is returned in the list.

Value Params
codec

codec to encode/decode a single element of the sequence

def listOfN[A](countCodec: Codec[Int], valueCodec: Codec[A]): Codec[List[A]]

Codec that encodes/decodes a List[A] of N elements using a Codec[A].

When encoding, the number of elements in the list is encoded using countCodec and the values are then each encoded using valueCodec.

When decoding, the number of elements is decoded using countCodec and then that number of elements are decoded using valueCodec. Any remaining bits are returned.

Note: when the count is known statically, use listOfN(provide(count), ...).

Value Params
codec

codec to encode/decode a single element of the sequence

def listMultiplexed[A](mux: (BitVector, BitVector) => BitVector, deMux: BitVector => (BitVector, BitVector), valueCodec: Codec[A]): Codec[List[A]]

Codec that encodes/decodes a List[A] from a Codec[A].

When encoding, each A in the list is encoded and all of the resulting bits are combined using mux.

When decoding, deMux is called repeatedly to obtain the next bits (to decode using valueCodec) and the remaining bits (input to deMux on next iteration) until a decoding error is encountered or no more bits remain. The final return value is a list of all decoded element values.

Note: For large lists, it may be necessary to compact bits in deMux.

Type Params
A

element type

Value Params
deMux

element de-multiplexer (should return the next bits to decode and the remaining bits for next iteration)

mux

element multiplexer

valueCodec

element codec (used to decode next bits)

def listDelimited[A](delimiter: BitVector, valueCodec: Codec[A]): Codec[List[A]]

Codec that encodes/decodes a List[A] from a Codec[A].

When encoding, each A in the list is encoded and all of the resulting bits are concatenated using delimiter.

When decoding, the input bits are first (logically) grouped into delimiter sized chunks and partitioned around delimiter chunks. Then, the individual partitions are (concatenated and) decoded using the valueCodec and the values collected are returned in a list.

Note: This method applies specific semantics to the notion of a delimiter. An alternate (and faster) implementation could be to search for the delimiter using BitVector.indexOfSlice but this would work only if value bits do not contain the delimiter bits at any bit position.

Example: {{{ val codec = listDelimited(BitVector(' '), ascii) codec.decode(ascii.encode("i am delimited").require).require.value // List("i", "am", "delimited") }}}

Type Params
A

element type

Value Params
delimiter

the bits used to separate element bit values

valueCodec

element codec (used to decode next bits)

def endiannessDependent[A](big: Codec[A], little: Codec[A])(using ordering: ByteOrdering): Codec[A]

Combinator that chooses amongst two codecs based on a given byte ordering.

Value Params
big

codec to use when big endian

little

codec to use when little endian

def either[L, R](indicator: Codec[Boolean], left: Codec[L], right: Codec[R]): Codec[Either[L, R]]

Either codec that supports bit vectors of form indicator ++ (left or right) where a value of false for the indicator indicates it is followed by a left value and a value of true indicates it is followed by a right value.

Value Params
indicator

codec that encodes/decodes false for left and true for right

left

codec the encodes a left value

right

codec the encodes a right value

def fallback[L, R](left: Codec[L], right: Codec[R]): Codec[Either[L, R]]

Either codec that supports bit vectors of form left or right where the right codec is consulted first when decoding. If the right codec fails to decode, the left codec is used.

Value Params
left

codec the encodes a left value

right

codec the encodes a right value

def lazily[A](codec: => Codec[A]): Codec[A]

Provides a Codec[A] that delegates to a lazily evaluated Codec[A].

def fail[A](err: Err): Codec[A]

Codec that always fails encoding and decoding with the specified message.

def fail[A](encErr: Err, decErr: Err): Codec[A]

Codec that always fails encoding and decoding with the specified messages.

def zlib[A](codec: Codec[A], level: Int, strategy: Int, nowrap: Boolean, chunkSize: Int): Codec[A]

Codec that compresses the results of encoding with the specified codec and decompresses prior to decoding with the specified codec.

Compression is performed using ZLIB. There are a number of defaulted parameters that control compression specifics.

Value Params
chunkSize

buffer size, in bytes, to use when compressing

level

compression level, 0-9, with 0 disabling compression and 9 being highest level of compression -- see java.util.zip.Deflater for details

nowrap

if true, ZLIB header and checksum will not be used

strategy

compression strategy -- see java.util.zip.Deflater for details

def filtered[A](codec: Codec[A], filter: Codec[BitVector]): Codec[A]

Codec that filters bits before/after decoding/encoding.

Note: the remainder returned from filter.decode is appended to the remainder of codec.decode.

Value Params
codec

the target codec

filter

a codec that represents pre/post-processing stages for input/output bits

def checksummed[A](target: Codec[A], checksum: BitVector => BitVector, framing: Codec[(BitVector, BitVector)], validate: Boolean): Codec[A]

Codec that supports a checksum.

When encoding, first the value is encoded using target, then a checksum is computed over the result the encoded value using checksum, and finally, the encoded value and the checksum are converted to a single vector using framing.encode(value -> chk).

When decoding, the input vector is split in to an encoded value, a checksum value, and a remainder using framing.decode. If validate is true, a checksum is computed over the encoded value and compared with the decoded checksum value. If the checksums match, the encoded value is decoded with target and the result is returned, with its remainder concatenated with the remainder of deframing. If the checksums do not match, a ChecksumMismatch error is raised.

For example: {{{ val crc32 = scodec.bits.crc(hex"04c11db7".bits, hex"ffffffff".bits, true, true, hex"ffffffff".bits)

 // Size of the string is not included in the checksum -- the `framing` codec handles adding the size *after* checksum computation
 val c = checksummed(utf8, crc32, variableSizeBytes(int32, bits) ~ bits(32))

 // Size of the string is included in the checksum
 val d = checksummed(utf8_32, crc32, peekVariableSizeBytes(int32) ~ bits(32))

}}}

Value Params
checksum

computes a checksum of the input

framing

codec used to convert the encoded value and computed checksum in to a single vector

target

codec used for encoding/decoding values of type A

def encrypted[A](codec: Codec[A], cipherFactory: CipherFactory): Codec[A]

Codec that encrypts and decrypts using a javax.crypto.Cipher.

Encoding a value of type A is delegated to the specified codec and the resulting bit vector is encrypted with a cipher provided by the given CipherFactory.

Decoding first decrypts all of the remaining bits and then decodes the decrypted bits with the specified codec. Successful decoding always returns no remaining bits, even if the specified codec does not consume all decrypted bits.

Value Params
cipherFactory

factory to use for encryption/decryption

codec

codec that encodes a value to plaintext bits and decodes plaintext bits to a value

def fixedSizeSignature[A](size: Int)(codec: Codec[A], signerFactory: SignerFactory): Codec[A]

Codec that includes a signature of the encoded bits.

Encoding a value of type A is delegated to the specified codec and then a signature of those bits is appended using the specified SignatureFactory to perform signing.

Decoding first decodes using the specified codec and then all of the remaining bits are treated as the signature of the decoded bits. The signature is verified and if it fails to verify, an error is returned.

Note: because decoding is first delegated to the specified code, care must be taken to ensure that codec does not consume the signature bits. For example, if the target codec is an unbounded string (e.g., ascii, utf8), decoding an encoded vector will result in the string codec trying to decode the signature bits as part of the string.

Use SignatureFactory or ChecksumFactory to create a SignerFactory.

Value Params
codec

codec to use to encode/decode value field

signatureFactory

factory to use for signing/verifying

size

size in bytes of signature

def variableSizeSignature[A](size: Codec[Int])(codec: Codec[A], signerFactory: SignerFactory): Codec[A]

Codec that includes a signature of the encoded bits.

Same functionality as fixedSizeSignature with one difference -- the size of the signature bytes are written between the encoded bits and the signature bits.

Use SignatureFactory or ChecksumFactory to create a SignerFactory.

Value Params
codec

codec to use to encode/decode value field

signatureFactory

factory to use for signing/verifying

size

codec to use to encode/decode size of signature field

def certificate(certType: String): Codec[Certificate]

Codec that encodes/decodes certificates using their default encoding.

Value Params
certType

certificate type to pass to java.security.cert.CertificateFactory.getInstance

def x509Certificate: Codec[X509Certificate]

Codec that encodes/decodes certificates using their default encoding.

def |(codec: Codec[A]): Codec[A]

Provides the | method on String, which is reverse syntax for codec withContext ctx.

Usage: {{{ val codec = "id" | uint8 }}}

final type ~[+A, +B] = (A, B)

Type alias for Tuple2 in order to allow left nested tuples to be written as A ~ B ~ C ~ ....

object ~ extends Serializable

Extractor that allows pattern matching on the tuples created by tupling codecs.

Provides syntax for building a DiscriminatorCodec.

Usage: {{{ val codecA: Codec[A] = ... val codecB: Codec[B] = ...

val codecE: Codec[Either[A,B]] = discriminated[Either[A,B]].by(uint8) .| (0) { case Left(l) => l } (Left.apply) (codecA) .| (1) { case Right(r) => r } (Right.apply) (codecB) }}}

This encodes an Either[A,B] by checking the given patterns in sequence from top to bottom. For the first pattern that matches, it emits the corresponding discriminator value: 0 for Left and 1 for Right, encoded via the uint8 codec. It then emits either an encoded A, encoded using codecA, or an encoded B, using codecB.

Decoding is the mirror of this; the returned codecE will first read an Int, using the uint8 codec. If it is a 0, it then runs codecA, and injects the result into Either via Left.apply. If it is a 1, it runs codecB and injects the result into Either via Right.apply.

There are a few variations on this syntax. See DiscriminatorCodec for details.

def mappedEnum[A, B](discriminatorCodec: Codec[B], mappings: (A, B)*): DiscriminatorCodec[A, B]

Provides a codec for an enumerated set of values, where each enumerated value is mapped to a tag.

Value Params
discriminatorCodec

codec used to encode/decode tag value

mappings

mapping from tag values to/from enum values

def mappedEnum[A, B](discriminatorCodec: Codec[B], map: Map[A, B]): DiscriminatorCodec[A, B]

Provides a codec for an enumerated set of values, where each enumerated value is mapped to a tag.

Value Params
discriminatorCodec

codec used to encode/decode tag value

map

mapping from tag values to/from enum values

def discriminatorFallback[L, R](left: Codec[L], right: Codec[R]): Codec[Either[L, R]]

Alternative to fallback that only falls back to left codec when the right codec fails to decode due to an unknown discriminator (i.e., KnownDiscriminatorType[_]#UnknownDiscriminator).

Value Params
left

codec to use when the right codec fails due to an unknown discriminator error

right

codec to use by default when decoding

def logBuilder[A](logEncode: (A, Attempt[BitVector]) => Unit, logDecode: (BitVector, Attempt[DecodeResult[A]]) => Unit)(codec: Codec[A]): Codec[A]

Wraps a codec and adds logging of each encoding and decoding operation.

The logEncode and logDecode functions are called with the result of each encoding and decoding operation.

This method is intended to be used to build a domain specific logging combinator. For example: {{{ def log[A] = logBuilder[A]((a, r) => myLogger.debug(s"..."), (b, r) => myLogger.debug(s"...")) _ ... log(myCodec) }}}

For quick logging to standard out, consider using logFailuresToStdOut.

def logSuccessesBuilder[A](logEncode: (A, BitVector) => Unit, logDecode: (BitVector, DecodeResult[A]) => Unit)(codec: Codec[A]): Codec[A]

Variant of logBuilder that only logs successful results.

def logFailuresBuilder[A](logEncode: (A, Err) => Unit, logDecode: (BitVector, Err) => Unit)(codec: Codec[A]): Codec[A]

Variant of logBuilder that only logs failed results.

def logToStdOut[A](codec: Codec[A], prefix: String): Codec[A]

Combinator intended for use in debugging that logs all encoded values and decoded values to standard out.

Value Params
prefix

prefix string to include in each log statement

def logFailuresToStdOut[A](codec: Codec[A], prefix: String): Codec[A]

Combinator intended for use in debugging that logs all failures while encoding or decoding to standard out.

Value Params
prefix

prefix string to include in each log statement

def constrainedVariableSizeBytes[A](size: Codec[Int], value: Codec[A], minSize: Int, maxSize: Int): Codec[A]

Codec that ensures variable size data is constrained within a minSize and maxSize bounds.

This means that the size is variable only within a limited range. It will work just as variableSizeBytes codec, but ensuring that the binary data is at least minSize bytes long and at most maxSize bytes long.

The minSize has the default value of 0.

Value Params
maxSize

maximum size in bytes that the message can have

minSize

minimum size in bytes that the message can have

size

codec that encodes/decodes the size in bits

value

codec the encodes/decodes the value

def constrainedVariableSizeBytesLong[A](size: Codec[Long], value: Codec[A], minSize: Long, maxSize: Long): Codec[A]

Codec that ensures variable size data is constrained within a minSize and maxSize bounds.

This means that the size is variable only within a limited range. It will work just as variableSizeBytes codec, but ensuring that the binary data is at least minSize bytes long and at most maxSize bytes long.

The minSize has the default value of 0.

Value Params
maxSize

maximum size in bytes that the message can have

minSize

minimum size in bytes that the message can have

size

codec that encodes/decodes the size in bits

value

codec the encodes/decodes the value

def constrainedVariableSizeBytes[A](size: Codec[Int], value: Codec[A], maxSize: Int): Codec[A]

Codec that ensures variable size data is constrained within a minSize and maxSize bounds.

This means that the size is variable only within a limited range. It will work just as variableSizeBytes codec, but ensuring that the binary data is at least minSize bytes long and at most maxSize bytes long.

The minSize has the default value of 0.

Value Params
maxSize

maximum size in bytes that the message can have

size

codec that encodes/decodes the size in bits

value

codec the encodes/decodes the value

def constrainedVariableSizeBytesLong[A](size: Codec[Long], value: Codec[A], maxSize: Long): Codec[A]

Codec that ensures variable size data is constrained within a minSize and maxSize bounds.

This means that the size is variable only within a limited range. It will work just as variableSizeBytes codec, but ensuring that the binary data is at least minSize bytes long and at most maxSize bytes long.

The minSize has the default value of 0.

Value Params
maxSize

maximum size in bytes that the message can have

size

codec that encodes/decodes the size in bits

value

codec the encodes/decodes the value

Value members

Methods

def enumerated(discriminator: Codec[Int], enumeration: Enumeration): DiscriminatorCodec[Value, Int]

Codec for an Enumeration that encodes/decodes using Enumeration.Value.id values.

Value Params
discriminator

the codec for Enumeration.Value.id values

enumeration

the target Enumeration

def peekVariableSizeBits(size: Codec[Int], sizePadding: Int): Codec[BitVector]

Codec that decodes vectors of the form size ++ rest as a BitVector, where the returned vector includes the size bits.

This differs from variableSizeBits(size, bits, sizePadding) in that the encoded size is expected to be encoded before calling encode and the encoded size is returned as part of the vector.

Value Params
size

size codec -- must have an exact size

sizePadding

number of bits to subtract from the size before decoding

def peekVariableSizeBitsLong(size: Codec[Long], sizePadding: Long): Codec[BitVector]

Long equivalent of peekVariableSizeBits.

Value Params
size

size codec -- must have an exact size

sizePadding

number of bits to subtract from the size before decoding

def peekVariableSizeBytes(size: Codec[Int], sizePadding: Int): Codec[BitVector]

Equivalent to peekVariableSizeBits where the size units are in bytes instead of bits.

Value Params
size

size codec -- must have an exact size

sizePadding

number of bytes to subtract from the size before decoding

def peekVariableSizeBytesLong(size: Codec[Long], sizePadding: Long): Codec[BitVector]

Long equivalent of peekVariableSizeBytes.

Value Params
size

size codec -- must have an exact size

sizePadding

number of bits to subtract from the size before decoding