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
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]
.
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)
Describes an isomorphism between two HList
s, 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.
Mixin for codecs/decoders that are known to discriminate by values of type D
.
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 ~ ....
Creates checksum implementations of SignerFactory.
Companion for CipherFactory.
Companion for CoproductBuilderAuto.
Companion for CoproductBuilderAutoDiscriminators.
Companion for CoproductBuilderKeyDiscriminators.
Companion for CoproductCodecBuilder.
Companion for DropUnits.
Companion for FlattenLeftPairs.
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.
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
Encodes by returning supplied bit vector; decodes by taking all remaining bits in the supplied bit vector.
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.
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
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.
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 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
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) .build
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, depending on whether you
have a PartialFunction
from the base type or an B => Option[S]
function from the base type to the subcase.
If you you already have a codec specific to the case, you can omit the 'injection' function. For instance:
val leftCodec: Codec[Left[A,B]] = codecA.widenOpt(Left.apply, Left.unapply) val rightCodec: Codec[Right[A,B]] = codecB.widenOpt(Left.apply, Left.unapply) val codecE: Codec[Either[A,B]] = discriminated[Either[A,B]].by(uint8) .\ (0) { case l@Left(_) => l } (leftCodec) // backslash instead of '|' .\ (1) { case r@Right(_) => r } (rightCodec)
The actual formatted bits are identical with either formulation.
64-bit big endian IEEE 754 floating point number.
64-bit little endian IEEE 754 floating point number.
Either codec that supports 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 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 that always fails encoding and decoding with the specified messages.
Codec that always fails encoding and decoding with the specified message.
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 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]
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, BitVector
s, and ByteVector
s.
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
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.
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 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)
String codec that utilizes the implicit Charset
to perform encoding/decoding.
String codec that utilizes 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(uint8, string)
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.
Encodes/decodes UUID
s 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
0x05 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
0x06 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
0x00000005 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
0x00000006 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 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]
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), ...)
.
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.
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
BitVector
s andByteVectors
directly. These are provided by bits and bytes methods. These codecs encode all of the bits/bytes directly in to the result and decode *all* of the remaining bits/bytes in to the result value. That is, the result ofdecode
always 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 ignore and constant.
Numeric Codecs
There are built-in codecs for
Int
,Long
,Float
, andDouble
.There are a number of predefined integral codecs named using the form:
where
u
stands for unsigned,size
is replaced by one of8, 16, 24, 32, 64
, andL
stands for little-endian. For each codec of that form, the type isCodec[Int]
orCodec[Long]
depending on the specified size. For example,int32
supports 32-bit big-endian 2s complement signed integers, and uint16L supports 16-bit little-endian unsigned integers. Note:uint64[L]
are not provided because a 64-bit unsigned integer does not fit in to 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 ofInt
andLong
.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 bool codecs.
Combinators
There are a number of methods provided that create codecs out of other codecs. These include simple combinators such as fixedSizeBits and variableSizeBits and advanced combinators such as discriminated, which provides its own DSL for building a large codec out of many small codecs. For a list of all combinators, see the Combinators section below.
Cryptography Codecs
There are codecs that support working with encrypted data (encrypted), digital signatures and checksums (fixedSizeSignature and variableSizeSignature). Additionally, support for
java.security.cert.Certificate
s is provided by certificate and x509Certificate.