Package

scodec

codecs

Permalink

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 BitVectors 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.Certificates is provided by certificate and x509Certificate.

Source
package.scala
Linear Supertypes
Content Hierarchy
Ordering
  1. Grouped
  2. Alphabetic
  3. By Inheritance
Inherited
  1. codecs
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Type Members

  1. case class ChecksumMismatch(bits: BitVector, expected: BitVector, actual: BitVector, context: List[String] = Nil) extends Err with Product with Serializable

    Permalink

    Indicates a checksum over bits did not match the expected value.

  2. trait CipherFactory extends AnyRef

    Permalink

    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.

  3. sealed abstract class CoproductBuilderAuto[A] extends DepFn0

    Permalink

    Witness that a coproduct codec builder of type A can be automatically created.

  4. sealed abstract class CoproductBuilderAutoDiscriminators[X, C <: Coproduct, A] extends AnyRef

    Permalink

    Witness for CoproductCodecBuilder#NeedDiscriminators#auto.

  5. sealed abstract class CoproductBuilderKeyDiscriminators[C <: Coproduct, L <: HList, A] extends AnyRef

    Permalink

    Witness for CoproductCodecBuilder#NeedDiscriminators#using.

  6. final class CoproductCodecBuilder[C <: Coproduct, L <: HList, R] extends AnyRef

    Permalink

    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) or discriminatedBy(codec) followed by one of the methods on NeedDiscriminators. The former uses the type index as the discriminator value.

    For example:

    (int32 :+: bool(8) :+: variableSizeBytes(uint8, ascii)).discriminatedByIndex(uint8)

    The first 8 bits of the resulting binary contains the discriminator value due to usage of the uint8 codec as the discriminator codec. A discriminator value of 0 causes the remaining bits to be encoded/decoded with int32. Similarly, a value of 1 causes the remaining bits to be encoded/decoded with bool(8) and a value of 2 causes the remaining bits to be encoded/decoded as a sized ASCII string.

    Alternatively, discriminator values can be explicitly specified using discriminatedBy(codec).using(Sized(...)).

    For example:

    (int32 :+: bool(8) :+: variableSizeBytes(uint8, ascii)).discriminatedBy(fixedSizeBytes(1, ascii)).using(Sized("i", "b", "s"))

    In this example, integers are associated with the discriminator i, booleans with b, and strings with s. The discriminator is encoded with fixedSizeBytes(1, ascii).

    The methods which generate a Codec return a Codec[R] instead of a Codec[C]. Typically, C =:= R but the xmap and exmap methods allow transformations between C and R to be deferred until after the codec is built.

    C

    coproduct type

    L

    hlist type that has a codec for each type in the coproduct C

    R

    resulting codec type

  7. final class DeriveHListElementAux[L <: HList, A] extends AnyVal

    Permalink

    Provides syntax support for Codec[L]#derive for some HList L.

    Provides syntax support for Codec[L]#derive for some HList L. See derive for more information.

  8. final case class Discriminated[X, D](codec: Codec[D], framing: CodecTransformation) extends Product with Serializable

    Permalink

    Wrapper class that indicates subtypes of X are discriminated by type D using the supplied Codec[D].

    Wrapper class that indicates subtypes of X are discriminated by type D using the supplied Codec[D].

    For example, an implicit Discriminated value can be defined in the companion of a sealed trait, along with implicit Discriminator values in each subtype companion. Given such implicits, a codec for the trait can be automatically derived using Codec[X].

    Contains an optional codec transformation, which is applied to every component codec before encoding/decoding. This allows common structure, e.g., size based framing, to be specified in one location.

    For example, if each discriminated subtype is prefixed by a size field, the framing could be specified as:

    Discriminated[X, D](uint, new CodecTransformation {
      def apply[Z](c: Codec[Z]) = variableSizeBytes(uint16, c)
    })
    X

    type that can be discriminated by discriminator values of type D

    D

    value type that discriminates Y in context of X from other types using discriminators of D for some type Y

  9. final case class Discriminator[X, Y, D](value: D) extends Product with Serializable

    Permalink

    Wrapper class that discriminates type Y in context of type X with a value of type D.

    Wrapper class that discriminates type Y in context of type X with a value of type D.

    For example, consider a sealed trait and its subclasses. Each subclass could be assigned an integer by defining a Discriminator[Parent, Subclass, Int] for each.

    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 of X

  10. final class DiscriminatorCodec[A, B] extends Codec[A] with KnownDiscriminatorType[B]

    Permalink

    Codec that supports the binary structure tag ++ value where the tag identifies the encoding/decoding of the value.

    Codec that supports the binary structure tag ++ value where the tag identifies the encoding/decoding of the value.

    To build an instance of this codec, call discriminated and specify the tag type via the by method. Then call one more more of the case combinators on this class.

    Each of the case combinators provides two forms, one that defines a case with a single tag value and another, overloaded form that defines a case with a tag value to use in encoding and a predicate on tag value to use in decoding.

    The most general case combinators are caseO and caseP (and their operator equivalents, ? and |). In addition to a tag or tag/predicate pair, the caseO combinators are defined by providing a mapping from A to Option[R], a mapping from R to A, and a Codec[R]. The case is used for encoding if the mapping from A to Option[R] returns a Some and it is used for decoding upon matching the tag value. The caseP combinators work the same but take a PartialFunction[A, R] instead of an A => Option[R].

    If R is a subtype of A, then the mapping from R to A can be omitted. Hence, the subcaseO and subcaseP (and the operator equivalents, / and \) constrain R to being a subtype of A and do not take a R => A function.

    Finally, the least generic case combinators are the typecase combinators which add further constraints to the subcase* combinators. Specifically, the typecase operators omit the A => Option[R] or PartialFunction[A, R] in favor of doing subtype checks. For example, the following codec is a Codec[AnyVal] that encodes a 0 if passed a Boolean and a 1 if passed an Int:

    discriminated[AnyVal].by(uint8).typecase(0, bool).typecase(1, int32)

    Often, the values are size-delimited -- that is, there is a size field after the tag field and before the value field. To support this, use the framing method to provide a transformation to each value codec. For example, framing(new CodecTransformation { def apply[X](c: Codec[X]) = variableSizeBytes(uint8, c) }).

    See also

    discriminated

  11. sealed trait DropUnits[K <: HList] extends AnyRef

    Permalink

    Describes an isomorphism between two HLists, K and L, where L has the same shape as K except unit values have been removed.

  12. sealed trait DropUnitsLowPriority extends AnyRef

    Permalink

    Low priority implicits for DropUnits.

  13. sealed trait FlattenLeftPairs[A] extends DepFn1[A]

    Permalink

    Type level operation on type A which flattens left unflattened pairs in to an hlist and vice versa.

    Type level operation on type A which flattens left unflattened pairs in to an hlist and vice versa.

    That is, the flatten method converts a (((A, B), C), D) in to a A :: B :: C :: D :: HNil and the unflatten method does the inverse.

  14. trait ImplicitCodecs extends ImplicitValues with ImplicitCollections

    Permalink

    Provides implicit codecs for common types.

  15. trait ImplicitCollections extends AnyRef

    Permalink

    Provides implicit codecs for collection types.

  16. trait ImplicitValues extends AnyRef

    Permalink

    Provides implicit codecs for simple value types.

  17. sealed trait InvertibleRemove[L <: HList, A] extends AnyRef

    Permalink

    Similar to Shapeless's remove support for HLists but supports inverting the removal.

  18. trait KnownDiscriminatorType[D] extends AnyRef

    Permalink

    Mixin for codecs/decoders that are known to discriminate by values of type D.

  19. sealed trait MultiplexedCodec extends AnyRef

    Permalink

    A trait that enables custom handling for encoding/decoding sequences.

  20. abstract class NeedDiscriminatorCodec[A] extends AnyRef

    Permalink

    Supports creation of a DiscriminatorCodec.

    Supports creation of a DiscriminatorCodec. See discriminated for details.

  21. class SignatureSigner extends Signer

    Permalink

    Signer implementation for java.security.Signature

  22. trait Signer extends AnyRef

    Permalink

    Represents the ability to create a "checksum" for use with fixedSizeSignature and variableSizeSignature.

  23. trait SignerFactory extends AnyRef

    Permalink

    Represents the ability to create a Signer for use with fixedSizeSignature and variableSizeSignature.

  24. implicit final class StringEnrichedWithCodecContextSupport extends AnyVal

    Permalink

    Provides the | method on String, which is reverse syntax for codec withContext ctx.

    Provides the | method on String, which is reverse syntax for codec withContext ctx.

    Usage:

    val codec = "id" | uint8
  25. sealed trait ToCoproductCodecs[C <: Coproduct, L <: HList] extends AnyRef

    Permalink

    Witness that allows converting an HList of codecs in to a list of coproduct codecs, where the coproduct is type aligned with the HList.

  26. trait ToHListCodec[In <: HList] extends DepFn1[In]

    Permalink

    Converts an HList of codecs in to a single codec.

    Converts an HList of codecs in to a single codec. That is, converts Codec[X0] :: Codec[X1] :: ... :: Codec[Xn] :: HNil in to a Codec[X0 :: X1 :: ... :: Xn :: HNil].

  27. 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)]

    Permalink
  28. 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)]

    Permalink
  29. 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)]

    Permalink
  30. final class Tuple3Codec[A, B, C] extends Codec[(A, B, C)]

    Permalink
  31. final class Tuple4Codec[A, B, C, D] extends Codec[(A, B, C, D)]

    Permalink
  32. final class Tuple5Codec[A, B, C, D, E] extends Codec[(A, B, C, D, E)]

    Permalink
  33. final class Tuple6Codec[A, B, C, D, E, F] extends Codec[(A, B, C, D, E, F)]

    Permalink
  34. final class Tuple7Codec[A, B, C, D, E, F, G] extends Codec[(A, B, C, D, E, F, G)]

    Permalink
  35. final class Tuple8Codec[A, B, C, D, E, F, G, H] extends Codec[(A, B, C, D, E, F, G, H)]

    Permalink
  36. final class Tuple9Codec[A, B, C, D, E, F, G, H, I] extends Codec[(A, B, C, D, E, F, G, H, I)]

    Permalink
  37. final class TupleCodec[A, B] extends Codec[(A, B)]

    Permalink
  38. implicit final class ValueEnrichedWithTuplingSupport[A] extends AnyRef

    Permalink

    Allows creation of left nested pairs by successive usage of ~ operator.

  39. final type ~[+A, +B] = (A, B)

    Permalink

    Type alias for Tuple2 in order to allow left nested tuples to be written as A ~ B ~ C ~ ....

