T
- The type this interface serializes to and deserializes from. For example,
JsonElement
or NbtTag.public interface DynamicOps<T>
This interface, along with the class Dynamic
, is a low-level serialization
abstraction used in the implementation of Codec
. The functionality offered by
Codec
is more easily composed than the fixed interface offered here.
Modifier and Type | Method and Description |
---|---|
default boolean |
compressMaps()
Whether the caller should serialize maps using a compressed representation.
|
default <U> U |
convertList(DynamicOps<U> outOps,
T input)
Converts a serialized list of values of the serialized type to another serialized type.
|
default <U> U |
convertMap(DynamicOps<U> outOps,
T input)
Converts a serialized map of entries of the serialized type to another serialized type.
|
<U> U |
convertTo(DynamicOps<U> outOps,
T input)
Converts a value of the serialization type to an equivalent value of another serialization type.
|
default T |
createBoolean(boolean value)
Serializes a
boolean value to the serialized type. |
default T |
createByte(byte value)
Serializes a
byte value to the serialized type. |
default T |
createByteList(ByteBuffer input)
Serializes a
ByteBuffer to the serialized type. |
default T |
createDouble(double value)
Serializes a
double value to the serialized type. |
default T |
createFloat(float value)
Serializes a
float value to the serialized type. |
default T |
createInt(int value)
Serializes a
int value to the serialized type. |
default T |
createIntList(IntStream input)
Serializes a
IntStream to the serialized type. |
T |
createList(Stream<T> input)
Serializes a list of values, in the form of a
Stream to the serialized type. |
default T |
createLong(long value)
Serializes a
long value to the serialized type. |
default T |
createLongList(LongStream input)
Serializes a
LongStream to the serialized type. |
default T |
createMap(Map<T,T> map)
Serializes the entries in the given
Map value to the serialized type. |
T |
createMap(Stream<(T,T)> map)
Serializes a
Stream of entries to a map serialized value. |
T |
createNumeric(Number i)
Serializes a
Number value to the serialized type. |
default T |
createShort(short value)
Serializes a
short value to the serialized type. |
T |
createString(String value)
Serializes a
String value to the serialized type. |
T |
empty()
Returns the empty value of the serialization type.
|
default T |
emptyList()
Creates a new empty list of the serialization type.
|
default T |
emptyMap()
Creates a new empty map of the serialization type.
|
default DataResult<T> |
get(T input,
String key)
Extracts the value associated with the given key from the input.
|
default DataResult<Boolean> |
getBooleanValue(T input)
Attempts to parse or coerce a
boolean value from the input. |
default DataResult<ByteBuffer> |
getByteBuffer(T input)
Extracts a
ByteBuffer from the given serialized value. |
default DataResult<T> |
getGeneric(T input,
T key)
Extracts the value associated with the given key from the input.
|
default DataResult<IntStream> |
getIntStream(T input)
Extracts an
IntStream from the serialized value. |
default DataResult<((T) -> void) -> void> |
getList(T input)
Extracts a
Consumer from the given value that iterates over the elements of the serialized list. |
default DataResult<LongStream> |
getLongStream(T input)
Extracts an
LongStream from the serialized value. |
default DataResult<MapLike<T>> |
getMap(T input)
Extracts the entries in the given value, returning them in a
MapLike object. |
default DataResult<((T,T) -> void) -> void> |
getMapEntries(T input)
Extracts a
Consumer from the given value that iterates over the entries of the serialized map. |
DataResult<Stream<(T,T)>> |
getMapValues(T input)
Extracts a
Stream of map entries from the given serialized value. |
DataResult<Number> |
getNumberValue(T input)
Attempts to parse or coerce a
Number value from the input. |
default Number |
getNumberValue(T input,
Number defaultValue)
Attempts to parse or coerce a
Number value from the input, falling back to a default value
if no number could be parsed. |
DataResult<Stream<T>> |
getStream(T input)
Extracts a
Stream of list elements from the given serialized value. |
DataResult<String> |
getStringValue(T input)
Attempts to parse or coerce a
String value from the input. |
default ListBuilder<T> |
listBuilder()
Returns a new
ListBuilder for creating lists of the serialized type. |
default RecordBuilder<T> |
mapBuilder()
Returns a new
RecordBuilder for creating maps of the serialized type. |
default DataResult<T> |
mergeToList(T list,
List<T> values)
Creates a new serialized list from the given serialized list with the values from the given
List appended. |
DataResult<T> |
mergeToList(T list,
T value)
Creates a new serialized list from the given serialized list with the given value appended.
|
default DataResult<T> |
mergeToMap(T map,
Map<T,T> values)
Creates a new serialized map from the given serialized map with the entries in the given
Map
added. |
default DataResult<T> |
mergeToMap(T map,
MapLike<T> values)
Creates a new serialized map from the given serialized map with the entries in the given
MapLike
added. |
DataResult<T> |
mergeToMap(T map,
T key,
T value)
Creates a new serialized map from the given serialized map with the given key-value mapping added.
|
default DataResult<T> |
mergeToPrimitive(T prefix,
T value)
Creates a new serialized primitive from the given serialized primitive with the given value
added.
|
T |
remove(T input,
String key)
Returns an equivalent value with the entry associated with the given key removed.
|
default T |
set(T input,
String key,
T value)
Sets the entry associated with the given key in the input to the given value.
|
default T |
update(T input,
String key,
(T) -> T function)
Sets the entry associated with the given key in the input to a value computed using the existing value
associated with that key.
|
default T |
updateGeneric(T input,
T key,
(T) -> T function)
Sets the entry associated with the given key in the input to a value computed using the existing value
associated with that key.
|
default <E> (T) -> DataResult<(E,T)> |
withDecoder(Decoder<E> decoder)
Returns a deserialization function that uses the given
Decoder , along with this implementation,
to decode data from the serialized type. |
default <E> (E) -> DataResult<T> |
withEncoder(Encoder<E> encoder)
Returns a serialization function that uses the given
Encoder , along with this implementation,
to encode data to the serialized type. |
default <E> (T) -> DataResult<E> |
withParser(Decoder<E> decoder)
Returns a deserialization function that uses the given
Decoder , along with this implementation,
to parse data from the serialized type. |
T empty()
The returned value must be a singleton. That is, clients are guaranteed to be able to compare
instances to empty()
using reference equality (==
).
default T emptyMap()
mergeToMap(Object, Object, Object)
.createMap(Collections.emptyMap())
.createMap(Map)
default T emptyList()
mergeToList(Object, Object)
.createList(Stream.empty())
.createList(Stream)
<U> U convertTo(DynamicOps<U> outOps, T input)
U
- The output serialization type.outOps
- The DynamicOps
object used to work with the output serialization type.input
- The value to convert to the output serialization type.DataResult<Number> getNumberValue(T input)
Number
value from the input.
This method may perform type coercions such as string-to-number and boolean-to-number conversion.
input
- The serialized value.DataResult
containing the parsed Number
, or else an error message.getNumberValue(Object, Number)
default Number getNumberValue(T input, Number defaultValue)
Number
value from the input, falling back to a default value
if no number could be parsed.
This method performs the same type coercions as getNumberValue(Object)
.
input
- The serialized value.defaultValue
- The default value to return if a number cannot be parsed.getNumberValue(Object)
T createNumeric(Number i)
Number
value to the serialized type.
There are no restrictions on the form of the serialized value, save that calling
getNumberValue(Object)
on the returned value should result in a value equal to i
.
default T createByte(byte value)
byte
value to the serialized type.
There are no restrictions on the form of the serialized value, save that calling
getNumberValue(Object)
on the returned value should result in a value whose byte
value
is equal to i
.
createNumeric(Byte.valueOf(value))
.createNumeric(Number)
default T createShort(short value)
short
value to the serialized type.
There are no restrictions on the form of the serialized value, save that calling
getNumberValue(Object)
on the returned value should result in a value whose short
value
is equal to i
.
createNumeric(Short.valueOf(value))
.createNumeric(Number)
default T createInt(int value)
int
value to the serialized type.
There are no restrictions on the form of the serialized value, save that calling
getNumberValue(Object)
on the returned value should result in a value whose int
value
is equal to i
.
createNumeric(Integer.valueOf(value))
.createNumeric(Number)
default T createLong(long value)
long
value to the serialized type.
There are no restrictions on the form of the serialized value, save that calling
getNumberValue(Object)
on the returned value should result in a value whose long
value
is equal to i
.
createNumeric(Long.valueOf(value))
.createNumeric(Number)
default T createFloat(float value)
float
value to the serialized type.
There are no restrictions on the form of the serialized value, save that calling
getNumberValue(Object)
on the returned value should result in a value whose float
value
is equal to i
.
createNumeric(Float.valueOf(value))
.createNumeric(Number)
default T createDouble(double value)
double
value to the serialized type.
There are no restrictions on the form of the serialized value, save that calling
getNumberValue(Object)
on the returned value should result in a value whose double
value
is equal to i
.
createNumeric(Double.valueOf(value))
.createNumeric(Number)
default DataResult<Boolean> getBooleanValue(T input)
boolean
value from the input.
This method may perform type coercions such as number-to-boolean conversion.
getNumberValue(Object)
and compares
the byte
value of the result to 0
.input
- The serialized value.DataResult
containing the parsed boolean
, or else an error message.createBoolean(boolean)
,
getNumberValue(Object)
default T createBoolean(boolean value)
boolean
value to the serialized type.
There are no restrictions on the form of the serialized value, save that calling
getBooleanValue(Object)
on the returned value should result in a value whose value
is equal to value
.
createByte((byte) (value ? 1 : 0))
.getBooleanValue(Object)
,
createByte(byte)
DataResult<String> getStringValue(T input)
String
value from the input.
This method may perform type coercions such as number-to-string and boolean-to-string conversion.
input
- The serialized value.DataResult
containing the parsed String
value, or else an error message.createString(String)
T createString(String value)
String
value to the serialized type.
There are no restrictions on the form of the serialized value, save that calling
getStringValue(Object)
on the returned value should result in a value whose value
is equal to value
.
getStringValue(Object)
DataResult<T> mergeToList(T list, T value)
list
- The list that is appended to.value
- The value to append to the list.DataResult
containing the merged list, or an error message if the lefthand argument
was not a list.default DataResult<T> mergeToList(T list, List<T> values)
List
appended. If list
does not represent a list, or values
could not
be appended, and error is returned.mergeToList(Object, Object)
for each element
of values
.list
- The list that is appended to.values
- The List
of values to append.DataResult
containing the merged list, or else an error message.DataResult<T> mergeToMap(T map, T key, T value)
String
.map
- The map to add to.key
- The key to add. The key must be convertible to String
.value
- The value to add.DataResult
containing the merged map, or an error message if either the map or
the key are of an incorrect type.mergeToMap(Object, Map)
default DataResult<T> mergeToMap(T map, Map<T,T> values)
Map
added. Only successful if the first argument is a map.MapLike
and calls mergeToMap(Object, MapLike)
.map
- The map to add to.values
- A Map
containing the values to add.DataResult
containing the merged map, or an error message if the serialized map
is of an incorrect type.mergeToMap(Object, MapLike)
default DataResult<T> mergeToMap(T map, MapLike<T> values)
MapLike
added. Only successful if the first argument is a map.values
, and calls
mergeToMap(Object, Object, Object)
for each one.map
- The map to add to.values
- A MapLike
containing the values to add.DataResult
containing the merged map, or an error message if the serialized map
is of an incorrect type.mergeToMap(Object, Object, Object)
,
MapLike
default DataResult<T> mergeToPrimitive(T prefix, T value)
prefix
for equality with empty()
, and returns
value
unchanged in this case, else an error.prefix
- The existing primitive value to add to.value
- The value to add.DataResult
containing the merged primitive, or an error message if the serialized primitive
is of an incorrect type.DataResult<Stream<(T,T)>> getMapValues(T input)
Stream
of map entries from the given serialized value.input
- The input value.DataResult
containing the extracted map entries, or an error message if input
is not a map.default DataResult<((T,T) -> void) -> void> getMapEntries(T input)
Consumer
from the given value that iterates over the entries of the serialized map.
The returned value logically encapsulates a iteration over the entries in the given map,
performing some user-specified action on each entry.input
- The input value.getMapValues(Object)
T createMap(Stream<(T,T)> map)
Stream
of entries to a map serialized value. The keys (first element in each entry)
must be convertible to String
.map
- The stream of entries.createMap(Map)
default DataResult<MapLike<T>> getMap(T input)
MapLike
object.input
- The serialized value.DataResult
containing the extracted entries, or an error message if the entries
could not be extracted.default T createMap(Map<T,T> map)
Map
value to the serialized type. The keys in the map must be
convertible to the type String
.map
- The map containing the entries to serialize.DataResult<Stream<T>> getStream(T input)
Stream
of list elements from the given serialized value.input
- The serialized value.DataResult
containing the extracted elements, or an error message if the input
does not represent a list.getIntStream(Object)
,
getLongStream(Object)
default DataResult<((T) -> void) -> void> getList(T input)
Consumer
from the given value that iterates over the elements of the serialized list.
The returned value logically encapsulates an iteration over the elements in the given list,
performing some user-specified action on each element.input
- The input value.getStream(Object)
T createList(Stream<T> input)
Stream
to the serialized type.input
- The elements to serialize.default DataResult<ByteBuffer> getByteBuffer(T input)
ByteBuffer
from the given serialized value.value
, then converts each element of
that list to a byte
value.input
- The serialized value.DataResult
containing the extracted buffer, or an error message if a buffer could
not be extracted.default T createByteList(ByteBuffer input)
ByteBuffer
to the serialized type.
There are no restrictions on the form of the serialized value, save that calling
getByteBuffer(Object)
on the returned value should result in a value whose value
is equal to input
.
byte
in input
using
createByte(byte)
, then serializes the list of bytes using createList(Stream)
.getByteBuffer(Object)
default DataResult<IntStream> getIntStream(T input)
IntStream
from the serialized value. This method is a specialization of
getStream(Object)
for elements convertible to primitive int
values.input
, then converts each
element to an int
value.input
- The serialized value.DataResult
containing the extracted stream, or else an error message.getStream(Object)
default T createIntList(IntStream input)
IntStream
to the serialized type.
There are no restrictions on the form of the serialized value, save that calling
getIntStream(Object)
on the returned value should result in a value whose value
is equal to input
.
int
in input
using
createInt(int)
, then serializes the list of bytes using createList(Stream)
.getIntStream(Object)
default DataResult<LongStream> getLongStream(T input)
LongStream
from the serialized value. This method is a specialization of
getStream(Object)
for elements convertible to primitive long
values.input
, then converts each
element to an long
value.input
- The serialized value.DataResult
containing the extracted stream, or else an error message.getStream(Object)
default T createLongList(LongStream input)
LongStream
to the serialized type.
There are no restrictions on the form of the serialized value, save that calling
getLongStream(Object)
on the returned value should result in a value whose value
is equal to input
.
long
in input
using
createLong(long)
, then serializes the list of bytes using createList(Stream)
.getLongStream(Object)
T remove(T input, String key)
input
- The input value.key
- The key to remove.input
minus the given key. If input
does not contain that key,
or is not a map, then it is returned unchanged.default boolean compressMaps()
MapEncoder
and MapDecoder
to determine whether
to serialize maps as a list of values keyed by index.false
. Implementations should override the default
and return true
if callers would gain space savings by compressing maps before serializing them.KeyCompressor
default DataResult<T> get(T input, String key)
getGeneric(Object, Object)
using the serialized form
of key
.input
- The serialized value.key
- The key to search for.DataResult
containing the extracted value, or an error message if a value associated
with the given key could not be extracted.getGeneric(Object, Object)
default DataResult<T> getGeneric(T input, T key)
getMap(Object)
, then searches
for the entry associated with the given key.input
- The serialized value.key
- The key to search for.DataResult
containing the extracted value, or an error message if a value associated
with the given key could not be extracted.get(Object, String)
default T set(T input, String key, T value)
DataResult
if the entry could not be set.mergeToMap(Object, Object, Object)
,
except that the input is returned unchanged if an error would otherwise be returned.input
- The serialized map to add the entry to.key
- The key, as a string.value
- The serialized value.mergeToMap(Object, Object, Object)
default T update(T input, String key, (T) -> T function)
DataResult
if the entry could not be set.get(Object, String)
, then sets a new value using set(Object, String, Object)
.input
- The seraialized map to set the entry to.key
- The key, as a string.function
- A function which computes a new value using the existing value.default T updateGeneric(T input, T key, (T) -> T function)
DataResult
if the entry could not be set.getGeneric(Object, Object)
, then sets a new value using mergeToMap(Object, Object, Object)
.input
- The seraialized map to set the entry to.key
- The serialized key.function
- A function which computes a new value using the existing value.default ListBuilder<T> listBuilder()
ListBuilder
for creating lists of the serialized type.ListBuilder.Builder
.default RecordBuilder<T> mapBuilder()
RecordBuilder
for creating maps of the serialized type.RecordBuilder.MapBuilder
.default <E> (E) -> DataResult<T> withEncoder(Encoder<E> encoder)
Encoder
, along with this implementation,
to encode data to the serialized type.E
- The type of values the encoder encodes.encoder
- The encoder to use.Encoder.encode(Object, DynamicOps, Object)
default <E> (T) -> DataResult<(E,T)> withDecoder(Decoder<E> decoder)
Decoder
, along with this implementation,
to decode data from the serialized type.E
- The type of values the decoder decodes.decoder
- The decoder to use.withParser(Decoder)
,
Decoder.decode(DynamicOps, Object)
default <E> (T) -> DataResult<E> withParser(Decoder<E> decoder)
Decoder
, along with this implementation,
to parse data from the serialized type.E
- The type of values the decoder parses.decoder
- The decoder to use.Decoder.parse(DynamicOps, Object)
default <U> U convertList(DynamicOps<U> outOps, T input)
getStream(Object)
, then
converts each element of the input list using convertTo(DynamicOps, Object)
.U
- The output type.outOps
- The DynamicOps
for the output type.input
- The serialized list.convertTo(DynamicOps, Object)
default <U> U convertMap(DynamicOps<U> outOps, T input)
getMapValues(Object)
, then
converts each key and value using convertTo(DynamicOps, Object)
.U
- The output type.outOps
- The DynamicOps
for the output type.input
- The serialized map.convertTo(DynamicOps, Object)