scodec-core/scodec.codecs/DiscriminatorCodec

DiscriminatorCodec

final
class DiscriminatorCodec[A, B] extends Codec[A] with KnownDiscriminatorType[B]

Codec that supports the binary structure tag ++ value where the tag identifies the encoding/decoding of the value.

To build an instance of this codec, call discriminated and specify the tag type via the by method. Then call one more more of the case combinators on this class.

The most general case combinators are caseO and caseP. In addition to a tag, the caseO combinator is defined by providing a mapping from A to Option[R], a mapping from R to A, and a Codec[R]. The case is used for encoding if the mapping 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, the subcaseO 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 typecase combinators which add further constraints to the subcase* combinators. Specifically, the typecase operators omit the A => Option[R] or PartialFunction[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 beforethevaluefield. To support this, use theframingmethod 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
trait Codec[A]
trait Decoder[A]
trait Encoder[A]
class Object
trait Matchable
class Any

Type members

Inherited classlikes

case
class UnknownDiscriminator(discriminator: D, context: List[String])

Error raised when an unknown discriminator is encountered when decoding.

Error raised when an unknown discriminator is encountered when decoding.

Inherited from
KnownDiscriminatorType

Value members

Concrete methods

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.

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 Rs

fromRep

function used during decoding that converts an R to an A

tag

tag value for this case

toRep

function used during encoding that converts an A to an Option[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.

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 Rs

fromRep

function used during decoding that converts an R to an A

tag

tag value for this case

toRep

partial function from A to R used during encoding

def decode(bits: BitVector): Attempt[DecodeResult[A]]
def encode(a: A): Attempt[BitVector]
def framing(framing: [x] => (x$1: Codec[x]) => Codec[x]): DiscriminatorCodec[A, B]

Replaces the current framing logic with the specified codec transformation.

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

def singleton[R <: A](tag: B, value: R): DiscriminatorCodec[A, B]
def subcaseO[R <: A](tag: B)(toRep: A => Option[R])(cr: Codec[R]): DiscriminatorCodec[A, B]

Returns a new discriminator codec with a new case added for the specified tag.

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 Rs

tag

tag value for this case

toRep

function used during encoding that converts an A to an Option[R]

def subcaseP[R <: A](tag: B)(toRep: PartialFunction[A, R])(cr: Codec[R]): DiscriminatorCodec[A, B]

Returns a new discriminator codec with a new case added for the specified tag.

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 Rs

tag

tag value for this case

toRep

partial function from A to R used during encoding

override
def toString: String
Definition Classes
Any
def typecase[R <: A](tag: B, cr: Codec[R])(using evidence$1: ClassTag[R]): DiscriminatorCodec[A, B]

Returns a new discriminator codec with a new case added for the specified tag.

Returns a new discriminator codec with a new case added for the specified tag.

Note: when encoding a value of A, this combinator compares the runtime class of that value to the runtime 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 Rs

tag

tag value for this case

Inherited methods

final
def <~[B](codecB: Codec[B])(using Unit =:= B): Codec[A]

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.

Inherited from
Codec
final
def >>~[B](f: A => Codec[B]): Codec[(A, B)]

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.

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.

Inherited from
Codec
def as[B](using iso: Iso[A, B]): Codec[B]

Transforms this codec to a Codec[B] if A is isomorphic to B.

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]
Inherited from
Codec
def asDecoder: Decoder[A]

Gets this as a Decoder.

Gets this as a Decoder.

Inherited from
Decoder
def asEncoder: Encoder[A]

Gets this as an Encoder.

Gets this as an Encoder.

Inherited from
Encoder
def collect[F[_], A2 >: A](buffer: BitVector, limit: Option[Int])(using factory: Factory[A2, F[A2]]): Attempt[DecodeResult[F[A2]]]

Repeatedly decodes values of type 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 been decoded. Exits upon first decoding error.

Repeatedly decodes values of type 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 been decoded. Exits upon first decoding error.

Inherited from
Decoder
final override
def compact: Codec[A]
Definition Classes
Inherited from
Codec
final override
def complete: Codec[A]
Definition Classes
Inherited from
Codec
final
def consume[B](f: A => Codec[B])(g: B => A): Codec[B]

Similar to flatZip except the A type is not visible in the resulting type -- the binary effects of the Codec[A] still occur though.

Similar to flatZip except the A type is not visible in the resulting type -- the binary effects 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) }
     }
