Package net.dv8tion.jda.api.utils.data

Class DataArray

java.lang.Object
net.dv8tion.jda.api.utils.data.DataArray
All Implemented Interfaces:
Iterable<Object>, SerializableArray
public class DataArray extends Object implements Iterable<Object>, SerializableArray
Represents a list of values used in communication with the Discord API.

Throws IndexOutOfBoundsException if provided with index out of bounds.

This class is not Thread-Safe

  • Method Details

    • empty

      @Nonnull public static DataArray empty()
      Creates a new empty DataArray, ready to be populated with values.
      Returns:
      An empty DataArray instance
      See Also:

    • fromCollection

      @Nonnull public static DataArray fromCollection(@Nonnull Collection<?> col)
      Creates a new DataArray and populates it with the contents of the provided collection.
      Parameters:
      col - The Collection
      Returns:
      A new DataArray populated with the contents of the collection

    • fromJson

      @Nonnull public static DataArray fromJson(@Nonnull String json)
      Parses a JSON Array into a DataArray instance.
      Parameters:
      json - The correctly formatted JSON Array
      Returns:
      A new DataArray instance for the provided array
      Throws:
      ParsingException - If the provided JSON is incorrectly formatted

    • fromJson

      @Nonnull public static DataArray fromJson(@Nonnull InputStream json)
      Parses a JSON Array into a DataArray instance.
      Parameters:
      json - The correctly formatted JSON Array
      Returns:
      A new DataArray instance for the provided array
      Throws:
      ParsingException - If the provided JSON is incorrectly formatted or an I/O error occurred

    • fromJson

      @Nonnull public static DataArray fromJson(@Nonnull Reader json)
      Parses a JSON Array into a DataArray instance.
      Parameters:
      json - The correctly formatted JSON Array
      Returns:
      A new DataArray instance for the provided array
      Throws:
      ParsingException - If the provided JSON is incorrectly formatted or an I/O error occurred

    • fromETF

      @Nonnull public static DataArray fromETF(@Nonnull byte[] data)
      Parses using ExTermDecoder. The provided data must start with the correct version header (131).
      Parameters:
      data - The data to decode
      Returns:
      A DataArray instance for the provided payload
      Throws:
      IllegalArgumentException - If the provided data is null
      ParsingException - If the provided ETF payload is incorrectly formatted or an I/O error occurred
      Since:
      4.2.1

    • isNull

      public boolean isNull(int index)
      Whether the value at the specified index is null.
      Parameters:
      index - The index to check
      Returns:
      True, if the value at the index is null

    • isType

      public boolean isType(int index, @Nonnull DataType type)
      Whether the value at the specified index is of the specified type.
      Parameters:
      index - The index to check
      type - The type to check
      Returns:
      True, if the type check is successful
      See Also:

    • length

      public int length()
      The length of the array.
      Returns:
      The length of the array

    • isEmpty

      public boolean isEmpty()
      Whether this array is empty
      Returns:
      True, if this array is empty

    • getObject

      @Nonnull public DataObject getObject(int index)
      Resolves the value at the specified index to a DataObject
      Parameters:
      index - The index to resolve
      Returns:
      The resolved DataObject
      Throws:
      ParsingException - If the value is of the wrong type or missing

    • getArray

      @Nonnull public DataArray getArray(int index)
      Resolves the value at the specified index to a DataArray
      Parameters:
      index - The index to resolve
      Returns:
      The resolved DataArray
      Throws:
      ParsingException - If the value is of the wrong type or null

    • getString

      @Nonnull public String getString(int index)
      Resolves the value at the specified index to a String.
      Parameters:
      index - The index to resolve
      Returns:
      The resolved String
      Throws:
      ParsingException - If the value is of the wrong type or null

    • getString

      @Contract("_, !null -> !null") public String getString(int index, @Nullable String defaultValue)
      Resolves the value at the specified index to a String.
      Parameters:
      index - The index to resolve
      defaultValue - Alternative value to use when the value associated with the index is null
      Returns:
      The resolved String
      Throws:
      ParsingException - If the value is of the wrong type

    • getBoolean

      public boolean getBoolean(int index)
      Resolves the value at the specified index to a boolean.
      Parameters:
      index - The index to resolve
      Returns:
      True, if the value is present and set to true. Otherwise false.
      Throws:
      ParsingException - If the value is of the wrong type

    • getBoolean

      public boolean getBoolean(int index, boolean defaultValue)
      Resolves the value at the specified index to a boolean.
      Parameters:
      index - The index to resolve
      defaultValue - Alternative value to use when the value associated with the index is null
      Returns:
      True, if the value is present and set to true. False, if it is set to false. Otherwise defaultValue.
      Throws:
      ParsingException - If the value is of the wrong type

    • getInt

      public int getInt(int index)
      Resolves the value at the specified index to an int.
      Parameters:
      index - The index to resolve
      Returns:
      The resolved int value
      Throws:
      ParsingException - If the value is of the wrong type

    • getInt

      public int getInt(int index, int defaultValue)
      Resolves the value at the specified index to an int.
      Parameters:
      index - The index to resolve
      defaultValue - Alternative value to use when the value associated with the index is null
      Returns:
      The resolved int value
      Throws:
      ParsingException - If the value is of the wrong type

    • getUnsignedInt

      public int getUnsignedInt(int index)
      Resolves the value at the specified index to an unsigned int.
      Parameters:
      index - The index to resolve
      Returns:
      The resolved unsigned int value
      Throws:
      ParsingException - If the value is of the wrong type

    • getUnsignedInt

      public int getUnsignedInt(int index, int defaultValue)
      Resolves the value at the specified index to an unsigned int.
      Parameters:
      index - The index to resolve
      defaultValue - Alternative value to use when the value associated with the index is null
      Returns:
      The resolved unsigned int value
      Throws:
      ParsingException - If the value is of the wrong type

    • getLong

      public long getLong(int index)
      Resolves the value at the specified index to a long.
      Parameters:
      index - The index to resolve
      Returns:
      The resolved long value
      Throws:
      ParsingException - If the value is of the wrong type

    • getLong

      public long getLong(int index, long defaultValue)
      Resolves the value at the specified index to a long.
      Parameters:
      index - The index to resolve
      defaultValue - Alternative value to use when the value associated with the index is null
      Returns:
      The resolved long value
      Throws:
      ParsingException - If the value is of the wrong type

    • getUnsignedLong

      public long getUnsignedLong(int index)
      Resolves the value at the specified index to an unsigned long.
      Parameters:
      index - The index to resolve
      Returns:
      The resolved unsigned long value
      Throws:
      ParsingException - If the value is of the wrong type

    • getOffsetDateTime

      @Nonnull public OffsetDateTime getOffsetDateTime(int index)
      Resolves the value at the specified index to an OffsetDateTime.
      Note: This method should be used on ISO8601 timestamps
      Parameters:
      index - The index to resolve
      Returns:
      Possibly-null OffsetDateTime object representing the timestamp
      Throws:
      ParsingException - If the value is missing, null, or not a valid ISO8601 timestamp

    • getOffsetDateTime

      @Contract("_, !null -> !null") public OffsetDateTime getOffsetDateTime(int index, @Nullable OffsetDateTime defaultValue)
      Resolves the value at the specified index to an OffsetDateTime.
      Note: This method should only be used on ISO8601 timestamps
      Parameters:
      index - The index to resolve
      defaultValue - Alternative value to use when no value or null value is associated with the key
      Returns:
      Possibly-null OffsetDateTime object representing the timestamp
      Throws:
      ParsingException - If the value is not a valid ISO8601 timestamp

    • getUnsignedLong

      public long getUnsignedLong(int index, long defaultValue)
      Resolves the value at the specified index to an unsigned long.
      Parameters:
      index - The index to resolve
      defaultValue - Alternative value to use when the value associated with the index is null
      Returns:
      The resolved unsigned long value
      Throws:
      ParsingException - If the value is of the wrong type

    • getDouble

      public double getDouble(int index)
      Resolves the value at the specified index to a double.
      Parameters:
      index - The index to resolve
      Returns:
      The resolved double value
      Throws:
      ParsingException - If the value is of the wrong type

    • getDouble

      public double getDouble(int index, double defaultValue)
      Resolves the value at the specified index to a double.
      Parameters:
      index - The index to resolve
      defaultValue - Alternative value to use when the value associated with the index is null
      Returns:
      The resolved double value
      Throws:
      ParsingException - If the value is of the wrong type

    • add

      @Nonnull public DataArray add(@Nullable Object value)
      Appends the provided value to the end of the array.
      Parameters:
      value - The value to append
      Returns:
      A DataArray with the value inserted at the end

    • addAll

      @Nonnull public DataArray addAll(@Nonnull Collection<?> values)
      Appends the provided values to the end of the array.
      Parameters:
      values - The values to append
      Returns:
      A DataArray with the values inserted at the end

    • addAll

      @Nonnull public DataArray addAll(@Nonnull DataArray array)
      Appends the provided values to the end of the array.
      Parameters:
      array - The values to append
      Returns:
      A DataArray with the values inserted at the end

    • insert

      @Nonnull public DataArray insert(int index, @Nullable Object value)
      Inserts the specified value at the provided index.
      Parameters:
      index - The target index
      value - The value to insert
      Returns:
      A DataArray with the value inserted at the specified index

    • remove

      @Nonnull public DataArray remove(int index)
      Removes the value at the specified index.
      Parameters:
      index - The target index to remove
      Returns:
      A DataArray with the value removed

    • remove

      @Nonnull public DataArray remove(@Nullable Object value)
      Removes the specified value.
      Parameters:
      value - The value to remove
      Returns:
      A DataArray with the value removed

    • toJson

      @Nonnull public byte[] toJson()
      Serializes this object as JSON.
      Returns:
      byte array containing the JSON representation of this object

    • toETF

      @Nonnull public byte[] toETF()
      Serializes this object as ETF LIST term.
      Returns:
      byte array containing the encoded ETF term
      Since:
      4.2.1

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toPrettyString

      @Nonnull public String toPrettyString()

    • toList

      @Nonnull public List<Object> toList()
      Converts this DataArray to a List.
      Returns:
      The resulting list

    • iterator

      @Nonnull public Iterator<Object> iterator()
      Specified by:
      iterator in interface Iterable<Object>

    • stream

      @Nonnull public <T> Stream<T> stream(BiFunction<? super DataArray,Integer,? extends T> mapper)

    • toDataArray

      @Nonnull public DataArray toDataArray()
      Description copied from interface: SerializableArray
      Serialized DataArray for this object.
      Specified by:
      toDataArray in interface SerializableArray
      Returns:
      DataArray

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object