Value Members

  1. object ChecksumCodec

    Permalink

    Provides methods to create a "checksum codec" (encodes a bit-range to a bit-checksum and decodes bits to a bit-range).

  2. object ChecksumFactory

    Permalink

    Creates checksum implementations of SignerFactory.

  3. object CipherFactory

    Permalink

    Companion for CipherFactory.

  4. object CoproductBuilderAuto

    Permalink

    Companion for CoproductBuilderAuto.

  5. object CoproductBuilderAutoDiscriminators

    Permalink

    Companion for CoproductBuilderAutoDiscriminators.

  6. object CoproductBuilderKeyDiscriminators

    Permalink

    Companion for CoproductBuilderKeyDiscriminators.

  7. object CoproductCodecBuilder

    Permalink

    Companion for CoproductCodecBuilder.

  8. object DeMultiplexer

    Permalink
  9. object DeriveHListElementAux

    Permalink

    Companion for DeriveHListElementAux.

  10. object Discriminated extends Serializable

    Permalink

    Companion for Discriminated.

  11. object DropUnits extends DropUnitsLowPriority

    Permalink

    Companion for DropUnits.

  12. object FlattenLeftPairs

    Permalink

    Companion for FlattenLeftPairs.

  13. object InvertibleRemove

    Permalink

    Companion for InvertibleRemove.

  14. object SignatureFactory

    Permalink

    Create java.security.Signature implementations for SignerFactory

  15. object ToCoproductCodecs

    Permalink

    Companion for ToCoproductCodecs.

  16. object ToHListCodec

    Permalink

    Companion for ToHListCodec.

  17. object VarIntCodec

    Permalink
  18. object VarLongCodec

    Permalink
  19. val ascii: Codec[String]

    Permalink

    String codec that uses the US-ASCII charset.

    String codec that uses the US-ASCII charset. See string for more information on String codecs.

  20. val ascii32: Codec[String]

    Permalink

    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.

  21. val ascii32L: Codec[String]

    Permalink

    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.

  22. def bits(size: Long): Codec[BitVector]

    Permalink

    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.

    size

    number of bits to encode/decode

  23. def bits: Codec[BitVector]

    Permalink

    Encodes by returning supplied bit vector; decodes by taking all remaining bits in the supplied bit vector.

  24. val bitsRemaining: Codec[Boolean]

    Permalink

    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.

  25. def bool(n: Long): Codec[Boolean]

    Permalink

    n-bit boolean codec, where false corresponds to bit vector of all 0s and true corresponds to all other vectors.

  26. val bool: Codec[Boolean]

    Permalink

    1-bit boolean codec, where false corresponds to bit value 0 and true corresponds to bit value 1.

  27. def byte(size: Int): Codec[Byte]

    Permalink

    Codec for n-bit 2s complement bytes.

    Codec for n-bit 2s complement bytes.

    size

    number of bits (must be 0 < size <= 8)

  28. val byte: Codec[Byte]

    Permalink

    Codec for 8-bit 2s complement bytes.

  29. def byteAligned[A](codec: Codec[A]): Codec[A]

    Permalink

    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.

    codec

    codec to align to next larger byte boundary

  30. def bytes(size: Int): Codec[ByteVector]

    Permalink

    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.

    size

    number of bits to encode/decode

  31. def bytes: Codec[ByteVector]

    Permalink

    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.

  32. def certificate(certType: String): Codec[Certificate]

    Permalink

    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

  33. def checksummed[A](target: Codec[A], checksum: (BitVector) ⇒ BitVector, framing: Codec[(BitVector, BitVector)], validate: Boolean = true): Codec[A]

    Permalink

    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))
    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

  34. def choice[A](codecs: Codec[A]*): Codec[A]

    Permalink

    Codec that encodes/decodes using the specified codecs by trying each codec in succession and using the first successful result.

  35. def conditional[A](included: Boolean, codec: ⇒ Codec[A]): Codec[Option[A]]

    Permalink

    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.

    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

  36. def constant[A](bits: A*)(implicit arg0: Integral[A]): Codec[Unit]

    Permalink

    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

  37. def constant(bytes: ByteVector): Codec[Unit]

    Permalink

    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

  38. def constant(bits: BitVector): Codec[Unit]

    Permalink

    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

  39. def constantLenient[A](bits: A*)(implicit arg0: Integral[A]): Codec[Unit]

    Permalink

    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

  40. def constantLenient(bytes: ByteVector): Codec[Unit]

    Permalink

    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

  41. def constantLenient(bits: BitVector): Codec[Unit]

    Permalink

    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

  42. def constrainedVariableSizeBytes[A](size: Codec[Int], value: Codec[A], maxSize: Int): Codec[A]

    Permalink

    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.

    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

  43. def constrainedVariableSizeBytes[A](size: Codec[Int], value: Codec[A], minSize: Int, maxSize: Int): Codec[A]

    Permalink

    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.

    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

  44. def constrainedVariableSizeBytesLong[A](size: Codec[Long], value: Codec[A], maxSize: Long): Codec[A]

    Permalink

    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.

    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

  45. def constrainedVariableSizeBytesLong[A](size: Codec[Long], value: Codec[A], minSize: Long, maxSize: Long): Codec[A]

    Permalink

    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.

    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

  46. val cstring: Codec[String]

    Permalink

    String codec that uses the US-ASCII charset that encodes strings with a trailing NUL termination byte and decodes a string up to the next NUL termination byte.

    String codec that uses the US-ASCII charset that encodes strings with a trailing NUL termination byte and decodes a string up to the next NUL termination byte. It fails to decode if the bit vector ends before a NUL termination byte can be found.

  47. def discriminated[A]: NeedDiscriminatorCodec[A]

    Permalink

    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.

  48. def discriminatorFallback[L, R](left: Codec[L], right: Codec[R]): Codec[Either[L, R]]

    Permalink

    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

  49. val double: Codec[Double]

    Permalink

    64-bit big endian IEEE 754 floating point number.

  50. val doubleL: Codec[Double]

    Permalink

    64-bit little endian IEEE 754 floating point number.

  51. def either[L, R](indicator: Codec[Boolean], left: Codec[L], right: Codec[R]): Codec[Either[L, R]]

    Permalink

    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.

    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

  52. def encrypted[A](codec: Codec[A])(implicit cipherFactory: CipherFactory): Codec[A]

    Permalink

    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

  53. def endiannessDependent[A](big: Codec[A], little: Codec[A])(implicit ordering: ByteOrdering): Codec[A]

    Permalink

    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

  54. def enumerated(discriminator: Codec[Int], enumeration: Enumeration): DiscriminatorCodec[Value, Int]

    Permalink

    Codec for an Enumeration that encodes/decodes using Enumeration.Value.id values.

    Codec for an Enumeration that encodes/decodes using Enumeration.Value.id values.

    discriminator

    the codec for Enumeration.Value.id values

    enumeration

    the target Enumeration

  55. def fail[A](encErr: Err, decErr: Err): Codec[A]

    Permalink

    Codec that always fails encoding and decoding with the specified messages.

  56. def fail[A](err: Err): Codec[A]

    Permalink

    Codec that always fails encoding and decoding with the specified message.

  57. def fallback[L, R](left: Codec[L], right: Codec[R]): Codec[Either[L, R]]

    Permalink

    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

  58. def filtered[A](codec: Codec[A], filter: Codec[BitVector]): Codec[A]

    Permalink

    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.

    codec

    the target codec

    filter

    a codec that represents pre/post-processing stages for input/output bits

  59. def fixedSizeBits[A](size: Long, codec: Codec[A]): Codec[A]

    Permalink

    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

  60. def fixedSizeBytes[A](size: Long, codec: Codec[A]): Codec[A]

    Permalink

    Byte equivalent of fixedSizeBits.

    Byte equivalent of fixedSizeBits.

    size

    number of bytes

    codec

    codec to limit

  61. def fixedSizeSignature[A](size: Int)(codec: Codec[A])(implicit signerFactory: SignerFactory): Codec[A]

    Permalink

    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

  62. val float: Codec[Float]

    Permalink

    32-bit big endian IEEE 754 floating point number.

  63. val floatL: Codec[Float]

    Permalink

    32-bit little endian IEEE 754 floating point number.

  64. def hlist[L <: HList](l: L)(implicit toHListCodec: ToHListCodec[L]): Out

    Permalink

    Converts an HList of codecs in to a single codec.

    Converts an HList of codecs in to a single codec. That is, converts Codec[X0] :: Codec[X1] :: ... :: Codec[Xn] :: HNil in to a Codec[X0 :: X1 :: ... :: Xn :: HNil].

  65. def ignore(size: Long): Codec[Unit]

    Permalink

    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.

    size

    number of bits to ignore

  66. object implicits extends ImplicitCodecs

    Permalink

    Provides common implicit codecs.

  67. def int(size: Int): Codec[Int]

    Permalink

    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)

  68. val int16: Codec[Int]

    Permalink

    Codec for 16-bit 2s complement big-endian integers.

  69. val int16L: Codec[Int]

    Permalink

    Codec for 16-bit 2s complement little-endian integers.

  70. val int24: Codec[Int]

    Permalink

    Codec for 24-bit 2s complement big-endian integers.

  71. val int24L: Codec[Int]

    Permalink

    Codec for 24-bit 2s complement little-endian integers.

  72. val int32: Codec[Int]

    Permalink

    Codec for 32-bit 2s complement big-endian integers.

  73. val int32L: Codec[Int]

    Permalink

    Codec for 32-bit 2s complement little-endian integers.

  74. val int64: Codec[Long]

    Permalink

    Codec for 64-bit 2s complement big-endian integers.

  75. val int64L: Codec[Long]

    Permalink

    Codec for 64-bit 2s complement little-endian integers.

  76. val int8: Codec[Int]

    Permalink

    Codec for 8-bit 2s complement big-endian integers.

  77. val int8L: Codec[Int]

    Permalink

    Codec for 8-bit 2s complement little-endian integers.

  78. def intL(bits: Int): Codec[Int]

    Permalink

    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)

  79. def lazily[A](codec: ⇒ Codec[A]): Codec[A]

    Permalink

    Provides a Codec[A] that delegates to a lazily evaluated Codec[A].

  80. implicit final def liftF2ToNestedTupleF[A, B, X](fn: (A, B) ⇒ X): ((A, B)) ⇒ X

    Permalink

    Allows use of a 2-arg function as a single arg function that takes a left-associated stack of pairs with 2 total elements.

  81. implicit final def liftF3ToNestedTupleF[A, B, C, X](fn: (A, B, C) ⇒ X): (((A, B), C)) ⇒ X

    Permalink

    Allows use of a 3-arg function as a single arg function that takes a left-associated stack of pairs with 3 total elements.

  82. implicit final def liftF4ToNestedTupleF[A, B, C, D, X](fn: (A, B, C, D) ⇒ X): ((((A, B), C), D)) ⇒ X

    Permalink

    Allows use of a 4-arg function as a single arg function that takes a left-associated stack of pairs with 4 total elements.

  83. implicit final def liftF5ToNestedTupleF[A, B, C, D, E, X](fn: (A, B, C, D, E) ⇒ X): (((((A, B), C), D), E)) ⇒ X

    Permalink

    Allows use of a 5-arg function as a single arg function that takes a left-associated stack of pairs with 5 total elements.

  84. 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

    Permalink

    Allows use of a 6-arg function as a single arg function that takes a left-associated stack of pairs with 6 total elements.

  85. 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

    Permalink

    Allows use of a 7-arg function as a single arg function that takes a left-associated stack of pairs with 7 total elements.

  86. 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

    Permalink

    Allows use of an 8-arg function as a single arg function that takes a left-associated stack of pairs with 8 total elements.

  87. def limitedSizeBits[A](limit: Long, codec: Codec[A]): Codec[A]

    Permalink

    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

  88. def limitedSizeBytes[A](limit: Long, codec: Codec[A]): Codec[A]

    Permalink

    Byte equivalent of limitedSizeBits.

    Byte equivalent of limitedSizeBits.

    codec

    codec to limit

  89. def list[A](codec: Codec[A]): Codec[List[A]]

    Permalink

    Codec that encodes/decodes a List[A] from a Codec[A].

    Codec that encodes/decodes a List[A] from a Codec[A].

    When encoding, each A in the list is encoded and all of the resulting vectors are concatenated.

    When decoding, codec.decode is called repeatedly until there are no more remaining bits and the value result of each decode is returned in the list.

    codec

    codec to encode/decode a single element of the sequence

  90. def listDelimited[A](delimiter: BitVector, valueCodec: Codec[A]): Codec[List[A]]

    Permalink

    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")
    A

    element type

    delimiter

    the bits used to separate element bit values

    valueCodec

    element codec (used to decode next bits)

  91. def listMultiplexed[A](mux: (BitVector, BitVector) ⇒ BitVector, deMux: (BitVector) ⇒ (BitVector, BitVector), valueCodec: Codec[A]): Codec[List[A]]

    Permalink

    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.

    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)

  92. def listOfN[A](countCodec: Codec[Int], valueCodec: Codec[A]): Codec[List[A]]

    Permalink

    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), ...).

  93. object literals

    Permalink

    Provides implicit conversions from literal types to constant codecs.

    Provides implicit conversions from literal types to constant codecs.

    For example, with literals._ imported, constant(0x47) ~> uint8 can be written as 0x47 ~> uint8.

    Supports literal bytes, ints, BitVectors, and ByteVectors.

  94. def logBuilder[A](logEncode: (A, Attempt[BitVector]) ⇒ Unit, logDecode: (BitVector, Attempt[DecodeResult[A]]) ⇒ Unit)(codec: Codec[A]): Codec[A]

    Permalink

    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.

  95. def logFailuresBuilder[A](logEncode: (A, Err) ⇒ Unit, logDecode: (BitVector, Err) ⇒ Unit)(codec: Codec[A]): Codec[A]

    Permalink

    Variant of logBuilder that only logs failed results.

  96. def logFailuresToStdOut[A](codec: Codec[A], prefix: String = ""): Codec[A]

    Permalink

    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

  97. def logSuccessesBuilder[A](logEncode: (A, BitVector) ⇒ Unit, logDecode: (BitVector, DecodeResult[A]) ⇒ Unit)(codec: Codec[A]): Codec[A]

    Permalink

    Variant of logBuilder that only logs successful results.

  98. def logToStdOut[A](codec: Codec[A], prefix: String = ""): Codec[A]

    Permalink

    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

  99. def long(bits: Int): Codec[Long]

    Permalink

    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)

  100. def longL(bits: Int): Codec[Long]

    Permalink

    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)

  101. def lookahead(target: Codec[Unit]): Codec[Boolean]

    Permalink

    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

  102. def mappedEnum[A, B](discriminatorCodec: Codec[B], map: Map[A, B]): DiscriminatorCodec[A, B]

    Permalink

    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

  103. def mappedEnum[A, B](discriminatorCodec: Codec[B], mappings: (A, B)*): DiscriminatorCodec[A, B]

    Permalink

    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

  104. def optional[A](guard: Codec[Boolean], target: Codec[A]): Codec[Option[A]]

    Permalink

    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.

    guard

    codec that determines whether the target codec is included

    target

    codec to conditionally include

  105. def paddedFixedSizeBits[A](size: Long, codec: Codec[A], padCodec: Codec[Unit]): Codec[A]

    Permalink

    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

  106. def paddedFixedSizeBitsDependent[A](size: Long, codec: Codec[A], padCodec: (Long) ⇒ Codec[Unit]): Codec[A]

    Permalink

    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.

    size

    number of bits

    codec

    codec to limit

    padCodec

    function that provides the codec to use for padding

  107. def paddedFixedSizeBytes[A](size: Long, codec: Codec[A], padCodec: Codec[Unit]): Codec[A]

    Permalink

    Byte equivalent of paddedFixedSizeBits.

    Byte equivalent of paddedFixedSizeBits.

    size

    number of bytes

    codec

    codec to limit

    padCodec

    codec to use for padding

  108. def paddedFixedSizeBytesDependent[A](size: Long, codec: Codec[A], padCodec: (Long) ⇒ Codec[Unit]): Codec[A]

    Permalink

    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

  109. def pbcd(nibbles: Int): Codec[Long]

    Permalink

    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)

  110. def peek[A](target: Codec[A]): Codec[A]

    Permalink

    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

  111. def peekVariableSizeBits(size: Codec[Int], sizePadding: Int = 0): Codec[BitVector]

    Permalink

    Codec that decodes vectors of the form size ++ rest as a BitVector, where the returned vector includes the size bits.

    Codec that decodes vectors of the form size ++ rest as a BitVector, where the returned vector includes the size bits.

    This differs from variableSizeBits(size, bits, sizePadding) in that the encoded size is expected to be encoded before calling encode and the encoded size is returned as part of the vector.

    size

    size codec -- must have an exact size

    sizePadding

    number of bits to subtract from the size before decoding

  112. def peekVariableSizeBitsLong(size: Codec[Long], sizePadding: Long = 0L): Codec[BitVector]

    Permalink

    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

  113. def peekVariableSizeBytes(size: Codec[Int], sizePadding: Int = 0): Codec[BitVector]

    Permalink

    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

  114. def peekVariableSizeBytesLong(size: Codec[Long], sizePadding: Long = 0L): Codec[BitVector]

    Permalink

    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

  115. def provide[A](value: A): Codec[A]

    Permalink

    Codec that always returns an empty vector from encode and always returns (empty, value) from decode.

    Codec that always returns an empty vector from encode and always returns (empty, value) from decode. This is often useful when combined with other codecs (e.g., the discriminated).

    value

    value to return from decode

  116. def recover(target: Codec[Unit]): Codec[Boolean]

    Permalink

    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

  117. def short(size: Int): Codec[Short]

    Permalink

    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)

  118. val short16: Codec[Short]

    Permalink

    Codec for 16-bit 2s complement big-endian shorts.

  119. val short16L: Codec[Short]

    Permalink

    Codec for 16-bit 2s complement little-endian shorts.

  120. def shortL(size: Int): Codec[Short]

    Permalink

    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)

  121. def sizedList[A](size: Nat, codec: Codec[A])(implicit toInt: ToInt[N]): Codec[Sized[List[A], N]]

    Permalink

    Codec that encodes/decodes a list of n elements, where n is known at compile time.

    Codec that encodes/decodes a list of n elements, where n is known at compile time.

    size

    number of elements in the list

    codec

    codec to encode/decode a single element of the sequence

  122. def sizedVector[A](size: Nat, codec: Codec[A])(implicit toInt: ToInt[N]): Codec[Sized[Vector[A], N]]

    Permalink

    Codec that encodes/decodes a vector of n elements, where n is known at compile time.

    Codec that encodes/decodes a vector of n elements, where n is known at compile time.

    size

    number of elements in the vector

    codec

    codec to encode/decode a single element of the sequence

  123. def string(implicit charset: Charset): Codec[String]

    Permalink

    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

  124. def string32(implicit charset: Charset): Codec[String]

    Permalink

    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

  125. def string32L(implicit charset: Charset): Codec[String]

    Permalink

    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

  126. def ubyte(size: Int): Codec[Byte]

    Permalink

    Codec for n-bit unsigned bytes.

    Codec for n-bit unsigned bytes.

    size

    number of bits (must be 0 < size <= 7)

  127. def uint(bits: Int): Codec[Int]

    Permalink

    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)

  128. val uint16: Codec[Int]

    Permalink

    Codec for 16-bit unsigned big-endian integers.

  129. val uint16L: Codec[Int]

    Permalink

    Codec for 16-bit unsigned little-endian integers.

  130. val uint2: Codec[Int]

    Permalink

    Codec for 2-bit unsigned big-endian integers.

  131. val uint24: Codec[Int]

    Permalink

    Codec for 24-bit unsigned big-endian integers.

  132. val uint24L: Codec[Int]

    Permalink

    Codec for 24-bit unsigned little-endian integers.

  133. val uint2L: Codec[Int]

    Permalink

    Codec for 2-bit unsigned little-endian integers.

  134. val uint32: Codec[Long]

    Permalink

    Codec for 32-bit unsigned big-endian integers.

  135. val uint32L: Codec[Long]

    Permalink

    Codec for 32-bit unsigned little-endian integers.

  136. val uint4: Codec[Int]

    Permalink

    Codec for 4-bit unsigned big-endian integers.

  137. val uint4L: Codec[Int]

    Permalink

    Codec for 4-bit unsigned little-endian integers.

  138. val uint8: Codec[Int]

    Permalink

    Codec for 8-bit unsigned big-endian integers.

  139. val uint8L: Codec[Int]

    Permalink

    Codec for 8-bit unsigned little-endian integers.

  140. def uintL(bits: Int): Codec[Int]

    Permalink

    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)

  141. def ulong(bits: Int): Codec[Long]

    Permalink

    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)

  142. def ulongL(bits: Int): Codec[Long]

    Permalink

    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)

  143. def ushort(size: Int): Codec[Short]

    Permalink

    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)

  144. val ushort8: Codec[Short]

    Permalink

    Codec for 8-bit unsigned bytes.

  145. def ushortL(size: Int): Codec[Short]

    Permalink

    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)

  146. val utf8: Codec[String]

    Permalink

    String codec that uses the UTF-8 charset.

    String codec that uses the UTF-8 charset. See string for more information on String codecs.

  147. val utf8_32: Codec[String]

    Permalink

    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.

  148. val utf8_32L: Codec[String]

    Permalink

    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.

  149. val uuid: Codec[UUID]

    Permalink

    Encodes/decodes UUIDs as 2 64-bit big-endian longs, first the high 64-bits then the low 64-bits.

  150. def variableSizeBits[A](size: Codec[Int], value: Codec[A], sizePadding: Int = 0): Codec[A]

    Permalink

    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".

    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)

  151. def variableSizeBitsLong[A](size: Codec[Long], value: Codec[A], sizePadding: Long = 0): Codec[A]

    Permalink

    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".

    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)

  152. def variableSizeBytes[A](size: Codec[Int], value: Codec[A], sizePadding: Int = 0): Codec[A]

    Permalink

    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)

  153. def variableSizeBytesLong[A](size: Codec[Long], value: Codec[A], sizePadding: Long = 0): Codec[A]

    Permalink

    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)

  154. def variableSizePrefixedBits[A, B](size: Codec[Int], prefix: Codec[A], value: Codec[B], sizePadding: Int = 0): Codec[(A, B)]

    Permalink

    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".

    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)

  155. def variableSizePrefixedBitsLong[A, B](size: Codec[Long], prefix: Codec[A], value: Codec[B], sizePadding: Long = 0): Codec[(A, B)]

    Permalink

    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".

    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)

  156. def variableSizePrefixedBytes[A, B](size: Codec[Int], prefix: Codec[A], value: Codec[B], sizePadding: Int = 0): Codec[(A, B)]

    Permalink

    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)

  157. def variableSizePrefixedBytesLong[A, B](size: Codec[Long], prefix: Codec[A], value: Codec[B], sizePadding: Long = 0): Codec[(A, B)]

    Permalink

    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)

  158. def variableSizeSignature[A](size: Codec[Int])(codec: Codec[A])(implicit signerFactory: SignerFactory): Codec[A]

    Permalink

    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

  159. def vector[A](codec: Codec[A]): Codec[Vector[A]]

    Permalink

    Codec that encodes/decodes a Vector[A] from a Codec[A].

    Codec that encodes/decodes a Vector[A] from a Codec[A].

    When encoding, each A in the vector is encoded and all of the resulting vectors are concatenated.

    When decoding, codec.decode is called repeatedly until there are no more remaining bits and the value result of each decode is returned in the vector.

    codec

    codec to encode/decode a single element of the sequence

  160. def vectorDelimited[A](delimiter: BitVector, valueCodec: Codec[A]): Codec[Vector[A]]

    Permalink

    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")
    A

    element type

    delimiter

    the bits used to separate element bit values

    valueCodec

    element codec (used to decode next bits)

  161. def vectorMultiplexed[A](mux: (BitVector, BitVector) ⇒ BitVector, deMux: (BitVector) ⇒ (BitVector, BitVector), valueCodec: Codec[A]): Codec[Vector[A]]

    Permalink

    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.

    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)

  162. def vectorOfN[A](countCodec: Codec[Int], valueCodec: Codec[A]): Codec[Vector[A]]

    Permalink

    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), ...).

  163. val vint: Codec[Int]

    Permalink

    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.

  164. val vintL: Codec[Int]

    Permalink

    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.

  165. val vlong: Codec[Long]

    Permalink

    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.

  166. val vlongL: Codec[Long]

    Permalink

    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.

  167. val vpbcd: Codec[Long]

    Permalink

    Codec for variable-length packed decimal longs.

    Codec for variable-length packed decimal longs. Negative values are not supported.

  168. def withDefault[A](opt: Codec[Option[A]], default: Codec[A]): Codec[A]

    Permalink

    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.

    opt

    optional codec

    default

    fallback codec used during decoding when opt decodes a None

  169. def withDefaultValue[A](opt: Codec[Option[A]], default: A): Codec[A]

    Permalink

    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.

    opt

    optional codec

    default

    fallback value returned from decode when opt decodes a None

  170. def x509Certificate: Codec[X509Certificate]

    Permalink

    Codec that encodes/decodes certificates using their default encoding.

  171. def zlib[A](codec: Codec[A], level: Int = Deflater.DEFAULT_COMPRESSION, strategy: Int = Deflater.DEFAULT_STRATEGY, nowrap: Boolean = false, chunkSize: Int = 4096): Codec[A]

    Permalink

    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

  172. object ~ extends Serializable

    Permalink

    Extractor that allows pattern matching on the tuples created by tupling codecs.

Inherited from AnyRef

Inherited from Any

Bits and Bytes Codecs

Number Codecs

Miscellaneous Value Codecs

Combinators

Guards

Tuple Support

Logging

Cryptography

Ungrouped