Package org.geysermc.adventure.text.serializer.nbt

Class HeterogeneousNbtList

java.lang.Object
org.geysermc.adventure.text.serializer.nbt.HeterogeneousNbtList
public final class HeterogeneousNbtList extends Object
A wrapper around a heterogeneous NBT list.

The NBT format does not support heterogeneous NBT lists, however Java Edition's codecs do. This poses a problem when Java Edition wants to save different types in the same NBT list: for example ["some text", {text: " some more text", color: red}] would normally not be possible. As a solution, Java Edition, when saving heterogeneous NBT lists, wraps all non-compound types in a compound tag with a single, empty-string key.

This class exists to construct and parse heterogeneous NBT lists. To write heterogeneous NBT lists (i.e., convert a list consisting of one or more NBT types into a list consisting of one), create a new instance of this class, add objects using add(Object) or add(NbtType, Object), and finally, use build() to convert the heterogenous NBT list to a homogeneous one. Alternatively, you can use the of(Object...) shorthand method, or collector() to collect a stream of NBT tags.

To parse heterogeneous NBT lists, use tryUnwrap(NbtList), which will take any NBT list and try to unwrap it, if it is a heterogeneous NBT list (if it isn't, the input is returned unmodified). Alternatively, you can use getList(NbtMap, String) to easily get a heterogeneous NBT list from an NbtMap.

See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    HeterogeneousNbtList()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    add(Object value)
    Adds the given NBT tag to this heterogeneous NBT list.
    <T> void
    add(org.cloudburstmc.nbt.NbtType<T> type, T value)
    Adds the given NBT tag to this heterogeneous NBT list.
    org.cloudburstmc.nbt.NbtList<?>
    build()
    Flattens this heterogeneous NBT list into a homogeneous one.
    static <T> Collector<T,?,org.cloudburstmc.nbt.NbtList<?>>
    collector()
    Creates a Collector to use with Stream.collect(Collector) to construct a homogeneous NBT list from a heterogeneous stream of NBT tags.
    static List<Object>
    getList(org.cloudburstmc.nbt.NbtMap map, String key)
    Attempts to parse a heterogeneous NBT list from the given NbtMap, using the given key.
    static org.cloudburstmc.nbt.NbtList<?>
    of()
    Shorthand method for creating an empty heterogeneous NBT list.
    static org.cloudburstmc.nbt.NbtList<?>
    of(Object... values)
    Constructs a heterogeneous NBT list from the given array of NBT tags.
    static List<Object>
    tryUnwrap(org.cloudburstmc.nbt.NbtList<?> list)
    Tries to unwrap (parse) the given heterogeneous NBT list.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • HeterogeneousNbtList

      public HeterogeneousNbtList()

  • Method Details

    • of

      public static org.cloudburstmc.nbt.NbtList<?> of()
      Shorthand method for creating an empty heterogeneous NBT list. This essentially returns NbtList.EMPTY.
      Returns:
      an empty heterogeneous NBT list
      See Also:

    • of

      public static org.cloudburstmc.nbt.NbtList<?> of(Object... values)
      Constructs a heterogeneous NBT list from the given array of NBT tags.
      Parameters:
      values - the NBT tags to construct a heterogeneous NBT list of
      Returns:
      the constructed heterogeneous NBT list

    • getList

      public static List<Object> getList(org.cloudburstmc.nbt.NbtMap map, String key)
      Attempts to parse a heterogeneous NBT list from the given NbtMap, using the given key.

      If key is not present in the NbtMap, an empty list is returned.

      Parameters:
      map - the NbtMap to fetch the key from
      key - the key
      Returns:
      the parsed heterogeneous NBT list, if it was present, or an empty list if it was not
      See Also:

    • tryUnwrap

      public static List<Object> tryUnwrap(org.cloudburstmc.nbt.NbtList<?> list)
      Tries to unwrap (parse) the given heterogeneous NBT list.

      If the given list is not a heterogeneous NBT list, it is returned unmodified.

      Parameters:
      list - the NBT list to unwrap
      Returns:
      the unwrapped heterogeneous NBT list, or the input if it was a homogeneous NBT list
      See Also:

    • add

      public void add(Object value)
      Adds the given NBT tag to this heterogeneous NBT list.

      This method uses NbtType.byClass(Class) to get the NbtType of the given tag. If it was not an NBT tag, an IllegalArgumentException is thrown.

      Parameters:
      value - the NBT tag to add to this heterogeneous NBT list
      Throws:
      IllegalArgumentException - when the given value was not an NBT tag
      See Also:

    • add

      public <T> void add(org.cloudburstmc.nbt.NbtType<T> type, T value)
      Adds the given NBT tag to this heterogeneous NBT list.
      Parameters:
      type - the NbtType of the value
      value - the NBT tag to add to this heterogeneous NBT list
      See Also:

    • build

      public org.cloudburstmc.nbt.NbtList<?> build()
      Flattens this heterogeneous NBT list into a homogeneous one.
      Returns:
      the flattened heterogeneous NBT list

    • collector

      public static <T> Collector<T,?,org.cloudburstmc.nbt.NbtList<?>> collector()
      Creates a Collector to use with Stream.collect(Collector) to construct a homogeneous NBT list from a heterogeneous stream of NBT tags.
      Type Parameters:
      T - the type of the Collector, usually Object for heterogeneous NBT lists
      Returns:
      the Collector