Attempts to decode a value of type A
from the specified bit vector.
Attempts to decode a value of type A
from the specified bit vector.
bits to decode
error if value could not be decoded or the remaining bits and the decoded value
Attempts to encode the specified value in to a bit vector.
Attempts to encode the specified value in to a bit vector.
value to encode
Provides a bound on the size of successfully encoded values.
Provides a bound on the size of successfully encoded values.
When called on a Codec[L]
for some L <: HList
, returns a new codec that encodes/decodes
the HList L
followed by a B
.
When called on a Codec[L]
for some L <: HList
, returns a new codec that encodes/decodes
the HList L
followed by a B
.
That is, this operator is a codec-level HList
append operation.
Supports creation of a coproduct codec.
Supports creation of a coproduct codec. See scodec.codecs.CoproductCodecBuilder for details.
When called on a Codec[A]
where A
is not a subytpe of HList
, creates a new codec that encodes/decodes an HList
of B :: A :: HNil
.
When called on a Codec[A]
where A
is not a subytpe of HList
, creates a new codec that encodes/decodes an HList
of B :: A :: HNil
.
For example,
uint8 :: utf8
has type Codec[Int :: String :: HNil]
.
uint8 :: utf8
}}}
When called on a Codec[L]
for some L <: HList
, returns a new codec representing Codec[B :: L]
.
When called on a Codec[L]
for some L <: HList
, returns a new codec representing Codec[B :: L]
.
That is, this operator is a codec-level HList
prepend operation.
codec to prepend
When called on a Codec[L]
for some L <: HList
, returns a new codec the encodes/decodes
the HList K
followed by the HList L
.
When called on a Codec[L]
for some L <: HList
, returns a new codec the encodes/decodes
the HList K
followed by the HList L
.
When called on a Codec[A]
, returns a new codec that encodes/decodes B :: A :: HNil
.
When called on a Codec[A]
, returns a new codec that encodes/decodes B :: A :: HNil
.
HList equivalent of ~>
.
When called on a Codec[L]
for some L <: HList
, returns a new codec that encodes/decodes
B :: L
but only returns L
.
When called on a Codec[L]
for some L <: HList
, returns a new codec that encodes/decodes
B :: L
but only returns L
. HList equivalent of ~>
.
Assuming 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 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.
Creates a new codec that encodes/decodes an HList
type of A :: L
given a function A => Codec[L]
.
Creates a new codec that encodes/decodes an HList
type of A :: L
given a function A => Codec[L]
.
This allows later parts of an HList
codec to be dependent on earlier values.
Operator alias for flatPrepend
.
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 (A, B)
where the codec of B
is dependent on A
.
Operator alias for flatZip.
Transforms using implicitly available evidence that such a transformation is possible.
Transforms using implicitly available evidence that such a transformation is possible.
Typical transformations include converting:
F[L]
for some L <: HList
to/from an F[CC]
for some case class CC
, where the types in the case class are
aligned with the types in L
F[C]
for some C <: Coproduct
to/from an F[SC]
for some sealed class SC
, where the component types in
the coproduct are the leaf subtypes of the sealed class.Gets this as a Decoder
.
Gets this as a Decoder
.
Gets this as an Encoder
.
Gets this as an Encoder
.
Converts this codec to a new codec that compacts the encoded bit vector before returning it.
Converts this codec to a new codec that fails decoding if there are remaining bits.
Converts this GenCodec
to a GenCodec[C, B]
using the supplied C => A
.
Converts this to a codec that fails encoding with an error.
Safely lifts this codec to a codec of a subtype.
Safely lifts this codec to a codec of a subtype.
When a supertype of B
that is not a supertype of A
is decoded,
an decoding error is returned.
Assuming 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 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.
Creates a new codec with all unit values filtered out.
Creates a new codec with all unit values filtered out.
Converts this GenCodec
to a GenCodec[C, B]
using the supplied C => Attempt[A]
.
Converts this GenCodec
to a GenCodec[A, C]
using the supplied B => Attempt[C]
.
Converts this to a codec that fails decoding with an error.
Converts this to a codec that fails decoding with an error.
Transforms using two functions, A => Attempt[B]
and B => Attempt[A]
.
When called on a Codec[L]
for some L <: HList
, returns a new codec the encodes/decodes
the HList L
followed by the value A
, where the latter is encoded/decoded with the codec
returned from applying L
to f
.
When called on a Codec[L]
for some L <: HList
, returns a new codec the encodes/decodes
the HList L
followed by the value A
, where the latter is encoded/decoded with the codec
returned from applying L
to f
.
When called on a Codec[L]
for some L <: HList
, returns a new codec the encodes/decodes
the HList L
followed by the HList M
, where the latter is encoded/decoded with the codec
returned from applying L
to f
.
When called on a Codec[L]
for some L <: HList
, returns a new codec the encodes/decodes
the HList L
followed by the HList M
, where the latter is encoded/decoded with the codec
returned from applying L
to f
.
Converts this decoder to a Decoder[B]
using the supplied A => Decoder[B]
.
Converts this decoder to a Decoder[B]
using the supplied A => Decoder[B]
.
Creates a new codec that encodes/decodes an HList
type of A :: L
given a function A => Codec[L]
.
Creates a new codec that encodes/decodes an HList
type of A :: L
given a function A => Codec[L]
.
This allows later parts of an HList
codec to be dependent on earlier values.
Returns a new codec that encodes/decodes a value of type (A, B)
where the codec of B
is dependent on A
.
Creates a new codec that encodes/decodes an HList
type of A :: B :: HNil
given a function A => Codec[B]
.
Creates a new codec that encodes/decodes an HList
type of A :: B :: HNil
given a function A => Codec[B]
.
If B
is an HList
type, consider using flatPrepend
instead, which avoids nested HLists
.
This is the direct HList
equivalent of flatZip
.
Converts this codec to an HList
based codec by flattening all left nested pairs.
Converts this codec to an HList
based codec by flattening all left nested pairs.
For example, flattenLeftPairs
on a Codec[(((A, B), C), D)]
results in a
Codec[A :: B :: C :: D :: HNil]
. This is particularly useful when combined
with ~
, ~>
, and <~
.
Converts this generalized codec in to a non-generalized codec assuming A
and B
are the same type.
Converts this generalized codec in to a non-generalized codec assuming A
and B
are the same type.
Lifts this codec in to a codec of a singleton hlist.
Converts this GenCodec
to a GenCodec[A, C]
using the supplied B => C
.
Transforms using two functions, A => Attempt[B]
and B => A
.
Transforms using two functions, A => Attempt[B]
and B => A
.
The supplied functions form an injection from B
to A
. Hence, this method converts from
a larger to a smaller type. Hence, the name narrow
.
Creates a Codec[(A, B)]
that first encodes/decodes an A
followed by a B
.
Converts this GenCodec
to a GenCodec[C, B]
using the supplied partial
function from C
to A
.
Polymorphic function version of xmap
.
Polymorphic function version of xmap
.
When called on a Codec[A]
where A
is not a subytpe of HList
, returns a new codec that's the result of
xmapping with p
and q
, using p
to convert from A
to B
and using q
to convert from
B
to A
.
polymorphic function that converts from A
to B
polymorphic function that converts from B
to A
Polymorphic function version of xmap
.
Polymorphic function version of xmap
.
When called on a Codec[L]
for some L <: HList
, returns a new codec that's the result of
xmapping with p
and q
, using p
to convert from L
to M
and using q
to convert from
M
to L
.
polymorphic function that converts from L
to M
polymorphic function that converts from M
to L
Polymorphic function version of xmap
that uses a single polymorphic function in both directions.
Polymorphic function version of xmap
that uses a single polymorphic function in both directions.
When called on a Codec[A]
where A
is not a subytpe of HList
, returns a new codec that's the result of
xmapping with p
for both forward and reverse directions.
polymorphic function that converts from A
to B
and from B
to A
Polymorphic function version of xmap
that uses a single polymorphic function in both directions.
Polymorphic function version of xmap
that uses a single polymorphic function in both directions.
When called on a Codec[L]
for some L <: HList
, returns a new codec that's the result of
xmapping with p
for both forward and reverse directions.
polymorphic function that converts from L
to M
and from M
to L
When called on a Decoder[C]
where C
is a coproduct containing type A
, converts to a Decoder[Option[A]]
.
When called on a Decoder[C]
where C
is a coproduct containing type A
, converts to a Decoder[Option[A]]
.
When called on a Encoder[C]
where C
is a coproduct containing type A
, converts to an Encoder[A]
.
When called on a Encoder[C]
where C
is a coproduct containing type A
, converts to an Encoder[A]
.
Lifts this codec to a codec of a shapeless field -- allowing it to be used in records and unions.
Lifts this codec to a codec of a shapeless field -- allowing it to be used in records and unions.
Lifts this codec to a codec of a shapeless field -- allowing it to be used in records and unions. The specified key is pushed in to the context of any errors that are returned from the resulting codec.
Converts this to a Codec[Unit]
that encodes using the specified zero value and
decodes a unit value when this codec decodes an A
successfully.
Safely lifts this codec to a codec of a supertype.
Safely lifts this codec to a codec of a supertype.
When a subtype of B
that is not a subtype of A
is passed to encode,
an encoding error is returned.
Transforms using two functions, A => B
and B => Attempt[A]
.
Transforms using two functions, A => B
and B => Attempt[A]
.
The supplied functions form an injection from A
to B
. Hence, this method converts from
a smaller to a larger type. Hence, the name widen
.
Transforms using two functions, A => B
and B => Option[A]
.
Transforms using two functions, A => B
and B => Option[A]
.
Particularly useful when combined with case class apply/unapply. E.g., widenOpt(fa, Foo.apply, Foo.unapply)
.
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.
Creates a new codec that is functionally equivalent to this codec but returns the specified string from toString
.
Transforms using the isomorphism described by two functions, A => B
and B => A
.
Creates a Codec[(A, B)]
that first encodes/decodes an A
followed by a B
.
Creates a Codec[(A, B)]
that first encodes/decodes an A
followed by a B
.
Operator alias for pairedWith.
Assuming 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 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.
Transforms using two functions, A => Attempt[B]
and B => Attempt[A]
.
Transforms using two functions, A => Attempt[B]
and B => Attempt[A]
.
(codec: TransformSyntax[Codec, A]).exmap(f, g)
Transforms using two functions, A => Attempt[B]
and B => A
.
Transforms using two functions, A => Attempt[B]
and B => A
.
The supplied functions form an injection from B
to A
. Hence, this method converts from
a larger to a smaller type. Hence, the name narrow
.
(codec: TransformSyntax[Codec, A]).narrow(f, g)
(codec: Tuple2CodecSupport[A]).self
(codec: EnrichedCoproductDecoder[A]).self
(codec: EnrichedCoproductEncoder[Coproduct]).self
(codec: ValueCodecEnrichedWithGenericSupport[A]).self
(codec: ValueCodecEnrichedWithHListSupport[A]).self
(codec: HListCodecEnrichedWithHListSupport[A]).self
Supports TransformSyntax.
Supports TransformSyntax.
(codec: TransformSyntax[Codec, A]).self
Transforms using two functions, A => B
and B => Attempt[A]
.
Transforms using two functions, A => B
and B => Attempt[A]
.
The supplied functions form an injection from A
to B
. Hence, this method converts from
a smaller to a larger type. Hence, the name widen
.
(codec: TransformSyntax[Codec, A]).widen(f, g)
Transforms using the isomorphism described by two functions, A => B
and B => A
.
Transforms using the isomorphism described by two functions, A => B
and B => A
.
(codec: TransformSyntax[Codec, A]).xmap(f, g)
Transforms using two functions, A => B
and B => Option[A]
.
Transforms using two functions, A => B
and B => Option[A]
.
Particularly useful when combined with case class apply/unapply. E.g., pxmap(fa, Foo.apply, Foo.unapply)
.
(Since version 1.7.0) Use widenOpt instead
Supports encoding a value of type
A
to aBitVector
and decoding aBitVector
to a value ofA
.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 typeA
. 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 onCodec
create return a new codec that has been transformed in some way. For example, the xmap method converts aCodec[A]
to aCodec[B]
given two functions,A => B
andB => 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.,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.
Tuple Codecs
The
~
operator supports combining aCodec[A]
and aCodec[B]
in to aCodec[(A, B)]
.For example:
Codecs generated with
~
result in left nested tuples. These left nested tuples can be pulled back apart by pattern matching with~
. For example:Alternatively, a function of N arguments can be lifted to a function of left-nested tuples. For example:
Similarly, a left nested tuple can be created with the
~
operator. This is useful when creating the tuple structure to pass to encode. For example:Tuple based codecs are of limited use compared to
HList
based codecs, which is discussed later.Note: this design is heavily based on Scala's parser combinator library and the syntax it provides.
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 isdef flatZip[B](f: A => Codec[B]): Codec[(A, B)]
. This is similar toflatMap
except the return type isCodec[(A, B)]
instead ofDecoder[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:In this example,
x
is aCodec[(Int, ByteVector)]
but we do not need the size directly in the model because it is redundant with the size stored in theByteVector
. Hence, we remove theInt
byxmap
-ping overx
. 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)
.HList Codecs
HList
s are similar to tuples in that they represent the product of an arbitrary number of types. That is, the size of anHList
is known at compile time and the type of each element is also known at compile time. For more information onHList
s in general, see Shapeless.Codec
makes heavy use ofHList
s. The primary operation is extending aCodec[L]
for someL <: HList
to aCodec[A :: L]
. For example:The
::
method is sort of like cons-ing on to theHList
but it is doing so *inside* theCodec
type. The resulting codec encodes values by passing each component of theHList
to the corresponding codec and concatenating all of the results.There are various methods on this trait that only work on
Codec[L]
for someL <: HList
. Besides the aforementioned::
method, there are others like:::
,flatPrepend
,flatConcat
, etc. One particularly useful method isdropUnits
, which removes anyUnit
values from theHList
.Given a
Codec[X0 :: X1 :: ... Xn :: HNil]
and a case class with typesX0
toXn
in the same order, theHList
codec can be turned in to a case class codec via theas
method. For example:flatPrepend
The
HList
analog toflatZip
isflatPrepend
. It has the signature:It forms a codec of
A
consed on toL
when called on aCodec[A]
and passed a functionA => Codec[L]
. Note that the specified function must return anHList
based codec. Implementing our example from earlier usingflatPrepend
:In this example,
bytes(numBytes)
returns aCodec[ByteVector]
so we called.hlist
on it to lift it in to aCodec[ByteVector :: HNil]
.There are similar methods for flat appending and flat concating.
Coproduct Codecs
Given some ordered list of types, potentially with duplicates, a value of the
HList
of those types has a value for *every* type in the list. In other words, anHList
represents having anX0
ANDX1
AND ... ANDXN
. ACoproduct
for the same list of types represents having a value for *one* of those types. In other words, aCoproduct
represents having anX0
ORX1
OR ... ORXN
. This is somewhat imprecise because a coproduct can tell us exactly whichXi
we have, even in the presence of duplicate types.A coproduct can also be thought of as an
Either
that has an unlimited number of choices instead of just 2 choices.Shapeless represents coproducts in a similar way as
HList
s. A coproduct type is built using the:+:
operator with a sentinal value ofCNil
. For example, anInt
orLong
orString
is represented as the coproduct type:For more information on coproducts in general, see Shapeless.
Like
HList
based codecs, scodec supportsCoproduct
based codecs by coopting syntax from Shapeless. Specifically, the:+:
operator is used:val builder = uint8 :+: int64 :+: utf8
Unlike
HList
based codecs, the result of:+:
is not a codec but rather a codecs.CoproductCodecBuilder. Having a list of types and a codec for each is not sufficient to build a coproduct codec. We also need to describe how each entry in the coproduct is differentiated from the other entries. There are a number of ways to do this and each way changes the binary format significantly. See the docs onCoproductCodecBuilder
for details.Derived Codecs
Codecs for case classes and sealed class hierarchies can often be automatically derived.
Consider this example:
In this example, no explicit codec was defined for
Point
yetCodec[Point]
successfully created one. It did this by "reflecting" over the structure ofPoint
and looking up a codec for each component type (note: no runtime reflection is performed - rather, this is implemented using macro-based compile time reflection). In this case, there are three components, each of typeInt
, so the compiler first looked for an implicitCodec[Int]
. It then combined eachCodec[Int]
using anHList
based codec and finally converted theHList
codec to aCodec[Point]
. It found the implicitCodec[Int]
instances due to the import ofscodec.codecs.implicits._
. Furthermore, if there was an error encoding or decoding a field, the field name (i.e., x, y, or z) is included as context on theErr
returned.This works similarly for sealed class hierarchies -- each subtype is internally represented as a member of a coproduct. There must be the following implicits in scope however:
Discriminated[A, D]
for some discriminator typeD
, which provides theCodec[D]
to use for encoding/decoding the discriminatorDiscriminator[A, X, D]
for each subtypeX
ofA
, which provides the discriminator value for typeX
Codec[X]
for each subtypeX
ofA
Full examples are available in the test directory of this project.
Implicit Codecs
If authoring combinators that require implicit codec arguments, use
shapeless.Lazy[Codec[A]]
instead ofCodec[A]
. This prevents the occurrence of diverging implicit expansion errors.Miscellaneous
Note: DecodingContext allows multiple decoders/codecs to be sequenced one after the other, with the remainder from each decode operation fed in to the input of the next.