package 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 and ByteVectors
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
of decode
always returns a empty bit vector for the remaining bits.
Similarly, fixed size alternatives are provided by the bits(size)
and bytes(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
, and Double
.
There are a number of predefined integral codecs named using the form:
[u]int$${size}[L]
where u
stands for unsigned, size
is replaced by one of 8, 16, 24, 32, 64
, and L
stands for little-endian.
For each codec of that form, the type is Codec[Int]
or Codec[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 a Long
.
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 of Int
and Long
.
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
, and UUID
.
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.
- Source
- package.scala
- Grouped
- Alphabetic
- By Inheritance
- codecs
- AnyRef
- Any
- Hide All
- Show All
- Public
- All
Type Members
-
case class
ChecksumMismatch(bits: BitVector, expected: BitVector, actual: BitVector, context: List[String] = Nil) extends Err with Product with Serializable
Indicates a checksum over
bits
did not match the expected value. -
trait
CipherFactory extends AnyRef
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.
-
sealed abstract
class
CoproductBuilderAuto[A] extends DepFn0
Witness that a coproduct codec builder of type
A
can be automatically created. -
sealed abstract
class
CoproductBuilderAutoDiscriminators[X, C <: Coproduct, A] extends AnyRef
Witness for
CoproductCodecBuilder#NeedDiscriminators#auto
. -
sealed abstract
class
CoproductBuilderKeyDiscriminators[C <: Coproduct, L <: HList, A] extends AnyRef
Witness for
CoproductCodecBuilder#NeedDiscriminators#using
. -
final
class
CoproductCodecBuilder[C <: Coproduct, L <: HList, R] extends AnyRef
Supports building a coproduct codec.
Supports building a coproduct codec.
A coproduct codec is built by:
- specifying a codec for each member of the coproduct, separated by the
:+:
operator - specifying the discriminator codec and mapping between discriminator values and coproduct members
- alternatively, instead of specifying a discriminator codec, using the
choice
combinator to create a codec that encodes no discriminator and hence, decodes by trying each codec in succession and using the first successful result
To specify the discriminator, call either
discriminatedByIndex(intCodec)
ordiscriminatedBy(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 withint32
. Similarly, a value of 1 causes the remaining bits to be encoded/decoded withbool(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 withb
, and strings withs
. The discriminator is encoded withfixedSizeBytes(1, ascii)
.The methods which generate a
Codec
return aCodec[R]
instead of aCodec[C]
. Typically,C =:= R
but thexmap
andexmap
methods allow transformations betweenC
andR
to be deferred until after the codec is built.- C
coproduct type
- L
hlist type that has a codec for each type in the coproduct
C
- R
resulting codec type
- specifying a codec for each member of the coproduct, separated by the
-
final
class
DeriveHListElementAux[L <: HList, A] extends AnyVal
Provides syntax support for
Codec[L]#derive
for someHList L
.Provides syntax support for
Codec[L]#derive
for someHList L
. Seederive
for more information. -
final
case class
Discriminated[X, D](codec: Codec[D], framing: CodecTransformation) extends Product with Serializable
Wrapper class that indicates subtypes of
X
are discriminated by typeD
using the suppliedCodec[D]
.Wrapper class that indicates subtypes of
X
are discriminated by typeD
using the suppliedCodec[D]
.For example, an implicit
Discriminated
value can be defined in the companion of a sealed trait, along with implicitDiscriminator
values in each subtype companion. Given such implicits, a codec for the trait can be automatically derived usingCodec[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) })
- X
type that can be discriminated by discriminator values of type
D
- D
value type that discriminates
Y
in context ofX
from other types using discriminators ofD
for some typeY
-
final
case class
Discriminator[X, Y, D](value: D) extends Product with Serializable
Wrapper class that discriminates type
Y
in context of typeX
with a value of typeD
.Wrapper class that discriminates type
Y
in context of typeX
with a value of typeD
.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.- X
context in which type
Y
is discriminated from other types- Y
type that is differentiated from other types by values of
D
- D
value type that discriminates values of
Y
from other types in context ofX
-
final
class
DiscriminatorCodec[A, B] extends Codec[A] with KnownDiscriminatorType[B]
Codec that supports the binary structure
tag ++ value
where thetag
identifies the encoding/decoding of the value.Codec that supports the binary structure
tag ++ value
where thetag
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
andcaseP
(and their operator equivalents,?
and|
). In addition to a tag or tag/predicate pair, thecaseO
combinators are defined by providing a mapping fromA
toOption[R]
, a mapping fromR
toA
, and aCodec[R]
. The case is used for encoding if the mapping fromA
toOption[R]
returns aSome
and it is used for decoding upon matching the tag value. ThecaseP
combinators work the same but take aPartialFunction[A, R]
instead of anA => Option[R]
.If
R
is a subtype ofA
, then the mapping fromR
toA
can be omitted. Hence, thesubcaseO
andsubcaseP
(and the operator equivalents,/
and\
) constrainR
to being a subtype ofA
and do not take aR => A
function.Finally, the least generic case combinators are the
typecase
combinators which add further constraints to thesubcase*
combinators. Specifically, the typecase operators omit theA => Option[R]
orPartialFunction[A, R]
in favor of doing subtype checks. For example, the following codec is aCodec[AnyVal]
that encodes a 0 if passed aBoolean
and a 1 if passed anInt
:discriminated[AnyVal].by(uint8).typecase(0, bool).typecase(1, int32)
Often, the values are size-delimited -- that is, there is a
size
field after thetag
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) }).
- See also
-
sealed
trait
DropUnits[K <: HList] extends AnyRef
Describes an isomorphism between two
HList
s,K
andL
, whereL
has the same shape asK
except unit values have been removed. -
sealed
trait
DropUnitsLowPriority extends AnyRef
Low priority implicits for DropUnits.
-
sealed
trait
FlattenLeftPairs[A] extends DepFn1[A]
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 aA :: B :: C :: D :: HNil
and theunflatten
method does the inverse. -
trait
ImplicitCodecs extends ImplicitValues with ImplicitCollections
Provides implicit codecs for common types.
-
trait
ImplicitCollections extends AnyRef
Provides implicit codecs for collection types.
-
trait
ImplicitValues extends AnyRef
Provides implicit codecs for simple value types.
-
sealed
trait
InvertibleRemove[L <: HList, A] extends AnyRef
Similar to Shapeless's remove support for HLists but supports inverting the removal.
-
trait
KnownDiscriminatorType[D] extends AnyRef
Mixin for codecs/decoders that are known to discriminate by values of type
D
. -
sealed
trait
MultiplexedCodec extends AnyRef
A trait that enables custom handling for encoding/decoding sequences.
-
abstract
class
NeedDiscriminatorCodec[A] extends AnyRef
Supports creation of a DiscriminatorCodec.
Supports creation of a DiscriminatorCodec. See discriminated for details.
- class PaddedVarAlignedCodec[A] extends Codec[A]
-
class
SignatureSigner extends Signer
Signer implementation for
java.security.Signature
-
trait
Signer extends AnyRef
Represents the ability to create a "checksum" for use with fixedSizeSignature and variableSizeSignature.
-
trait
SignerFactory extends AnyRef
Represents the ability to create a Signer for use with fixedSizeSignature and variableSizeSignature.
-
implicit final
class
StringEnrichedWithCodecContextSupport extends AnyVal
Provides the
|
method onString
, which is reverse syntax forcodec withContext ctx
.Provides the
|
method onString
, which is reverse syntax forcodec withContext ctx
.Usage:
val codec = "id" | uint8
-
sealed
trait
ToCoproductCodecs[C <: Coproduct, L <: HList] extends AnyRef
Witness that allows converting an
HList
of codecs in to a list of coproduct codecs, where the coproduct is type aligned with theHList
. -
trait
ToHListCodec[In <: HList] extends DepFn1[In]
Converts an
HList
of codecs in to a single codec.Converts an
HList
of codecs in to a single codec. That is, convertsCodec[X0] :: Codec[X1] :: ... :: Codec[Xn] :: HNil
in to aCodec[X0 :: X1 :: ... :: Xn :: HNil].
- final class Tuple10Codec[A, B, C, D, E, F, G, H, I, J] extends Codec[(A, B, C, D, E, F, G, H, I, J)]
- final class Tuple11Codec[A, B, C, D, E, F, G, H, I, J, K] extends Codec[(A, B, C, D, E, F, G, H, I, J, K)]
- final class Tuple12Codec[A, B, C, D, E, F, G, H, I, J, K, L] extends Codec[(A, B, C, D, E, F, G, H, I, J, K, L)]
- final class Tuple3Codec[A, B, C] extends Codec[(A, B, C)]
- final class Tuple4Codec[A, B, C, D] extends Codec[(A, B, C, D)]
- final class Tuple5Codec[A, B, C, D, E] extends Codec[(A, B, C, D, E)]
- final class Tuple6Codec[A, B, C, D, E, F] extends Codec[(A, B, C, D, E, F)]
- final class Tuple7Codec[A, B, C, D, E, F, G] extends Codec[(A, B, C, D, E, F, G)]
- final class Tuple8Codec[A, B, C, D, E, F, G, H] extends Codec[(A, B, C, D, E, F, G, H)]
- final class Tuple9Codec[A, B, C, D, E, F, G, H, I] extends Codec[(A, B, C, D, E, F, G, H, I)]
- final class TupleCodec[A, B] extends Codec[(A, B)]
-
implicit final
class
ValueEnrichedWithTuplingSupport[A] extends AnyRef
Allows creation of left nested pairs by successive usage of
~
operator. -
final
type
~[+A, +B] = (A, B)
Type alias for Tuple2 in order to allow left nested tuples to be written as A ~ B ~ C ~ ....
Value Members
-
val
ascii: Codec[String]
String codec that uses the
US-ASCII
charset.String codec that uses the
US-ASCII
charset. See string for more information onString
codecs. -
val
ascii32: Codec[String]
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. -
val
ascii32L: Codec[String]
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. -
def
bits(size: Long): Codec[BitVector]
Encodes by returning the supplied bit vector if its length is
size
bits, padding with zeroes if smaller thansize
bits, returning error if greater; decodes by takingsize
bits from the supplied bit vector.Encodes by returning the supplied bit vector if its length is
size
bits, padding with zeroes if smaller thansize
bits, returning error if greater; decodes by takingsize
bits from the supplied bit vector.- size
number of bits to encode/decode
-
def
bits: Codec[BitVector]
Encodes by returning supplied bit vector; decodes by taking all remaining bits in the supplied bit vector.
-
val
bitsRemaining: Codec[Boolean]
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.
-
def
bitsStrict(size: Long): Codec[BitVector]
Encodes by returning the supplied bit vector if its length is
size
bits, otherwise returning error; decodes by takingsize
bits from the supplied bit vector.Encodes by returning the supplied bit vector if its length is
size
bits, otherwise returning error; decodes by takingsize
bits from the supplied bit vector.- size
number of bits to encode/decode
-
def
bool(n: Long): Codec[Boolean]
n-bit boolean codec, where false corresponds to bit vector of all 0s and true corresponds to all other vectors.
-
val
bool: Codec[Boolean]
1-bit boolean codec, where false corresponds to bit value 0 and true corresponds to bit value 1.
-
def
byte(size: Int): Codec[Byte]
Codec for n-bit 2s complement bytes.
Codec for n-bit 2s complement bytes.
- size
number of bits (must be 0 < size <= 8)
-
val
byte: Codec[Byte]
Codec for 8-bit 2s complement bytes.
-
def
byteAligned[A](codec: Codec[A]): Codec[A]
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 allowsbyteAligned(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]
orByteBuffer
.- codec
codec to align to next larger byte boundary
-
def
bytes(size: Int): Codec[ByteVector]
Encodes by returning the supplied byte vector if its length is
size
bytes, padding with zeroes if smaller thansize
bytes, returning error if greater; decodes by takingsize * 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 thansize
bytes, returning error if greater; decodes by takingsize * 8
bits from the supplied bit vector and converting to a byte vector.- size
number of bits to encode/decode
-
def
bytes: Codec[ByteVector]
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.
-
def
bytesStrict(size: Int): Codec[ByteVector]
Encodes by returning the supplied byte vector if its length is
size
bytes, otherwise returning error; decodes by takingsize * 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 takingsize * 8
bits from the supplied bit vector and converting to a byte vector.- size
number of bits to encode/decode
-
def
certificate(certType: String): Codec[Certificate]
Codec that encodes/decodes certificates using their default encoding.
Codec that encodes/decodes certificates using their default encoding.
- certType
certificate type to pass to
java.security.cert.CertificateFactory.getInstance
-
def
checksummed[A](target: Codec[A], checksum: (BitVector) ⇒ BitVector, framing: Codec[(BitVector, BitVector)], validate: Boolean = true): Codec[A]
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 usingchecksum
, and finally, the encoded value and the checksum are converted to a single vector usingframing.encode(value -> chk)
.When decoding, the input vector is split in to an encoded value, a checksum value, and a remainder using
framing.decode
. Ifvalidate
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 withtarget
and the result is returned, with its remainder concatenated with the remainder of deframing. If the checksums do not match, aChecksumMismatch
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))
- target
codec used for encoding/decoding values of type
A
- checksum
computes a checksum of the input
- framing
codec used to convert the encoded value and computed checksum in to a single vector
-
def
choice[A](codecs: Codec[A]*): Codec[A]
Codec that encodes/decodes using the specified codecs by trying each codec in succession and using the first successful result.
-
def
conditional[A](included: Boolean, codec: ⇒ Codec[A]): Codec[Option[A]]
Codec of
Option[A]
that delegates to aCodec[A]
when theincluded
parameter is true.Codec of
Option[A]
that delegates to aCodec[A]
when theincluded
parameter is true.When encoding, if
included
is true and the value to encode is aSome
, 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 aSome
. Otherwise, aNone
is returned.- 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
codec to conditionally include
-
def
constant[A](bits: A*)(implicit arg0: Integral[A]): Codec[Unit]
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.- bits
constant bits
-
def
constant(bytes: ByteVector): Codec[Unit]
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.- bytes
constant bytes
-
def
constant(bits: BitVector): Codec[Unit]
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.- bits
constant bits
-
def
constantLenient[A](bits: A*)(implicit arg0: Integral[A]): Codec[Unit]
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.- bits
constant bits
-
def
constantLenient(bytes: ByteVector): Codec[Unit]
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.- bytes
constant bytes
-
def
constantLenient(bits: BitVector): Codec[Unit]
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.- bits
constant bits
-
def
constrainedVariableSizeBytes[A](size: Codec[Int], value: Codec[A], maxSize: Int): Codec[A]
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 mostmaxSize
bytes long.The
minSize
has the default value of0
.- size
codec that encodes/decodes the size in bits
- value
codec the encodes/decodes the value
- maxSize
maximum size in bytes that the message can have
-
def
constrainedVariableSizeBytes[A](size: Codec[Int], value: Codec[A], minSize: Int, maxSize: Int): Codec[A]
Codec that ensures variable size data is constrained within a minSize and maxSize bounds.
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 mostmaxSize
bytes long.The
minSize
has the default value of0
.- size
codec that encodes/decodes the size in bits
- value
codec the encodes/decodes the value
- minSize
minimum size in bytes that the message can have
- maxSize
maximum size in bytes that the message can have
-
def
constrainedVariableSizeBytesLong[A](size: Codec[Long], value: Codec[A], maxSize: Long): Codec[A]
Codec that ensures variable size data is constrained within a minSize and maxSize bounds.
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 mostmaxSize
bytes long.The
minSize
has the default value of0
.- size
codec that encodes/decodes the size in bits
- value
codec the encodes/decodes the value
- maxSize
maximum size in bytes that the message can have
-
def
constrainedVariableSizeBytesLong[A](size: Codec[Long], value: Codec[A], minSize: Long, maxSize: Long): Codec[A]
Codec that ensures variable size data is constrained within a minSize and maxSize bounds.
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 mostmaxSize
bytes long.The
minSize
has the default value of0
.- size
codec that encodes/decodes the size in bits
- value
codec the encodes/decodes the value
- minSize
minimum size in bytes that the message can have
- maxSize
maximum size in bytes that the message can have
-
val
cstring: Codec[String]
String codec that uses the
US-ASCII
charset that encodes strings with a trailingNUL
termination byte and decodes a string up to the nextNUL
termination byte.String codec that uses the
US-ASCII
charset that encodes strings with a trailingNUL
termination byte and decodes a string up to the nextNUL
termination byte. It fails to decode if the bit vector ends before aNUL
termination byte can be found. -
def
discriminated[A]: NeedDiscriminatorCodec[A]
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
forLeft
and1
forRight
, encoded via theuint8
codec. It then emits either an encodedA
, encoded usingcodecA
, or an encodedB
, usingcodecB
.Decoding is the mirror of this; the returned
codecE
will first read anInt
, using theuint8
codec. If it is a0
, it then runscodecA
, and injects the result intoEither
viaLeft.apply
. If it is a1
, it runscodecB
and injects the result intoEither
viaRight.apply
.There are a few variations on this syntax. See DiscriminatorCodec for details.
-
def
discriminatorFallback[L, R](left: Codec[L], right: Codec[R]): Codec[Either[L, R]]
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
).- left
codec to use when the right codec fails due to an unknown discriminator error
- right
codec to use by default when decoding
-
val
double: Codec[Double]
64-bit big endian IEEE 754 floating point number.
-
val
doubleL: Codec[Double]
64-bit little endian IEEE 754 floating point number.
-
def
either[L, R](indicator: Codec[Boolean], left: Codec[L], right: Codec[R]): Codec[Either[L, R]]
Either codec that supports bit vectors of form
indicator ++ (left or right)
where a value offalse
for the indicator indicates it is followed by a left value and a value oftrue
indicates it is followed by a right value.Either codec that supports bit vectors of form
indicator ++ (left or right)
where a value offalse
for the indicator indicates it is followed by a left value and a value oftrue
indicates it is followed by a right value.- 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
-
def
encrypted[A](codec: Codec[A])(implicit cipherFactory: CipherFactory): Codec[A]
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
codec that encodes a value to plaintext bits and decodes plaintext bits to a value
- cipherFactory
factory to use for encryption/decryption
-
def
endiannessDependent[A](big: Codec[A], little: Codec[A])(implicit ordering: ByteOrdering): Codec[A]
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.
- big
codec to use when big endian
- little
codec to use when little endian
-
def
enumerated(discriminator: Codec[Int], enumeration: Enumeration): DiscriminatorCodec[Value, Int]
Codec for an
Enumeration
that encodes/decodes usingEnumeration.Value.id
values.Codec for an
Enumeration
that encodes/decodes usingEnumeration.Value.id
values.- discriminator
the codec for
Enumeration.Value.id
values- enumeration
the target
Enumeration
-
def
fail[A](encErr: Err, decErr: Err): Codec[A]
Codec that always fails encoding and decoding with the specified messages.
-
def
fail[A](err: Err): Codec[A]
Codec that always fails encoding and decoding with the specified message.
-
def
fallback[L, R](left: Codec[L], right: Codec[R]): Codec[Either[L, R]]
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.- left
codec the encodes a left value
- right
codec the encodes a right value
-
def
filtered[A](codec: Codec[A], filter: Codec[BitVector]): Codec[A]
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 ofcodec.decode
.- codec
the target codec
- filter
a codec that represents pre/post-processing stages for input/output bits
-
def
fixedSizeBits[A](size: Long, codec: Codec[A]): 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 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.- size
number of bits
- codec
codec to limit
-
def
fixedSizeBytes[A](size: Long, codec: Codec[A]): Codec[A]
Byte equivalent of fixedSizeBits.
Byte equivalent of fixedSizeBits.
- size
number of bytes
- codec
codec to limit
-
def
fixedSizeSignature[A](size: Int)(codec: Codec[A])(implicit signerFactory: SignerFactory): Codec[A]
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
size in bytes of signature
- codec
codec to use to encode/decode value field
-
val
float: Codec[Float]
32-bit big endian IEEE 754 floating point number.
-
val
floatL: Codec[Float]
32-bit little endian IEEE 754 floating point number.
-
def
hlist[L <: HList](l: L)(implicit toHListCodec: ToHListCodec[L]): Out
Converts an
HList
of codecs in to a single codec.Converts an
HList
of codecs in to a single codec. That is, convertsCodec[X0] :: Codec[X1] :: ... :: Codec[Xn] :: HNil
in to aCodec[X0 :: X1 :: ... :: Xn :: HNil].
-
def
ignore(size: Long): Codec[Unit]
Codec that always encodes
size
0 bits and always decodessize
bits and then discards them, returning()
instead.Codec that always encodes
size
0 bits and always decodessize
bits and then discards them, returning()
instead.- size
number of bits to ignore
-
def
int(size: Int): Codec[Int]
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
.- size
number of bits (must be 0 < size <= 32)
-
val
int16: Codec[Int]
Codec for 16-bit 2s complement big-endian integers.
-
val
int16L: Codec[Int]
Codec for 16-bit 2s complement little-endian integers.
-
val
int24: Codec[Int]
Codec for 24-bit 2s complement big-endian integers.
-
val
int24L: Codec[Int]
Codec for 24-bit 2s complement little-endian integers.
-
val
int32: Codec[Int]
Codec for 32-bit 2s complement big-endian integers.
-
val
int32L: Codec[Int]
Codec for 32-bit 2s complement little-endian integers.
-
val
int64: Codec[Long]
Codec for 64-bit 2s complement big-endian integers.
-
val
int64L: Codec[Long]
Codec for 64-bit 2s complement little-endian integers.
-
val
int8: Codec[Int]
Codec for 8-bit 2s complement big-endian integers.
-
val
int8L: Codec[Int]
Codec for 8-bit 2s complement little-endian integers.
-
def
intL(bits: Int): Codec[Int]
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
.- bits
number of bits (must be 0 < size <= 32)
-
def
lazily[A](codec: ⇒ Codec[A]): Codec[A]
Provides a
Codec[A]
that delegates to a lazily evaluatedCodec[A]
. -
implicit final
def
liftF2ToNestedTupleF[A, B, X](fn: (A, B) ⇒ X): ((A, B)) ⇒ X
Allows use of a 2-arg function as a single arg function that takes a left-associated stack of pairs with 2 total elements.
-
implicit final
def
liftF3ToNestedTupleF[A, B, C, X](fn: (A, B, C) ⇒ X): (((A, B), C)) ⇒ X
Allows use of a 3-arg function as a single arg function that takes a left-associated stack of pairs with 3 total elements.
-
implicit final
def
liftF4ToNestedTupleF[A, B, C, D, X](fn: (A, B, C, D) ⇒ X): ((((A, B), C), D)) ⇒ X
Allows use of a 4-arg function as a single arg function that takes a left-associated stack of pairs with 4 total elements.
-
implicit final
def
liftF5ToNestedTupleF[A, B, C, D, E, X](fn: (A, B, C, D, E) ⇒ X): (((((A, B), C), D), E)) ⇒ X
Allows use of a 5-arg function as a single arg function that takes a left-associated stack of pairs with 5 total elements.
-
implicit final
def
liftF6ToNestedTupleF[A, B, C, D, E, F, X](fn: (A, B, C, D, E, F) ⇒ X): ((((((A, B), C), D), E), F)) ⇒ X
Allows use of a 6-arg function as a single arg function that takes a left-associated stack of pairs with 6 total elements.
-
implicit final
def
liftF7ToNestedTupleF[A, B, C, D, E, F, G, X](fn: (A, B, C, D, E, F, G) ⇒ X): (((((((A, B), C), D), E), F), G)) ⇒ X
Allows use of a 7-arg function as a single arg function that takes a left-associated stack of pairs with 7 total elements.
-
implicit final
def
liftF8ToNestedTupleF[A, B, C, D, E, F, G, H, X](fn: (A, B, C, D, E, F, G, H) ⇒ X): ((((((((A, B), C), D), E), F), G), H)) ⇒ X
Allows use of an 8-arg function as a single arg function that takes a left-associated stack of pairs with 8 total elements.
-
def
limitedSizeBits[A](limit: Long, codec: Codec[A]): 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.- codec
codec to limit
-
def
limitedSizeBytes[A](limit: Long, codec: Codec[A]): Codec[A]
Byte equivalent of limitedSizeBits.
Byte equivalent of limitedSizeBits.
- codec
codec to limit
-
def
list[A](codec: Codec[A]): Codec[List[A]]
Codec that encodes/decodes a
List[A]
from aCodec[A]
.Codec that encodes/decodes a
List[A]
from aCodec[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 eachdecode
is returned in the list.- codec
codec to encode/decode a single element of the sequence
-
def
listDelimited[A](delimiter: BitVector, valueCodec: Codec[A]): Codec[List[A]]
Codec that encodes/decodes a
List[A]
from aCodec[A]
.Codec that encodes/decodes a
List[A]
from aCodec[A]
.When encoding, each
A
in the list is encoded and all of the resulting bits are concatenated usingdelimiter
.When decoding, the input bits are first (logically) grouped into
delimiter
sized chunks and partitioned arounddelimiter
chunks. Then, the individual partitions are (concatenated and) decoded using thevalueCodec
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 thedelimiter
usingBitVector.indexOfSlice
but this would work only if value bits do not contain thedelimiter
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")
- A
element type
- delimiter
the bits used to separate element bit values
- valueCodec
element codec (used to decode next bits)
-
def
listMultiplexed[A](mux: (BitVector, BitVector) ⇒ BitVector, deMux: (BitVector) ⇒ (BitVector, BitVector), valueCodec: Codec[A]): Codec[List[A]]
Codec that encodes/decodes a
List[A]
from aCodec[A]
.Codec that encodes/decodes a
List[A]
from aCodec[A]
.When encoding, each
A
in the list is encoded and all of the resulting bits are combined usingmux
.When decoding,
deMux
is called repeatedly to obtain the next bits (to decode usingvalueCodec
) and the remaining bits (input todeMux
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
.- A
element type
- mux
element multiplexer
- deMux
element de-multiplexer (should return the next bits to decode and the remaining bits for next iteration)
- valueCodec
element codec (used to decode next bits)
-
def
listOfN[A](countCodec: Codec[Int], valueCodec: Codec[A]): Codec[List[A]]
Codec that encodes/decodes a
List[A]
ofN
elements using aCodec[A]
.Codec that encodes/decodes a
List[A]
ofN
elements using aCodec[A]
.When encoding, the number of elements in the list is encoded using
countCodec
and the values are then each encoded usingvalueCodec
.When decoding, the number of elements is decoded using
countCodec
and then that number of elements are decoded usingvalueCodec
. Any remaining bits are returned.Note: when the count is known statically, use
listOfN(provide(count), ...)
. -
def
logBuilder[A](logEncode: (A, Attempt[BitVector]) ⇒ Unit, logDecode: (BitVector, Attempt[DecodeResult[A]]) ⇒ Unit)(codec: Codec[A]): Codec[A]
Wraps a codec and adds logging of each encoding and decoding operation.
Wraps a codec and adds logging of each encoding and decoding operation.
The
logEncode
andlogDecode
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.
-
def
logFailuresBuilder[A](logEncode: (A, Err) ⇒ Unit, logDecode: (BitVector, Err) ⇒ Unit)(codec: Codec[A]): Codec[A]
Variant of logBuilder that only logs failed results.
-
def
logFailuresToStdOut[A](codec: Codec[A], prefix: String = ""): Codec[A]
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
prefix string to include in each log statement
-
def
logSuccessesBuilder[A](logEncode: (A, BitVector) ⇒ Unit, logDecode: (BitVector, DecodeResult[A]) ⇒ Unit)(codec: Codec[A]): Codec[A]
Variant of logBuilder that only logs successful results.
-
def
logToStdOut[A](codec: Codec[A], prefix: String = ""): Codec[A]
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
prefix string to include in each log statement
-
def
long(bits: Int): Codec[Long]
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
.- bits
number of bits (must be 0 < size <= 64)
-
def
longL(bits: Int): Codec[Long]
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
.- bits
number of bits (must be 0 < size <= 64)
-
def
lookahead(target: Codec[Unit]): Codec[Boolean]
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.
- target
codec to recover errors from
-
def
lpbcd(nibbles: Int): Codec[Long]
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.- nibbles
number of nibbles (4-bit chunks)
-
def
mappedEnum[A, B](discriminatorCodec: Codec[B], map: Map[A, B]): DiscriminatorCodec[A, B]
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.
- discriminatorCodec
codec used to encode/decode tag value
- map
mapping from tag values to/from enum values
-
def
mappedEnum[A, B](discriminatorCodec: Codec[B], mappings: (A, B)*): DiscriminatorCodec[A, B]
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.
- discriminatorCodec
codec used to encode/decode tag value
- mappings
mapping from tag values to/from enum values
-
def
optional[A](guard: Codec[Boolean], target: Codec[A]): Codec[Option[A]]
Codec of
Option[A]
that delegates to aCodec[A]
when theguard
codec decodes a true.Codec of
Option[A]
that delegates to aCodec[A]
when theguard
codec decodes a true.When encoding, a
Some
results inguard
encoding atrue
andtarget
encoding the value. ANone
results inguard
encoding a false and thetarget
not encoding anything.Various guard codecs and combinators are provided by this library -- e.g.,
bitsRemaining
andrecover
.- guard
codec that determines whether the target codec is included
- target
codec to conditionally include
-
def
paddedFixedSizeBits[A](size: Long, codec: Codec[A], padCodec: Codec[Unit]): 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.
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.- size
number of bits
- codec
codec to limit
- padCodec
codec to use for padding
-
def
paddedFixedSizeBitsDependent[A](size: Long, codec: Codec[A], padCodec: (Long) ⇒ Codec[Unit]): Codec[A]
Codec that limits the number of bits the specified codec works with.
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 frompadCodec(remainingBitCount)
. A decoding error is returned if any padding decode iteration returns an error.- size
number of bits
- codec
codec to limit
- padCodec
function that provides the codec to use for padding
-
def
paddedFixedSizeBytes[A](size: Long, codec: Codec[A], padCodec: Codec[Unit]): Codec[A]
Byte equivalent of paddedFixedSizeBits.
Byte equivalent of paddedFixedSizeBits.
- size
number of bytes
- codec
codec to limit
- padCodec
codec to use for padding
-
def
paddedFixedSizeBytesDependent[A](size: Long, codec: Codec[A], padCodec: (Long) ⇒ Codec[Unit]): Codec[A]
Byte equivalent of paddedFixedSizeBitsDependent.
Byte equivalent of paddedFixedSizeBitsDependent.
The
padCodec
function is passed the number of *bits* of padding required -- not bytes.- size
number of bytes
- codec
codec to limit
- padCodec
function that provides the codec to use for padding
-
def
paddedVarAlignedBits[A](sizeCodec: Codec[Long], valueCodec: Codec[A], multipleForPadding: Int): PaddedVarAlignedCodec[A]
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
- sizeCodec
codec that determines the size
- valueCodec
codec for encoding the payload
- multipleForPadding
multiple to align the value to with padding
-
def
paddedVarAlignedBytes[A](sizeCodec: Codec[Int], valueCodec: Codec[A], multipleForPadding: Int): Codec[A] { val sizedWiden: scodec.Codec[Long] }
Byte equivalent of paddedVarAligendBits.
Byte equivalent of paddedVarAligendBits.
- sizeCodec
codec that determines the size
- valueCodec
coec for encoding the payload
- multipleForPadding
multiple of bytes to align the value to with padding
-
def
pbcd(nibbles: Int): Codec[Long]
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
.- nibbles
number of nibbles (4-bit chunks)
-
def
peek[A](target: Codec[A]): Codec[A]
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.
- target
codec that encodes/decodes the value
- returns
codec that behaves the same as
target
but resets remainder to the input vector after decoding
-
def
peekVariableSizeBits(size: Codec[Int], sizePadding: Int = 0): Codec[BitVector]
Codec that decodes vectors of the form
size ++ rest
as aBitVector
, where the returned vector includes the size bits.Codec that decodes vectors of the form
size ++ rest
as aBitVector
, 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
size codec -- must have an exact size
- sizePadding
number of bits to subtract from the size before decoding
-
def
peekVariableSizeBitsLong(size: Codec[Long], sizePadding: Long = 0L): Codec[BitVector]
Long
equivalent of peekVariableSizeBits.Long
equivalent of peekVariableSizeBits.- size
size codec -- must have an exact size
- sizePadding
number of bits to subtract from the size before decoding
-
def
peekVariableSizeBytes(size: Codec[Int], sizePadding: Int = 0): Codec[BitVector]
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
size codec -- must have an exact size
- sizePadding
number of bytes to subtract from the size before decoding
-
def
peekVariableSizeBytesLong(size: Codec[Long], sizePadding: Long = 0L): Codec[BitVector]
Long
equivalent of peekVariableSizeBytes.Long
equivalent of peekVariableSizeBytes.- size
size codec -- must have an exact size
- sizePadding
number of bits to subtract from the size before decoding
-
def
provide[A](value: A): Codec[A]
Codec that always returns an empty vector from
encode
and always returns(empty, value)
fromdecode
.Codec that always returns an empty vector from
encode
and always returns(empty, value)
fromdecode
. This is often useful when combined with other codecs (e.g., the discriminated).- value
value to return from decode
-
def
recover(target: Codec[Unit]): Codec[Boolean]
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.
- target
codec to recover errors from
-
def
short(size: Int): Codec[Short]
Codec for n-bit 2s complement big-endian shorts.
Codec for n-bit 2s complement big-endian shorts.
- size
number of bits (must be 0 < size <= 16)
-
val
short16: Codec[Short]
Codec for 16-bit 2s complement big-endian shorts.
-
val
short16L: Codec[Short]
Codec for 16-bit 2s complement little-endian shorts.
-
def
shortL(size: Int): Codec[Short]
Codec for n-bit 2s complement little-endian shorts.
Codec for n-bit 2s complement little-endian shorts.
- size
number of bits (must be 0 < size <= 16)
-
def
sizedList[A](size: Nat, codec: Codec[A])(implicit toInt: ToInt[N]): Codec[Sized[List[A], N]]
Codec that encodes/decodes a list of
n
elements, wheren
is known at compile time.Codec that encodes/decodes a list of
n
elements, wheren
is known at compile time.- size
number of elements in the list
- codec
codec to encode/decode a single element of the sequence
-
def
sizedVector[A](size: Nat, codec: Codec[A])(implicit toInt: ToInt[N]): Codec[Sized[Vector[A], N]]
Codec that encodes/decodes a vector of
n
elements, wheren
is known at compile time.Codec that encodes/decodes a vector of
n
elements, wheren
is known at compile time.- size
number of elements in the vector
- codec
codec to encode/decode a single element of the sequence
-
def
string(implicit charset: Charset): Codec[String]
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
charset to use to convert strings to/from binary
-
def
string32(implicit charset: Charset): Codec[String]
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
charset to use to convert strings to/from binary
-
def
string32L(implicit charset: Charset): Codec[String]
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
charset to use to convert strings to/from binary
-
def
ubyte(size: Int): Codec[Byte]
Codec for n-bit unsigned bytes.
Codec for n-bit unsigned bytes.
- size
number of bits (must be 0 < size <= 7)
-
def
uint(bits: Int): Codec[Int]
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
.- bits
number of bits (must be 0 < size <= 31)
-
val
uint16: Codec[Int]
Codec for 16-bit unsigned big-endian integers.
-
val
uint16L: Codec[Int]
Codec for 16-bit unsigned little-endian integers.
-
val
uint2: Codec[Int]
Codec for 2-bit unsigned big-endian integers.
-
val
uint24: Codec[Int]
Codec for 24-bit unsigned big-endian integers.
-
val
uint24L: Codec[Int]
Codec for 24-bit unsigned little-endian integers.
-
val
uint2L: Codec[Int]
Codec for 2-bit unsigned little-endian integers.
-
val
uint32: Codec[Long]
Codec for 32-bit unsigned big-endian integers.
-
val
uint32L: Codec[Long]
Codec for 32-bit unsigned little-endian integers.
-
val
uint4: Codec[Int]
Codec for 4-bit unsigned big-endian integers.
-
val
uint4L: Codec[Int]
Codec for 4-bit unsigned little-endian integers.
-
val
uint8: Codec[Int]
Codec for 8-bit unsigned big-endian integers.
-
val
uint8L: Codec[Int]
Codec for 8-bit unsigned little-endian integers.
-
def
uintL(bits: Int): Codec[Int]
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
.- bits
number of bits (must be 0 < size <= 31)
-
def
ulong(bits: Int): Codec[Long]
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
.- bits
number of bits (must be 0 < size <= 63)
-
def
ulongL(bits: Int): Codec[Long]
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
.- bits
number of bits (must be 0 < size <= 63)
-
def
ushort(size: Int): Codec[Short]
Codec for n-bit unsigned big-endian shorts.
Codec for n-bit unsigned big-endian shorts.
- size
number of bits (must be 0 < size <= 15)
-
val
ushort8: Codec[Short]
Codec for 8-bit unsigned bytes.
-
def
ushortL(size: Int): Codec[Short]
Codec for n-bit unsigned little-endian shorts.
Codec for n-bit unsigned little-endian shorts.
- size
number of bits (must be 0 < size <= 15)
-
val
utf8: Codec[String]
String codec that uses the
UTF-8
charset.String codec that uses the
UTF-8
charset. See string for more information onString
codecs. -
val
utf8_32: Codec[String]
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. -
val
utf8_32L: Codec[String]
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. -
val
uuid: Codec[UUID]
Encodes/decodes
UUID
s as 2 64-bit big-endian longs, first the high 64-bits then the low 64-bits. -
def
variableSizeBits[A](size: Codec[Int], value: Codec[A], sizePadding: Int = 0): Codec[A]
Codec that supports vectors of the form
size ++ value
where thesize
field decodes to the bit length of thevalue
field.Codec that supports vectors of the form
size ++ value
where thesize
field decodes to the bit length of thevalue
field.For example, encoding the string
"hello"
withvariableSizeBits(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 anyInt
codec. An optional padding can be applied to the size field. ThesizePadding
is added to the calculated size before encoding, and subtracted from the decoded size before decoding the value.For example, encoding
"hello"
withvariableSizeBits(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"
.- size
codec that encodes/decodes the size in bits
- value
codec the encodes/decodes the value
- sizePadding
number of bits to add to the size before encoding (and subtract from the size before decoding)
-
def
variableSizeBitsLong[A](size: Codec[Long], value: Codec[A], sizePadding: Long = 0): Codec[A]
Codec that supports vectors of the form
size ++ value
where thesize
field decodes to the bit length of thevalue
field.Codec that supports vectors of the form
size ++ value
where thesize
field decodes to the bit length of thevalue
field.For example, encoding the string
"hello"
withvariableSizeBitsLong(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 anyLong
codec. An optional padding can be applied to the size field. ThesizePadding
is added to the calculated size before encoding, and subtracted from the decoded size before decoding the value.For example, encoding
"hello"
withvariableSizeBitsLong(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"
.- size
codec that encodes/decodes the size in bits
- value
codec the encodes/decodes the value
- sizePadding
number of bits to add to the size before encoding (and subtract from the size before decoding)
-
def
variableSizeBytes[A](size: Codec[Int], value: Codec[A], sizePadding: Int = 0): Codec[A]
Byte equivalent of variableSizeBits.
Byte equivalent of variableSizeBits.
- size
codec that encodes/decodes the size in bytes
- value
codec the encodes/decodes the value
- sizePadding
number of bytes to add to the size before encoding (and subtract from the size before decoding)
-
def
variableSizeBytesLong[A](size: Codec[Long], value: Codec[A], sizePadding: Long = 0): Codec[A]
Byte equivalent of variableSizeBitsLong.
Byte equivalent of variableSizeBitsLong.
- size
codec that encodes/decodes the size in bytes
- value
codec the encodes/decodes the value
- sizePadding
number of bytes to add to the size before encoding (and subtract from the size before decoding)
-
def
variableSizeDelimited[A](delimiterCodec: Codec[Unit], value: Codec[A], multipleValueSize: Long): Codec[A]
Codec that supports vectors of the form
value ++ delimiter
where thedelimiter
marks the end of thevalue
field.Codec that supports vectors of the form
value ++ delimiter
where thedelimiter
marks the end of thevalue
field.- value
codec the encodes/decodes the value
- multipleValueSize
the size or a mutiple size of the expected value
-
def
variableSizeDelimited[A](delimiterCodec: Codec[Unit], value: Codec[A]): Codec[A]
Codec that supports vectors of the form
value ++ delimiter
where thedelimiter
marks the end of thevalue
field.Codec that supports vectors of the form
value ++ delimiter
where thedelimiter
marks the end of thevalue
field.- value
codec the encodes/decodes the value
-
def
variableSizePrefixedBits[A, B](size: Codec[Int], prefix: Codec[A], value: Codec[B], sizePadding: Int = 0): Codec[(A, B)]
Codec that supports vectors of the form
size ++ prefix ++ value
where thesize
field decodes to the bit length of thevalue
field.Codec that supports vectors of the form
size ++ prefix ++ value
where thesize
field decodes to the bit length of thevalue
field.For example, encoding
(3, "hello")
withvariableSizePrefixedBits(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 anyInt
codec. An optional padding can be applied to the size field. ThesizePadding
is added to the calculated size before encoding, and subtracted from the decoded size before decoding the value.For example, encoding
(3, "hello")
withvariableSizePrefixedBits(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"
.- size
codec that encodes/decodes the size in bits
- prefix
codec that encodes/decodes the prefix
- value
codec the encodes/decodes the value
- sizePadding
number of bits to add to the size before encoding (and subtract from the size before decoding)
-
def
variableSizePrefixedBitsLong[A, B](size: Codec[Long], prefix: Codec[A], value: Codec[B], sizePadding: Long = 0): Codec[(A, B)]
Codec that supports vectors of the form
size ++ prefix ++ value
where thesize
field decodes to the bit length of thevalue
field.Codec that supports vectors of the form
size ++ prefix ++ value
where thesize
field decodes to the bit length of thevalue
field.For example, encoding the string
(3, "hello")
withvariableSizePrefixedBitsLong(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 anyLong
codec. An optional padding can be applied to the size field. ThesizePadding
is added to the calculated size before encoding, and subtracted from the decoded size before decoding the value.For example, encoding
(3, "hello")
withvariableSizePrefixedBitsLong(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"
.- size
codec that encodes/decodes the size in bits
- prefix
codec that encodes/decodes the prefix
- value
codec the encodes/decodes the value
- sizePadding
number of bits to add to the size before encoding (and subtract from the size before decoding)
-
def
variableSizePrefixedBytes[A, B](size: Codec[Int], prefix: Codec[A], value: Codec[B], sizePadding: Int = 0): Codec[(A, B)]
Byte equivalent of variableSizePrefixedBits.
Byte equivalent of variableSizePrefixedBits.
- size
codec that encodes/decodes the size in bytes
- prefix
codec that encodes/decodes the prefix
- value
codec the encodes/decodes the value
- sizePadding
number of bytes to add to the size before encoding (and subtract from the size before decoding)
-
def
variableSizePrefixedBytesLong[A, B](size: Codec[Long], prefix: Codec[A], value: Codec[B], sizePadding: Long = 0): Codec[(A, B)]
Byte equivalent of variableSizePrefixedBitsLong.
Byte equivalent of variableSizePrefixedBitsLong.
- size
codec that encodes/decodes the size in bytes
- prefix
codec that encodes/decodes the prefix
- value
codec the encodes/decodes the value
- sizePadding
number of bytes to add to the size before encoding (and subtract from the size before decoding)
-
def
variableSizeSignature[A](size: Codec[Int])(codec: Codec[A])(implicit signerFactory: SignerFactory): Codec[A]
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.
- size
codec to use to encode/decode size of signature field
- codec
codec to use to encode/decode value field
-
def
vector[A](codec: Codec[A]): Codec[Vector[A]]
Codec that encodes/decodes a
Vector[A]
from aCodec[A]
.Codec that encodes/decodes a
Vector[A]
from aCodec[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 eachdecode
is returned in the vector.- codec
codec to encode/decode a single element of the sequence
-
def
vectorDelimited[A](delimiter: BitVector, valueCodec: Codec[A]): Codec[Vector[A]]
Codec that encodes/decodes a
Vector[A]
from aCodec[A]
.Codec that encodes/decodes a
Vector[A]
from aCodec[A]
.When encoding, each
A
in the vector is encoded and all of the resulting bits are concatenated usingdelimiter
.When decoding, the input bits are first (logically) grouped into
delimiter
sized chunks and partitioned arounddelimiter
chunks. Then, the individual partitions are (concatenated and) decoded using thevalueCodec
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 thedelimiter
usingBitVector.indexOfSlice
but this would work only if value bits do not contain thedelimiter
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")
- A
element type
- delimiter
the bits used to separate element bit values
- valueCodec
element codec (used to decode next bits)
-
def
vectorMultiplexed[A](mux: (BitVector, BitVector) ⇒ BitVector, deMux: (BitVector) ⇒ (BitVector, BitVector), valueCodec: Codec[A]): Codec[Vector[A]]
Codec that encodes/decodes a
Vector[A]
from aCodec[A]
.Codec that encodes/decodes a
Vector[A]
from aCodec[A]
.When encoding, each
A
in the vector is encoded and all of the resulting bits are combined usingmux
.When decoding,
deMux
is called repeatedly to obtain the next bits (to decode usingvalueCodec
) and the remaining bits (input todeMux
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
.- A
element type
- mux
element multiplexer
- deMux
element de-multiplexer (should return the next bits to decode and the remaining bits for next iteration)
- valueCodec
element codec (used to decode next bits)
-
def
vectorOfN[A](countCodec: Codec[Int], valueCodec: Codec[A]): Codec[Vector[A]]
Codec that encodes/decodes a
Vector[A]
ofN
elements using aCodec[A]
.Codec that encodes/decodes a
Vector[A]
ofN
elements using aCodec[A]
.When encoding, the number of elements in the vector is encoded using
countCodec
and the values are then each encoded usingvalueCodec
.When decoding, the number of elements is decoded using
countCodec
and then that number of elements are decoded usingvalueCodec
. Any remaining bits are returned.Note: when the count is known statically, use
vectorOfN(provide(count), ...)
. -
val
vint: Codec[Int]
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.
-
val
vintL: Codec[Int]
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.
-
val
vlong: Codec[Long]
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.
-
val
vlongL: Codec[Long]
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.
-
val
vpbcd: Codec[Long]
Codec for variable-length packed decimal longs.
Codec for variable-length packed decimal longs. Negative values are not supported.
-
def
withDefault[A](opt: Codec[Option[A]], default: Codec[A]): Codec[A]
Creates a
Codec[A]
from aCodec[Option[A]]
and a fallbackCodec[A]
.Creates a
Codec[A]
from aCodec[Option[A]]
and a fallbackCodec[A]
.When encoding, the
A
is encoded withopt
(by wrapping it in aSome
). When decoding,opt
is first used to decode the buffer. If it decodes aSome(a)
, that value is returned. If it decodes aNone
,default
is used to decode the buffer.- opt
optional codec
- default
fallback codec used during decoding when
opt
decodes aNone
-
def
withDefaultValue[A](opt: Codec[Option[A]], default: A): Codec[A]
Creates a
Codec[A]
from aCodec[Option[A]]
and a fallback valueA
.Creates a
Codec[A]
from aCodec[Option[A]]
and a fallback valueA
.When encoding, the
A
is encoded withopt
(by wrapping it in aSome
). When decoding,opt
is first used to decode the buffer. If it decodes aSome(a)
, that value is returned. If it decodes aNone
, thedefault
value is return.- opt
optional codec
- default
fallback value returned from
decode
whenopt
decodes aNone
-
def
x509Certificate: Codec[X509Certificate]
Codec that encodes/decodes certificates using their default encoding.
-
def
zlib[A](codec: Codec[A], level: Int = Deflater.DEFAULT_COMPRESSION, strategy: Int = Deflater.DEFAULT_STRATEGY, nowrap: Boolean = false, chunkSize: Int = 4096): Codec[A]
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.
- level
compression level, 0-9, with 0 disabling compression and 9 being highest level of compression -- see
java.util.zip.Deflater
for details- strategy
compression strategy -- see
java.util.zip.Deflater
for details- nowrap
if true, ZLIB header and checksum will not be used
- chunkSize
buffer size, in bytes, to use when compressing
-
object
ChecksumCodec
Provides methods to create a "checksum codec" (encodes a bit-range to a bit-checksum and decodes bits to a bit-range).
-
object
ChecksumFactory
Creates checksum implementations of SignerFactory.
-
object
CipherFactory
Companion for CipherFactory.
-
object
CoproductBuilderAuto
Companion for CoproductBuilderAuto.
-
object
CoproductBuilderAutoDiscriminators
Companion for CoproductBuilderAutoDiscriminators.
-
object
CoproductBuilderKeyDiscriminators
Companion for CoproductBuilderKeyDiscriminators.
-
object
CoproductCodecBuilder
Companion for CoproductCodecBuilder.
- object DeMultiplexer
-
object
DeriveHListElementAux
Companion for DeriveHListElementAux.
-
object
Discriminated extends Serializable
Companion for Discriminated.
-
object
DropUnits extends DropUnitsLowPriority
Companion for DropUnits.
-
object
FlattenLeftPairs
Companion for FlattenLeftPairs.
-
object
InvertibleRemove
Companion for InvertibleRemove.
-
object
SignatureFactory
Create
java.security.Signature
implementations for SignerFactory -
object
ToCoproductCodecs
Companion for ToCoproductCodecs.
-
object
ToHListCodec
Companion for ToHListCodec.
- object VarIntCodec
- object VarLongCodec
-
object
implicits extends ImplicitCodecs
Provides common implicit codecs.
-
object
literals
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 as0x47 ~> uint8
.Supports literal bytes, ints,
BitVector
s, andByteVector
s. -
object
~ extends Serializable
Extractor that allows pattern matching on the tuples created by tupling codecs.