Module net.luis.utils
Package net.luis.utils.io.codec

Interface Codec<C>

Type Parameters:
C - The type of the value that is encoded and decoded by this codec
All Superinterfaces:
Decoder<C>, Encoder<C>
All Known Subinterfaces:
KeyableCodec<C>
All Known Implementing Classes:
EitherCodec, ListCodec, MapCodec, NamedCodec, OptionalCodec, RangeCodec, UnitCodec
public interface Codec<C> extends Encoder<C>, Decoder<C>
A codec is a combination of an encoder and a decoder.
It is used to encode and decode values of a specific type.
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Codec<Boolean>
    BOOLEAN
    A codec that encodes and decodes boolean values.
    static final RangeCodec<Byte>
    BYTE
    A range codec that encodes and decodes byte values.
    static final Codec<byte[]>
    BYTE_ARRAY
    A codec that encodes and decodes byte arrays.
    The underlying byte array is converted to and from a list of bytes.
    static final Codec<Charset>
    CHARSET
    A codec that encodes and decodes charsets.
    The underlying charset is converted to and from a string.
    static final RangeCodec<Double>
    DOUBLE
    A range codec that encodes and decodes double values.
    static final Codec<DoubleStream>
    DOUBLE_STREAM
    A codec that encodes and decodes double streams.
    The underlying double stream is converted to and from a Stream of doubles.
    static final Codec<File>
    FILE
    A codec that encodes and decodes files.
    The underlying file is converted to and from a string.
    static final RangeCodec<Float>
    FLOAT
    A range codec that encodes and decodes float values.
    static final Codec<IntStream>
    INT_STREAM
    A codec that encodes and decodes int streams.
    The underlying int stream is converted to and from a Stream of integers.
    static final RangeCodec<Integer>
    INTEGER
    A range codec that encodes and decodes integer values.
    static final Codec<LocalDate>
    LOCAL_DATE
    A codec that encodes and decodes local date values.
    The underlying local date is converted to and from a string.
    static final Codec<LocalDateTime>
    LOCAL_DATE_TIME
    A codec that encodes and decodes local date time values.
    The underlying local date time is converted to and from a string.
    static final Codec<LocalTime>
    LOCAL_TIME
    A codec that encodes and decodes local time values.
    The underlying local time is converted to and from a string.
    static final RangeCodec<Long>
    LONG
    A range codec that encodes and decodes long values.
    static final Codec<LongStream>
    LONG_STREAM
    A codec that encodes and decodes long streams.
    The underlying long stream is converted to and from a Stream of longs.
    static final Codec<Path>
    PATH
    A codec that encodes and decodes paths.
    The underlying path is converted to and from a string.
    static final RangeCodec<Short>
    SHORT
    A range codec that encodes and decodes short values.
    static final KeyableCodec<String>
    STRING
    A codec that encodes and decodes strings.
    static final Codec<URI>
    URI
    A codec that encodes and decodes URIs.
    The underlying URI is converted to and from a string.
    static final Codec<URL>
    URL
    A codec that encodes and decodes URLs.
    The underlying URL is converted to and from a string.
    static final KeyableCodec<UUID>
    UUID
    A keyable codec that encodes and decodes UUIDs.
    The underlying UUID is converted to and from a string.
    static final Codec<ZonedDateTime>
    ZONED_DATE_TIME
    A codec that encodes and decodes zoned date time values.
    The underlying zoned date time is converted to and from a string.

  • Method Summary

    Modifier and Type
    Method
    Description
    private @NotNull Codec<C>
    codec(@NotNull String name)
    Wraps the current codec into a new codec with the given codec name.
    default <O> @NotNull ConfiguredCodec<C,O>
    configure(@NotNull String name, @NotNull Function<O,C> getter)
    Creates a new configured codec.
    This method combines the named(String, String...) and getter(Function) methods.
    static <E extends Enum<E>>
    @NotNull KeyableCodec<E>
    dynamicEnum(@NotNull Class<E> clazz)
    Creates a new keyable codec for an enum class.
    The enum is encoded using the name of the enum value.
    The decoder supports both the name and the ordinal value of the enum.
    static <F, S> @NotNull Codec<Either<F,S>>
    either(@NotNull Codec<F> firstCodec, @NotNull Codec<S> secondCodec)
    Creates a new either codec for the given codecs.
    The value which is encoded and decoded by this codec can be either of type F or S.
    The codec will try to use the first codec to encode and decode the value,
    if that fails, it will try to use the second codec.
    static <E extends Enum<E>>
    @NotNull KeyableCodec<E>
    enumName(@NotNull Class<E> clazz)
    Creates a new keyable codec for the given enum class.
    The enum value is encoded and decoded using its name.
    static <E extends Enum<E>>
    @NotNull KeyableCodec<E>
    enumOrdinal(@NotNull Class<E> clazz)
    Creates a new keyable codec for the given enum class.
    The enum value is encoded and decoded using its ordinal value.
    static <E extends Enum<E>>
    @NotNull KeyableCodec<E>
    friendlyEnumName(@NotNull Function<E,String> friendlyEncoder, @NotNull Function<String,E> friendlyDecoder)
    Creates a new keyable codec for an enum class.
    The enum value is encoded and decoded using a friendly name.
    default <O> @NotNull ConfiguredCodec<C,O>
    getter(@NotNull Function<O,C> getter)
    Creates a new configured codec.
    The configured codec is used in the codec builder to create codecs for complex data structures.
    The configured codec encodes and decodes components of the data structure using the given getter function.
    It is expected that this is only called on named codecs.
    default @NotNull KeyableCodec<C>
    keyable(@NotNull Function<C,String> keyEncoder, @NotNull Function<String,@Nullable C> keyDecoder)
    Wraps the current codec into a new keyable codec using the given key encoder and key decoder.
    The key encoder and key decoder are defined as functions that convert keys of the type C to and from strings.
    If the key decoder is unable to decode a key, it should return null.
    static <C> @NotNull KeyableCodec<C>
    keyable(@NotNull Codec<C> codec, @NotNull Function<C,String> keyEncoder, @NotNull Function<String,@Nullable C> keyDecoder)
    Creates a new keyable codec for the given codec using the given key encoder and key decoder.
    The key encoder and key decoder are defined as functions that convert keys of the type C to and from strings.
    If the key decoder is unable to decode a key, it should return null.
    static <C> @NotNull KeyableCodec<C>
    keyable(@NotNull Codec<C> codec, @NotNull Function<String,@Nullable C> keyDecoder)
    Creates a new keyable codec for the given codec using the given key encoder and key decoder.
    The key encoder is the java built-in toString() method.
    The key decoder is defined as function that converts keys from strings to values of the type C.
    If the key decoder is unable to decode a key, it should return null.
    static <C> @NotNull KeyableCodec<C>
    keyable(@NotNull Codec<C> codec, @NotNull KeyableEncoder<C> encoder, @NotNull KeyableDecoder<C> decoder)
    Creates a new keyable codec for the given codec using the given key encoder and key decoder.
    default @NotNull Codec<List<C>>
    list()
    Creates a new list codec uses the current codec as element codec for the list codec.
    The created list codec has no size restrictions.
    default @NotNull Codec<List<C>>
    list(int maxSize)
    Creates a new list codec uses the current codec as element codec for the list codec with the given maximum size.
    The list must have at most the maximum size after encoding and decoding.
    default @NotNull Codec<List<C>>
    list(int minSize, int maxSize)
    Creates a new list codec uses the current codec as element codec for the list codec with the given minimum and maximum size.
    The list must have at least the minimum size and at most the maximum size after encoding and decoding.
    static <C> @NotNull Codec<List<C>>
    list(@NotNull Codec<C> codec)
    Creates a new list codec for the given codec.
    The created list codec has no size restrictions.
    static <C> @NotNull Codec<List<C>>
    list(@NotNull Codec<C> codec, int maxSize)
    Creates a new list codec for the given codec and maximum size.
    The list must have at most the maximum size after encoding and decoding.
    static <C> @NotNull Codec<List<C>>
    list(@NotNull Codec<C> codec, int minSize, int maxSize)
    Creates a new list codec for the given codec and minimum and maximum size.
    The list must have at least the minimum size and at most the maximum size after encoding and decoding.
    static <C> @NotNull Codec<Map<String,C>>
    map(@NotNull Codec<C> valueCodec)
    Creates a new map codec with STRING as key codec and the given value codec.
    The created map codec has no size restrictions.
    static <K, V> @NotNull Codec<Map<K,V>>
    map(@NotNull KeyableCodec<K> keyCodec, @NotNull Codec<V> valueCodec)
    Creates a new map codec with the given key codec and value codec.
    The created map codec has no size restrictions.
    static <K, V> @NotNull Codec<Map<K,V>>
    map(@NotNull KeyableCodec<K> keyCodec, @NotNull Codec<V> valueCodec, int maxSize)
    Creates a new map codec with the given key codec and value codec and maximum size.
    The map must have at most the maximum size after encoding and decoding.
    static <K, V> @NotNull Codec<Map<K,V>>
    map(@NotNull KeyableCodec<K> keyCodec, @NotNull Codec<V> valueCodec, int minSize, int maxSize)
    Creates a new map codec with the given key codec and value codec and minimum and maximum size.
    The map must have at least the minimum size and at most the maximum size after encoding and decoding.
    default <O> @NotNull Codec<O>
    map(@NotNull ResultingFunction<O,C> to, @NotNull ResultMappingFunction<C,O> from)
    Creates a new mapped codec of type O from the current codec.
    This mapping functions allows the handling of errors that occur during mapping.
    default <O> @NotNull Codec<O>
    mapFlat(@NotNull Function<O,C> to, @NotNull ResultMappingFunction<C,O> from)
    Creates a new mapped codec of type O from the current codec.
    default @NotNull Codec<C>
    named(@NotNull String name, String @NotNull ... aliases)
    Creates a new named codec with the current codec using the given name and aliases.
    default @NotNull Codec<List<C>>
    noneEmptyList()
    Creates a new list codec uses the current codec as element codec for the list codec for non-empty lists.
    The list must not be empty after encoding and decoding.
    static <C> @NotNull Codec<List<C>>
    noneEmptyList(@NotNull Codec<C> codec)
    Creates a new list codec for the given codec for non-empty lists.
    The list must not be empty after encoding and decoding.
    static <K, V> @NotNull Codec<Map<K,V>>
    noneEmptyMap(@NotNull KeyableCodec<K> keyCodec, @NotNull Codec<V> valueCodec)
    Creates a new map codec with the given key codec and value codec for non-empty maps.
    The map must not be empty after encoding and decoding.
    static @NotNull KeyableCodec<String>
    noneEmptyString()
    Creates a new keyable string codec for non-empty strings.
    The string must not be empty after encoding and decoding.
    static <C> @NotNull Codec<C>
    of(@NotNull Encoder<C> encoder, @NotNull Decoder<C> decoder, @NotNull String name)
    Creates a new codec from the given encoder and decoder with the given name.
    default @NotNull Codec<Optional<C>>
    optional()
    Wraps the current codec into a new optional codec.
    static <C> @NotNull Codec<Optional<C>>
    optional(@NotNull Codec<C> codec)
    Creates a new optional codec for the given codec.
    default @NotNull Codec<C>
    orElse(C defaultValue)
    Creates a new codec that will return the given default value in an error case during decoding.
    default @NotNull Codec<C>
    orElseGet(@NotNull Supplier<C> supplier)
    Creates a new codec that will return the value provided by the given supplier in an error case during decoding.
    default @NotNull Codec<Stream<C>>
    stream()
    Creates a new stream codec uses the current codec as element codec for the stream codec.
    static <C> @NotNull Codec<Stream<C>>
    stream(@NotNull Codec<C> codec)
    Creates a new stream codec for the given codec.
    static @NotNull KeyableCodec<String>
    string(int length)
    Creates a new keyable string codec for the given maximum length.
    static @NotNull KeyableCodec<String>
    string(int minLength, int maxLength)
    Creates a new keyable string codec for the given minimum and maximum length.
    static <E> @NotNull Codec<E>
    stringResolver(@NotNull Function<E,String> stringEncoder, @NotNull Function<String,@Nullable E> stringDecoder)
    Creates a new codec that encodes and decodes values of the type C to and from strings.
    The string encoder and decoder are defined as functions that convert values of the type C to and from strings.
    If the decoder is unable to decode a string, it should return null.
    static <C> @NotNull Codec<C>
    unit(C value)
    Creates a new unit codec for the given value.
    static <C> @NotNull Codec<C>
    unit(@NotNull Supplier<C> supplier)
    Creates a new unit codec for the given supplier.
    default @NotNull Codec<C>
    validate(@NotNull Function<C,Result<C>> validator)
    Creates a new codec that will validate the result of the decoding process using the given validator function.
    The validator function is applied to the decoded value and must return a result that contains the validated value or an error message.
    default @NotNull Codec<C>
    withAlternative(@NotNull Codec<? extends C> alternative)
    Creates a new codec that uses the current codec as the main codec and the given codec as alternative codec.
    If the main codec fails to encode or decode a value, the alternative codec is used.
    static <C> @NotNull Codec<C>
    withAlternative(@NotNull Codec<C> main, @NotNull Codec<? extends C> alternative)
    Creates a new codec that uses the given codec as the main codec and the given codec as alternative codec.
    If the main codec fails to encode or decode a value, the alternative codec is used.
    default <O> @NotNull Codec<O>
    xmap(@NotNull Function<O,C> to, @NotNull Function<C,O> from)
    Creates a new mapped codec of type O from the current codec.

    Methods inherited from interface net.luis.utils.io.codec.decoder.Decoder

    decode, decodeStart, mapDecoder

    Methods inherited from interface net.luis.utils.io.codec.encoder.Encoder

    encode, encode, encodeStart, mapEncoder

  • Field Details

    • BOOLEAN

      static final Codec<Boolean> BOOLEAN
      A codec that encodes and decodes boolean values.

    • BYTE

      static final RangeCodec<Byte> BYTE
      A range codec that encodes and decodes byte values.

    • SHORT

      static final RangeCodec<Short> SHORT
      A range codec that encodes and decodes short values.

    • INTEGER

      static final RangeCodec<Integer> INTEGER
      A range codec that encodes and decodes integer values.

    • LONG

      static final RangeCodec<Long> LONG
      A range codec that encodes and decodes long values.

    • FLOAT

      static final RangeCodec<Float> FLOAT
      A range codec that encodes and decodes float values.

    • DOUBLE

      static final RangeCodec<Double> DOUBLE
      A range codec that encodes and decodes double values.

    • STRING

      static final KeyableCodec<String> STRING
      A codec that encodes and decodes strings.

    • BYTE_ARRAY

      static final Codec<byte[]> BYTE_ARRAY
      A codec that encodes and decodes byte arrays.
      The underlying byte array is converted to and from a list of bytes.

    • INT_STREAM

      static final Codec<IntStream> INT_STREAM
      A codec that encodes and decodes int streams.
      The underlying int stream is converted to and from a Stream of integers.

    • LONG_STREAM

      static final Codec<LongStream> LONG_STREAM
      A codec that encodes and decodes long streams.
      The underlying long stream is converted to and from a Stream of longs.

    • DOUBLE_STREAM

      static final Codec<DoubleStream> DOUBLE_STREAM
      A codec that encodes and decodes double streams.
      The underlying double stream is converted to and from a Stream of doubles.

    • UUID

      static final KeyableCodec<UUID> UUID
      A keyable codec that encodes and decodes UUIDs.
      The underlying UUID is converted to and from a string.

    • LOCAL_TIME

      static final Codec<LocalTime> LOCAL_TIME
      A codec that encodes and decodes local time values.
      The underlying local time is converted to and from a string.

    • LOCAL_DATE

      static final Codec<LocalDate> LOCAL_DATE
      A codec that encodes and decodes local date values.
      The underlying local date is converted to and from a string.

    • LOCAL_DATE_TIME

      static final Codec<LocalDateTime> LOCAL_DATE_TIME
      A codec that encodes and decodes local date time values.
      The underlying local date time is converted to and from a string.

    • ZONED_DATE_TIME

      static final Codec<ZonedDateTime> ZONED_DATE_TIME
      A codec that encodes and decodes zoned date time values.
      The underlying zoned date time is converted to and from a string.

    • CHARSET

      static final Codec<Charset> CHARSET
      A codec that encodes and decodes charsets.
      The underlying charset is converted to and from a string.

    • FILE

      static final Codec<File> FILE
      A codec that encodes and decodes files.
      The underlying file is converted to and from a string.

    • PATH

      static final Codec<Path> PATH
      A codec that encodes and decodes paths.
      The underlying path is converted to and from a string.

    • URI

      static final Codec<URI> URI
      A codec that encodes and decodes URIs.
      The underlying URI is converted to and from a string.

    • URL

      static final Codec<URL> URL
      A codec that encodes and decodes URLs.
      The underlying URL is converted to and from a string.

  • Method Details

    • of

      @NotNull static <C> @NotNull Codec<C> of(@NotNull @NotNull Encoder<C> encoder, @NotNull @NotNull Decoder<C> decoder, @NotNull @NotNull String name)
      Creates a new codec from the given encoder and decoder with the given name.
      Type Parameters:
      C - The type of the value that is encoded and decoded by the codec
      Parameters:
      encoder - The encoder that is used to encode values of the type C
      decoder - The decoder that is used to decode values of the type C
      name - The name of the codec
      Returns:
      A new codec
      Throws:
      NullPointerException - If the encoder, decoder or name is null

    • keyable

      @NotNull static <C> @NotNull KeyableCodec<C> keyable(@NotNull @NotNull Codec<C> codec, @NotNull @NotNull Function<String,@Nullable C> keyDecoder)
      Creates a new keyable codec for the given codec using the given key encoder and key decoder.
      The key encoder is the java built-in toString() method.
      The key decoder is defined as function that converts keys from strings to values of the type C.
      If the key decoder is unable to decode a key, it should return null.
      Type Parameters:
      C - The type of the value that is encoded and decoded by the codec
      Parameters:
      codec - The base codec that is used to encode and decode values of the type C
      keyDecoder - The key decoder
      Returns:
      A new keyable codec
      Throws:
      NullPointerException - If the codec or key decoder is null
      See Also:

    • keyable

      @NotNull static <C> @NotNull KeyableCodec<C> keyable(@NotNull @NotNull Codec<C> codec, @NotNull @NotNull Function<C,String> keyEncoder, @NotNull @NotNull Function<String,@Nullable C> keyDecoder)
      Creates a new keyable codec for the given codec using the given key encoder and key decoder.
      The key encoder and key decoder are defined as functions that convert keys of the type C to and from strings.
      If the key decoder is unable to decode a key, it should return null.
      Type Parameters:
      C - The type of the value that is encoded and decoded by the codec
      Parameters:
      codec - The base codec that is used to encode and decode values of the type C
      keyEncoder - The key encoder
      keyDecoder - The key decoder
      Returns:
      A new keyable codec
      Throws:
      NullPointerException - If the codec, key encoder or key decoder is null
      See Also:

    • keyable

      @NotNull static <C> @NotNull KeyableCodec<C> keyable(@NotNull @NotNull Codec<C> codec, @NotNull @NotNull KeyableEncoder<C> encoder, @NotNull @NotNull KeyableDecoder<C> decoder)
      Creates a new keyable codec for the given codec using the given key encoder and key decoder.
      Type Parameters:
      C - The type of the value that is encoded and decoded by the codec
      Parameters:
      codec - The base codec that is used to encode and decode values of the type C
      encoder - The key encoder that is used to encode keys of the type C
      decoder - The key decoder that is used to decode keys of the type C
      Returns:
      A new keyable codec
      Throws:
      NullPointerException - If the codec, key encoder or key decoder is null
      See Also:

    • enumOrdinal

      @NotNull static <E extends Enum<E>> @NotNull KeyableCodec<E> enumOrdinal(@NotNull @NotNull Class<E> clazz)
      Creates a new keyable codec for the given enum class.
      The enum value is encoded and decoded using its ordinal value.
      Type Parameters:
      E - The type of the enum
      Parameters:
      clazz - The enum class
      Returns:
      A new keyable codec
      Throws:
      NullPointerException - If the enum class is null
      See Also:

    • enumName

      @NotNull static <E extends Enum<E>> @NotNull KeyableCodec<E> enumName(@NotNull @NotNull Class<E> clazz)
      Creates a new keyable codec for the given enum class.
      The enum value is encoded and decoded using its name.
      Type Parameters:
      E - The type of the enum
      Parameters:
      clazz - The enum class
      Returns:
      A new keyable codec
      Throws:
      NullPointerException - If the enum class is null
      See Also:

    • friendlyEnumName

      @NotNull static <E extends Enum<E>> @NotNull KeyableCodec<E> friendlyEnumName(@NotNull @NotNull Function<E,String> friendlyEncoder, @NotNull @NotNull Function<String,E> friendlyDecoder)
      Creates a new keyable codec for an enum class.
      The enum value is encoded and decoded using a friendly name.
      Type Parameters:
      E - The type of the enum
      Parameters:
      friendlyEncoder - The function that converts an enum value to a friendly name
      friendlyDecoder - The function that converts a friendly name to an enum value
      Returns:
      A new keyable codec
      Throws:
      NullPointerException - If the friendly name encoder or decoder is null
      See Also:

    • dynamicEnum

      @NotNull static <E extends Enum<E>> @NotNull KeyableCodec<E> dynamicEnum(@NotNull @NotNull Class<E> clazz)
      Creates a new keyable codec for an enum class.
      The enum is encoded using the name of the enum value.
      The decoder supports both the name and the ordinal value of the enum.
      Type Parameters:
      E - The type of the enum
      Parameters:
      clazz - The enum class
      Returns:
      A new keyable codec
      Throws:
      NullPointerException - If the enum class is null
      See Also:

    • string

      @NotNull static @NotNull KeyableCodec<String> string(int length)
      Creates a new keyable string codec for the given maximum length.
      Parameters:
      length - The maximum length of the string (inclusive)
      Returns:
      A new keyable string codec
      Throws:
      IllegalArgumentException - If the length is less than 0
      See Also:

    • string

      @NotNull static @NotNull KeyableCodec<String> string(int minLength, int maxLength)
      Creates a new keyable string codec for the given minimum and maximum length.
      Parameters:
      minLength - The minimum length of the string (inclusive)
      maxLength - The maximum length of the string (inclusive)
      Returns:
      A new keyable string codec
      Throws:
      IllegalArgumentException - If the minimum length is less than zero or greater than the maximum length
      See Also:

    • noneEmptyString

      @NotNull static @NotNull KeyableCodec<String> noneEmptyString()
      Creates a new keyable string codec for non-empty strings.
      The string must not be empty after encoding and decoding.
      Returns:
      A new keyable string codec
      See Also:

    • unit

      @NotNull static <C> @NotNull Codec<C> unit(@Nullable C value)
      Creates a new unit codec for the given value.
      Type Parameters:
      C - The type of the value
      Parameters:
      value - The value
      Returns:
      A new unit codec
      See Also:

    • unit

      @NotNull static <C> @NotNull Codec<C> unit(@NotNull @NotNull Supplier<C> supplier)
      Creates a new unit codec for the given supplier.
      Type Parameters:
      C - The type of the value
      Parameters:
      supplier - The supplier that provides the value
      Returns:
      A new unit codec
      Throws:
      NullPointerException - If the supplier is null
      See Also:

    • optional

      @NotNull static <C> @NotNull Codec<Optional<C>> optional(@NotNull @NotNull Codec<C> codec)
      Creates a new optional codec for the given codec.
      Type Parameters:
      C - The type of the value that is encoded and decoded by the codec
      Parameters:
      codec - The base codec
      Returns:
      A new optional codec
      Throws:
      NullPointerException - If the codec is null
      See Also:

    • list

      @NotNull static <C> @NotNull Codec<List<C>> list(@NotNull @NotNull Codec<C> codec)
      Creates a new list codec for the given codec.
      The created list codec has no size restrictions.
      Type Parameters:
      C - The type of the list elements that are encoded and decoded by the codec
      Parameters:
      codec - The base codec
      Returns:
      A new list codec
      Throws:
      NullPointerException - If the codec is null
      See Also:

    • list

      @NotNull static <C> @NotNull Codec<List<C>> list(@NotNull @NotNull Codec<C> codec, int maxSize)
      Creates a new list codec for the given codec and maximum size.
      The list must have at most the maximum size after encoding and decoding.
      Type Parameters:
      C - The type of the list elements that are encoded and decoded by the codec
      Parameters:
      codec - The base codec
      maxSize - The maximum size of the list (inclusive)
      Returns:
      A new list codec
      Throws:
      NullPointerException - If the codec is null
      IllegalArgumentException - If the maximum size is less than 0
      See Also:

    • list

      @NotNull static <C> @NotNull Codec<List<C>> list(@NotNull @NotNull Codec<C> codec, int minSize, int maxSize)
      Creates a new list codec for the given codec and minimum and maximum size.
      The list must have at least the minimum size and at most the maximum size after encoding and decoding.
      Type Parameters:
      C - The type of the list elements that are encoded and decoded by the codec
      Parameters:
      codec - The base codec
      minSize - The minimum size of the list (inclusive)
      maxSize - The maximum size of the list (inclusive)
      Returns:
      A new list codec
      Throws:
      NullPointerException - If the codec is null
      IllegalArgumentException - If the minimum size is less than zero or greater than the maximum size
      See Also:

    • noneEmptyList

      @NotNull static <C> @NotNull Codec<List<C>> noneEmptyList(@NotNull @NotNull Codec<C> codec)
      Creates a new list codec for the given codec for non-empty lists.
      The list must not be empty after encoding and decoding.
      Type Parameters:
      C - The type of the list elements that are encoded and decoded by the codec
      Parameters:
      codec - The base codec
      Returns:
      A new list codec
      Throws:
      NullPointerException - If the codec is null
      See Also:

    • stream

      @NotNull static <C> @NotNull Codec<Stream<C>> stream(@NotNull @NotNull Codec<C> codec)
      Creates a new stream codec for the given codec.
      Type Parameters:
      C - The type of the stream elements that are encoded and decoded by the codec
      Parameters:
      codec - The base codec
      Returns:
      A new stream codec
      Throws:
      NullPointerException - If the codec is null

    • map

      @NotNull static <C> @NotNull Codec<Map<String,C>> map(@NotNull @NotNull Codec<C> valueCodec)
      Creates a new map codec with STRING as key codec and the given value codec.
      The created map codec has no size restrictions.
      Type Parameters:
      C - The type of the map values that are encoded and decoded by the codec
      Parameters:
      valueCodec - The value codec
      Returns:
      A new map codec
      Throws:
      NullPointerException - If the value codec is null
      See Also:

    • map

      @NotNull static <K, V> @NotNull Codec<Map<K,V>> map(@NotNull @NotNull KeyableCodec<K> keyCodec, @NotNull @NotNull Codec<V> valueCodec)
      Creates a new map codec with the given key codec and value codec.
      The created map codec has no size restrictions.
      Type Parameters:
      K - The type of the map keys that are encoded and decoded by the codec
      V - The type of the map values that are encoded and decoded by the codec
      Parameters:
      keyCodec - The key codec
      valueCodec - The value codec
      Returns:
      A new map codec
      Throws:
      NullPointerException - If the key codec or value codec is null
      See Also:

    • map

      @NotNull static <K, V> @NotNull Codec<Map<K,V>> map(@NotNull @NotNull KeyableCodec<K> keyCodec, @NotNull @NotNull Codec<V> valueCodec, int maxSize)
      Creates a new map codec with the given key codec and value codec and maximum size.
      The map must have at most the maximum size after encoding and decoding.
      Type Parameters:
      K - The type of the map keys that are encoded and decoded by the codec
      V - The type of the map values that are encoded and decoded by the codec
      Parameters:
      keyCodec - The key codec
      valueCodec - The value codec
      maxSize - The maximum size of the map (inclusive)
      Returns:
      A new map codec
      Throws:
      NullPointerException - If the key codec or value codec is null
      IllegalArgumentException - If the maximum size is less than 0
      See Also:

    • map

      @NotNull static <K, V> @NotNull Codec<Map<K,V>> map(@NotNull @NotNull KeyableCodec<K> keyCodec, @NotNull @NotNull Codec<V> valueCodec, int minSize, int maxSize)
      Creates a new map codec with the given key codec and value codec and minimum and maximum size.
      The map must have at least the minimum size and at most the maximum size after encoding and decoding.
      Type Parameters:
      K - The type of the map keys that are encoded and decoded by the codec
      V - The type of the map values that are encoded and decoded by the codec
      Parameters:
      keyCodec - The key codec
      valueCodec - The value codec
      minSize - The minimum size of the map (inclusive)
      maxSize - The maximum size of the map (inclusive)
      Returns:
      A new map codec
      Throws:
      NullPointerException - If the key codec or value codec is null
      IllegalArgumentException - If the minimum size is less than zero or greater than the maximum size
      See Also:

    • noneEmptyMap

      @NotNull static <K, V> @NotNull Codec<Map<K,V>> noneEmptyMap(@NotNull @NotNull KeyableCodec<K> keyCodec, @NotNull @NotNull Codec<V> valueCodec)
      Creates a new map codec with the given key codec and value codec for non-empty maps.
      The map must not be empty after encoding and decoding.
      Type Parameters:
      K - The type of the map keys that are encoded and decoded by the codec
      V - The type of the map values that are encoded and decoded by the codec
      Parameters:
      keyCodec - The key codec
      valueCodec - The value codec
      Returns:
      A new map codec
      Throws:
      NullPointerException - If the key codec or value codec is null
      See Also:

    • either

      @NotNull static <F, S> @NotNull Codec<Either<F,S>> either(@NotNull @NotNull Codec<F> firstCodec, @NotNull @NotNull Codec<S> secondCodec)
      Creates a new either codec for the given codecs.
      The value which is encoded and decoded by this codec can be either of type F or S.
      The codec will try to use the first codec to encode and decode the value,
      if that fails, it will try to use the second codec.

      Note: If the first codec is a string codec, it will always succeed,
      so the second codec will never be used.

      Type Parameters:
      F - The type of the first value
      S - The type of the second value
      Parameters:
      firstCodec - The first codec
      secondCodec - The second codec
      Returns:
      A new either codec
      Throws:
      NullPointerException - If the first codec or second codec is null
      See Also:

    • withAlternative

      @NotNull static <C> @NotNull Codec<C> withAlternative(@NotNull @NotNull Codec<C> main, @NotNull @NotNull Codec<? extends C> alternative)
      Creates a new codec that uses the given codec as the main codec and the given codec as alternative codec.
      If the main codec fails to encode or decode a value, the alternative codec is used.
      Type Parameters:
      C - The type of the value that is encoded and decoded by the codec
      Parameters:
      main - The main codec
      alternative - The alternative codec
      Returns:
      A new codec
      Throws:
      NullPointerException - If the main codec or alternative codec is null

    • stringResolver

      @NotNull static <E> @NotNull Codec<E> stringResolver(@NotNull @NotNull Function<E,String> stringEncoder, @NotNull @NotNull Function<String,@Nullable E> stringDecoder)
      Creates a new codec that encodes and decodes values of the type C to and from strings.
      The string encoder and decoder are defined as functions that convert values of the type C to and from strings.
      If the decoder is unable to decode a string, it should return null.
      Type Parameters:
      E - The type of the value that is encoded and decoded by the codec
      Parameters:
      stringEncoder - The encoder function
      stringDecoder - The decoder function
      Returns:
      A new codec
      Throws:
      NullPointerException - If the string encoder or decoder is null

    • codec

      @NotNull private @NotNull Codec<C> codec(@NotNull @NotNull String name)
      Wraps the current codec into a new codec with the given codec name.
      Parameters:
      name - The name of the codec
      Returns:
      A new codec
      Throws:
      NullPointerException - If the codec name is null
      See Also:

    • keyable

      @NotNull default @NotNull KeyableCodec<C> keyable(@NotNull @NotNull Function<C,String> keyEncoder, @NotNull @NotNull Function<String,@Nullable C> keyDecoder)
      Wraps the current codec into a new keyable codec using the given key encoder and key decoder.
      The key encoder and key decoder are defined as functions that convert keys of the type C to and from strings.
      If the key decoder is unable to decode a key, it should return null.
      Parameters:
      keyEncoder - The key encoder
      keyDecoder - The key decoder
      Returns:
      A new keyable codec
      Throws:
      NullPointerException - If the key encoder or key decoder is null
      See Also:

    • optional

      @NotNull default @NotNull Codec<Optional<C>> optional()
      Wraps the current codec into a new optional codec.
      Returns:
      A new optional codec for the current codec
      See Also:

    • list

      @NotNull default @NotNull Codec<List<C>> list()
      Creates a new list codec uses the current codec as element codec for the list codec.
      The created list codec has no size restrictions.
      Returns:
      A new list codec for the current codec
      See Also:

    • list

      @NotNull default @NotNull Codec<List<C>> list(int maxSize)
      Creates a new list codec uses the current codec as element codec for the list codec with the given maximum size.
      The list must have at most the maximum size after encoding and decoding.
      Parameters:
      maxSize - The maximum size of the list (inclusive)
      Returns:
      A new list codec for the current codec
      Throws:
      IllegalArgumentException - If the maximum size is less than 0
      See Also:

    • list

      @NotNull default @NotNull Codec<List<C>> list(int minSize, int maxSize)
      Creates a new list codec uses the current codec as element codec for the list codec with the given minimum and maximum size.
      The list must have at least the minimum size and at most the maximum size after encoding and decoding.
      Parameters:
      minSize - The minimum size of the list (inclusive)
      maxSize - The maximum size of the list (inclusive)
      Returns:
      A new list codec for the current codec
      Throws:
      IllegalArgumentException - If the minimum size is less than zero or greater than the maximum size
      See Also:

    • noneEmptyList

      @NotNull default @NotNull Codec<List<C>> noneEmptyList()
      Creates a new list codec uses the current codec as element codec for the list codec for non-empty lists.
      The list must not be empty after encoding and decoding.
      Returns:
      A new list codec for the current codec
      See Also:

    • stream

      @NotNull default @NotNull Codec<Stream<C>> stream()
      Creates a new stream codec uses the current codec as element codec for the stream codec.
      Returns:
      A new stream codec for the current codec
      See Also:

    • withAlternative

      @NotNull default @NotNull Codec<C> withAlternative(@NotNull @NotNull Codec<? extends C> alternative)
      Creates a new codec that uses the current codec as the main codec and the given codec as alternative codec.
      If the main codec fails to encode or decode a value, the alternative codec is used.
      Parameters:
      alternative - The alternative codec
      Returns:
      A new codec
      Throws:
      NullPointerException - If the alternative codec is null
      See Also:

    • xmap

      @NotNull default <O> @NotNull Codec<O> xmap(@NotNull @NotNull Function<O,C> to, @NotNull @NotNull Function<C,O> from)
      Creates a new mapped codec of type O from the current codec.

      The mapped codec maps the raw input and output values using the given functions.
      The functions are applied before encoding and after decoding the base codec, on the raw values.
      Any errors that occur during mapping must be self-contained and should not affect the base codec.

      Type Parameters:
      O - The type of the mapped value
      Parameters:
      to - The encoding mapping function
      from - The decoding mapping function
      Returns:
      A new mapped codec
      Throws:
      NullPointerException - If the encoding mapping function or decoding mapping function is null
      See Also:

    • mapFlat

      @NotNull default <O> @NotNull Codec<O> mapFlat(@NotNull @NotNull Function<O,C> to, @NotNull @NotNull ResultMappingFunction<C,O> from)
      Creates a new mapped codec of type O from the current codec.

      The mapped codec maps the raw input value using the given function.
      The function is applied before encoding the base codec.

      This mapping functions allows the handling of errors that occur during decode-mapping.
      Therefor the mapping function is applied to the result of the base codec.
      The mapping function must return a new result that contains the mapped value or an error message.

      Type Parameters:
      O - The type of the mapped value
      Parameters:
      to - The encoding mapping function
      from - The decoding mapping function
      Returns:
      A new mapped codec
      Throws:
      NullPointerException - If the encoding mapping function or decoding mapping function is null
      See Also:

    • map

      @NotNull default <O> @NotNull Codec<O> map(@NotNull @NotNull ResultingFunction<O,C> to, @NotNull @NotNull ResultMappingFunction<C,O> from)
      Creates a new mapped codec of type O from the current codec.
      This mapping functions allows the handling of errors that occur during mapping.

      The encode-mapping function is applied before encoding the base codec.
      The function can return a new result that contains the mapped value or an error message.

      The decode-mapping function is applied to the result of the base codec.
      The function can return a new result that contains the mapped value or an error message.

      Type Parameters:
      O - The type of the mapped value
      Parameters:
      to - The encoding mapping function
      from - The decoding mapping function
      Returns:
      A new mapped codec
      Throws:
      NullPointerException - If the encoding mapping function or decoding mapping function is null
      See Also:

    • validate

      @NotNull default @NotNull Codec<C> validate(@NotNull @NotNull Function<C,Result<C>> validator)
      Creates a new codec that will validate the result of the decoding process using the given validator function.
      The validator function is applied to the decoded value and must return a result that contains the validated value or an error message.
      Parameters:
      validator - The validator function
      Returns:
      A new codec
      Throws:
      NullPointerException - If the validator function is null

    • orElse

      @NotNull default @NotNull Codec<C> orElse(@Nullable C defaultValue)
      Creates a new codec that will return the given default value in an error case during decoding.
      Parameters:
      defaultValue - The default value
      Returns:
      A new codec
      See Also:

    • orElseGet

      @NotNull default @NotNull Codec<C> orElseGet(@NotNull @NotNull Supplier<C> supplier)
      Creates a new codec that will return the value provided by the given supplier in an error case during decoding.
      Parameters:
      supplier - The default value supplier
      Returns:
      A new codec
      Throws:
      NullPointerException - If the default value supplier is null

    • named

      @NotNull default @NotNull Codec<C> named(@NotNull @NotNull String name, String @NotNull ... aliases)
      Creates a new named codec with the current codec using the given name and aliases.
      Parameters:
      name - The name of the codec
      aliases - The aliases of the codec
      Returns:
      A new named codec
      Throws:
      NullPointerException - If the codec name is null
      See Also:

    • getter

      @NotNull default <O> @NotNull ConfiguredCodec<C,O> getter(@NotNull @NotNull Function<O,C> getter)
      Creates a new configured codec.
      The configured codec is used in the codec builder to create codecs for complex data structures.
      The configured codec encodes and decodes components of the data structure using the given getter function.
      It is expected that this is only called on named codecs.
      Type Parameters:
      O - The type of the object which contains the component
      Parameters:
      getter - The getter function
      Returns:
      A new configured codec
      Throws:
      NullPointerException - If the getter function is null
      See Also:

    • configure

      @NotNull default <O> @NotNull ConfiguredCodec<C,O> configure(@NotNull @NotNull String name, @NotNull @NotNull Function<O,C> getter)
      Creates a new configured codec.
      This method combines the named(String, String...) and getter(Function) methods.

      The configured codec is used in the codec builder to create codecs for complex data structures.
      The configured codec encodes and decodes components of the data structure using the given getter function.

      Type Parameters:
      O - The type of the object which contains the component
      Parameters:
      name - The name of the codec
      getter - The getter function
      Returns:
      A new configured codec
      Throws:
      NullPointerException - If the codec name or getter function is null
      See Also: