com.mojang.serialization

Class MapCodec<A>

java.lang.Object

com.mojang.serialization.CompressorHolder

com.mojang.serialization.MapCodec<A>

Type Parameters:

A - The type this MapCodec serializes and deserializes.

All Implemented Interfaces:

Compressable, Keyable, MapDecoder<A>, MapEncoder<A>

Direct Known Subclasses:

EitherMapCodec, KeyDispatchCodec, OptionalFieldCodec, PairMapCodec, SimpleMapCodec

public abstract class MapCodec<A>
extends CompressorHolder
implements MapDecoder<A>, MapEncoder<A>

A combined MapEncoder and MapDecoder.

A MapCodec is a specialized version of a Codec that serializes and deserializes a fixed set of record fields. While a MapCodec is not itself a Codec, it may be turned into one via the codec() method.

Implementations of MapCodec are immutable once created. The methods defined in this interface never mutate the codec in a way visible to the outside.

Implementation Requirements:

An implementation must include, at a minimum, definitions for the MapEncoder.encode(Object, DynamicOps, RecordBuilder) and MapDecoder.decode(DynamicOps, MapLike) methods.

Implementation Note:

The default methods in this interface that return map codecs or codecs wrap this codec without adding any debugging context. These methods should be overridden if deeply nested codecs are undesirable or additional debugging context is desired.

See Also:

Codec

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MapCodec.MapCodecCodec<A> A Codec adapter for a MapCodec.
static interface	MapCodec.ResultFunction<A> A unary operator applied on the result obtained from decoding or encoding from a MapCodec.

Nested classes/interfaces inherited from interface com.mojang.serialization.MapDecoder

MapDecoder.Implementation<A>

Nested classes/interfaces inherited from interface com.mojang.serialization.MapEncoder

MapEncoder.Implementation<A>

Constructor Summary

Constructors

Constructor and Description
MapCodec()

Method Summary

Modifier and Type	Method and Description
Codec<A>	codec() Returns a Codec that implements the same operations as this map codec.
<E> MapCodec<A>	dependent(MapCodec<E> initialInstance, (A) -> (E,MapCodec<E>) splitter, (A,E) -> A combiner) Creates a map codec where the encoding and decoding of the given fields depends on the values of the fields decoded using this map codec.
MapCodec<A>	deprecated(int since) Sets this map codec to produce deprecated results.
MapCodec<A>	fieldOf(String name) Returns a MapCodec that operates on the same type as this map codec, but that extracts the values from a record field with the given name.
<S> MapCodec<S>	flatXmap((? super A) -> ? extends DataResult<? extends S> to, (? super S) -> ? extends DataResult<? extends A> from) Transforms this map codec into another map codec using the given partially invertible partial function.
<O> RecordCodecBuilder<O,A>	forGetter((O) -> A getter) Returns a RecordCodecBuilder that encodes and decodes the field defined by this map codec.
abstract <T> Stream<T>	keys(DynamicOps<T> ops) Returns the set of keys this object defines or accepts, serialized to the provided form.
MapCodec<A>	mapResult(MapCodec.ResultFunction<A> function) Transforms the DataResult returned from this map codec's MapEncoder.encode(Object, DynamicOps, RecordBuilder) and MapDecoder.decode(DynamicOps, MapLike) methods.
static <A> MapCodec<A>	of(MapEncoder<A> encoder, MapDecoder<A> decoder) Creates a MapCodec given a map encoder and a map decoder.
static <A> MapCodec<A>	of(MapEncoder<A> encoder, MapDecoder<A> decoder, by-name String name) Creates a named MapCodec given a map encoder and a map decoder.
MapCodec<A>	orElse(A value) Provides a default value to return if a decoding or encoding error occurs.
MapCodec<A>	orElse((String) -> void onError, A value) Provides a callback to run and a default value to return if a decoding or encoding error occurs.
MapCodec<A>	orElse((String) -> String onError, A value) Provides an error transformation and a default value to return if a decoding or encoding error occurs.
MapCodec<A>	orElseGet((String) -> void onError, by-name ? extends A value) Provides a callback to run and a default value to supply if a decoding or encoding error occurs.
MapCodec<A>	orElseGet(by-name ? extends A value) Provides a default value to supply if a decoding or encoding error occurs.
MapCodec<A>	orElseGet((String) -> String onError, by-name ? extends A value) Provides an error transformation and a default supply to return if a decoding or encoding error occurs.
MapCodec<A>	setPartial(by-name A value)
MapCodec<A>	stable() Sets this map codec to produce stable results.
static <A> MapCodec<A>	unit(A defaultValue) Returns a map codec that always provides the same value.
static <A> MapCodec<A>	unit(by-name A defaultValue) Returns a map codec that always provides the supplied value.
MapCodec<A>	withLifecycle(Lifecycle lifecycle) Sets the Lifecycle of the results this map codec returns.
<S> MapCodec<S>	xmap((? super A) -> ? extends S to, (? super S) -> ? extends A from) Transforms this map codec into another map codec using the given invertible mapping functions.

