scodec.codecs
package scodec.codecs
Document{}
Codec that supports the binary structure
the value.
tag ++ value
where the tag
identifies the encoding/decoding ofthe value.
To build an instance of this codec, call discriminated and specify the tag type via the
call one more more of the case combinators on this class.
by
method. Thencall one more more of the case combinators on this class.
The most general case combinators are
In addition to a tag, the
mapping from
The
caseO
and caseP
.In addition to a tag, the
caseO
combinator is defined by providing a mapping fromA
to Option[R]
, a mapping from R
to A
, and a Codec[R]
. The case is used for encoding if themapping 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, thesubcaseO
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
to the
that encodes a 0 if passed a
{{{
discriminated[AnyVal] .by(uint8).typecase(0, bool).typecase(1, int32)
}}}
typecase
combinators which add further constraintsto the
subcase*
combinators. Specifically, the typecase operators omit the A => Option[R]
orPartialFunction[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) })`.- Value Params
- by
-
codec that encodec/decodes the tag value
- cases
-
cases, ordered from highest priority to lowest priority, that handle subsets of
A
- See also
trait Signer
Represents the ability to create a "checksum" for use with fixedSizeSignature and variableSizeSignature.
trait SignerFactory
Represents the ability to create a Signer for use with fixedSizeSignature and variableSizeSignature.
Provides the
|
method on String
, which is reverse syntax for codec withContext ctx
.Usage:
{{{
val codec = "id" | uint8
}}}
{{{
val codec = "id" | uint8
}}}
String codec that uses the
in a 32-bit 2s complement big endian field.
US-ASCII
charset and prefixes the encoded string by the byte sizein a 32-bit 2s complement big endian field.
String codec that uses the
in a 32-bit 2s complement little endian field.
US-ASCII
charset and prefixes the encoded string by the byte sizein a 32-bit 2s complement little endian field.
Encodes by returning supplied bit vector; decodes by taking all remaining bits in the supplied bit vector.
Encodes by returning the supplied bit vector if its length is
decodes by taking
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
Codec that decodes true when the input vector is non-empty and false when it is empty.
Encodes to an empty bit vector.
Encodes to an empty bit vector.
Encodes by returning the supplied bit vector if its length is
decodes by taking
size
bits, otherwise returning error;decodes by taking
size
bits from the supplied bit vector.- Value Params
- size
-
number of bits to encode/decode
n-bit boolean codec, where false corresponds to bit vector of all 0s and true corresponds to all other vectors.
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
- 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.,
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
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.
Encodes by returning the supplied byte vector if its length is
decodes by taking
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
Encodes by returning the supplied byte vector if its length is
decodes by taking
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
Codec that encodes/decodes certificates using their default encoding.
- Value Params
- certType
-
certificate type to pass to
java.security.cert.CertificateFactory.getInstance
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
and finally, the encoded value and the checksum are converted to a single vector 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
If
match, the encoded value is decoded with
deframing. If the checksums do not match, a
framing.decode
.If
validate
is true, a checksum is computed over the encoded value and compared with the decoded checksum value. If the checksumsmatch, the encoded value is decoded with
target
and the result is returned, with its remainder concatenated with the remainder ofdeframing. 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)
{{{
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
Codec that encodes/decodes using the specified codecs by trying each codec in succession
and using the first successful result.
and using the first successful result.
Codec of
Option[A]
that delegates to a Codec[A]
when the included
parameter is true.When encoding, if
Otherwise, an empty bit vector is returned.
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 returnsNone
from decode
Codec that always encodes the specified bits and always decodes the specified bits, returning
the specified bits and returning an error otherwise.
()
if the actual bits matchthe specified bits and returning an error otherwise.
- Value Params
- bits
-
constant bits
Codec that always encodes the specified bytes and always decodes the specified bytes, returning
the specified bytes and returning an error otherwise.
()
if the actual bytes matchthe specified bytes and returning an error otherwise.
- Value Params
- bytes
-
constant bytes
Codec that always encodes the specified bits and always decodes the specified bits, returning
the specified bits and returning an error otherwise.
()
if the actual bits matchthe specified bits and returning an error otherwise.
- Value Params
- bits
-
constant bits
Codec that always encodes the specified bits and always decodes n bits, returning
specified bits.
()
, where n is the length of thespecified bits.
- Value Params
- bits
-
constant bits
Codec that always encodes the specified bytes and always decodes n bytes, returning
specified bytes.
()
, where n is the length of thespecified bytes.
- Value Params
- bytes
-
constant bytes
Codec that always encodes the specified bits and always decodes n bits, returning
specified bits.
()
, where n is the length of thespecified bits.
- Value Params
- bits
-
constant bits
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
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
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
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], 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
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], 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
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
String codec that uses the
and decodes a string up to the next
It fails to decode if the bit vector ends before a
US-ASCII
charset that encodes strings with a trailing NUL
termination byteand 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.Provides syntax for building a DiscriminatorCodec.
Usage:
{{{
val codecA: Codec[A] = ...
val codecB: Codec[B] = ...
{{{
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)
}}}
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
in sequence from top to bottom. For the first pattern that matches,
it emits the corresponding discriminator value:
and
either an encoded
using
Either[A,B]
by checking the given patternsin 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 emitseither an encoded
A
, encoded using codecA
, or an encoded B
,using
codecB
.Decoding is the mirror of this; the returned
read an
runs
If it is a
via
codecE
will firstread an
Int
, using the uint8
codec. If it is a 0
, it thenruns
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.
Alternative to fallback that only falls back to left codec when the right codec fails to decode
due to an unknown discriminator (i.e.,
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
Either codec that supports bit vectors of form
value of
of
indicator ++ (left or right)
where avalue of
false
for the indicator indicates it is followed by a left value and a valueof
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
Codec that encrypts and decrypts using a
javax.crypto.Cipher
.Encoding a value of type
with a cipher provided by the implicit CipherFactory.
A
is delegated to the specified codec and the resulting bit vector is encryptedwith 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.
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
Combinator that chooses amongst two codecs based on an implicitly available byte ordering.
- Value Params
- big
-
codec to use when big endian
- little
-
codec to use when little endian
Either codec that supports bit vectors of form
is consulted first when decoding. If the right codec fails to decode, the left codec
is used.
left or right
where the right codecis 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
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
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.
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
given, any remaining bits are discarded.
size
bits. If the specified codec does not consume all the bits it wasgiven, any remaining bits are discarded.
- Value Params
- codec
-
codec to limit
- size
-
number of bits
Codec that includes a signature of the encoded bits.
Encoding a value of type
appended using the specified SignatureFactory to perform signing.
A
is delegated to the specified codec and then a signature of those bits isappended 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.
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.
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.
- Value Params
- codec
-
codec to use to encode/decode value field
- signatureFactory
-
factory to use for signing/verifying
- size
-
size in bytes of signature
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
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)
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)
Allows use of a 2-arg function as a single arg function that takes a left-associated stack of pairs with 2 total elements.
Allows use of a 3-arg function as a single arg function that takes a left-associated stack of pairs with 3 total elements.
final implicit def liftF4ToNestedTupleF[A, B, C, D, X](fn: (A, B, C, D) => X): (((A, B), C), D) => X
Allows use of a 4-arg function as a single arg function that takes a left-associated stack of pairs with 4 total elements.
final implicit def liftF5ToNestedTupleF[A, B, C, D, E, X](fn: (A, B, C, D, E) => X): ((((A, B), C), D), E) => X
Allows use of a 5-arg function as a single arg function that takes a left-associated stack of pairs with 5 total elements.
final implicit def liftF6ToNestedTupleF[A, B, C, D, E, F, X](fn: (A, B, C, D, E, F) => X): (((((A, B), C), D), E), F) => X
Allows use of a 6-arg function as a single arg function that takes a left-associated stack of pairs with 6 total elements.
final implicit def liftF7ToNestedTupleF[A, B, C, D, E, F, G, X](fn: (A, B, C, D, E, F, G) => X): ((((((A, B), C), D), E), F), G) => X
Allows use of a 7-arg function as a single arg function that takes a left-associated stack of pairs with 7 total elements.
final implicit def liftF8ToNestedTupleF[A, B, C, D, E, F, G, H, X](fn: (A, B, C, D, E, F, G, H) => X): (((((((A, B), C), D), E), F), G), H) => X
Allows use of an 8-arg function as a single arg function that takes a left-associated stack of pairs with 8 total elements.
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
size.
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 specifiedsize.
When decoding, the specified codec is only given
given, any remaining bits are returned with the overall remainder.
size
bits. If the specified codec does not consume all the bits it wasgiven, any remaining bits are returned with the overall remainder.
- Value Params
- codec
-
codec to limit
- size
-
number of bits
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,
of each
codec.decode
is called repeatedly until there are no more remaining bits and the value resultof each
decode
is returned in the list.- Value Params
- codec
-
codec to encode/decode a single element of the sequence
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
Then, the individual partitions are (concatenated and) decoded using the
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
for the
any bit position.
delimiter
. An alternate (and faster) implementation could be to searchfor the
delimiter
using BitVector.indexOfSlice
but this would work only if value bits do not contain the delimiter
bits atany bit position.
Example:
{{{
val codec = listDelimited(BitVector(' '), ascii)
codec.decode(ascii.encode("i am delimited").require).require.value // List("i", "am", "delimited")
}}}
{{{
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 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,
remaining bits (input to
The final return value is a list of all decoded element values.
deMux
is called repeatedly to obtain the next bits (to decode using valueCodec
) and theremaining 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)
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
and the values are then each encoded using
countCodec
and the values are then each encoded using
valueCodec
.When decoding, the number of elements is decoded using
are decoded using
countCodec
and then that number of elementsare 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 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
operation.
logEncode
and logDecode
functions are called with the result of each encoding and decodingoperation.
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)
}}}
{{{
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 logFailuresBuilder[A](logEncode: (A, Err) => Unit, logDecode: (BitVector, Err) => Unit)(codec: Codec[A]): Codec[A]
Variant of logBuilder that only logs failed results.
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 logSuccessesBuilder[A](logEncode: (A, BitVector) => Unit, logDecode: (BitVector, DecodeResult[A]) => Unit)(codec: Codec[A]): Codec[A]
Variant of logBuilder that only logs successful results.
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
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)
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)
Lookahead version of recover -- i.e., upon successful decoding with the target codec,
the original buffer is returned instead of the remaining buffer.
the original buffer is returned instead of the remaining buffer.
- Value Params
- target
-
codec to recover errors from
Codec for n-nibble packed decimal (BCD) integers that are represented with
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.
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)
Provides a codec for an enumerated set of values, where each enumerated value is
mapped to a tag.
mapped to a tag.
- Value Params
- discriminatorCodec
-
codec used to encode/decode tag value
- mappings
-
mapping from tag values to/from enum values
Provides a codec for an enumerated set of values, where each enumerated value is
mapped to a tag.
mapped to a tag.
- Value Params
- discriminatorCodec
-
codec used to encode/decode tag value
- map
-
mapping from tag values to/from enum values
Codec of
Option[A]
that delegates to a Codec[A]
when the guard
codec decodes a true.When encoding, a
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
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.
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.
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
given, all remaining bits are repeatedly decoded by padCodec. A decoding error is returned if any
padCodec decode returns an error.
size
bits. If the specified codec does not consume all the bits it wasgiven, 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.
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
An encoding error is returned if the padCodec result does not precisely fill the remaining space.
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
given, all remaining bits are repeatedly decoded by the codec returned from
A decoding error is returned if any padding decode iteration returns an error.
size
bits. If the specified codec does not consume all the bits it wasgiven, 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
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
Codec for n-nibble packed decimal (BCD) integers that are represented with
Long
.- Value Params
- nibbles
-
number of nibbles (4-bit chunks)
Decodes using the specified codec but resets the remainder to the original vector.
Encodes with the specified codec.
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
Codec that always returns an empty vector from
This is often useful when combined with other codecs (e.g., the discriminated).
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
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 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.
in encoding of an empty vector.
- Value Params
- target
-
codec to recover errors from
Codec for n-bit 2s complement big-endian shorts.
- Value Params
- size
-
number of bits (must be 0 < size <= 16)
Codec for n-bit 2s complement little-endian shorts.
- Value Params
- size
-
number of bits (must be 0 < size <= 16)
String codec that uses the implicit
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)
}}}
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
String codec that uses the implicit
in a 32-bit 2s complement big endian field.
Charset
and prefixes the encoded string by the byte sizein a 32-bit 2s complement big endian field.
- Value Params
- charset
-
charset to use to convert strings to/from binary
String codec that uses the implicit
in a 32-bit 2s complement little endian field.
Charset
and prefixes the encoded string by the byte sizein a 32-bit 2s complement little endian field.
- Value Params
- charset
-
charset to use to convert strings to/from binary
Codec for n-bit unsigned big-endian integers that are represented with
Int
.- Value Params
- bits
-
number of bits (must be 0 < size <= 31)
Codec for n-bit unsigned little-endian integers that are represented with
Int
.- Value Params
- bits
-
number of bits (must be 0 < size <= 31)
Codec for n-bit unsigned big-endian integers that are represented with
Long
.- Value Params
- bits
-
number of bits (must be 0 < size <= 63)
Codec for n-bit unsigned little-endian integers that are represented with
Long
.- Value Params
- bits
-
number of bits (must be 0 < size <= 63)
Codec for n-bit unsigned big-endian shorts.
- Value Params
- size
-
number of bits (must be 0 < size <= 15)
Codec for n-bit unsigned little-endian shorts.
- Value Params
- size
-
number of bits (must be 0 < size <= 15)
String codec that uses the
in a 32-bit 2s complement big endian field.
UTF-8
charset and prefixes the encoded string by the byte sizein a 32-bit 2s complement big endian field.
String codec that uses the
in a 32-bit 2s complement little endian field.
UTF-8
charset and prefixes the encoded string by the byte sizein a 32-bit 2s complement little endian field.
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
0x28 and the next 5 bytes being the US-ASCII encoding of
"hello"
with variableSizeBits(uint8, ascii)
yields a vector of 6 bytes -- the first byte being0x28 and the next 5 bytes being the US-ASCII encoding of
"hello"
.The
the calculated size before encoding, and subtracted from the decoded size before decoding the value.
size
field can be any Int
codec. An optional padding can be applied to the size field. The sizePadding
is added tothe calculated size before encoding, and subtracted from the decoded size before decoding the value.
For example, encoding
0x29 and the next 5 bytes being the US-ASCII encoding of
"hello"
with variableSizeBits(uint8, ascii, 1)
yields a vector of 6 bytes -- the first byte being0x29 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
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
0x00000028 and the next 5 bytes being the US-ASCII encoding of
"hello"
with variableSizeBitsLong(uint32, ascii)
yields a vector of 9 bytes -- the first four bytes being0x00000028 and the next 5 bytes being the US-ASCII encoding of
"hello"
.The
the calculated size before encoding, and subtracted from the decoded size before decoding the value.
size
field can be any Long
codec. An optional padding can be applied to the size field. The sizePadding
is added tothe calculated size before encoding, and subtracted from the decoded size before decoding the value.
For example, encoding
0x00000029 and the next 5 bytes being the US-ASCII encoding of
"hello"
with variableSizeBitsLong(uint32, ascii, 1)
yields a vector of 9 bytes -- the first 4 bytes being0x00000029 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
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
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
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
0x28, the next 4 bytes being 0x00000003, and the last 5 bytes being the US-ASCII encoding of
(3, "hello")
with variableSizePrefixedBits(uint8, int32, ascii)
yields a vector of 10 bytes -- the first byte being0x28, the next 4 bytes being 0x00000003, and the last 5 bytes being the US-ASCII encoding of
"hello"
.The
the calculated size before encoding, and subtracted from the decoded size before decoding the value.
size
field can be any Int
codec. An optional padding can be applied to the size field. The sizePadding
is added tothe calculated size before encoding, and subtracted from the decoded size before decoding the value.
For example, encoding
0x29, the next 4 bytes being 0x00000003, and the last 5 bytes being the US-ASCII encoding of
(3, "hello")
with variableSizePrefixedBits(uint8, int32, ascii, 1)
yields a vector of 10 bytes -- the first byte being0x29, 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 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
first four bytes being 0x00000028, the next 4 bytes being 0x00000003, and the last 5 bytes being the US-ASCII encoding of
(3, "hello")
with variableSizePrefixedBitsLong(uint32, int32, ascii)
yields a vector of 13 bytes -- thefirst four bytes being 0x00000028, the next 4 bytes being 0x00000003, and the last 5 bytes being the US-ASCII encoding of
"hello"
.The
the calculated size before encoding, and subtracted from the decoded size before decoding the value.
size
field can be any Long
codec. An optional padding can be applied to the size field. The sizePadding
is added tothe calculated size before encoding, and subtracted from the decoded size before decoding the value.
For example, encoding
4 bytes being 0x00000029, the next 4 bytes being 0x00000003, and the last 5 bytes being the US-ASCII encoding of
(3, "hello")
with variableSizePrefixedBitsLong(uint32, int32, ascii, 1)
yields a vector of 13 bytes -- the first4 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 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 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 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.
written between the encoded bits and the signature bits.
- 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
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,
of each
codec.decode
is called repeatedly until there are no more remaining bits and the value resultof each
decode
is returned in the vector.- Value Params
- codec
-
codec to encode/decode a single element of the sequence
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
Then, the individual partitions are (concatenated and) decoded using the
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
for the
any bit position.
delimiter
. An alternate (and faster) implementation could be to searchfor the
delimiter
using BitVector.indexOfSlice
but this would work only if value bits do not contain the delimiter
bits atany bit position.
Example:
{{{
val codec = vectorDelimited(BitVector(' '), ascii)
codec.decode(ascii.encode("i am delimited").require).require.value // Vector("i", "am", "delimited")
}}}
{{{
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 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,
remaining bits (input to
The final return value is a vector of all decoded element values.
deMux
is called repeatedly to obtain the next bits (to decode using valueCodec
) and theremaining 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)
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
and the values are then each encoded using
countCodec
and the values are then each encoded using
valueCodec
.When decoding, the number of elements is decoded using
are decoded using
countCodec
and then that number of elementsare 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
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.
Encoding requires between 1 and 5 bytes, depending on the value.
Smaller ints require less bytes. Negative values are always encoded with 5 bytes.
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.
Encoding requires between 1 and 5 bytes, depending on the value.
Smaller ints require less bytes. Negative values are always encoded with 5 bytes.
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.
Encoding requires between 1 and 9 bytes, depending on the value.
Smaller longs require less bytes.
Negative values are not supported.
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.
Encoding requires between 1 and 9 bytes, depending on the value.
Smaller longs require less bytes.
Negative values are not supported.
Creates a
Codec[A]
from a Codec[Option[A]]
and a fallback Codec[A]
.When encoding, the
When decoding,
value is returned. If it decodes a
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)
, thatvalue 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 aNone
- opt
-
optional codec
Creates a
Codec[A]
from a Codec[Option[A]]
and a fallback value A
.When encoding, the
When decoding,
value is returned. If it decodes a
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)
, thatvalue is returned. If it decodes a
None
, the default
value is return.- Value Params
- default
-
fallback value returned from
decode
whenopt
decodes aNone
- opt
-
optional codec
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
Type members
Classlikes
object ChecksumCodec
Provides methods to create a "checksum codec" (encodes a bit-range to a bit-checksum and decodes bits to a bit-range).
case class ChecksumMismatch(bits: BitVector, expected: BitVector, actual: BitVector, context: List[String]) extends Err
Indicates a checksum over
bits
did not match the expected value.Value members
Methods
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
Codec that decodes vectors of the form
size ++ rest
as a BitVector
, where the returned vector includes the size bits.This differs from
calling encode and the encoded size is returned as part of the vector.
variableSizeBits(size, bits, sizePadding)
in that the encoded size is expected to be encoded beforecalling 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
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
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
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