Package org.tomlj

Interface TomlArray

All Known Subinterfaces:
MutableTomlArray
public interface TomlArray
An array of TOML values.

An array that can be edited is a MutableTomlArray; the arrays of a parse result are.

  • Method Summary

    Modifier and Type
    Method
    Description
    default <T> T
    as(Class<T> type)
    Bind this array to a Java type, with the default options.
    default <T> T
    as(Class<T> type, TomlBindOptions options)
    Bind this array to a Java type.
    default <T> T
    as(GenericType<T> type)
    Bind this array to a generic Java type, with the default options.
    default <T> T
    as(GenericType<T> type, TomlBindOptions options)
    Bind this array to a generic Java type.
    default @Nullable TomlComment
    comment(int index, TomlComment.Placement placement)
    Get the comment attached to a value at a placement.
    default List<TomlComment>
    comments(int index)
    Get the comments attached to a value.
    List<TomlElement>
    elements()
    Get the elements written in this array, in document order.
    TomlEntry
    entry(int index)
    Get the entry at an index.
    default Object
    get(int index)
    Get a value at a specified index.
    default TomlArray
    getArray(int index)
    Get an array at a specified index.
    default boolean
    getBoolean(int index)
    Get a boolean at a specified index.
    default double
    getDouble(int index)
    Get a double at a specified index.
    default LocalDate
    getLocalDate(int index)
    Get a local date at a specified index.
    default LocalDateTime
    getLocalDateTime(int index)
    Get a local date time at a specified index.
    default LocalTime
    getLocalTime(int index)
    Get a local time at a specified index.
    default long
    getLong(int index)
    Get a long at a specified index.
    default OffsetDateTime
    getOffsetDateTime(int index)
    Get an offset date time at a specified index.
    default String
    getString(int index)
    Get a string at a specified index.
    default TomlTable
    getTable(int index)
    Get a table at a specified index.
    default @Nullable TomlPosition
    inputPositionOf(int index)
    Get the position where a value is defined in the TOML document.
    default boolean
    isArray(int index)
    true if the value at an index is an array.
    default boolean
    isBoolean(int index)
    true if the value at an index is a boolean.
    default boolean
    isDouble(int index)
    true if the value at an index is a double.
    boolean
    isEmpty()
    true if the array is empty.
    default boolean
    isLocalDate(int index)
    true if the value at an index is a local date.
    default boolean
    isLocalDateTime(int index)
    true if the value at an index is a local date-time.
    default boolean
    isLocalTime(int index)
    true if the value at an index is a local time.
    default boolean
    isLong(int index)
    true if the value at an index is a long.
    default boolean
    isOffsetDateTime(int index)
    true if the value at an index is an offset date-time.
    default boolean
    isString(int index)
    true if the value at an index is a string.
    default boolean
    isTable(int index)
    true if the value at an index is a table.
    int
    size()
    The size of the array.
    default void
    toJson(Appendable appendable, EnumSet<JsonOptions> options)
    Append a JSON representation of this array to the appendable output.
    default void
    toJson(Appendable appendable, JsonOptions... options)
    Append a JSON representation of this array to the appendable output.
    default String
    toJson(EnumSet<JsonOptions> options)
    Return a representation of this array using JSON.
    default String
    toJson(JsonOptions... options)
    Return a representation of this array using JSON.
    List<Object>
    toList()
    Get the elements of this array as a List.
    default String
    toToml()
    Return a representation of this array using TOML, written with the default options.
    default void
    toToml(Appendable appendable)
    Append a TOML representation of this array to the appendable output, written with the default options.
    default void
    toToml(Appendable appendable, TomlWriteOptions options)
    Append a TOML representation of this array to the appendable output.
    default String
    toToml(TomlWriteOptions options)
    Return a representation of this array using TOML.

  • Method Details

    • size

      int size()
      The size of the array.
      Returns:
      The size of the array.

    • isEmpty

      boolean isEmpty()
      true if the array is empty.
      Returns:
      true if the array is empty.

    • get

      default Object get(int index)
      Get a value at a specified index.

      This is a shortcut for entry(int), returning its value.

      Parameters:
      index - The array index.
      Returns:
      The value.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.

    • isString

      default boolean isString(int index)
      true if the value at an index is a string.
      Parameters:
      index - The array index.
      Returns:
      true if the value at the index is a string.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.

    • getString

      default String getString(int index)
      Get a string at a specified index.
      Parameters:
      index - The array index.
      Returns:
      The value.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.
      TomlInvalidTypeException - If the value is not a string.

    • isLong

      default boolean isLong(int index)
      true if the value at an index is a long.
      Parameters:
      index - The array index.
      Returns:
      true if the value at the index is a long.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.

    • getLong

      default long getLong(int index)
      Get a long at a specified index.
      Parameters:
      index - The array index.
      Returns:
      The value.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.
      TomlInvalidTypeException - If the value is not a long.

    • isDouble

      default boolean isDouble(int index)
      true if the value at an index is a double.
      Parameters:
      index - The array index.
      Returns:
      true if the value at the index is a double.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.

    • getDouble

      default double getDouble(int index)
      Get a double at a specified index.
      Parameters:
      index - The array index.
      Returns:
      The value.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.
      TomlInvalidTypeException - If the value is not a double.

    • isBoolean

      default boolean isBoolean(int index)
      true if the value at an index is a boolean.
      Parameters:
      index - The array index.
      Returns:
      true if the value at the index is a boolean.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.

    • getBoolean

      default boolean getBoolean(int index)
      Get a boolean at a specified index.
      Parameters:
      index - The array index.
      Returns:
      The value.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.
      TomlInvalidTypeException - If the value is not a boolean.

    • isOffsetDateTime

      default boolean isOffsetDateTime(int index)
      true if the value at an index is an offset date-time.
      Parameters:
      index - The array index.
      Returns:
      true if the value at the index is an offset date-time.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.

    • getOffsetDateTime

      default OffsetDateTime getOffsetDateTime(int index)
      Get an offset date time at a specified index.
      Parameters:
      index - The array index.
      Returns:
      The value.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.
      TomlInvalidTypeException - If the value is not an OffsetDateTime.

    • isLocalDateTime

      default boolean isLocalDateTime(int index)
      true if the value at an index is a local date-time.
      Parameters:
      index - The array index.
      Returns:
      true if the value at the index is a local date-time.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.

    • getLocalDateTime

      default LocalDateTime getLocalDateTime(int index)
      Get a local date time at a specified index.
      Parameters:
      index - The array index.
      Returns:
      The value.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.
      TomlInvalidTypeException - If the value is not an LocalDateTime.

    • isLocalDate

      default boolean isLocalDate(int index)
      true if the value at an index is a local date.
      Parameters:
      index - The array index.
      Returns:
      true if the value at the index is a local date.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.

    • getLocalDate

      default LocalDate getLocalDate(int index)
      Get a local date at a specified index.
      Parameters:
      index - The array index.
      Returns:
      The value.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.
      TomlInvalidTypeException - If the value is not an LocalDate.

    • isLocalTime

      default boolean isLocalTime(int index)
      true if the value at an index is a local time.
      Parameters:
      index - The array index.
      Returns:
      true if the value at the index is a local time.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.

    • getLocalTime

      default LocalTime getLocalTime(int index)
      Get a local time at a specified index.
      Parameters:
      index - The array index.
      Returns:
      The value.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.
      TomlInvalidTypeException - If the value is not an LocalTime.

    • isArray

      default boolean isArray(int index)
      true if the value at an index is an array.
      Parameters:
      index - The array index.
      Returns:
      true if the value at the index is an array.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.

    • getArray

      default TomlArray getArray(int index)
      Get an array at a specified index.
      Parameters:
      index - The array index.
      Returns:
      The value.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.
      TomlInvalidTypeException - If the value is not an array.

    • isTable

      default boolean isTable(int index)
      true if the value at an index is a table.
      Parameters:
      index - The array index.
      Returns:
      true if the value at the index is a table.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.

    • getTable

      default TomlTable getTable(int index)
      Get a table at a specified index.
      Parameters:
      index - The array index.
      Returns:
      The value.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.
      TomlInvalidTypeException - If the value is not a table.

    • inputPositionOf

      default @Nullable TomlPosition inputPositionOf(int index)
      Get the position where a value is defined in the TOML document.

      This is a shortcut for entry(int), returning its position.

      Parameters:
      index - The array index.
      Returns:
      The input position, or null if the entry was not read from a document.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.

    • comments

      default List<TomlComment> comments(int index)
      Get the comments attached to a value.

      Returns the comments in document order: the run directly above the value, if any, then the comment on its line, if any, so at most two, each with its TomlComment.placement().

      In an array of tables, the comments on each [[x]] header are attached to the table it opens: comments(0) for the first header, and so on.

      This is a shortcut for entry(int), returning its comments.

      Parameters:
      index - The array index.
      Returns:
      The attached comments, in document order. Unmodifiable.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.

    • comment

      default @Nullable TomlComment comment(int index, TomlComment.Placement placement)
      Get the comment attached to a value at a placement.

      This is a shortcut for entry(int), returning TomlEntry.comment(TomlComment.Placement).

      Parameters:
      index - The array index.
      placement - TomlComment.Placement.ABOVE for the run directly above the value, or TomlComment.Placement.AFTER for the comment on its line.
      Returns:
      The comment at that placement, or null if there is none.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.
      NullPointerException - If placement is null.
      IllegalArgumentException - If placement is TomlComment.Placement.UNATTACHED.

    • entry

      TomlEntry entry(int index)
      Get the entry at an index.

      The entry is the TomlEntry that elements() holds for the index. get(int), inputPositionOf(int) and comments(int) are shortcuts reading its value, position and comments.

      Parameters:
      index - The array index.
      Returns:
      The entry.
      Throws:
      IndexOutOfBoundsException - If the index is out of bounds.

    • elements

      List<TomlElement> elements()
      Get the elements written in this array, in document order.

      Each element is a TomlEntry, an entry of this array, or an unattached TomlComment. The entries hold the values get(int) returns, in the same order. A comment is unattached when it is neither directly above a value nor on its line: a run separated by a blank line from the value below it, a run before the closing bracket, or a comment on a line with no value.

      Returns:
      The elements, in document order. Unmodifiable.

    • toList

      List<Object> toList()
      Get the elements of this array as a List.

      Note that this does not do a deep conversion. If this array contains tables or arrays, they will be of type TomlTable or TomlArray respectively.

      Returns:
      The elements of this array as a List.

    • toJson

      default String toJson(JsonOptions... options)
      Return a representation of this array using JSON.
      Parameters:
      options - Options for the JSON encoder.
      Returns:
      A JSON representation of this table.

    • toJson

      default String toJson(EnumSet<JsonOptions> options)
      Return a representation of this array using JSON.
      Parameters:
      options - Options for the JSON encoder.
      Returns:
      A JSON representation of this table.

    • toJson

      default void toJson(Appendable appendable, JsonOptions... options) throws IOException
      Append a JSON representation of this array to the appendable output.
      Parameters:
      appendable - The appendable output.
      options - Options for the JSON encoder.
      Throws:
      IOException - If an IO error occurs.

    • toJson

      default void toJson(Appendable appendable, EnumSet<JsonOptions> options) throws IOException
      Append a JSON representation of this array to the appendable output.
      Parameters:
      appendable - The appendable output.
      options - Options for the JSON encoder.
      Throws:
      IOException - If an IO error occurs.

    • toToml

      default String toToml()
      Return a representation of this array using TOML, written with the default options.

      An array is always written in the default style, whether or not it was parsed, keeping the literal form each of its values was parsed with.

      Returns:
      A TOML representation of this array.
      See Also:

    • toToml

      default String toToml(TomlWriteOptions options)
      Return a representation of this array using TOML.

      An array is always written in the default style, whether or not it was parsed; see toToml().

      Parameters:
      options - The options to write with.
      Returns:
      A TOML representation of this array.
      Throws:
      IllegalArgumentException - If the version the options write for cannot write this array: TOML 1.0.0 and an inline table holding a comment, or text copied from a document that only TOML 1.1.0 allows; see TomlWriteOptions.withVersion(TomlVersion).
      See Also:

    • toToml

      default void toToml(Appendable appendable) throws IOException
      Append a TOML representation of this array to the appendable output, written with the default options.

      Written as toToml() writes it.

      Parameters:
      appendable - The appendable output.
      Throws:
      IOException - If an IO error occurs.
      See Also:

    • toToml

      default void toToml(Appendable appendable, TomlWriteOptions options) throws IOException
      Append a TOML representation of this array to the appendable output.

      Written as toToml(TomlWriteOptions) writes it.

      Parameters:
      appendable - The appendable output.
      options - The options to write with.
      Throws:
      IOException - If an IO error occurs.
      IllegalArgumentException - If the version the options write for cannot write this array: TOML 1.0.0 and an inline table holding a comment, or text copied from a document that only TOML 1.1.0 allows; see TomlWriteOptions.withVersion(TomlVersion).
      See Also:

    • as

      default <T> T as(Class<T> type)
      Bind this array to a Java type, with the default options.
      Type Parameters:
      T - The type to bind to.
      Parameters:
      type - The type to bind to.
      Returns:
      A new instance of the type, holding the values of this array.
      Throws:
      TomlBindException - If any value of this array cannot be bound.
      IllegalArgumentException - If the type, or a type it holds, cannot be bound to.
      See Also:

    • as

      default <T> T as(Class<T> type, TomlBindOptions options)
      Bind this array to a Java type. 
      
 record Server(String host, int port) {}

 Server[] servers = result.getArray("servers").as(Server[].class, TomlBindOptions.defaults());

      The value of each key or element is bound to the type declared for it, as follows:

      • A string to String, an enum constant, or char for a string of one character. An enum constant is matched by its name, or else by its name ignoring case and with - and space read as _; a constant with a TomlName annotation is matched by the annotation's value only.
      • An integer to long, int, short, byte, BigInteger, or to a floating point type if it can be represented exactly. A value out of range for the type is an error.
      • A float to double, float or BigDecimal.
      • A boolean to boolean.
      • An offset date-time to OffsetDateTime, ZonedDateTime or Instant, and a local date-time, date or time to LocalDateTime, LocalDate or LocalTime.
      • An array to a List, Set, Collection, Iterable, a concrete collection class, or a Java array.
      • A table to a record, a class, or a Map with String keys.
      • Any value to Object, unchanged, and a table or array to TomlTable or TomlArray, or to a copy of it for MutableTomlTable or MutableTomlArray.
      • Any value to Optional<T>, by binding it to T.
      • Any value to a type that has a converter in the options, by that converter.

      A table is bound to a record through its canonical constructor, with a key for each component. It is bound to a class by creating an instance with its constructor without parameters, then setting a field for each key. Every field of the class and its superclasses is bound except static, transient and final fields. The key of a field or component is its name, converted by the options' key naming, or the value of its TomlName annotation.

      A key the table does not have is bound as follows:

      • An Optional is empty.
      • A field of a class keeps the value it was given when the instance was created.
      • A record component, or a field of a class that is null once the instance is created, is null if it is nullable, and an error if it is never null. A primitive is never null; otherwise, an annotation named NonNull, NotNull or Nonnull marks a field or component as never null, and one named Nullable marks it as nullable, from any package, as long as the annotation is kept at runtime. Without either, it is never null if its class, an enclosing class, its package or its module is annotated as JSpecify's NullMarked, and nullable otherwise.
      A key in the table that names no field or component is an error, unless the options ignore unknown keys.

      Binding does not stop at the first error. Every value is bound, and the errors, each with the path and position of the value, are thrown together in a TomlBindException. An exception thrown by a record's constructor or a converter is reported as an error at the position of the value being bound.

      TomlJ binds to private fields and classes by reflection. In a named module, the package holding them must be opened to the module org.tomlj.

      Type Parameters:
      T - The type to bind to.
      Parameters:
      type - The type to bind to.
      options - The options to bind with.
      Returns:
      A new instance of the type, holding the values of this array.
      Throws:
      TomlBindException - If any value of this array cannot be bound.
      IllegalArgumentException - If the type, or a type it holds, cannot be bound to.

    • as

      default <T> T as(GenericType<T> type)
      Bind this array to a generic Java type, with the default options.
      Type Parameters:
      T - The type to bind to.
      Parameters:
      type - The type to bind to.
      Returns:
      A new instance of the type, holding the values of this array.
      Throws:
      TomlBindException - If any value of this array cannot be bound.
      IllegalArgumentException - If the type, or a type it holds, cannot be bound to.
      See Also:

    • as

      default <T> T as(GenericType<T> type, TomlBindOptions options)
      Bind this array to a generic Java type.

      This binds as as(Class, TomlBindOptions) does, to a type such as List<Server> that a Class cannot name.

      Type Parameters:
      T - The type to bind to.
      Parameters:
      type - The type to bind to.
      options - The options to bind with.
      Returns:
      A new instance of the type, holding the values of this array.
      Throws:
      TomlBindException - If any value of this array cannot be bound.
      IllegalArgumentException - If the type, or a type it holds, cannot be bound to.