Package io.bytestreams.codec.core

Class Codecs

java.lang.Object
io.bytestreams.codec.core.Codecs
public class Codecs extends Object
Unified entry point for creating all codec types.

This facade provides factory methods for number, string, hex, binary, boolean, list, composition, and object codecs.

Example usage: 


 // Number codecs
 Codec<Integer> u8 = Codecs.uint8();
 Codec<Long> i64 = Codecs.int64();

 // String codecs
 Codec<String> ascii = Codecs.ascii(10);
 Codec<String> utf8 = Codecs.utf8();

 // Constant bytes
 Codec<byte[]> magic = Codecs.constant(new byte[] {0x4D, 0x5A});

 // Numeric string codecs
 Codec<Integer> bcd = Codecs.bcdInt(4);
 Codec<Integer> asciiNum = Codecs.asciiInt(4);
 Codec<Long> ebcdicNum = Codecs.ebcdicLong(10);

 // Composition
 Codec<String> prefixed = Codecs.prefixed(Codecs.uint16(), Codecs.utf8());
 Codec<List<Integer>> list = Codecs.listOf(5, Codecs.uint8());

 // Object codecs
 SequentialObjectCodec<Msg> codec = Codecs.<Msg>sequential(Msg::new)
     .field("id", Codecs.int32(), Msg::getId, Msg::setId)
     .build();

  • Method Summary

    Modifier and Type
    Method
    Description
    static Codec<String>
    ascii()
    Creates a variable-length US-ASCII string codec.
    static Codec<String>
    ascii(int length)
    Creates a fixed-length US-ASCII string codec.
    static Codec<String>
    ascii(Codec<Integer> lengthCodec)
    Creates a variable-length US-ASCII string codec where the code point count is encoded as a prefix.
    static Codec<Integer>
    asciiInt(int digits)
    Creates a fixed-length ASCII numeric codec that decodes to Integer.
    static Codec<Long>
    asciiLong(int digits)
    Creates a fixed-length ASCII numeric codec that decodes to Long.
    static Codec<Integer>
    bcdInt(int digits)
    Creates a fixed-length BCD (Binary Coded Decimal) codec that decodes to Integer.
    static Codec<Long>
    bcdLong(int digits)
    Creates a fixed-length BCD (Binary Coded Decimal) codec that decodes to Long.
    static Codec<byte[]>
    binary()
    Creates a variable-length binary codec that reads all remaining bytes from the stream.
    static Codec<byte[]>
    binary(int length)
    Creates a fixed-length binary codec.
    static Codec<byte[]>
    binary(Codec<Integer> lengthCodec)
    Creates a variable-length binary codec where the byte count is encoded as a prefix.
    static Codec<Boolean>
    bool()
    Creates a boolean codec (single byte: 0x00 = false, 0x01 = true).
    static <V> ChoiceCodec.Builder<V>
    choice(Codec<Class<? extends V>> classCodec)
    Creates a new builder for a choice codec that encodes discriminated unions.
    static Codec<byte[]>
    constant(byte[] expected)
    Creates a constant codec that always writes the expected bytes on encode (ignoring the input value) and validates that the bytes match on decode.
    static Codec<String>
    ebcdic()
    Creates a variable-length EBCDIC (IBM1047) string codec.
    static Codec<String>
    ebcdic(int length)
    Creates a fixed-length EBCDIC (IBM1047) string codec.
    static Codec<String>
    ebcdic(Codec<Integer> lengthCodec)
    Creates a variable-length EBCDIC (IBM1047) string codec where the code point count is encoded as a prefix.
    static Codec<Integer>
    ebcdicInt(int digits)
    Creates a fixed-length EBCDIC numeric codec that decodes to Integer.
    static Codec<Long>
    ebcdicLong(int digits)
    Creates a fixed-length EBCDIC numeric codec that decodes to Long.
    static Codec<Float>
    float32()
    Creates a codec for float values (IEEE 754 single-precision, 4 bytes).
    static Codec<Double>
    float64()
    Creates a codec for double values (IEEE 754 double-precision, 8 bytes).
    static Codec<String>
    hex()
    Creates a variable-length hex string codec.
    static Codec<String>
    hex(int length)
    Creates a fixed-length hex string codec.
    static Codec<String>
    hex(Codec<Integer> lengthCodec)
    Creates a variable-length hex string codec where the hex digit count is encoded as a prefix.
    static Codec<Short>
    int16()
    Creates a codec for signed short values (-32768 to 32767), encoded as 2-byte big-endian binary.
    static Codec<Integer>
    int32()
    Creates a codec for signed integer values (-2147483648 to 2147483647), encoded as 4-byte big-endian binary.
    static Codec<Long>
    int64()
    Creates a codec for signed long values, encoded as 8-byte big-endian binary.
    static Codec<String>
    latin1()
    Creates a variable-length ISO-8859-1 (Latin-1) string codec.
    static Codec<String>
    latin1(int length)
    Creates a fixed-length ISO-8859-1 (Latin-1) string codec.
    static Codec<String>
    latin1(Codec<Integer> lengthCodec)
    Creates a variable-length ISO-8859-1 (Latin-1) string codec where the code point count is encoded as a prefix.
    static <V> Codec<V>
    lazy(Supplier<Codec<V>> supplier)
    Creates a lazy codec that defers resolution to first use, enabling recursive definitions.
    static <V> Codec<List<V>>
    listOf(int length, Codec<V> itemCodec)
    Creates a fixed-length list codec that encodes/decodes exactly length items.
    static <V> Codec<List<V>>
    listOf(Codec<Integer> lengthCodec, Codec<V> itemCodec)
    Creates a variable-length list codec where the item count is encoded as a prefix.
    static <V> Codec<List<V>>
    listOf(Codec<V> itemCodec)
    Creates a stream list codec that reads items until EOF.
    static Codec<String>
    ofCharset(Charset charset)
    Creates a variable-length string codec with the specified charset.
    static Codec<String>
    ofCharset(Charset charset, int length)
    Creates a fixed-length string codec with the specified charset.
    static Codec<String>
    ofCharset(Charset charset, Codec<Integer> lengthCodec)
    Creates a variable-length string codec where the code point count is encoded as a prefix.
    static <A, B> PairCodec<A,B>
    pair(Codec<A> first, Codec<B> second)
    Creates a pair codec that encodes and decodes two values sequentially.
    static <V> Codec<V>
    prefixed(Codec<Integer> lengthCodec, Codec<V> valueCodec)
    Creates a variable-length codec where the byte count is encoded as a prefix.
    static <V> Codec<V>
    prefixed(Codec<Integer> lengthCodec, ToIntFunction<V> lengthOf, IntFunction<Codec<V>> codecFactory)
    Creates a variable-length codec where the item count is encoded as a prefix.
    static <T> SequentialObjectCodec.Builder<T>
    sequential(Supplier<T> factory)
    Creates a new builder for a sequential object codec.
    static <K> TaggedObjectCodec.Builder<TaggedData<K>,K>
    tagged(Codec<K> tagCodec)
    Creates a new builder for a tagged object codec using TaggedData.
    static <T extends Tagged<T, K>, K>
    TaggedObjectCodec.Builder<T,K>
    tagged(Supplier<T> factory, Codec<K> tagCodec)
    Creates a new builder for a tagged object codec.
    static <A, B, C> TripleCodec<A,B,C>
    triple(Codec<A> first, Codec<B> second, Codec<C> third)
    Creates a triple codec that encodes and decodes three values sequentially.
    static Codec<Integer>
    uint16()
    Creates a codec for unsigned short values (0 to 65535), encoded as 2-byte big-endian binary.
    static Codec<Long>
    uint32()
    Creates a codec for unsigned integer values (0 to 4294967295), encoded as 4-byte big-endian binary.
    static Codec<Integer>
    uint8()
    Creates a codec for unsigned byte values (0 to 255), encoded as 1-byte binary.
    static Codec<String>
    utf8()
    Creates a variable-length UTF-8 string codec.
    static Codec<String>
    utf8(int length)
    Creates a fixed-length UTF-8 string codec.
    static Codec<String>
    utf8(Codec<Integer> lengthCodec)
    Creates a variable-length UTF-8 string codec where the code point count is encoded as a prefix.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • uint8

      public static Codec<Integer> uint8()
      Creates a codec for unsigned byte values (0 to 255), encoded as 1-byte binary.
      Returns:
      a new unsigned byte codec

    • uint16

      public static Codec<Integer> uint16()
      Creates a codec for unsigned short values (0 to 65535), encoded as 2-byte big-endian binary.
      Returns:
      a new unsigned short codec

    • uint32

      public static Codec<Long> uint32()
      Creates a codec for unsigned integer values (0 to 4294967295), encoded as 4-byte big-endian binary.
      Returns:
      a new unsigned integer codec

    • int16

      public static Codec<Short> int16()
      Creates a codec for signed short values (-32768 to 32767), encoded as 2-byte big-endian binary.
      Returns:
      a new signed short codec

    • int32

      public static Codec<Integer> int32()
      Creates a codec for signed integer values (-2147483648 to 2147483647), encoded as 4-byte big-endian binary.
      Returns:
      a new signed integer codec

    • int64

      public static Codec<Long> int64()
      Creates a codec for signed long values, encoded as 8-byte big-endian binary.
      Returns:
      a new signed long codec

    • float32

      public static Codec<Float> float32()
      Creates a codec for float values (IEEE 754 single-precision, 4 bytes).
      Returns:
      a new float codec

    • float64

      public static Codec<Double> float64()
      Creates a codec for double values (IEEE 754 double-precision, 8 bytes).
      Returns:
      a new double codec

    • ascii

      public static Codec<String> ascii(int length)
      Creates a fixed-length US-ASCII string codec.
      Parameters:
      length - the number of code points
      Returns:
      a new codec

    • ascii

      public static Codec<String> ascii()
      Creates a variable-length US-ASCII string codec.
      Returns:
      a new codec

    • ascii

      public static Codec<String> ascii(Codec<Integer> lengthCodec)
      Creates a variable-length US-ASCII string codec where the code point count is encoded as a prefix.
      Parameters:
      lengthCodec - the codec for the code point count prefix
      Returns:
      a new codec

    • utf8

      public static Codec<String> utf8(int length)
      Creates a fixed-length UTF-8 string codec.
      Parameters:
      length - the number of code points
      Returns:
      a new codec

    • utf8

      public static Codec<String> utf8()
      Creates a variable-length UTF-8 string codec.
      Returns:
      a new codec

    • utf8

      public static Codec<String> utf8(Codec<Integer> lengthCodec)
      Creates a variable-length UTF-8 string codec where the code point count is encoded as a prefix.
      Parameters:
      lengthCodec - the codec for the code point count prefix
      Returns:
      a new codec

    • latin1

      public static Codec<String> latin1(int length)
      Creates a fixed-length ISO-8859-1 (Latin-1) string codec.
      Parameters:
      length - the number of code points
      Returns:
      a new codec

    • latin1

      public static Codec<String> latin1()
      Creates a variable-length ISO-8859-1 (Latin-1) string codec.
      Returns:
      a new codec

    • latin1

      public static Codec<String> latin1(Codec<Integer> lengthCodec)
      Creates a variable-length ISO-8859-1 (Latin-1) string codec where the code point count is encoded as a prefix.
      Parameters:
      lengthCodec - the codec for the code point count prefix
      Returns:
      a new codec

    • ebcdic

      public static Codec<String> ebcdic(int length)
      Creates a fixed-length EBCDIC (IBM1047) string codec.
      Parameters:
      length - the number of code points
      Returns:
      a new codec

    • ebcdic

      public static Codec<String> ebcdic()
      Creates a variable-length EBCDIC (IBM1047) string codec.
      Returns:
      a new codec

    • ebcdic

      public static Codec<String> ebcdic(Codec<Integer> lengthCodec)
      Creates a variable-length EBCDIC (IBM1047) string codec where the code point count is encoded as a prefix.
      Parameters:
      lengthCodec - the codec for the code point count prefix
      Returns:
      a new codec

    • ofCharset

      public static Codec<String> ofCharset(Charset charset, int length)
      Creates a fixed-length string codec with the specified charset.
      Parameters:
      charset - the charset
      length - the number of code points
      Returns:
      a new codec

    • ofCharset

      public static Codec<String> ofCharset(Charset charset)
      Creates a variable-length string codec with the specified charset.
      Parameters:
      charset - the charset
      Returns:
      a new codec

    • ofCharset

      public static Codec<String> ofCharset(Charset charset, Codec<Integer> lengthCodec)
      Creates a variable-length string codec where the code point count is encoded as a prefix.

      For single-byte charsets, uses String.length() for the count (O(1)). For multibyte charsets, uses Strings.codePointCount(java.lang.String) (O(n)).

      Parameters:
      charset - the charset
      lengthCodec - the codec for the code point count prefix
      Returns:
      a new codec

    • hex

      public static Codec<String> hex(int length)
      Creates a fixed-length hex string codec. Odd-length values are left-padded with '0' to align to byte boundaries.
      Parameters:
      length - the number of hex digits
      Returns:
      a new codec

    • hex

      public static Codec<String> hex()
      Creates a variable-length hex string codec. Odd-length values are left-padded with '0' to align to byte boundaries.
      Returns:
      a new codec

    • hex

      public static Codec<String> hex(Codec<Integer> lengthCodec)
      Creates a variable-length hex string codec where the hex digit count is encoded as a prefix. Odd-length values are left-padded with '0' to align to byte boundaries.
      Parameters:
      lengthCodec - the codec for the hex digit count prefix
      Returns:
      a new codec

    • bcdInt

      public static Codec<Integer> bcdInt(int digits)
      Creates a fixed-length BCD (Binary Coded Decimal) codec that decodes to Integer.

      Each byte holds two decimal digits (0–9) in its high and low nibbles. Odd-length digit counts are left-padded with a zero nibble. 

      
 Codec<Integer> codec = Codecs.bcdInt(4);
 codec.encode(42, out);   // writes 0x00, 0x42
 codec.decode(in);        // reads 0x00, 0x42 → 42
      Parameters:
      digits - the number of BCD digits (1 to 9)
      Returns:
      a new BCD integer codec
      Throws:
      IllegalArgumentException - if digits is not between 1 and 9

    • bcdLong

      public static Codec<Long> bcdLong(int digits)
      Creates a fixed-length BCD (Binary Coded Decimal) codec that decodes to Long.

      Each byte holds two decimal digits (0–9) in its high and low nibbles. Odd-length digit counts are left-padded with a zero nibble. 

      
 Codec<Long> codec = Codecs.bcdLong(10);
 codec.encode(1234567890L, out);  // writes 0x12, 0x34, 0x56, 0x78, 0x90
 codec.decode(in);                // reads 0x12, 0x34, 0x56, 0x78, 0x90 → 1234567890
      Parameters:
      digits - the number of BCD digits (1 to 18)
      Returns:
      a new BCD long codec
      Throws:
      IllegalArgumentException - if digits is not between 1 and 18

    • asciiInt

      public static Codec<Integer> asciiInt(int digits)
      Creates a fixed-length ASCII numeric codec that decodes to Integer.

      The value is encoded as a zero-padded decimal string in US-ASCII. 

      
 Codec<Integer> codec = Codecs.asciiInt(4);
 codec.encode(42, out);   // writes "0042" in ASCII
 codec.decode(in);        // reads "0042" in ASCII → 42
      Parameters:
      digits - the number of digits (1 to 9)
      Returns:
      a new ASCII integer codec
      Throws:
      IllegalArgumentException - if digits is not between 1 and 9

    • asciiLong

      public static Codec<Long> asciiLong(int digits)
      Creates a fixed-length ASCII numeric codec that decodes to Long.

      The value is encoded as a zero-padded decimal string in US-ASCII. 

      
 Codec<Long> codec = Codecs.asciiLong(10);
 codec.encode(1234567890L, out);  // writes "1234567890" in ASCII
 codec.decode(in);                // reads "1234567890" in ASCII → 1234567890
      Parameters:
      digits - the number of digits (1 to 18)
      Returns:
      a new ASCII long codec
      Throws:
      IllegalArgumentException - if digits is not between 1 and 18

    • ebcdicInt

      public static Codec<Integer> ebcdicInt(int digits)
      Creates a fixed-length EBCDIC numeric codec that decodes to Integer.

      The value is encoded as a zero-padded decimal string in EBCDIC (IBM1047). 

      
 Codec<Integer> codec = Codecs.ebcdicInt(4);
 codec.encode(42, out);   // writes "0042" in EBCDIC
 codec.decode(in);        // reads "0042" in EBCDIC → 42
      Parameters:
      digits - the number of digits (1 to 9)
      Returns:
      a new EBCDIC integer codec
      Throws:
      IllegalArgumentException - if digits is not between 1 and 9

    • ebcdicLong

      public static Codec<Long> ebcdicLong(int digits)
      Creates a fixed-length EBCDIC numeric codec that decodes to Long.

      The value is encoded as a zero-padded decimal string in EBCDIC (IBM1047). 

      
 Codec<Long> codec = Codecs.ebcdicLong(10);
 codec.encode(1234567890L, out);  // writes "1234567890" in EBCDIC
 codec.decode(in);                // reads "1234567890" in EBCDIC → 1234567890
      Parameters:
      digits - the number of digits (1 to 18)
      Returns:
      a new EBCDIC long codec
      Throws:
      IllegalArgumentException - if digits is not between 1 and 18

    • choice

      public static <V> ChoiceCodec.Builder<V> choice(Codec<Class<? extends V>> classCodec)
      Creates a new builder for a choice codec that encodes discriminated unions.

      The class tag codec determines which alternative to use. The tag-to-class mapping is handled externally via xmap.

      Type Parameters:
      V - the base type of the discriminated union
      Parameters:
      classCodec - the codec for the class tag
      Returns:
      a new choice codec builder

    • lazy

      public static <V> Codec<V> lazy(Supplier<Codec<V>> supplier)
      Creates a lazy codec that defers resolution to first use, enabling recursive definitions.
      Type Parameters:
      V - the value type
      Parameters:
      supplier - supplies the codec on first use
      Returns:
      a new lazy codec

    • pair

      public static <A, B> PairCodec<A,B> pair(Codec<A> first, Codec<B> second)
      Creates a pair codec that encodes and decodes two values sequentially.
      Type Parameters:
      A - the first value type
      B - the second value type
      Parameters:
      first - the codec for the first value
      second - the codec for the second value
      Returns:
      a new pair codec

    • triple

      public static <A, B, C> TripleCodec<A,B,C> triple(Codec<A> first, Codec<B> second, Codec<C> third)
      Creates a triple codec that encodes and decodes three values sequentially.
      Type Parameters:
      A - the first value type
      B - the second value type
      C - the third value type
      Parameters:
      first - the codec for the first value
      second - the codec for the second value
      third - the codec for the third value
      Returns:
      a new triple codec

    • prefixed

      public static <V> Codec<V> prefixed(Codec<Integer> lengthCodec, Codec<V> valueCodec)
      Creates a variable-length codec where the byte count is encoded as a prefix.
      Type Parameters:
      V - the value type
      Parameters:
      lengthCodec - the codec for the byte count prefix
      valueCodec - the codec for the value
      Returns:
      a new variable byte-length codec

    • prefixed

      public static <V> Codec<V> prefixed(Codec<Integer> lengthCodec, ToIntFunction<V> lengthOf, IntFunction<Codec<V>> codecFactory)
      Creates a variable-length codec where the item count is encoded as a prefix.
      Type Parameters:
      V - the value type
      Parameters:
      lengthCodec - the codec for the item count prefix
      lengthOf - a function that returns the item count for a given value
      codecFactory - a function that creates a codec for the given item count
      Returns:
      a new variable item-length codec

    • listOf

      public static <V> Codec<List<V>> listOf(int length, Codec<V> itemCodec)
      Creates a fixed-length list codec that encodes/decodes exactly length items.
      Type Parameters:
      V - the item type
      Parameters:
      length - the exact number of items
      itemCodec - the codec for individual list items
      Returns:
      a new fixed list codec

    • listOf

      public static <V> Codec<List<V>> listOf(Codec<V> itemCodec)
      Creates a stream list codec that reads items until EOF.
      Type Parameters:
      V - the item type
      Parameters:
      itemCodec - the codec for individual list items
      Returns:
      a new stream list codec

    • listOf

      public static <V> Codec<List<V>> listOf(Codec<Integer> lengthCodec, Codec<V> itemCodec)
      Creates a variable-length list codec where the item count is encoded as a prefix.
      Type Parameters:
      V - the item type
      Parameters:
      lengthCodec - the codec for the item count prefix
      itemCodec - the codec for individual list items
      Returns:
      a new codec

    • sequential

      public static <T> SequentialObjectCodec.Builder<T> sequential(Supplier<T> factory)
      Creates a new builder for a sequential object codec.
      Type Parameters:
      T - the type of object to encode/decode
      Parameters:
      factory - factory that creates new instances during decoding
      Returns:
      a new sequential object codec builder

    • tagged

      public static <T extends Tagged<T, K>, K> TaggedObjectCodec.Builder<T,K> tagged(Supplier<T> factory, Codec<K> tagCodec)
      Creates a new builder for a tagged object codec.
      Type Parameters:
      T - the type of object to encode/decode
      K - the tag key type
      Parameters:
      factory - factory that creates new instances during decoding
      tagCodec - the codec used to read and write tags
      Returns:
      a new tagged object codec builder

    • tagged

      public static <K> TaggedObjectCodec.Builder<TaggedData<K>,K> tagged(Codec<K> tagCodec)
      Creates a new builder for a tagged object codec using TaggedData.
      Type Parameters:
      K - the tag key type
      Parameters:
      tagCodec - the codec used to read and write tags
      Returns:
      a new tagged object codec builder

    • binary

      public static Codec<byte[]> binary(int length)
      Creates a fixed-length binary codec.
      Parameters:
      length - the number of bytes
      Returns:
      a new binary codec

    • binary

      public static Codec<byte[]> binary()
      Creates a variable-length binary codec that reads all remaining bytes from the stream.
      Returns:
      a new codec

    • binary

      public static Codec<byte[]> binary(Codec<Integer> lengthCodec)
      Creates a variable-length binary codec where the byte count is encoded as a prefix.
      Parameters:
      lengthCodec - the codec for the byte count prefix
      Returns:
      a new codec

    • constant

      public static Codec<byte[]> constant(byte[] expected)
      Creates a constant codec that always writes the expected bytes on encode (ignoring the input value) and validates that the bytes match on decode.

      Useful for magic numbers, version bytes, and protocol signatures. The value passed to encode is ignored; null is acceptable. 

      
 Codec<byte[]> magic = Codecs.constant(new byte[] {0x4D, 0x5A});
      Parameters:
      expected - the expected byte sequence (must be non-null and non-empty)
      Returns:
      a new constant codec
      Throws:
      NullPointerException - if expected is null
      IllegalArgumentException - if expected is empty

    • bool

      public static Codec<Boolean> bool()
      Creates a boolean codec (single byte: 0x00 = false, 0x01 = true).
      Returns:
      a new boolean codec