Interface Codec<T extends @UnknownNullability Object>

Type Parameters:

T - The type to be represented by this codec, nullable T will provide nullable results.

All Superinterfaces:

Decoder<T>, Encoder<T>

All Known Subinterfaces:

DataComponent<T>, StructCodec<R>

public interface Codec<T extends @UnknownNullability Object>
extends Encoder<T>, Decoder<T>

A Codec represents a combined Encoder and Decoder for a value. Enabling easy encoding and decoding of values to and from a between formats, making serialization simple, reusable and type safe. Going between formats is handled by Transcoder.

Most of the primitive or commonly used codecs are provided as static fields in this interface. For example, INT is a codec for integers, and STRING is a codec for strings. You can even use Enum(Class) for enums, which will convert the enum to a string representation and back.

Codecs are immutable, you must chain methods to create a codec that you want. For example

        Codec<@Nullable String> codec = Codec.STRING.optional()
        Codec<Set<@Nullable String>> setCodec = codec.set();
    

Heavily inspired by Mojang/DataFixerUpper, licensed under the MIT license.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	Codec.RawValue	A raw value wrapper for entry is an object combined with its current decoder.

Field Summary

Fields

Modifier and Type	Field	Description
static final Codec<Point>	BLOCK_POSITION
static final Codec<Boolean>	BOOLEAN
static final Codec<Byte>	BYTE
static final Codec<byte[]>	BYTE_ARRAY
static final Codec<Component>	COMPONENT
static final Codec<Style>	COMPONENT_STYLE
static final Codec<Double>	DOUBLE
static final Codec<Float>	FLOAT
static final Codec<Integer>	INT
static final Codec<int[]>	INT_ARRAY
static final Codec<Key>	KEY
static final Codec<Long>	LONG
static final Codec<long[]>	LONG_ARRAY
static final Codec<BinaryTag>	NBT
static final StructCodec<CompoundBinaryTag>	NBT_COMPOUND
static final Codec<Codec.RawValue>	RAW_VALUE
static final Codec<Short>	SHORT
static final Codec<String>	STRING
static final Codec<Unit>	UNIT
static final Codec<UUID>	UUID
static final Codec<UUID>	UUID_COERCED
static final Codec<UUID>	UUID_STRING
static final Codec<Point>	VECTOR3D

Method Summary

Modifier and Type	Method	Description
static <L,R> Codec<Either<L,R>>	Either(Codec<L> leftCodec, Codec<R> rightCodec)	Creates an Either Codec, depending on the value of Either decides which codec to use.
static <L,R> StructCodec<Either<L,R>>	EitherStruct(StructCodec<L> leftCodec, StructCodec<R> rightCodec)	Creates an Either Codec, depending on the value of Either decides which codec to use.
static <E extends Enum<E>> Codec<E>	Enum(Class<E> enumClass)	Creates an enum codec from a given class Converts the Enum.name() into lowercase when encoding and uppercase into decoding then passing it to Enum.valueOf(Class, String)
static <T> Codec<T>	ForwardRef(Supplier<Codec<T>> supplier)	Lazily gets the reference of a codec; considered immutably lazy.
default Codec<@Unmodifiable List<T>>	list()	Creates an unmodifiable unbounded list codec.
default Codec<@Unmodifiable List<T>>	list(int maxSize)	Creates an unmodifiable list codec of T where its size is no larger than maxSize.
default Codec<@Unmodifiable @Nullable List<T>>	listOrSingle()	Returns an unmodifiable unbounded list or the first element or null if no such element exists.
default Codec<@Unmodifiable @Nullable List<T>>	listOrSingle(int maxSize)	Returns an unmodifiable list or the first element or null if no such element exists.
default <V> Codec<@Unmodifiable Map<T,V>>	mapValue(Codec<V> valueCodec)	Creates an unmodifiable map of key T and value of V.
default <V> Codec<@Unmodifiable Map<T,V>>	mapValue(Codec<V> valueCodec, int maxSize)	Creates an unmodifiable map of key T and value of V
default Codec<@Nullable T>	optional()	Creates an optional codec, where null is encodable into Transcoder.createNull().
default Codec<@UnknownNullability T>	optional(T defaultValue)	Creates an optional codec, where null is encodable and is encoded when value equals defaultValue or null through Transcoder.createNull().
default Codec<T>	orElse(Codec<T> other)	Creates a or else codec where it will attempt to use the first codec then use the second one if it fails.
static <T> Codec<T>	Recursive(Function<Codec<T>,Codec<T>> func)	Create a recursive codec from the parent codec Useful when you want to keep encoding/decoding until there is nothing left.
static <T> StructCodec<T>	RegistryTaggedUnion(String key, Registries.Selector<StructCodec<? extends T>> registrySelector, Function<T, StructCodec<? extends T>> serializerGetter)	Creates a StructCodec to bidirectionally map values of T to their encoded values Registry selectors will be used to lookup values of codecs of T.
static <T> StructCodec<T>	RegistryTaggedUnion(String key, Registry<StructCodec<? extends T>> registry, Function<T, StructCodec<? extends T>> serializerGetter)	Shortcut for RegistryTaggedUnion(String, Registries.Selector, Function) where selector will be registry
static <T> StructCodec<T>	RegistryTaggedUnion(Registries.Selector<StructCodec<? extends T>> registrySelector, Function<T, StructCodec<? extends T>> serializerGetter)	Shortcut for RegistryTaggedUnion(String, Registries.Selector, Function) where key will be "type"
static <T> StructCodec<T>	RegistryTaggedUnion(Registries.Selector<StructCodec<? extends T>> registrySelector, Function<T, StructCodec<? extends T>> serializerGetter, String key)	Deprecated. Use RegistryTaggedUnion(String, Registries.Selector, Function) instead.
static <T> StructCodec<T>	RegistryTaggedUnion(Registry<StructCodec<? extends T>> registry, Function<T, StructCodec<? extends T>> serializerGetter)	Shortcut for RegistryTaggedUnion(String, Registry, Function) where key will be "type"
static <T> StructCodec<T>	RegistryTaggedUnion(Registry<StructCodec<? extends T>> registry, Function<T, StructCodec<? extends T>> serializerGetter, String key)	Deprecated. Use RegistryTaggedUnion(String, Registry, Function) instead.
default Codec<@Unmodifiable Set<T>>	set()	Creates an unmodifiable unbounded set.
default Codec<@Unmodifiable Set<T>>	set(int maxSize)	Creates an unmodifiable set where its max is no larger than maxSize
default <S extends @UnknownNullability Object> Codec<S>	transform(ThrowingFunction<T,S> to, ThrowingFunction<S,T> from)	Transforms an object from S to another T and from T back to S
default <R> StructCodec<R>	unionType(String keyField, Function<T, StructCodec<? extends R>> serializers, Function<R, ? extends T> keyFunc)	Creates a union type of type R Useful when you have an interface of T and want a codec subclasses of T
default <R> StructCodec<R>	unionType(Function<T, StructCodec<? extends R>> serializers, Function<R, ? extends T> keyFunc)	Creates a union type of type R.