Methods inherited from class com.mojang.serialization.CompressorHolder

compressor

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.mojang.serialization.MapDecoder

ap, compressedDecode, compressor, decode, decoder, flatMap, map

Methods inherited from interface com.mojang.serialization.MapEncoder

comap, compressedBuilder, compressor, encode, encoder, flatComap, makeCompressedBuilder

Methods inherited from interface com.mojang.serialization.Keyable

forStrings

Constructor Detail

MapCodec

public MapCodec()

Method Detail

forGetter

public final <O> RecordCodecBuilder<O,A> forGetter((O) -> A getter)

Returns a RecordCodecBuilder that encodes and decodes the field defined by this map codec.

Multiple RecordCodecBuilder objects, each wrapping one map codec, may be combined in order to create a codec that can serialize and deserialize whole objects.

Type Parameters:

O - The object type that holds a value this map codec can operate on.

Parameters:

getter - A function that extracts a value to encode from some object type.

Returns:

A RecordCodecBuilder that encodes and decodes values extracted from getter.

See Also:

RecordCodecBuilder

of

public static <A> MapCodec<A> of(MapEncoder<A> encoder,
                                 MapDecoder<A> decoder)

Creates a MapCodec given a map encoder and a map decoder.

Type Parameters:

A - The type that the returned MapCodec operates on.

Parameters:

encoder - The MapEncoder that the returned map codec uses to encode values.

decoder - The MapDecoder that the returned map codec uses to decode values.

Returns:

A MapCodec that encodes and decodes values based on the provided encoder and decoder.

of

public static <A> MapCodec<A> of(MapEncoder<A> encoder,
                                 MapDecoder<A> decoder,
                                 by-name String name)

Creates a named MapCodec given a map encoder and a map decoder. The returned map codec will use the given name in its string representation.

Type Parameters:

A - The type that the returned MapCodec operates on.

Parameters:

encoder - The MapEncoder that the returned map codec uses to encode values.

decoder - The MapDecoder that the returned map codec uses to decode values.

name - The name that is displayed in the Object.toString() representation of the returned map codec.

Returns:

A MapCodec that encodes and decodes values based on the provided encoder and decoder.

fieldOf

public MapCodec<A> fieldOf(String name)

Returns a MapCodec that operates on the same type as this map codec, but that extracts the values from a record field with the given name. This method can be used to nest records within one another.

Implementation Requirements:

This implementation is equivalent to codec().fieldOf(name).

Parameters:

name - The name of the field values are extracted from.

Returns:

A MapCodec that extracts values to be passed to this map codec from a record field.

withLifecycle

public MapCodec<A> withLifecycle(Lifecycle lifecycle)

Sets the Lifecycle of the results this map codec returns.

Specified by:

withLifecycle in interface MapDecoder<A>

Specified by:

withLifecycle in interface MapEncoder<A>

Parameters:

lifecycle - The lifecycle to use.

Returns:

A map codec equivalent to this map codec, but using the given lifecycle for the encoded and decoded results.

codec

public Codec<A> codec()

Returns a Codec that implements the same operations as this map codec.

stable

public MapCodec<A> stable()

Sets this map codec to produce stable results.

Returns:

A map codec that produces results with the stable lifecycle.

See Also:

withLifecycle(Lifecycle), Lifecycle.stable()

deprecated

public MapCodec<A> deprecated(int since)

Sets this map codec to produce deprecated results.

Parameters:

since - The deprecation version.

Returns:

A map codec that produces results with a deprecated lifecycle.

See Also:

withLifecycle(Lifecycle), Lifecycle.deprecated(int)

xmap

public <S> MapCodec<S> xmap((? super A) -> ? extends S to,
                            (? super S) -> ? extends A from)

Transforms this map codec into another map codec using the given invertible mapping functions.

This method performs a map operation on both MapDecoder and MapEncoder.

Implementation Requirements:

The default implementation calls MapEncoder.comap(Function) and MapDecoder.map(Function) on this map codec.

Type Parameters:

S - The new type.

Parameters:

to - A function from this map codec's type to the new type.

from - A function from the new type to this map codec's type.

Returns:

A map codec for the new type.

See Also:

MapDecoder.map(Function), MapEncoder.comap(Function)

flatXmap

public <S> MapCodec<S> flatXmap((? super A) -> ? extends DataResult<? extends S> to,
                                (? super S) -> ? extends DataResult<? extends A> from)

Transforms this map codec into another map codec using the given partially invertible partial function.

This method performs a flatMap operation on both MapDecoder and MapEncoder.

Implementation Requirements:

The default implementation calls MapEncoder.flatComap(Function) and MapDecoder.flatMap(Function).

Type Parameters:

S - The new type.

Parameters:

to - A partial function form this map codec's type to the new type.The value and any errors are wrapped in a DataResult.

from - A partial function from the new type to this map codec's type. The value and any errors are wrapped in a DataResult.

Returns:

A codec for the new type.

See Also:

MapDecoder.flatMap(Function), MapEncoder.flatComap(Function)

