scodec.codecs
Type members
Classlikes
Provides methods to create a "checksum codec" (encodes a bit-range to a bit-checksum and decodes bits to a bit-range).
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.
Creates checksum implementations of SignerFactory.
Indicates a checksum over bits
did not match the expected value.
Indicates a checksum over bits
did not match the expected value.
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.
The most general case combinators are caseO
and caseP
.
In addition to a tag, the caseO
combinator is defined by providing a mapping from
A
to Option[R]
, a mapping from R
to A
, and a Codec[R]
. The case is used for encoding if the
mapping from A
to Option[R]
returns a Some
and it is used for decoding upon matching the tag value.
The caseP
combinators work the same but take a PartialFunction[A, R]
instead of an A => Option[R]
.
If R
is a subtype of A
, then the mapping from R
to A
can be omitted. Hence, the
subcaseO
and subcaseP
constrain R
to being a subtype of A
and do not take a R => A
function.
Finally, the least generic case combinators are the typecase
combinators which add further constraints
to the subcase*
combinators. Specifically, the typecase operators omit the A => Option[R]
or
PartialFunction[A, R]
in favor of doing subtype checks. For example, the following codec is a Codec[AnyVal]
that encodes a 0 if passed a Boolean
and a 1 if passed an Int
:
discriminated[AnyVal].by(uint8).typecase(0, bool).typecase(1, int32)
Often, the values are size-delimited -- that is, there is a size
field after the tag
field and beforethe
valuefield. To support this, use the
framingmethod to provide a transformation to each value codec. For example,
framing(new CodecTransformation { def apply[X](c: Codec[X]) = variableSizeBytes(uint8, c) })`.
- Value Params
- by
codec that encodec/decodes the tag value
- cases
cases, ordered from highest priority to lowest priority, that handle subsets of
A
- See also
Mixin for codecs/decoders that are known to discriminate by values of type D
.
Mixin for codecs/decoders that are known to discriminate by values of type D
.
A trait that enables custom handling for encoding/decoding sequences.
A trait that enables custom handling for encoding/decoding sequences.
Supports creation of a DiscriminatorCodec. See discriminated for details.
Supports creation of a DiscriminatorCodec. See discriminated for details.
Create java.security.Signature
implementations for SignerFactory
Create java.security.Signature
implementations for SignerFactory
Represents the ability to create a "checksum" for use with fixedSizeSignature and variableSizeSignature.
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.
Represents the ability to create a Signer for use with fixedSizeSignature and variableSizeSignature.
Value members
Concrete methods
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.
- Value Params
- size
number of bits to encode/decode
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.
- Value Params
- size
number of bits to encode/decode
n-bit boolean codec, where false corresponds to bit vector of all 0s and true corresponds to all other vectors.
n-bit boolean codec, where false corresponds to bit vector of all 0s and true corresponds to all other vectors.
Codec for n-bit 2s complement bytes.
Codec for n-bit 2s complement bytes.
- Value Params
- size
number of bits (must be 0 < size <= 8)
Codec that:
Codec that:
- encodes using the specified codec but right-pads with 0 bits to the next largest byte when the size of the encoded bit vector is not divisible by 8
- decodes using the specified codec but drops any leading bits of the remainder when the number of bytes consumed by the specified codec is not divisible by 8
This combinator allows byte alignment without manually specifying ignore bits. For example, instead of writing
(bool(1) :: bool(1) :: ignore(6)).dropUnits
, this combinator allows byteAligned(bool(1) :: bool(1))
.
Note that aligning large structures on byte boundaries can provide significant performance improvements when
converting to/from data structures that are based on bytes -- e.g., Array[Byte]
or ByteBuffer
.
- Value Params
- codec
codec to align to next larger byte boundary
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.
- Value Params
- size
number of bytes to encode/decode
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.
- Value Params
- size
number of bytes to encode/decode
Codec that encodes/decodes certificates using their default encoding.
Codec that encodes/decodes certificates using their default encoding.
- Value Params
- certType
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))
- Value Params
- checksum
computes a checksum of the input
- framing
codec used to convert the encoded value and computed checksum in to a single vector
- target
codec used for encoding/decoding values of type
A
Codec that encodes/decodes using the specified codecs by trying each codec in succession and using the first successful result.
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.
- Value Params
- codec
codec to conditionally include
- included
whether this codec is enabled (meaning it delegates to the specified codec) or disabled, in which case it encodes no bits and returns
None
from decode
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.
- Value Params
- bits
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.
- Value Params
- bytes
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.
- Value Params
- bits
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.
- Value Params
- 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.
- Value Params
- 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.
- Value Params
- 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
.
- Value Params
- maxSize
maximum size in bytes that the message can have
- minSize
minimum size in bytes that the message can have
- size
codec that encodes/decodes the size in bits
- value
codec the encodes/decodes the value
Codec that ensures variable size data is constrained within a minSize and maxSize bounds.
Codec that ensures variable size data is constrained within a minSize and maxSize bounds.
This means that the size is variable only within a limited range. It will work just as variableSizeBytes codec,
but ensuring that the binary data is at least minSize
bytes long and at most maxSize
bytes long.
The minSize
has the default value of 0
.
- Value Params
- maxSize
maximum size in bytes that the message can have
- size
codec that encodes/decodes the size in bits
- value
codec the encodes/decodes the value
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
.
- Value Params
- maxSize
maximum size in bytes that the message can have
- minSize
minimum size in bytes that the message can have
- size
codec that encodes/decodes the size in bits
- value
codec the encodes/decodes the value
Codec that ensures variable size data is constrained within a minSize and maxSize bounds.
Codec that ensures variable size data is constrained within a minSize and maxSize bounds.
This means that the size is variable only within a limited range. It will work just as variableSizeBytes codec,
but ensuring that the binary data is at least minSize
bytes long and at most maxSize
bytes long.
The minSize
has the default value of 0
.
- Value Params
- maxSize
maximum size in bytes that the message can have
- size
codec that encodes/decodes the size in bits
- value
codec the encodes/decodes the value
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
).
- Value Params
- left
codec to use when the right codec fails due to an unknown discriminator error
- right
codec to use by default when decoding
Either codec that supports bit vectors of form 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.
- Value Params
- indicator
codec that encodes/decodes false for left and true for right
- left
codec the encodes a left value
- right
codec the encodes a right value
Codec that encrypts and decrypts using a javax.crypto.Cipher
.
Codec that encrypts and decrypts using a javax.crypto.Cipher
.
Encoding a value of type A
is delegated to the specified codec and the resulting bit vector is encrypted
with a cipher provided by the given CipherFactory.
Decoding first decrypts all of the remaining bits and then decodes the decrypted bits with the specified codec. Successful decoding always returns no remaining bits, even if the specified codec does not consume all decrypted bits.
- Value Params
- cipherFactory
factory to use for encryption/decryption
- codec
codec that encodes a value to plaintext bits and decodes plaintext bits to a value
Combinator that chooses amongst two codecs based on a given byte ordering.
Combinator that chooses amongst two codecs based on a given byte ordering.
- Value Params
- big
codec to use when big endian
- little
codec to use when little endian
Codec for an Enumeration
that encodes/decodes using Enumeration.Value.id
values.
Codec for an Enumeration
that encodes/decodes using Enumeration.Value.id
values.
- Value Params
- discriminator
the codec for
Enumeration.Value.id
values- enumeration
the target
Enumeration
Codec that always fails encoding and decoding with the specified message.
Codec that always fails encoding and decoding with the specified message.
Codec that always fails encoding and decoding with the specified messages.
Codec that always fails encoding and decoding with the specified messages.
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.
Either codec that supports bit vectors of form left or right
where the right codec
is consulted first when decoding. If the right codec fails to decode, the left codec
is used.
- Value Params
- left
codec the encodes a left value
- right
codec the encodes a right value
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
.
- Value Params
- codec
the target codec
- filter
a codec that represents pre/post-processing stages for input/output bits
Codec that limits the number of bits the specified codec works with.
Codec that limits the number of bits the specified codec works with.
When encoding, if encoding with the specified codec results in less than the specified size, the vector is right padded with 0 bits. If the result is larger than the specified size, an encoding error is returned.
When decoding, the specified codec is only given size
bits. If the specified codec does not consume all the bits it was
given, any remaining bits are discarded.
- Value Params
- codec
codec to limit
- size
number of bits
Byte equivalent of fixedSizeBits.
Byte equivalent of fixedSizeBits.
- Value Params
- codec
codec to limit
- size
number of bytes
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.
- Value Params
- codec
codec to use to encode/decode value field
- signatureFactory
factory to use for signing/verifying
- size
size in bytes of signature
Codec that always encodes size
0 bits and always decodes size
bits and then discards them, returning ()
instead.
Codec that always encodes size
0 bits and always decodes size
bits and then discards them, returning ()
instead.
- Value Params
- size
number of bits to ignore
Codec for n-bit 2s complement big-endian integers that are represented with Int
.
Codec for n-bit 2s complement big-endian integers that are represented with Int
.
- Value Params
- size
number of bits (must be 0 < size <= 32)
Codec for n-bit 2s complement little-endian integers that are represented with Int
.
Codec for n-bit 2s complement little-endian integers that are represented with Int
.
- Value Params
- bits
number of bits (must be 0 < size <= 32)
Provides a Codec[A]
that delegates to a lazily evaluated Codec[A]
.
Provides a Codec[A]
that delegates to a lazily evaluated Codec[A]
.
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.
- Value Params
- codec
codec to limit
- size
number of bits
Byte equivalent of limitedSizeBits.
Byte equivalent of limitedSizeBits.
- Value Params
- codec
codec to limit
- size
number of bytes
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.
- Value Params
- codec
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")
- Type Params
- A
element type
- Value Params
- delimiter
the bits used to separate element bit values
- valueCodec
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
.
- Type Params
- A
element type
- Value Params
- deMux
element de-multiplexer (should return the next bits to decode and the remaining bits for next iteration)
- mux
element multiplexer
- valueCodec
element codec (used to decode next bits)
Codec that encodes/decodes a List[A]
of N
elements using a Codec[A]
.
Codec that encodes/decodes a List[A]
of N
elements using a Codec[A]
.
When encoding, the number of elements in the list is encoded using countCodec
and the values are then each encoded using valueCodec
.
When decoding, the number of elements is decoded using countCodec
and then that number of elements
are decoded using valueCodec
. Any remaining bits are returned.
Note: when the count is known statically, use listOfN(provide(count), ...)
.
- Value Params
- codec
codec to encode/decode a single element of the sequence
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.
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.
- Value Params
- prefix
prefix string to include in each log statement
Variant of logBuilder that only logs successful results.
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.
- Value Params
- prefix
prefix string to include in each log statement
Codec for n-bit 2s complement big-endian integers that are represented with Long
.
Codec for n-bit 2s complement big-endian integers that are represented with Long
.
- Value Params
- bits
number of bits (must be 0 < size <= 64)
Codec for n-bit 2s complement little-endian integers that are represented with Long
.
Codec for n-bit 2s complement little-endian integers that are represented with Long
.
- Value Params
- bits
number of bits (must be 0 < size <= 64)
Lookahead version of recover -- i.e., upon successful decoding with the target codec, the original buffer is returned instead of the remaining buffer.
Lookahead version of recover -- i.e., upon successful decoding with the target codec, the original buffer is returned instead of the remaining buffer.
- Value Params
- target
codec to recover errors from
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.
Codec for n-nibble packed decimal (BCD) integers that are represented with Long
.
This codec, despite requiring the size in nibbles, is byte-size oriented.
This means it expects to parse complete bytes (even if nibble size is
odd). For encoding, this codec will pad 0s on the left while, for
decoding, it will fetch the size in bytes round up.
- Value Params
- nibbles
number of nibbles (4-bit chunks)
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.
- Value Params
- discriminatorCodec
codec used to encode/decode tag value
- mappings
mapping from tag values to/from enum values
Provides a codec for an enumerated set of values, where each enumerated value is mapped to a tag.
Provides a codec for an enumerated set of values, where each enumerated value is mapped to a tag.
- Value Params
- discriminatorCodec
codec used to encode/decode tag value
- map
mapping from tag values to/from enum values
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
.
- Value Params
- guard
codec that determines whether the target codec is included
- target
codec to conditionally include
Codec that limits the number of bits the specified codec works with.
Codec that limits the number of bits the specified codec works with.
If the encoded result is larger than the specified size, an encoding error is returned.
If encoding with the specified codec results in less than the specified size, the vector is right padded by repeatedly encoding with padCodec. An encoding error is returned if the padCodec result does not precisely fill the remaining space.
When decoding, the specified codec is only given size
bits. If the specified codec does not consume all the bits it was
given, all remaining bits are repeatedly decoded by padCodec. A decoding error is returned if any
padCodec decode returns an error.
- Value Params
- codec
codec to limit
- padCodec
codec to use for padding
- size
number of bits
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.
- Value Params
- codec
codec to limit
- padCodec
function that provides the codec to use for padding
- size
number of bits
Byte equivalent of paddedFixedSizeBits.
Byte equivalent of paddedFixedSizeBits.
- Value Params
- codec
codec to limit
- padCodec
codec to use for padding
- size
number of bytes
Byte equivalent of paddedFixedSizeBitsDependent.
Byte equivalent of paddedFixedSizeBitsDependent.
The padCodec
function is passed the number of bits of padding required -- not bytes.
- Value Params
- codec
codec to limit
- padCodec
function that provides the codec to use for padding
- size
number of bytes
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
- Value Params
- multipleForPadding
multiple to align the value to with padding
- sizeCodec
codec that determines the size
- valueCodec
codec for encoding the payload
Byte equivalent of paddedVarAlignedBits.
Byte equivalent of paddedVarAlignedBits.
- Value Params
- multipleForPadding
multiple of bytes to align the value to with padding
- sizeCodec
codec that determines the size
- valueCodec
coec for encoding the payload
Codec for n-nibble packed decimal (BCD) integers that are represented with Long
.
Codec for n-nibble packed decimal (BCD) integers that are represented with Long
.
- Value Params
- nibbles
number of nibbles (4-bit chunks)
Decodes using the specified codec but resets the remainder to the original vector. Encodes with the specified codec.
Decodes using the specified codec but resets the remainder to the original vector. Encodes with the specified codec.
- Value Params
- target
codec that encodes/decodes the value
- Returns
codec that behaves the same as
target
but resets remainder to the input vector after decoding
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.
- Value Params
- size
size codec -- must have an exact size
- sizePadding
number of bits to subtract from the size before decoding
Long
equivalent of peekVariableSizeBits.
Long
equivalent of peekVariableSizeBits.
- Value Params
- size
size codec -- must have an exact size
- sizePadding
number of bits to subtract from the size before decoding
Equivalent to peekVariableSizeBits where the size units are in bytes instead of bits.
Equivalent to peekVariableSizeBits where the size units are in bytes instead of bits.
- Value Params
- size
size codec -- must have an exact size
- sizePadding
number of bytes to subtract from the size before decoding
Long
equivalent of peekVariableSizeBytes.
Long
equivalent of peekVariableSizeBytes.
- Value Params
- size
size codec -- must have an exact size
- sizePadding
number of bits to subtract from the size before decoding
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).
Codec that always returns an empty vector from encode
and always returns (empty, value)
from decode
.
This is often useful when combined with other codecs (e.g., the discriminated).
- Value Params
- value
value to return from decode
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.
Creates a codec that decodes true when the target codec decodes successfully and decodes false when the target codec decodes unsuccessfully. Upon a successful decode of the target codec, the remaining bits are returned, whereas upon an unsuccessful decode, the original input buffer is returned.
When encoding, a true results in the target codec encoding a unit whereas a false results in encoding of an empty vector.
- Value Params
- target
codec to recover errors from
Codec for n-bit 2s complement big-endian shorts.
Codec for n-bit 2s complement big-endian shorts.
- Value Params
- size
number of bits (must be 0 < size <= 16)
Codec for n-bit 2s complement little-endian shorts.
Codec for n-bit 2s complement little-endian shorts.
- Value Params
- size
number of bits (must be 0 < size <= 16)
String codec that uses the supplied Charset
to perform encoding/decoding.
String codec that uses the supplied Charset
to perform encoding/decoding.
This codec does not encode the size of the string in to the output. Hence, decoding a vector that has additional data after the encoded string will result in unexpected output. Instead, it is common to use this codec along with either fixedSizeBits or variableSizeBits. For example, a common encoding is a size field, say 2 bytes, followed by the encoded string. This can be accomplished with:
variableSizeBits(uint16, string)
- Value Params
- charset
charset to use to convert strings to/from binary
String codec that uses the given Charset
and prefixes the encoded string by the byte size
in a 32-bit 2s complement big endian field.
String codec that uses the given Charset
and prefixes the encoded string by the byte size
in a 32-bit 2s complement big endian field.
- Value Params
- charset
charset to use to convert strings to/from binary
String codec that uses the given Charset
and prefixes the encoded string by the byte size
in a 32-bit 2s complement little endian field.
String codec that uses the given Charset
and prefixes the encoded string by the byte size
in a 32-bit 2s complement little endian field.
- Value Params
- charset
charset to use to convert strings to/from binary
Codec for n-bit unsigned bytes.
Codec for n-bit unsigned bytes.
- Value Params
- size
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
.
- Value Params
- bits
number of bits (must be 0 < size <= 31)
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
.
- Value Params
- bits
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
.
- Value Params
- bits
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
.
- Value Params
- bits
number of bits (must be 0 < size <= 63)
Codec for n-bit unsigned big-endian shorts.
Codec for n-bit unsigned big-endian shorts.
- Value Params
- size
number of bits (must be 0 < size <= 15)
Codec for n-bit unsigned little-endian shorts.
Codec for n-bit unsigned little-endian shorts.
- Value Params
- size
number of bits (must be 0 < size <= 15)
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"
.
- Value Params
- size
codec that encodes/decodes the size in bits
- sizePadding
number of bits to add to the size before encoding (and subtract from the size before decoding)
- value
codec the encodes/decodes the value
Codec that supports vectors of the form size ++ value
where the size
field decodes to the bit length of the value
field.
Codec that supports vectors of the form size ++ value
where the size
field decodes to the bit length of the value
field.
For example, encoding the string "hello"
with variableSizeBitsLong(uint32, ascii)
yields a vector of 9 bytes -- the first four bytes being
0x00000028 and the next 5 bytes being the US-ASCII encoding of "hello"
.
The size
field can be any Long
codec. An optional padding can be applied to the size field. The sizePadding
is added to
the calculated size before encoding, and subtracted from the decoded size before decoding the value.
For example, encoding "hello"
with variableSizeBitsLong(uint32, ascii, 1)
yields a vector of 9 bytes -- the first 4 bytes being
0x00000029 and the next 5 bytes being the US-ASCII encoding of "hello"
.
- Value Params
- size
codec that encodes/decodes the size in bits
- sizePadding
number of bits to add to the size before encoding (and subtract from the size before decoding)
- value
codec the encodes/decodes the value
Byte equivalent of variableSizeBits.
Byte equivalent of variableSizeBits.
- Value Params
- size
codec that encodes/decodes the size in bytes
- sizePadding
number of bytes to add to the size before encoding (and subtract from the size before decoding)
- value
codec the encodes/decodes the value
Byte equivalent of variableSizeBitsLong.
Byte equivalent of variableSizeBitsLong.
- Value Params
- size
codec that encodes/decodes the size in bytes
- sizePadding
number of bytes to add to the size before encoding (and subtract from the size before decoding)
- value
codec the encodes/decodes the value
Codec that supports vectors of the form value ++ delimiter
where the delimiter
marks the end of the value
field.
Codec that supports vectors of the form value ++ delimiter
where the delimiter
marks the end of the value
field.
- Value Params
- size
codec that encodes/decodes the delimiter
- value
codec the encodes/decodes the value
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.
- Value Params
- multipleValueSize
the size or a mutiple size of the expected value
- size
codec that encodes/decodes the delimiter
- value
codec the encodes/decodes the value
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"
.
- Value Params
- prefix
codec that encodes/decodes the prefix
- size
codec that encodes/decodes the size in bits
- sizePadding
number of bits to add to the size before encoding (and subtract from the size before decoding)
- value
codec the encodes/decodes the value
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"
.
- Value Params
- prefix
codec that encodes/decodes the prefix
- size
codec that encodes/decodes the size in bits
- sizePadding
number of bits to add to the size before encoding (and subtract from the size before decoding)
- value
codec the encodes/decodes the value
Byte equivalent of variableSizePrefixedBits.
Byte equivalent of variableSizePrefixedBits.
- Value Params
- prefix
codec that encodes/decodes the prefix
- size
codec that encodes/decodes the size in bytes
- sizePadding
number of bytes to add to the size before encoding (and subtract from the size before decoding)
- value
codec the encodes/decodes the value
Byte equivalent of variableSizePrefixedBitsLong.
Byte equivalent of variableSizePrefixedBitsLong.
- Value Params
- prefix
codec that encodes/decodes the prefix
- size
codec that encodes/decodes the size in bytes
- sizePadding
number of bytes to add to the size before encoding (and subtract from the size before decoding)
- value
codec the encodes/decodes the value
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.
- Value Params
- codec
codec to use to encode/decode value field
- signatureFactory
factory to use for signing/verifying
- size
codec to use to encode/decode size of signature field
Codec that encodes/decodes a Vector[A]
from a Codec[A]
.
Codec that encodes/decodes a Vector[A]
from a Codec[A]
.
When encoding, each A
in the vector is encoded and all of the resulting vectors are concatenated.
When decoding, codec.decode
is called repeatedly until there are no more remaining bits and the value result
of each decode
is returned in the vector.
- Value Params
- codec
codec to encode/decode a single element of the sequence
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")
- Type Params
- A
element type
- Value Params
- delimiter
the bits used to separate element bit values
- valueCodec
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
.
- Type Params
- A
element type
- Value Params
- deMux
element de-multiplexer (should return the next bits to decode and the remaining bits for next iteration)
- mux
element multiplexer
- valueCodec
element codec (used to decode next bits)
Codec that encodes/decodes a Vector[A]
of N
elements using a Codec[A]
.
Codec that encodes/decodes a Vector[A]
of N
elements using a Codec[A]
.
When encoding, the number of elements in the vector is encoded using countCodec
and the values are then each encoded using valueCodec
.
When decoding, the number of elements is decoded using countCodec
and then that number of elements
are decoded using valueCodec
. Any remaining bits are returned.
Note: when the count is known statically, use vectorOfN(provide(count), ...)
.
- Value Params
- codec
codec to encode/decode a single element of the sequence
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.
- Value Params
- default
fallback codec used during decoding when
opt
decodes aNone
- opt
optional codec
Creates a Codec[A]
from a Codec[Option[A]]
and a fallback value A
.
Creates a Codec[A]
from a Codec[Option[A]]
and a fallback value A
.
When encoding, the A
is encoded with opt
(by wrapping it in a Some
).
When decoding, opt
is first used to decode the buffer. If it decodes a Some(a)
, that
value is returned. If it decodes a None
, the default
value is return.
- Value Params
- default
fallback value returned from
decode
whenopt
decodes aNone
- opt
optional codec
Codec that encodes/decodes certificates using their default encoding.
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.
- Value Params
- chunkSize
buffer size, in bytes, to use when compressing
- level
compression level, 0-9, with 0 disabling compression and 9 being highest level of compression -- see
java.util.zip.Deflater
for details- nowrap
if true, ZLIB header and checksum will not be used
- strategy
compression strategy -- see
java.util.zip.Deflater
for details
Concrete fields
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 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.
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 supplied bit vector; decodes by taking all remaining bits in the supplied bit vector.
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. Encodes to an empty bit vector.
Codec that decodes true when the input vector is non-empty and false when it is empty. Encodes to an empty bit vector.
1-bit boolean codec, where false corresponds to bit value 0 and true corresponds to bit value 1.
1-bit boolean codec, where false corresponds to bit value 0 and true corresponds to bit value 1.
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 supplied byte vector as a bit vector; decodes by taking all remaining bits in supplied bit vector and converting to a byte vector.
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.
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.
64-bit little endian IEEE 754 floating point number.
64-bit little endian IEEE 754 floating point number.
32-bit little endian IEEE 754 floating point number.
32-bit little endian IEEE 754 floating point number.
Codec for 16-bit 2s complement big-endian integers.
Codec for 16-bit 2s complement big-endian integers.
Codec for 16-bit 2s complement little-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 big-endian integers.
Codec for 24-bit 2s complement little-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 big-endian integers.
Codec for 32-bit 2s complement little-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 big-endian integers.
Codec for 64-bit 2s complement little-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 big-endian integers.
Codec for 8-bit 2s complement little-endian integers.
Codec for 8-bit 2s complement little-endian integers.
Codec for 16-bit 2s complement little-endian shorts.
Codec for 16-bit 2s complement little-endian shorts.
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 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.
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 UUID
s as 2 64-bit big-endian longs, first the high 64-bits then the low 64-bits.
Encodes/decodes UUID
s as 2 64-bit big-endian longs, first the high 64-bits then the low 64-bits.
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 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. Encoding requires between 1 and 5 bytes, depending on the value. Smaller ints require less bytes. Negative values are always encoded with 5 bytes.
Codec for variable-length little-endian integers. Encoding requires between 1 and 5 bytes, depending on the value. Smaller ints require less bytes. Negative values are always encoded with 5 bytes.
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 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. Encoding requires between 1 and 9 bytes, depending on the value. Smaller longs require less bytes. Negative values are not supported.
Codec for variable-length little-endian longs. Encoding requires between 1 and 9 bytes, depending on the value. Smaller longs require less bytes. Negative values are not supported.