Methods inherited from interface Decoder

decode

Methods inherited from interface Encoder

encode

Field Details

RAW_VALUE

static final Codec<Codec.RawValue> RAW_VALUE

UNIT

static final Codec<Unit> UNIT

BOOLEAN

static final Codec<Boolean> BOOLEAN

BYTE

static final Codec<Byte> BYTE

SHORT

static final Codec<Short> SHORT

INT

static final Codec<Integer> INT

LONG

static final Codec<Long> LONG

FLOAT

static final Codec<Float> FLOAT

DOUBLE

static final Codec<Double> DOUBLE

STRING

static final Codec<String> STRING

KEY

static final Codec<Key> KEY

BYTE_ARRAY

static final Codec<byte[]> BYTE_ARRAY

INT_ARRAY

static final Codec<int[]> INT_ARRAY

LONG_ARRAY

static final Codec<long[]> LONG_ARRAY

UUID

static final Codec<UUID> UUID

UUID_STRING

static final Codec<UUID> UUID_STRING

UUID_COERCED

static final Codec<UUID> UUID_COERCED

COMPONENT

static final Codec<Component> COMPONENT

COMPONENT_STYLE

static final Codec<Style> COMPONENT_STYLE

BLOCK_POSITION

static final Codec<Point> BLOCK_POSITION

VECTOR3D

static final Codec<Point> VECTOR3D

NBT

static final Codec<BinaryTag> NBT

NBT_COMPOUND

static final StructCodec<CompoundBinaryTag> NBT_COMPOUND

Method Details

Enum

@Contract(pure=true,
          value="_ -> new")
static <E extends Enum<E>> Codec<E> Enum(Class<E> enumClass)

Creates an enum codec from a given class
Converts the Enum.name() into lowercase when encoding and uppercase into decoding then passing it to Enum.valueOf(Class, String)

Type Parameters:

E - Enum type, E must be an enum

Parameters:

enumClass - the enum class

Returns:

the codec enum

Recursive

@Contract(pure=true,
          value="_ -> new")
static <T> Codec<T> Recursive(Function<Codec<T>,Codec<T>> func)

Create a recursive codec from the parent codec
Useful when you want to keep encoding/decoding until there is nothing left.

Type Parameters:

T - The codec Type

Parameters:

func - the function to get the codec from.

Returns:

the recursive codec

ForwardRef

@Contract(pure=true,
          value="_ -> new")
static <T> Codec<T> ForwardRef(Supplier<Codec<T>> supplier)

