Codec
Supports encoding a value of type
A
to a BitVector
and decoding a BitVector
to a value of A
.Not every value of
of type
remaining bits in the bit vector that it did not use in decoding.
A
can be encoded to a bit vector and similarly, not every bit vector can be decoded to a valueof type
A
. Hence, both encode and decode return either an error or the result. Furthermore, decode returns theremaining bits in the bit vector that it did not use in decoding.
There are various ways to create instances of
constructor methods in the companion can be used (e.g.,
create return a new codec that has been transformed in some way. For example, the xmap method
converts a
Codec
. The trait can be implemented directly or one of theconstructor 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
pushes the specified context string in to any errors (i.e.,
def withContext(context: String): Codec[A]
, whichpushes the specified context string in to any errors (i.e.,
Err
s) 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.
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
}}}
}}}
{{{
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 isdropUnits
, which removes any Unit
values from the tuple.Given a
the codec can be turned in to a case class codec via the
{{{
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]
}}}
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
the left hand side and right hand side. Its signature is
This is similar to
The
flatZip
method is important in these types of situations -- it represents a dependency betweenthe 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
{{{
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,
because it is redundant with the size stored in the
Note: there is a combinator that expresses this pattern more succinctly --
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 modelbecause it is redundant with the size stored in the
ByteVector
. Hence, we remove the Int
byxmap
-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
right nested tuples instead of a extending the arity of a single tuple. To do the latter, there's
{{{
def flatPrepend[B <: Tuple] (f: A => Codec[B] ): Codec[A *: B]
}}}
It forms a codec of
Note that the specified function must return a tuple codec. Implementing our example from earlier
using
{{{
val x: Codec[(Int, ByteVector)] = uint8.flatPrepend { numBytes => bytes(numBytes).tuple }
}}}
In this example,
in to a
flatZip
returns a Codec[B]
where B <: Tuple
, you end up creatingright 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 itin 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
of the
have an implicitly available codec of the corresponding type. In this case, each element was an
an implicit
{{{
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, an implicit one was derived as a resultof the
derives Codec
clause. Derivation of a codec for a case class requires each element of the case class tohave an implicitly available codec of the corresponding type. In this case, each element was an
Int
and there isan implicit
Codec[Int]
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.
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
class PaddedVarAlignedCodec[A]
Document{}
Extension method from Codec
When called on a
the tuple
returned from applying
Codec[A]
for some A <: Tuple
, returns a new codec that encodes/decodesthe tuple
A
followed by the value B
, where the latter is encoded/decoded with the codecreturned from applying
A
to f
.Extension method from Codec
Builds a
That is, this operator is a codec-level tuple prepend operation.
Codec[A *: B]
from a Codec[A]
and a Codec[B]
where B
is a tuple type.That is, this operator is a codec-level tuple prepend operation.
- Value Params
- codec
-
codec to prepend
Extension method from Codec
codecB :+ codecA
returns a new codec that encodes/decodes the tuple B
followed by an A
.That is, this operator is a codec-level tuple append operation.
Extension method from Codec
Builds a
That is, this operator is a codec-level tuple concat operation.
Codec[A ++ B]
from a Codec[A]
and a Codec[B]
where A
and B
are tuples.That is, this operator is a codec-level tuple concat operation.
- Value Params
- codecA
-
codec to concat
Extension method from Codec
When called on a
the tuple
returned from applying
Codec[A]
for some A <: Tuple
, returns a new codec that encodes/decodesthe tuple
A
followed by the tuple B
, where the latter is encoded/decoded with the codecreturned from applying
A
to f
.Extension method from Codec
When called on a
For example,
{{{
uint8 :: utf8
}}}
has type
uint8 :: utf8
}}}
Codec[A]
where A
is not a tuple, creates a new codec that encodes/decodes a tuple of (B, A)
.For example,
{{{
uint8 :: utf8
}}}
has type
Codec[(Int, Int)]
.uint8 :: utf8
}}}
Extension method from Codec
Creates a new codec that encodes/decodes a tuple of
This allows later parts of a tuple codec to be dependent on earlier values.
A :: B
given a function A => Codec[B]
.This allows later parts of a tuple codec to be dependent on earlier values.
Assuming
decodes a unit followed by a
A
is Unit
, creates a Codec[B]
that: encodes the unit followed by a B
;decodes a unit followed by a
B
and discards the decoded unit.Assuming
decodes a unit followed by a
A
is Unit
, creates a Codec[B]
that: encodes the unit followed by a B
;decodes a unit followed by a
B
and discards the decoded unit.Operator alias of dropLeft.
Assuming
decodes an
B
is Unit
, creates a Codec[A]
that: encodes the A
followed by a unit;decodes an
A
followed by a unit and discards the decoded unit.Assuming
decodes an
B
is Unit
, creates a Codec[A]
that: encodes the A
followed by a unit;decodes an
A
followed by a unit and discards the decoded unit.Operator alias of dropRight.
Converts this to a
decodes a unit value when this codec decodes an
Codec[Unit]
that encodes using the specified zero value anddecodes a unit value when this codec decodes an
A
successfully.Returns a new codec that encodes/decodes a value of type
(A, B)
where the codec of B
is dependent on A
.Returns a new codec that encodes/decodes a value of type
Operator alias for flatZip.
(A, B)
where the codec of B
is dependent on A
.Operator alias for flatZip.
Similar to
effects of the
flatZip
except the A
type is not visible in the resulting type -- the binaryeffects of the
Codec[A]
still occur though.Example usage:
{{{
case class Flags(x: Boolean, y: Boolean, z: Boolean)
(bool :: bool :: bool :: ignore(5)).consume { flgs =>
conditional(flgs.x, uint8) :: conditional(flgs.y, uint8) :: conditional(flgs.z, uint8)
} {
case (x, y, z) => Flags(x.isDefined, y.isDefined, z.isDefined) }
}
}}}
{{{
case class Flags(x: Boolean, y: Boolean, z: Boolean)
(bool :: bool :: bool :: ignore(5)).consume { flgs =>
conditional(flgs.x, uint8) :: conditional(flgs.y, uint8) :: conditional(flgs.z, uint8)
} {
case (x, y, z) => Flags(x.isDefined, y.isDefined, z.isDefined) }
}
}}}
Safely lifts this codec to a codec of a supertype.
When a subtype of
an encoding error is returned.
B
that is not a subtype of A
is passed to encode,an encoding error is returned.
Safely lifts this codec to a codec of a subtype.
When a supertype of
an decoding error is returned.
B
that is not a supertype of A
is decoded,an decoding error is returned.
Creates a new codec that is functionally equivalent to this codec but pushes the specified
context string in to any errors returned from encode or decode.
context string in to any errors returned from encode or decode.
Creates a new codec that is functionally equivalent to this codec but returns the specified string from
toString
.Attempts to encode the specified value in to a bit vector.
- Value Params
- value
-
value to encode
- Returns
-
error or binary encoding of the value
- Inhertied from
- Encoder
Converts this encoder to an
function from
Encoder[B]
using the supplied partialfunction from
B
to A
. The encoding will fail for any B
thatf
maps to None
.- Inhertied from
- Encoder
def collect[F <: ([_$3] =>> Any), A2 >: A](buffer: BitVector, limit: Option[Int])(factory: Factory[A2, F[A2]]): Attempt[DecodeResult[F[A2]]]
Repeatedly decodes values of type
Terminates when no more bits are available in the vector or when
decoded. Exits upon first decoding error.
A
from the specified vector and returns a collection of the specified type.Terminates when no more bits are available in the vector or when
limit
is defined and that many records have beendecoded. Exits upon first decoding error.
- Inhertied from
- Decoder
Encodes all elements of the specified sequence and concatenates the results, or returns the first encountered error.
- Inhertied from
- Encoder
Attempts to decode a value of type
A
from the specified bit vector.- Value Params
- bits
-
bits to decode
- Returns
-
error if value could not be decoded or the remaining bits and the decoded value
- Inhertied from
- Decoder
final def decodeAll[B](f: A => B)(zero: B, append: (B, B) => B)(buffer: BitVector): (Option[Err], B)
Repeatedly decodes values of type
A
from the specified vector, converts each value to a B
and appends it to an accumulator of typeB
using the supplied zero
value and append
function. Terminates when no more bits are available in the vector. Exits upon first decoding error.- Returns
-
tuple consisting of the terminating error if any and the accumulated value
- Inhertied from
- Decoder
Attempts to decode a value of type
A
from the specified bit vector and discards the remaining bits.- Value Params
- bits
-
bits to decode
- Returns
-
error if value could not be decoded or the decoded value
- Inhertied from
- Decoder