scodec.codecs

Used in conjunction with encrypted. Typically provided implicitly to all encryption codecs in a larger codec.

To build an instance of this codec, call discriminated and specify the tag type via the by method. Then
call one more more of the case combinators on this class.

The most general case combinators are caseO and caseP.
In addition to a tag, the caseO combinator is defined by providing a mapping from
A to Option[R], a mapping from R to A, and a Codec[R]. The case is used for encoding if the
mapping from A to Option[R] returns a Some and it is used for decoding upon matching the tag value.
The caseP combinators work the same but take a PartialFunction[A, R] instead of an A => Option[R].

If R is a subtype of A, then the mapping from R to A can be omitted. Hence, the
subcaseO and subcaseP constrain R to being a subtype of A and do not take a R => A function.

Finally, the least generic case combinators are the typecase combinators which add further constraints
to the subcase* combinators. Specifically, the typecase operators omit the A => Option[R] or
PartialFunction[A, R] in favor of doing subtype checks. For example, the following codec is a Codec[AnyVal]
that encodes a 0 if passed a Boolean and a 1 if passed an Int:
{{{
discriminated[AnyVal] .by(uint8).typecase(0, bool).typecase(1, int32)
}}}

Often, the values are size-delimited -- that is, there is a size field after the tag field and before the value field. To support this, use the framing method to provide a transformation to each value codec. For example, framing(new CodecTransformation { def apply[X] (c: Codec[X] ) = variableSizeBytes(uint8, c) })`.

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

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.

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))

}}}

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.

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.

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.

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.

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.

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.

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 implicit 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.

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

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.

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.

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.

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.

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")
}}}

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.

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), ...).

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.

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.

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.

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.

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

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

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

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)
}}}

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".

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".

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".

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".

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.

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.

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")
}}}

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.

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), ...).

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.

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.

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

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.