dependent

public <E> MapCodec<A> dependent(MapCodec<E> initialInstance,
                                 (A) -> (E,MapCodec<E>) splitter,
                                 (A,E) -> A combiner)

Creates a map codec where the encoding and decoding of the given fields depends on the values of the fields decoded using this map codec.

This is similar to Codec.dispatch(String, Function, Function), except that the fields that are extracted are the same fields that are dispatched.

Type Parameters:

E - The type representing the collection of dependent fields.

Parameters:

initialInstance - A codec that specifies the set of dependent fields.

splitter - A function that takes an object and extracts both a set of fields and the codecs associated with those fields, for that particular object.

combiner - A function that combines an object and a set of decoded fields.

Returns:

A map codec that delegates the given fields to some other codecs based on the values of fields decoded using this map codec.

See Also:

Codec.dispatch(Function, Function), MapCodec.Dependent

keys

public abstract <T> Stream<T> keys(DynamicOps<T> ops)

Description copied from interface: Keyable

Returns the set of keys this object defines or accepts, serialized to the provided form.

Specified by:

keys in interface Keyable

Type Parameters:

T - The type of the serialized form.

Parameters:

ops - The DynamicOps instance defining the serialized form.

Returns:

The set of keys this object defines.

mapResult

public MapCodec<A> mapResult(MapCodec.ResultFunction<A> function)

Transforms the DataResult returned from this map codec's MapEncoder.encode(Object, DynamicOps, RecordBuilder) and MapDecoder.decode(DynamicOps, MapLike) methods.

Parameters:

function - The transformation to apply to results.

Returns:

A map codec that applies the given transformation after encoding and decoding values.

orElse

public MapCodec<A> orElse((String) -> void onError,
                          A value)

Provides a callback to run and a default value to return if a decoding or encoding error occurs. The returned map codec will attempt to promote a partial result before falling back to the provided default value.

Parameters:

onError - A callback to run when a decoding or encoding error occurs. The callback receives the error message.

value - The default value to use if a decoding error occurs and no partial result is present.

Returns:

A map codec that returns the default value from its decode method if decoding returns an error.

orElse

public MapCodec<A> orElse((String) -> String onError,
                          A value)

Provides an error transformation and a default value to return if a decoding or encoding error occurs. The returned map codec will attempt to promote a partial result before falling back to the provided default value.

Parameters:

onError - A function that transforms the error message when a decoding or encoding error occurs.

value - The default value to use if a decoding error occurs and no partial result is present.

Returns:

A map codec that returns the default value from its decode method if decoding returns an error.

orElseGet

public MapCodec<A> orElseGet((String) -> void onError,
                             by-name ? extends A value)

Provides a callback to run and a default value to supply if a decoding or encoding error occurs. The returned map codec will attempt to promote a partial result before falling back to the provided default value.

Parameters:

onError - A callback to run when a decoding or encoding error occurs.

value - A supplier of the default value to use if a decoding error occurs and no partial result is present.

Returns:

A map codec that returns the default value from its decode method if decoding returns an error.

orElseGet

public MapCodec<A> orElseGet((String) -> String onError,
                             by-name ? extends A value)

Provides an error transformation and a default supply to return if a decoding or encoding error occurs. The returned map codec will attempt to promote a partial result before falling back to the provided default value.

Parameters:

onError - A function that transforms the error message when a decoding or encoding error occurs.

value - A supplier of default value to use if a decoding error occurs and no partial result is present.

Returns:

A map codec that returns the default value from its decode method if decoding returns an error.

orElse

public MapCodec<A> orElse(A value)

Provides a default value to return if a decoding or encoding error occurs. The returned map codec will attempt to promote a partial result before falling back to the provided default value.

Parameters:

value - The default value to use if a decoding error occurs and no partial result is present.

Returns:

A map codec that returns the default value from its decode method if decoding returns an error.

orElseGet

public MapCodec<A> orElseGet(by-name ? extends A value)

Provides a default value to supply if a decoding or encoding error occurs. The returned map codec will attempt to promote a partial result before falling back to the provided default value.

Parameters:

value - A supplier of the default value to use if a decoding error occurs and no partial result is present.

Returns:

A map codec that returns the default value from its decode method if decoding returns an error.

setPartial

public MapCodec<A> setPartial(by-name A value)

unit

public static <A> MapCodec<A> unit(A defaultValue)

Returns a map codec that always provides the same value. As the value is constant, the returned map codec does not add any fields to the output.

Type Parameters:

A - The type of object the returned map codec operates on.

Parameters:

defaultValue - The value to provide when decoding.

Returns:

A map codec that always encodes and decodes the given value.

unit

public static <A> MapCodec<A> unit(by-name A defaultValue)

Returns a map codec that always provides the supplied value. As the value is constant, the returned map codec does not add any fields to the output.

Type Parameters:

A - The type of object the returned map codec operates on.

Parameters:

defaultValue - A supplier of the default value.

Returns:

A map codec that always encodes and decodes the given value.

See Also:

unit(Object)