DiscriminatorCodec
Codec that supports the binary structure
the value.
tag ++ value
where the tag
identifies the encoding/decoding ofthe value.
To build an instance of this codec, call discriminated and specify the tag type via the
call one more more of the case combinators on this class.
by
method. Thencall one more more of the case combinators on this class.
The most general case combinators are
In addition to a tag, the
mapping from
The
caseO
and caseP
.In addition to a tag, the
caseO
combinator is defined by providing a mapping fromA
to Option[R]
, a mapping from R
to A
, and a Codec[R]
. The case is used for encoding if themapping 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, thesubcaseO
and subcaseP
constrain R
to being a subtype of A
and do not take a R => A
function.Finally, the least generic case combinators are the
to the
that encodes a 0 if passed a
{{{
discriminated[AnyVal] .by(uint8).typecase(0, bool).typecase(1, int32)
}}}
typecase
combinators which add further constraintsto the
subcase*
combinators. Specifically, the typecase operators omit the A => Option[R]
orPartialFunction[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) })`.- Value Params
- by
-
codec that encodec/decodes the tag value
- cases
-
cases, ordered from highest priority to lowest priority, that handle subsets of
A
- See also
Document{}
def caseO[R](tag: B)(toRep: A => Option[R])(fromRep: R => A)(cr: Codec[R]): DiscriminatorCodec[A, B]
Returns a new discriminator codec with a new case added for the specified tag.
- Type Params
- R
-
representative type that this case handles
- Value Params
- cr
-
codec that encodes/decodes
R
s - fromRep
-
function used during decoding that converts an
R
to anA
- tag
-
tag value for this case
- toRep
-
function used during encoding that converts an
A
to anOption[R]
def caseP[R](tag: B)(toRep: PartialFunction[A, R])(fromRep: R => A)(cr: Codec[R]): DiscriminatorCodec[A, B]
Returns a new discriminator codec with a new case added for the specified tag.
- Type Params
- R
-
representative type that this case handles
- Value Params
- cr
-
codec that encodes/decodes
R
s - fromRep
-
function used during decoding that converts an
R
to anA
- tag
-
tag value for this case
- toRep
-
partial function from
A
toR
used during encoding
Returns a new discriminator codec with a new case added for the specified tag.
- Type Params
- R
-
representative type that this case handles
- Value Params
- cr
-
codec that encodes/decodes
R
s - tag
-
tag value for this case
- toRep
-
function used during encoding that converts an
A
to anOption[R]
Returns a new discriminator codec with a new case added for the specified tag.
- Type Params
- R
-
representative type that this case handles
- Value Params
- cr
-
codec that encodes/decodes
R
s - tag
-
tag value for this case
- toRep
-
partial function from
A
toR
used during encoding
Returns a new discriminator codec with a new case added for the specified tag.
Note: when encoding a value of
runtime class of the supplied
this operation is not safe to use with parameterized representation types.
A
, this combinator compares the runtime class of that value to theruntime class of the supplied
ClassTag[R]
. As such, the erased type of A
is used and hence,this operation is not safe to use with parameterized representation types.
- Type Params
- R
-
representative type that this case handles
- Value Params
- cr
-
codec that encodes/decodes
R
s - tag
-
tag value for this case
Replaces the current framing logic with the specified codec transformation.
Every representative codec is wrapped with the framing logic when encoding/decoding.
- Value Params
- framing
-
new framing logic
Encodes all elements of the specified sequence and concatenates the results, or returns the first encountered error.
- Inhertied from
- Encoder
Creates a new codec that is functionally equivalent to this codec but returns the specified string from
toString
.- Inhertied from
- Codec
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.- Inhertied from
- Codec
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
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.- Inhertied from
- Codec
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.
- Inhertied from
- Codec
Returns a new codec that encodes/decodes a value of type
(A, B)
where the codec of B
is dependent on A
.- Inhertied from
- Codec
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.- Inhertied from
- Codec
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.
- Inhertied from
- Codec
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) }
}
}}}
- Inhertied from
- Codec
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
Type members
Inherited classlikes
Error raised when an unknown discriminator is encountered when decoding.
- Inhertied from
- KnownDiscriminatorType
Value members
Methods
Inherited methods
Transforms this codec to a
Codec[B]
if A
is isomorphic to B
.This is most commonly used to convert a tuple codec to a case class:
- Example
- {{{
case class Point(x: Int, y: Int, z: Int)
val c: Codec[(Int, Int, Int)] = int8 :: int8 :: int8
val p: Codec[Point] = c.as[Point]
}}} - Inhertied from
- Codec