Lazily gets the reference of a codec; considered immutably lazy.
Useful for breaking possible cyclic loading of recursive codecs. This may become a stable value in the future; don't rely on supplier getting called multiple times.

Type Parameters:

T - the codec type

Parameters:

supplier - the supplier to load the codec from.

Returns:

the supplier

RegistryTaggedUnion

@Deprecated
@Contract(pure=true,
          value="_, _, _ -> new")
static <T> StructCodec<T> RegistryTaggedUnion(Registry<StructCodec<? extends T>> registry,
 Function<T, StructCodec<? extends T>> serializerGetter,
 String key)

Deprecated.

Use RegistryTaggedUnion(String, Registry, Function) instead. Shortcut for RegistryTaggedUnion(Registries.Selector, Function, String)

Type Parameters:

T - the struct codec type.

Parameters:

registry - the codec registry

serializerGetter - the codec getter

key - the map key

Returns:

a StructCodec

RegistryTaggedUnion

@Deprecated
@Contract(pure=true,
          value="_, _, _ -> new")
static <T> StructCodec<T> RegistryTaggedUnion(Registries.Selector<StructCodec<? extends T>> registrySelector,
 Function<T, StructCodec<? extends T>> serializerGetter,
 String key)

Deprecated.

Use RegistryTaggedUnion(String, Registries.Selector, Function) instead. Creates a StructCodec to bidirectionally map values of T to their encoded values
Registry selectors will be used to lookup values of codecs of T. Then will be used to map to object T from key

Type Parameters:

T - the codec type

Parameters:

registrySelector - the registry selector used during lookup.

serializerGetter - the serializer for each value of T

key - the map key for T

Returns:

a StructCodec bidirectionally mapping values of T

RegistryTaggedUnion

@Contract(pure=true,
          value="_, _ -> new")
static <T> StructCodec<T> RegistryTaggedUnion(Registry<StructCodec<? extends T>> registry,
 Function<T, StructCodec<? extends T>> serializerGetter)

Shortcut for RegistryTaggedUnion(String, Registry, Function) where key will be "type"

Type Parameters:

T - the struct codec type.

Parameters:

registry - the codec registry

serializerGetter - the codec getter

Returns:

a StructCodec

RegistryTaggedUnion

@Contract(pure=true,
          value="_, _, _ -> new")
static <T> StructCodec<T> RegistryTaggedUnion(String key,
 Registry<StructCodec<? extends T>> registry,
 Function<T, StructCodec<? extends T>> serializerGetter)

Shortcut for RegistryTaggedUnion(String, Registries.Selector, Function) where selector will be registry

Type Parameters:

T - the struct codec type.

Parameters:

key - the map key

registry - the codec registry

serializerGetter - the codec getter

Returns:

a StructCodec

RegistryTaggedUnion

@Contract(pure=true,
          value="_, _ -> new")
static <T> StructCodec<T> RegistryTaggedUnion(Registries.Selector<StructCodec<? extends T>> registrySelector,
 Function<T, StructCodec<? extends T>> serializerGetter)

Shortcut for RegistryTaggedUnion(String, Registries.Selector, Function) where key will be "type"

Type Parameters:

T - the codec type

Parameters:

registrySelector - the registry selector used during lookup.

serializerGetter - the serializer for each value of T

Returns:

a StructCodec bidirectionally mapping values of T

RegistryTaggedUnion

@Contract(pure=true,
          value="_, _, _ -> new")
static <T> StructCodec<T> RegistryTaggedUnion(String key,
 Registries.Selector<StructCodec<? extends T>> registrySelector,
 Function<T, StructCodec<? extends T>> serializerGetter)

Creates a StructCodec to bidirectionally map values of T to their encoded values
Registry selectors will be used to lookup values of codecs of T. Then will be used to map to object T from key

Type Parameters:

T - the codec type

Parameters:

key - the map key for T

registrySelector - the registry selector used during lookup.

serializerGetter - the serializer for each value of T

Returns:

a StructCodec bidirectionally mapping values of T

Either

@Contract(pure=true,
          value="_, _ -> new")
static <L,R> Codec<Either<L,R>> Either(Codec<L> leftCodec,
 Codec<R> rightCodec)

Creates an Either Codec, depending on the value of Either decides which codec to use.

Type Parameters:

L - the left type

R - the right type

Parameters:

leftCodec - the left codec

rightCodec - the right codec

Returns:

a Codec with Either of L and R

EitherStruct

@Contract(pure=true,
          value="_, _ -> new")
static <L,R> StructCodec<Either<L,R>> EitherStruct(StructCodec<L> leftCodec,
 StructCodec<R> rightCodec)

Creates an Either Codec, depending on the value of Either decides which codec to use.

Type Parameters:

L - the left type

R - the right type

Parameters:

leftCodec - the left codec

rightCodec - the right codec

Returns:

a StructCodec with Either of L and R

optional

@Contract(pure=true,
          value="-> new")
default Codec<@Nullable T> optional()

Creates an optional codec, where null is encodable into Transcoder.createNull().

Returns:

the optional codec of type T

optional

@Contract(pure=true,
          value="_ -> new")
default Codec<@UnknownNullability T> optional(T defaultValue)

Creates an optional codec, where null is encodable and is encoded when value equals defaultValue or null through Transcoder.createNull().
The default value will be used if the decoding is null or fails to decode.

Parameters:

defaultValue - the default value

Returns:

the optional codec of type T

Throws:

NullPointerException - if defaultValue is null, use optional() instead.

transform

@Contract(pure=true,
          value="_, _ -> new")
default <S extends @UnknownNullability Object>
Codec<S> transform(ThrowingFunction<T,S> to,
 ThrowingFunction<S,T> from)

Transforms an object from S to another T and from T back to S

Type Parameters:

S - the type

Parameters:

to - the function to S from T

from - the function from S to T

Returns:

the transforming codec of S

list

@Contract(pure=true,
          value="_ -> new")
default Codec<@Unmodifiable List<T>> list(int maxSize)

Creates an unmodifiable list codec of T where its size is no larger than maxSize.

Parameters:

maxSize - the max size of the list before returning an error result.

Returns:

the list codec of type T

list

@Contract(pure=true,
          value="-> new")
default Codec<@Unmodifiable List<T>> list()

Creates an unmodifiable unbounded list codec. See list(int)

Returns:

the unbounded list codec of type T

listOrSingle

@Contract(pure=true,
          value="_ -> new")
default Codec<@Unmodifiable @Nullable List<T>> listOrSingle(int maxSize)

Returns an unmodifiable list or the first element or null if no such element exists.

Parameters:

maxSize - the max size of the list before returning an error result

Returns:

the list codec of type T

listOrSingle

@Contract(pure=true,
          value="-> new")
default Codec<@Unmodifiable @Nullable List<T>> listOrSingle()

Returns an unmodifiable unbounded list or the first element or null if no such element exists. See listOrSingle(int)

Returns:

the list codec of type T

set

@Contract(pure=true,
          value="_ -> new")
default Codec<@Unmodifiable Set<T>> set(int maxSize)

Creates an unmodifiable set where its max is no larger than maxSize

Parameters:

maxSize - the max size before returning an error result

Returns:

the set codec of type T

set

@Contract(pure=true,
          value="-> new")
default Codec<@Unmodifiable Set<T>> set()

Creates an unmodifiable unbounded set. See set(int)

Returns:

the set codec of type T

mapValue

@Contract(pure=true,
          value="_, _ -> new")
default <V> Codec<@Unmodifiable Map<T,V>> mapValue(Codec<V> valueCodec,
 int maxSize)

Creates an unmodifiable map of key T and value of V

Type Parameters:

V - the value type

Parameters:

valueCodec - the codec to use for V

maxSize - the max size before returning an error result.

Returns:

the map codec of type T and V

mapValue

@Contract(pure=true,
          value="_ -> new")
default <V> Codec<@Unmodifiable Map<T,V>> mapValue(Codec<V> valueCodec)

Creates an unmodifiable map of key T and value of V. See mapValue(Codec, int)

Type Parameters:

V - the value type

Parameters:

valueCodec - the codec to use for V

Returns:

the map codec of type T and V

unionType

@Contract(pure=true,
          value="_, _ -> new")
default <R> StructCodec<R> unionType(Function<T, StructCodec<? extends R>> serializers,
 Function<R, ? extends T> keyFunc)

Creates a union type of type R. See unionType(String, Function, Function)
Useful when you have an interface of T and want a codec subclasses of T

Type Parameters:

R - the return type; T or a subclass

Parameters:

serializers - the map from T value to its serializer

keyFunc - to map from R to its value of T

Returns:

the struct codec union of R

unionType

@Contract(pure=true,
          value="_, _, _ -> new")
default <R> StructCodec<R> unionType(String keyField,
 Function<T, StructCodec<? extends R>> serializers,
 Function<R, ? extends T> keyFunc)

Creates a union type of type R
Useful when you have an interface of T and want a codec subclasses of T

Type Parameters:

R - the return type; T or a subclass

Parameters:

keyField - the map key

serializers - the map from T value to its serializer

keyFunc - to map from R to its value of T

Returns:

the struct codec union of R

orElse

@Contract(pure=true,
          value="_ -> new")
default Codec<T> orElse(Codec<T> other)

Creates a or else codec where it will attempt to use the first codec then use the second one if it fails.
If both codecs fail the first error will be returned instead.

Parameters:

other - the other codec

Returns:

the or else codec of T