scodec

package scodec

Type members

Classlikes

trait Codec[A] extends Encoder[A] with Decoder[A]

Supports encoding a value of type A to a BitVector and decoding a BitVector to a value of A.

Not every value of A can be encoded to a bit vector and similarly, not every bit vector can be decoded to a value of type A. Hence, both encode and decode return either an error or the result. Furthermore, decode returns the remaining bits in the bit vector that it did not use in decoding.

There are various ways to create instances of Codec. The trait can be implemented directly or one of the constructor methods in the companion can be used (e.g., apply). Most of the methods on Codec create return a new codec that has been transformed in some way. For example, the xmap method converts a Codec[A] to a Codec[B] given two functions, A => B and B => A.

One of the simplest transformation methods is def withContext(context: String): Codec[A], which pushes the specified context string in to any errors (i.e., Errs) returned from encode or decode.

See the methods on this trait for additional transformation types.

See the codecs package object for pre-defined codecs for many common data types and combinators for building larger codecs out of smaller ones.

== Tuple Codecs ==

The :: operator supports combining a Codec[A] and a Codec[B] in to a Codec[(A, B)].

For example: {{{ val codec: Codec[(Int, Int, Int)] = uint8 :: uint8 :: uint8 }}} }}}

There are various methods on Codec that only work on Codec[A] for some A <: Tuple. Besides the aforementioned :: method, they include methods like ++, flatPrepend, flatConcat, etc. One particularly useful method is dropUnits, which removes any Unit values from the tuple.

Given a Codec[(X0, X1, ..., Xn)] and a case class with types X0 to Xn in the same order, the codec can be turned in to a case class codec via the as method. For example: {{{ case class Point(x: Int, y: Int, z: Int) val threeInts: Codec[(Int, Int, Int)] = uint8 :: uint8 :: uint8 val point: Codec[Point] = threeInts.as[Point] }}}

=== flatZip ===

Sometimes when combining codecs, a latter codec depends on a formerly decoded value. The flatZip method is important in these types of situations -- it represents a dependency between the left hand side and right hand side. Its signature is def flatZip[B](f: A => Codec[B]): Codec[(A, B)]. This is similar to flatMap except the return type is Codec[(A, B)] instead of Decoder[B].

Consider a binary format of an 8-bit unsigned integer indicating the number of bytes following it. To implement this with flatZip, we could write: {{{ val x: Codec[(Int, ByteVector)] = uint8.flatZip { numBytes => bytes(numBytes) } val y: Codec[ByteVector] = x.xmap[ByteVector]({ case (_, bv) => bv }, bv => (bv.size, bv)) }}} In this example, x is a Codec[(Int, ByteVector)] but we do not need the size directly in the model because it is redundant with the size stored in the ByteVector. Hence, we remove the Int by xmap-ping over x. The notion of removing redundant data from models comes up frequently. Note: there is a combinator that expresses this pattern more succinctly -- variableSizeBytes(uint8, bytes).

=== flatPrepend ===

When the function passed to flatZip returns a Codec[B] where B <: Tuple, you end up creating right nested tuples instead of a extending the arity of a single tuple. To do the latter, there's flatPrepend. It has the signature: {{{ def flatPrepend[B <: Tuple](f: A => Codec[B]): Codec[A *: B] }}} It forms a codec of A consed on to B when called on a Codec[A] and passed a function A => Codec[B]. Note that the specified function must return a tuple codec. Implementing our example from earlier using flatPrepend: {{{ val x: Codec[(Int, ByteVector)] = uint8.flatPrepend { numBytes => bytes(numBytes).tuple } }}} In this example, bytes(numBytes) returns a Codec[ByteVector] so we called .tuple on it to lift it in to a Codec[ByteVector *: Unit].

There are similar methods for flat appending and flat concating.

== Derived Codecs ==

Codecs for case classes and sealed class hierarchies can often be automatically derived.

Consider this example: {{{ case class Point(x: Int, y: Int, z: Int) derives Codec Codec[Point].encode(Point(1, 2, 3)) }}} In this example, no explicit codec was defined for Point and instead, one was derived as a result of the derives Codec clause. Derivation of a codec for a case class requires each element of the case class to have a given codec of the corresponding type. In this case, each element was an Int and there is a Codec[Int] given in the companion of Codec.

Derived codecs include the name of each element in any errors produced when encoding/decoding the element.

This works similarly for ADTs / sealed class hierarchies. The binary form is represented as a single unsigned 8-bit integer representing the ordinal of the sum, followed by the derived form of the product.

Full examples are available in the test directory of this project.

Companion
object

Companion for Codec.

Companion
class
trait Decoder[+A]

Supports decoding a value of type A from a BitVector.

Companion
object
object Decoder extends DecoderFunctions

Companion for Decoder.

Companion
class

Provides functions for working with decoders.

object DropUnits
trait Encoder[-A]

Supports encoding a value of type A to a BitVector.

Companion
object
object Encoder extends EncoderFunctions

Companion for Encoder.

Companion
class

Provides functions for working with encoders.

trait Err

Describes an error.

An error has a message and a list of context identifiers that provide insight into where an error occurs in a large structure.

This type is not sealed so that codecs can return domain specific subtypes and dispatch on those subtypes.

Companion
object
object Err

Companion for Err.

Companion
class
@implicitNotFound("Could not prove ${A} is isomorphic to ${B}.")
trait Iso[A, B]
Companion
object
object Iso extends IsoLowPriority

Companion for Iso.

Companion
class
case class SizeBound(lowerBound: Long, upperBound: Option[Long])

Bounds the size, in bits, of the binary encoding of a codec -- i.e., it provides a lower bound and an upper bound on the size of bit vectors returned as a result of encoding.

Value Params
lowerBound

Minimum number of bits

upperBound

Maximum number of bits

Companion
object
object SizeBound

Companion for SizeBound.

Companion
class
trait Transform[F[_]]

Typeclass that describes type constructors that support the exmap operation.

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

Types

type DropUnits[A <: Tuple] = A match { case hd *: tl => hd match { case Unit => DropUnits[tl] case _ => hd *: DropUnits[tl] } case EmptyTuple => EmptyTuple }

The tuple which is the result of removing all 'Unit' types from the tuple 'A'.