scodec

Right biased Either[Err, A].

An Attempt is either an Attempt.Successful or an Attempt.Failure. Attempts can be created by calling Attempt.successful or Attempt.failure, as well as converting from an Option via fromOption.

Attributes

Companion: object
Source: Attempt.scala
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all
Known subtypes: class Failure

class Successful[A]

Companion for Attempt.

Attributes

Companion: class
Source: Attempt.scala
Supertypes: trait Sum

trait Mirror

class Object

trait Matchable

class Any
Self type: Attempt.type

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.

Attributes

Companion: object
Source: Codec.scala
Supertypes: trait Decoder[A]

trait Encoder[A]

class Object

trait Matchable

class Any
Known subtypes: class DiscriminatorCodec[A, B]
Self type: Codec[A]

Companion for Codec.

Attributes

Companion: trait
Source: Codec.scala
Supertypes: trait DecoderFunctions

trait EncoderFunctions

class Object

trait Matchable

class Any
Self type: Codec.type

Result of a decoding operation, which consists of the decoded value and the remaining bits that were not consumed by decoding.

Attributes

Source: DecodeResult.scala
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Supports decoding a value of type A from a BitVector.

Attributes

Companion: object
Source: Decoder.scala
Supertypes: class Object

trait Matchable

class Any
Known subtypes: trait Codec[A]

class DiscriminatorCodec[A, B]
Self type: Decoder[A]

Companion for Decoder.

Attributes

Companion: trait
Source: Decoder.scala
Supertypes: trait DecoderFunctions

class Object

trait Matchable

class Any
Self type: Decoder.type

Provides functions for working with decoders.

Attributes

Source: Decoder.scala
Supertypes: class Object

trait Matchable

class Any
Known subtypes: object Codec.type

object Decoder.type

Attributes

Source: DropUnits.scala
Supertypes: class Object

trait Matchable

class Any
Self type: DropUnits.type

Supports encoding a value of type A to a BitVector.

Attributes

Companion: object
Source: Encoder.scala
Supertypes: class Object

trait Matchable

class Any
Known subtypes: trait Codec[A]

class DiscriminatorCodec[A, B]
Self type: Encoder[A]

Companion for Encoder.

Attributes

Companion: trait
Source: Encoder.scala
Supertypes: trait EncoderFunctions

class Object

trait Matchable

class Any
Self type: Encoder.type

Provides functions for working with encoders.

Attributes

Source: Encoder.scala
Supertypes: class Object

trait Matchable

class Any
Known subtypes: object Codec.type

object Encoder.type

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.

Attributes

Companion: object
Source: Err.scala
Supertypes: class Object

trait Matchable

class Any
Known subtypes: class Mismatch

class ChecksumMismatch

class UnknownDiscriminator

class Composite

class General

class InsufficientBits

class MatchingDiscriminatorNotFound[A]
Show all

Companion for Err.

Attributes

Companion: trait
Source: Err.scala
Supertypes: class Object

trait Matchable

class Any
Self type: Err.type

Attributes

Companion: object
Source: Iso.scala
Supertypes: class Object

trait Matchable

class Any
Self type: Iso[A, B]

Companion for Iso.

Attributes

Companion: trait
Source: Iso.scala
Supertypes: class Object

trait Matchable

class Any
Self type: Iso.type

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 parameters

lowerBound: Minimum number of bits
upperBound: Maximum number of bits

Attributes

Companion: object
Source: SizeBound.scala
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Companion for SizeBound.

Attributes

Companion: class
Source: SizeBound.scala
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: SizeBound.type

Typeclass that describes type constructors that support the exmap operation.

Attributes

Source: Transform.scala
Supertypes: class Object

trait Matchable

class Any
Known subtypes: object given_Transform_Codec.type

object given_Transform_Decoder.type

object given_Transform_Encoder.type

Empty object which allows cross building against scodec 1.11 without errors.

Attributes

Source: compat.scala
Supertypes: class Object

trait Matchable

class Any
Self type: compat.type

scodec

Members list

Packages

Type members

Classlikes

Attributes

Attributes

Tuple Codecs

flatZip

flatPrepend

Derived Codecs

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Value parameters

Attributes

Attributes

Attributes

Attributes

Types

Attributes