Package io.bytestreams.codec.core

Interface Codec<V>

Type Parameters:
V - the type of value this codec handles
All Known Implementing Classes:
BinaryCodec, BinaryNumberCodec, BooleanCodec, ChoiceCodec, ConstantCodec, FixedCodePointStringCodec, FixedHexStringCodec, FixedListCodec, LazyCodec, NotImplementedCodec, PairCodec, RecordingCodec, SequentialObjectCodec, StreamCodePointStringCodec, StreamHexStringCodec, StreamListCodec, TaggedObjectCodec, TripleCodec, VariableByteLengthCodec, VariableItemLengthCodec
public interface Codec<V>
Interface for encoding and decoding values to and from byte streams.

  • Method Summary

    Modifier and Type
    Method
    Description
    V
    decode(InputStream input)
    Decodes a value from the input stream.
    EncodeResult
    encode(V value, OutputStream output)
    Encodes the given value and writes it to the output stream.
    default <U> Codec<U>
    xmap(Converter<V,U> converter)
    Returns a new codec that maps between types using a Converter.
    default <U> Codec<U>
    xmap(Function<V,U> decoder, Function<U,V> encoder)
    Returns a new codec that applies bidirectional mapping functions to transform between value types.

  • Method Details

    • encode

      EncodeResult encode(V value, OutputStream output) throws IOException
      Encodes the given value and writes it to the output stream.
      Parameters:
      value - the value to encode
      output - the output stream to write the encoded bytes to
      Returns:
      the encode result containing logical count and bytes written
      Throws:
      IOException - if an I/O error occurs during encoding
      IllegalArgumentException - if the value violates codec constraints (e.g. wrong length)
      CodecException - if an encoding error is detected (e.g. invalid value, field errors)

    • decode

      V decode(InputStream input) throws IOException
      Decodes a value from the input stream.
      Parameters:
      input - the input stream to read the encoded bytes from
      Returns:
      the decoded value
      Throws:
      IOException - if an I/O error occurs during decoding
      CodecException - if a decoding error is detected (e.g. invalid data, field errors)

    • xmap

      default <U> Codec<U> xmap(Function<V,U> decoder, Function<U,V> encoder)
      Returns a new codec that applies bidirectional mapping functions to transform between value types.

      The decoder function is applied after decoding (base type → mapped type), and the encoder function is applied before encoding (mapped type → base type).

      Type Parameters:
      U - the mapped value type
      Parameters:
      decoder - the function to apply after decoding
      encoder - the function to apply before encoding
      Returns:
      a new codec that maps between V and U

    • xmap

      default <U> Codec<U> xmap(Converter<V,U> converter)
      Returns a new codec that maps between types using a Converter.

      The converter provides the bidirectional mapping between the base type V and the mapped type U. This is useful for reusable or composed conversions. 

      
 BiMap<Integer, Color> colors = BiMap.of(
     Map.entry(1, Color.RED),
     Map.entry(2, Color.GREEN),
     Map.entry(3, Color.BLUE)
 );
 Codec<Color> colorCodec = Codecs.uint8().xmap(colors);
      Type Parameters:
      U - the mapped value type
      Parameters:
      converter - the bidirectional conversion between V and U
      Returns:
      a new codec that maps between V and U