Inherited from
Codec
def contramap[B](f: B => A): Encoder[B]

Converts this encoder to an Encoder[B] using the supplied B => A.

Converts this encoder to an Encoder[B] using the supplied B => A.

Inherited from
Encoder
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 type B using the supplied zero value and append function. Terminates when no more bits are available in the vector. Exits upon first decoding error.

Repeatedly decodes values of type A from the specified vector, converts each value to a B and appends it to an accumulator of type B 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

Inherited from
Decoder
override
def decodeOnly[AA >: A]: Codec[AA]
Definition Classes
Inherited from
Codec
final
def decodeValue(bits: BitVector): Attempt[A]

Attempts to decode a value of type A from the specified bit vector and discards the remaining bits.

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

Inherited from
Decoder
final
def downcast[B <: A](using TypeTest[A, B]): Codec[B]

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.

Inherited from
Codec
final
def dropLeft[B](codecB: Codec[B])(using ev: Unit =:= A): Codec[B]

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.

Inherited from
Codec
final
def dropRight[B](codecB: Codec[B])(using ev: Unit =:= B): Codec[A]

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.

Inherited from
Codec
def econtramap[B](f: B => Attempt[A]): Encoder[B]

Converts this encoder to an Encoder[B] using the supplied B => Attempt[A].

Converts this encoder to an Encoder[B] using the supplied B => Attempt[A].

Inherited from
Encoder
def emap[B](f: A => Attempt[B]): Decoder[B]

Converts this decoder to a Decoder[B] using the supplied A => Attempt[B].

Converts this decoder to a Decoder[B] using the supplied A => Attempt[B].

Inherited from
Decoder
def encodeAll(as: Iterable[A]): Attempt[BitVector]

Encodes all elements of the specified sequence and concatenates the results, or returns the first encountered error.

Encodes all elements of the specified sequence and concatenates the results, or returns the first encountered error.

Inherited from
Encoder
def encodeOnly: Codec[A]

Converts this to a codec that fails decoding with an error.

Converts this to a codec that fails decoding with an error.

Inherited from
Encoder
final
def exmap[B](f: A => Attempt[B], g: B => Attempt[A]): Codec[B]

Transforms using two functions, A => Attempt[B] and B => Attempt[A].

Transforms using two functions, A => Attempt[B] and B => Attempt[A].

Inherited from
Codec
def flatMap[B](f: A => Decoder[B]): Decoder[B]

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

Inherited from
Decoder
final
def flatZip[B](f: A => Codec[B]): Codec[(A, B)]

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.

Inherited from
Codec
def map[B](f: A => B): Decoder[B]

Converts this decoder to a Decoder[B] using the supplied A => B.

Converts this decoder to a Decoder[B] using the supplied A => B.

Inherited from
Decoder
def pcontramap[B](f: B => Option[A]): Encoder[B]

Converts this encoder to an Encoder[B] using the supplied partial function from B to A. The encoding will fail for any B that f maps to None.

Converts this encoder to an Encoder[B] using the supplied partial function from B to A. The encoding will fail for any B that f maps to None.

Inherited from
Encoder
final
def tuple: Codec[A *: EmptyTuple]

Lifts this codec in to a codec of a singleton tuple.

Lifts this codec in to a codec of a singleton tuple.

Inherited from
Codec
final
def unit(zero: A): Codec[Unit]

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.

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.

Inherited from
Codec
final
def upcast[B >: A](using TypeTest[B, A]): Codec[B]

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.

Inherited from
Codec
final
def withContext(context: String): Codec[A]

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 pushes the specified context string in to any errors returned from encode or decode.

Inherited from
Codec
final
def withToString(str: => String): Codec[A]

Creates a new codec that is functionally equivalent to this codec but returns the specified string from toString.

Creates a new codec that is functionally equivalent to this codec but returns the specified string from toString.

Inherited from
Codec
final
def xmap[B](f: A => B, g: B => A): Codec[B]

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.

Inherited from
Codec
final
def ~>[B](codecB: Codec[B])(using Unit =:= A): Codec[B]

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.

Inherited from
Codec

Deprecated and Inherited methods

@deprecated("Use .tuple instead", "2.0.0")
final
def hlist: Codec[A *: EmptyTuple]
Deprecated
Inherited from
Codec