codecs
Indicates a checksum over bits did not match the expected value.
Represents the ability to create a Cipher for encryption or decryption.
Represents the ability to create a Cipher for encryption or decryption.
Used in conjunction with encrypted. Typically provided implicitly to all encryption codecs in a larger codec.
Witness that a coproduct codec builder of type A can be automatically created.
Witness for CoproductCodecBuilder#NeedDiscriminators#auto.
Witness for CoproductCodecBuilder#NeedDiscriminators#using.
Supports building a coproduct codec.
Supports building a coproduct codec.
A coproduct codec is built by:
:+: operatorchoice combinator to create
a codec that encodes no discriminator and hence, decodes by trying each codec in succession and using
the first successful resultTo specify the discriminator, call either discriminatedByIndex(intCodec) or discriminatedBy(codec) followed by
one of the methods on NeedDiscriminators. The former uses the type index as the discriminator value.
For example:
(int32 :+: bool(8) :+: variableSizeBytes(uint8, ascii)).discriminatedByIndex(uint8)The first 8 bits of the resulting binary contains the discriminator value due to usage of the uint8 codec as
the discriminator codec. A discriminator value of 0 causes the remaining bits to be encoded/decoded with int32.
Similarly, a value of 1 causes the remaining bits to be encoded/decoded with bool(8) and a value of 2 causes
the remaining bits to be encoded/decoded as a sized ASCII string.
Alternatively, discriminator values can be explicitly specified using discriminatedBy(codec).using(Sized(...)).
For example:
(int32 :+: bool(8) :+: variableSizeBytes(uint8, ascii)).discriminatedBy(fixedSizeBytes(1, ascii)).using(Sized("i", "b", "s"))
In this example, integers are associated with the discriminator i, booleans with b, and strings with s. The discriminator
is encoded with fixedSizeBytes(1, ascii).
The methods which generate a Codec return a Codec[R] instead of a Codec[C]. Typically, C =:= R but the xmap and
exmap methods allow transformations between C and R to be deferred until after the codec is built.
coproduct type
hlist type that has a codec for each type in the coproduct C
resulting codec type
Provides syntax support for Codec[L]#derive for some HList L.
Provides syntax support for Codec[L]#derive for some HList L. See derive for more information.
Wrapper class that indicates subtypes of X are discriminated by type D
using the supplied Codec[D].
Wrapper class that indicates subtypes of X are discriminated by type D
using the supplied Codec[D].
For example, an implicit Discriminated value can be defined in the companion
of a sealed trait, along with implicit Discriminator values in each subtype
companion. Given such implicits, a codec for the trait can be automatically
derived using Codec[X].
Contains an optional codec transformation, which is applied to every component codec before encoding/decoding. This allows common structure, e.g., size based framing, to be specified in one location.
For example, if each discriminated subtype is prefixed by a size field, the framing could be specified as:
Discriminated[X, D](uint, new CodecTransformation { def apply[Z](c: Codec[Z]) = variableSizeBytes(uint16, c) })
type that can be discriminated by discriminator values of type D
value type that discriminates Y in context of X from other types
using discriminators of D for some type Y
Wrapper class that discriminates type Y in context of type X with a
value of type D.
Wrapper class that discriminates type Y in context of type X with a
value of type D.
For example, consider a sealed trait and its subclasses. Each subclass
could be assigned an integer by defining a Discriminator[Parent, Subclass, Int]
for each.
context in which type Y is discriminated from other types
type that is differentiated from other types by values of D
value type that discriminates values of Y from other types in context of X
Codec that supports the binary structure tag ++ value where the tag identifies the encoding/decoding of
the value.
Codec that supports the binary structure tag ++ value where the tag identifies the encoding/decoding of
the value.
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.
Each of the case combinators provides two forms, one that defines a case with a single tag value and another, overloaded form that defines a case with a tag value to use in encoding and a predicate on tag value to use in decoding.
The most general case combinators are caseO and caseP (and their operator equivalents, ? and |).
In addition to a tag or tag/predicate pair, the caseO combinators are 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 (and the operator equivalents, / and \) 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) }).
Describes an isomorphism between two HLists, K and L, where L has the same shape as K except unit
values have been removed.
Low priority implicits for DropUnits.
Type level operation on type A which flattens left unflattened pairs in to an hlist and vice versa.
Type level operation on type A which flattens left unflattened pairs in to an hlist and vice versa.
That is, the flatten method converts a (((A, B), C), D) in to a A :: B :: C :: D :: HNil and
the unflatten method does the inverse.
Provides implicit codecs for common types.
Provides implicit codecs for collection types.
Provides implicit codecs for simple value types.
Similar to Shapeless's remove support for HLists but supports inverting the removal.
Mixin for codecs/decoders that are known to discriminate by values of type D.
A trait that enables custom handling for encoding/decoding sequences.
Supports creation of a DiscriminatorCodec.
Supports creation of a DiscriminatorCodec. See discriminated for details.
Signer implementation for java.security.Signature
Represents the ability to create a "checksum" for use with fixedSizeSignature and variableSizeSignature.
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.
Provides the | method on String, which is reverse syntax for codec withContext ctx.
Usage:
val codec = "id" | uint8
Witness that allows converting an HList of codecs in to a list of coproduct codecs, where the coproduct is type aligned with the HList.
Converts an HList of codecs in to a single codec.
Converts an HList of codecs in to a single codec.
That is, converts Codec[X0] :: Codec[X1] :: ... :: Codec[Xn] :: HNil in to a Codec[X0 :: X1 :: ... :: Xn :: HNil].
Allows creation of left nested pairs by successive usage of ~ operator.
Type alias for Tuple2 in order to allow left nested tuples to be written as A ~ B ~ C ~ ....
Provides methods to create a "checksum codec" (encodes a bit-range to a bit-checksum and decodes bits to a bit-range).
Creates checksum implementations of SignerFactory.
Companion for CipherFactory.
Companion for CoproductBuilderAuto.
Companion for CoproductBuilderAutoDiscriminators.
Companion for CoproductBuilderKeyDiscriminators.
Companion for CoproductCodecBuilder.
Companion for DeriveHListElementAux.
Companion for Discriminated.
Companion for DropUnits.
Companion for FlattenLeftPairs.
Companion for InvertibleRemove.
Create java.security.Signature implementations for SignerFactory
Companion for ToCoproductCodecs.
Companion for ToHListCodec.
String codec that uses the US-ASCII charset.
String codec that uses the US-ASCII charset. See string for more information on String codecs.
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.
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.
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.
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.
number of bits to encode/decode
Encodes by returning supplied bit vector; decodes by taking all remaining bits in the supplied bit vector.
Codec that decodes true when the input vector is non-empty and false when it is empty.
Codec that decodes true when the input vector is non-empty and false when it is empty. Encodes to an empty bit vector.
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.
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.
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.
1-bit boolean codec, where false corresponds to bit value 0 and true corresponds to bit value 1.
Codec for n-bit 2s complement bytes.
Codec for n-bit 2s complement bytes.
number of bits (must be 0 < size <= 8)
Codec for 8-bit 2s complement bytes.
Codec that:
Codec that:
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.
codec to align to next larger byte boundary
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.
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.
number of bits to encode/decode
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 size bytes, otherwise returning error;
decodes by taking size * 8 bits from the supplied bit vector and converting to a byte vector.
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.
number of bits to encode/decode
Codec that encodes/decodes certificates using their default encoding.
Codec that encodes/decodes certificates using their default encoding.
certificate type to pass to java.security.cert.CertificateFactory.getInstance
Codec that supports a checksum.
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))
codec used for encoding/decoding values of type A
computes a checksum of the input
codec used to convert the encoded value and computed checksum in to a single vector
Codec that encodes/decodes using the specified codecs by trying each codec in succession and using the first successful result.
Codec of Option[A] that delegates to a Codec[A] when the included parameter is true.
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.
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
codec to conditionally include
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.
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.
constant bits
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.
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.
constant bytes
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.
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.
constant bits
Codec that always encodes the specified bits and always decodes n bits, returning (), where n is the length of the
specified bits.
Codec that always encodes the specified bits and always decodes n bits, returning (), where n is the length of the
specified bits.
constant bits
Codec that always encodes the specified bytes and always decodes n bytes, returning (), where n is the length of the
specified bytes.
Codec that always encodes the specified bytes and always decodes n bytes, returning (), where n is the length of the
specified bytes.
constant bytes
Codec that always encodes the specified bits and always decodes n bits, returning (), where n is the length of the
specified bits.
Codec that always encodes the specified bits and always decodes n bits, returning (), where n is the length of the
specified bits.
constant bits
Codec that ensures variable size data is constrained within a minSize and maxSize bounds.
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.
codec that encodes/decodes the size in bits
codec the encodes/decodes the value
maximum size in bytes that the message can have
Codec that ensures variable size data is constrained within a minSize and maxSize bounds.
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.
codec that encodes/decodes the size in bits
codec the encodes/decodes the value
minimum size in bytes that the message can have
maximum size in bytes that the message can have
Codec that ensures variable size data is constrained within a minSize and maxSize bounds.
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.
codec that encodes/decodes the size in bits
codec the encodes/decodes the value
maximum size in bytes that the message can have
Codec that ensures variable size data is constrained within a minSize and maxSize bounds.
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.
codec that encodes/decodes the size in bits
codec the encodes/decodes the value
minimum size in bytes that the message can have
maximum size in bytes that the message can have
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.
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.
Provides syntax for building a DiscriminatorCodec.
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.
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).
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).
codec to use when the right codec fails due to an unknown discriminator error
codec to use by default when decoding
64-bit big endian IEEE 754 floating point number.
64-bit little endian IEEE 754 floating point number.
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.
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.
codec that encodes/decodes false for left and true for right
codec the encodes a left value
codec the encodes a right value
Codec that encrypts and decrypts using a javax.crypto.Cipher.
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 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.
codec that encodes a value to plaintext bits and decodes plaintext bits to a value
factory to use for encryption/decryption
Combinator that chooses amongst two codecs based on an implicitly available byte ordering.
Combinator that chooses amongst two codecs based on an implicitly available byte ordering.
codec to use when big endian
codec to use when little endian
Codec for an Enumeration that encodes/decodes using Enumeration.Value.id values.
Codec for an Enumeration that encodes/decodes using Enumeration.Value.id values.
the codec for Enumeration.Value.id values
the target Enumeration
Codec that always fails encoding and decoding with the specified messages.
Codec that always fails encoding and decoding with the specified message.
Either codec that supports bit vectors of form left or right where the right codec
is consulted first when decoding.
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.
codec the encodes a left value
codec the encodes a right value
Codec that filters bits before/after decoding/encoding.
Codec that filters bits before/after decoding/encoding.
Note: the remainder returned from filter.decode is appended to the remainder of codec.decode.
the target codec
a codec that represents pre/post-processing stages for input/output bits
Codec that limits the number of bits the specified codec works with.
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.
number of bits
codec to limit
Byte equivalent of fixedSizeBits.
Byte equivalent of fixedSizeBits.
number of bytes
codec to limit
Codec that includes a signature of the encoded bits.
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.
size in bytes of signature
codec to use to encode/decode value field
32-bit big endian IEEE 754 floating point number.
32-bit little endian IEEE 754 floating point number.
Converts an HList of codecs in to a single codec.
Converts an HList of codecs in to a single codec.
That is, converts Codec[X0] :: Codec[X1] :: ... :: Codec[Xn] :: HNil in to a
Codec[X0 :: X1 :: ... :: Xn :: HNil].
Codec that always encodes size 0 bits and always decodes size bits and then discards them, returning () instead.
Codec that always encodes size 0 bits and always decodes size bits and then discards them, returning () instead.
number of bits to ignore
Provides common implicit codecs.
Codec for n-bit 2s complement big-endian integers that are represented with Int.
Codec for n-bit 2s complement big-endian integers that are represented with Int.
number of bits (must be 0 < size <= 32)
Codec for 16-bit 2s complement big-endian integers.
Codec for 16-bit 2s complement little-endian integers.
Codec for 24-bit 2s complement big-endian integers.
Codec for 24-bit 2s complement little-endian integers.
Codec for 32-bit 2s complement big-endian integers.
Codec for 32-bit 2s complement little-endian integers.
Codec for 64-bit 2s complement big-endian integers.
Codec for 64-bit 2s complement little-endian integers.
Codec for 8-bit 2s complement big-endian integers.
Codec for 8-bit 2s complement little-endian integers.
Codec for n-bit 2s complement little-endian integers that are represented with Int.
Codec for n-bit 2s complement little-endian integers that are represented with Int.
number of bits (must be 0 < size <= 32)
Provides a Codec[A] that delegates to a lazily evaluated Codec[A].
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.
Allows use of a 4-arg function as a single arg function that takes a left-associated stack of pairs with 4 total elements.
Allows use of a 5-arg function as a single arg function that takes a left-associated stack of pairs with 5 total elements.
Allows use of a 6-arg function as a single arg function that takes a left-associated stack of pairs with 6 total elements.
Allows use of a 7-arg function as a single arg function that takes a left-associated stack of pairs with 7 total elements.
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.
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.
codec to limit
Byte equivalent of limitedSizeBits.
Byte equivalent of limitedSizeBits.
codec to limit
Codec that encodes/decodes a List[A] from a Codec[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.
codec to encode/decode a single element of the sequence
Codec that encodes/decodes a List[A] from a Codec[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")
element type
the bits used to separate element bit values
element codec (used to decode next bits)
Codec that encodes/decodes a List[A] from a Codec[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.
element type
element multiplexer
element de-multiplexer (should return the next bits to decode and the remaining bits for next iteration)
element codec (used to decode next bits)
Codec that encodes/decodes a List[A] of N elements using a Codec[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), ...).
Provides implicit conversions from literal types to constant codecs.
Provides implicit conversions from literal types to constant codecs.
For example, with literals._ imported, constant(0x47) ~> uint8
can be written as 0x47 ~> uint8.
Supports literal bytes, ints, BitVectors, and ByteVectors.
Wraps a codec and adds logging of each encoding and decoding operation.
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.
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.
Combinator intended for use in debugging that logs all failures while encoding or decoding to standard out.
prefix string to include in each log statement
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.
Combinator intended for use in debugging that logs all encoded values and decoded values to standard out.
prefix string to include in each log statement
Codec for n-bit 2s complement big-endian integers that are represented with Long.
Codec for n-bit 2s complement big-endian integers that are represented with Long.
number of bits (must be 0 < size <= 64)
Codec for n-bit 2s complement little-endian integers that are represented with Long.
Codec for n-bit 2s complement little-endian integers that are represented with Long.
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.
Lookahead version of recover -- i.e., upon successful decoding with the target codec, the original buffer is returned instead of the remaining buffer.
codec to recover errors from
Codec for n-nibble packed decimal (BCD) integers that are represented with 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.
number of nibbles (4-bit chunks)
Provides a codec for an enumerated set of values, where each enumerated value is mapped to a tag.
Provides a codec for an enumerated set of values, where each enumerated value is mapped to a tag.
codec used to encode/decode tag value
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.
Provides a codec for an enumerated set of values, where each enumerated value is mapped to a tag.
codec used to encode/decode tag value
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.
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.
codec that determines whether the target codec is included
codec to conditionally include
Codec that limits the number of bits the specified codec works with.
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.
number of bits
codec to limit
codec to use for padding
Codec that limits the number of bits the specified codec works with.
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.
number of bits
codec to limit
function that provides the codec to use for padding
Byte equivalent of paddedFixedSizeBits.
Byte equivalent of paddedFixedSizeBits.
number of bytes
codec to limit
codec to use for padding
Byte equivalent of paddedFixedSizeBitsDependent.
Byte equivalent of paddedFixedSizeBitsDependent.
The padCodec function is passed the number of *bits* of padding required -- not bytes.
number of bytes
codec to limit
function that provides the codec to use for padding
Codec that pads on a multiplier.
Codec that pads on a multiplier.
Similar to ByteAligendCodec, but instead of only padding to 8 bits, pads to a variable size
codec that determines the size
codec for encoding the payload
multiple to align the value to with padding
Byte equivalent of paddedVarAligendBits.
Byte equivalent of paddedVarAligendBits.
codec that determines the size
coec for encoding the payload
multiple of bytes to align the value to with padding
Codec for n-nibble packed decimal (BCD) integers that are represented with Long.
Codec for n-nibble packed decimal (BCD) integers that are represented with Long.
number of nibbles (4-bit chunks)
Decodes using the specified codec but resets the remainder to the original vector.
Decodes using the specified codec but resets the remainder to the original vector. Encodes with the specified codec.
codec that encodes/decodes the value
codec that behaves the same as target but resets remainder to the input vector after decoding
Codec that decodes vectors of the form size ++ rest as a BitVector, where the returned vector includes the size bits.
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.
size codec -- must have an exact size
number of bits to subtract from the size before decoding
Long equivalent of peekVariableSizeBits.
Long equivalent of peekVariableSizeBits.
size codec -- must have an exact size
number of bits to subtract from the size before decoding
Equivalent to peekVariableSizeBits where the size units are in bytes instead of bits.
Equivalent to peekVariableSizeBits where the size units are in bytes instead of bits.
size codec -- must have an exact size
number of bytes to subtract from the size before decoding
Long equivalent of peekVariableSizeBytes.
Long equivalent of peekVariableSizeBytes.
size codec -- must have an exact size
number of bits to subtract from the size before decoding
Codec that always returns an empty vector from encode and always returns (empty, value) from decode.
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 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.
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.
codec to recover errors from
Codec for n-bit 2s complement big-endian shorts.
Codec for n-bit 2s complement big-endian shorts.
number of bits (must be 0 < size <= 16)
Codec for 16-bit 2s complement big-endian shorts.
Codec for 16-bit 2s complement little-endian shorts.
Codec for n-bit 2s complement little-endian shorts.
Codec for n-bit 2s complement little-endian shorts.
number of bits (must be 0 < size <= 16)
Codec that encodes/decodes a list of n elements, where n is known at compile time.
Codec that encodes/decodes a list of n elements, where n is known at compile time.
number of elements in the list
codec to encode/decode a single element of the sequence
Codec that encodes/decodes a vector of n elements, where n is known at compile time.
Codec that encodes/decodes a vector of n elements, where n is known at compile time.
number of elements in the vector
codec to encode/decode a single element of the sequence
String codec that uses the implicit Charset to perform encoding/decoding.
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)
charset to use to convert strings to/from binary
String codec that uses the implicit Charset and prefixes the encoded string by the byte size
in a 32-bit 2s complement big endian field.
String codec that uses the implicit Charset and prefixes the encoded string by the byte size
in a 32-bit 2s complement big endian field.
charset to use to convert strings to/from binary
String codec that uses the implicit Charset and prefixes the encoded string by the byte size
in a 32-bit 2s complement little endian field.
String codec that uses the implicit Charset and prefixes the encoded string by the byte size
in a 32-bit 2s complement little endian field.
charset to use to convert strings to/from binary
Codec for n-bit unsigned bytes.
Codec for n-bit unsigned bytes.
number of bits (must be 0 < size <= 7)
Codec for n-bit unsigned big-endian integers that are represented with Int.
Codec for n-bit unsigned big-endian integers that are represented with Int.
number of bits (must be 0 < size <= 31)
Codec for 16-bit unsigned big-endian integers.
Codec for 16-bit unsigned little-endian integers.
Codec for 2-bit unsigned big-endian integers.
Codec for 24-bit unsigned big-endian integers.
Codec for 24-bit unsigned little-endian integers.
Codec for 2-bit unsigned little-endian integers.
Codec for 32-bit unsigned big-endian integers.
Codec for 32-bit unsigned little-endian integers.
Codec for 4-bit unsigned big-endian integers.
Codec for 4-bit unsigned little-endian integers.
Codec for 8-bit unsigned big-endian integers.
Codec for 8-bit unsigned little-endian integers.
Codec for n-bit unsigned little-endian integers that are represented with Int.
Codec for n-bit unsigned little-endian integers that are represented with Int.
number of bits (must be 0 < size <= 31)
Codec for n-bit unsigned big-endian integers that are represented with Long.
Codec for n-bit unsigned big-endian integers that are represented with Long.
number of bits (must be 0 < size <= 63)
Codec for n-bit unsigned little-endian integers that are represented with Long.
Codec for n-bit unsigned little-endian integers that are represented with Long.
number of bits (must be 0 < size <= 63)
Codec for n-bit unsigned big-endian shorts.
Codec for n-bit unsigned big-endian shorts.
number of bits (must be 0 < size <= 15)
Codec for 8-bit unsigned bytes.
Codec for n-bit unsigned little-endian shorts.
Codec for n-bit unsigned little-endian shorts.
number of bits (must be 0 < size <= 15)
String codec that uses the UTF-8 charset.
String codec that uses the UTF-8 charset. See string for more information on String codecs.
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.
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.
Encodes/decodes UUIDs as 2 64-bit big-endian longs, first the high 64-bits then the low 64-bits.
Codec that supports vectors of the form size ++ value where the size field decodes to the bit length of the value 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 "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".
codec that encodes/decodes the size in bits
codec the encodes/decodes the value
number of bits to add to the size before encoding (and subtract from the size before decoding)
Codec that supports vectors of the form size ++ value where the size field decodes to the bit length of the value 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 "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".
codec that encodes/decodes the size in bits
codec the encodes/decodes the value
number of bits to add to the size before encoding (and subtract from the size before decoding)
Byte equivalent of variableSizeBits.
Byte equivalent of variableSizeBits.
codec that encodes/decodes the size in bytes
codec the encodes/decodes the value
number of bytes to add to the size before encoding (and subtract from the size before decoding)
Byte equivalent of variableSizeBitsLong.
Byte equivalent of variableSizeBitsLong.
codec that encodes/decodes the size in bytes
codec the encodes/decodes the value
number of bytes to add to the size before encoding (and subtract from the size before decoding)
Codec that supports vectors of the form value ++ delimiter where the delimiter marks the end of the value field.
Codec that supports vectors of the form value ++ delimiter where the delimiter marks the end of the value field.
codec the encodes/decodes the value
the size or a mutiple size of the expected value
Codec that supports vectors of the form value ++ delimiter where the delimiter marks the end of the value field.
Codec that supports vectors of the form value ++ delimiter where the delimiter marks the end of the value field.
codec the encodes/decodes the value
Codec that supports vectors of the form size ++ prefix ++ value where the size field decodes to the bit length of the value field.
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".
codec that encodes/decodes the size in bits
codec that encodes/decodes the prefix
codec the encodes/decodes the value
number of bits to add to the size before encoding (and subtract from the size before decoding)
Codec that supports vectors of the form size ++ prefix ++ value where the size field decodes to the bit length of the value field.
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".
codec that encodes/decodes the size in bits
codec that encodes/decodes the prefix
codec the encodes/decodes the value
number of bits to add to the size before encoding (and subtract from the size before decoding)
Byte equivalent of variableSizePrefixedBits.
Byte equivalent of variableSizePrefixedBits.
codec that encodes/decodes the size in bytes
codec that encodes/decodes the prefix
codec the encodes/decodes the value
number of bytes to add to the size before encoding (and subtract from the size before decoding)
Byte equivalent of variableSizePrefixedBitsLong.
Byte equivalent of variableSizePrefixedBitsLong.
codec that encodes/decodes the size in bytes
codec that encodes/decodes the prefix
codec the encodes/decodes the value
number of bytes to add to the size before encoding (and subtract from the size before decoding)
Codec that includes a signature of the encoded bits.
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.
codec to use to encode/decode size of signature field
codec to use to encode/decode value field
Codec that encodes/decodes a Vector[A] from a Codec[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.
codec to encode/decode a single element of the sequence
Codec that encodes/decodes a Vector[A] from a Codec[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")
element type
the bits used to separate element bit values
element codec (used to decode next bits)
Codec that encodes/decodes a Vector[A] from a Codec[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.
element type
element multiplexer
element de-multiplexer (should return the next bits to decode and the remaining bits for next iteration)
element codec (used to decode next bits)
Codec that encodes/decodes a Vector[A] of N elements using a Codec[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), ...).
Codec for variable-length big-endian integers.
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.
Codec for variable-length little-endian integers.
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.
Codec for variable-length big-endian longs.
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.
Codec for variable-length little-endian longs.
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.
Codec for variable-length packed decimal longs.
Codec for variable-length packed decimal longs. Negative values are not supported.
Creates a Codec[A] from a Codec[Option[A]] and a fallback 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.
optional codec
fallback codec used during decoding when opt decodes a None
Creates a Codec[A] from a Codec[Option[A]] and a fallback value 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.
optional codec
fallback value returned from decode when opt decodes a None
Codec that encodes/decodes certificates using their default encoding.
Codec that compresses the results of encoding with the specified codec and decompresses prior to decoding with the specified 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.
compression level, 0-9, with 0 disabling compression and 9 being highest level of compression -- see java.util.zip.Deflater for details
compression strategy -- see java.util.zip.Deflater for details
if true, ZLIB header and checksum will not be used
buffer size, in bytes, to use when compressing
Extractor that allows pattern matching on the tuples created by tupling 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 andByteVectorsdirectly. These are provided bybitsandbytesmethods. 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 ofdecodealways returns a empty bit vector for the remaining bits.Similarly, fixed size alternatives are provided by the
bits(size)andbytes(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
ignoreandconstant.Numeric Codecs
There are built-in codecs for
Int,Long,Float, andDouble.There are a number of predefined integral codecs named using the form:
[u]int$${size}[L]where
ustands for unsigned,sizeis replaced by one of8, 16, 24, 32, 64, andLstands for little-endian. For each codec of that form, the type isCodec[Int]orCodec[Long]depending on the specified size. For example,int32supports 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 aLong.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 ofIntandLong.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, andUUID.Boolean values are supported by the
boolcodecs.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.