Class Array

java.lang.Object
org.rapidcontext.core.data.Array
All Implemented Interfaces:
Iterable<Object>

public class Array extends Object implements Iterable<Object>
A general data array. Compared to the standard ArrayList, this class provides a number of improvements;
  • Access Methods -- Methods to provide easy access to integer, boolean and string values without casting.
  • Negative indices -- Using a negative index will access elements from the end of the array.
  • Sealing -- Simple creation of read-only objects.
  • Deep Copies -- Provides a meaningful way to clone or copy data.
  • Serialization -- Utility classes are available for serializing to JSON, XML, etc.
  • Debug Info -- The toString() method provides a more usable default implementation.
The values in the array may have any type, but recommended types are String, Integer, Boolean, Dict and Array. Circular or self-referencing structures should not be used, since most data serialization cannot handle them.
Version:
1.0
  • Constructor Summary

    Constructors
    Constructor
    Description
    Creates a new empty array.
    Array(int initialCapacity)
    Creates a new empty array.
  • Method Summary

    Modifier and Type
    Method
    Description
    add(Object value)
    Adds an array value to the end of the list.
    Adds all entries from another array into this one.
    addBoolean(boolean value)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use add(value) with auto-boxing instead.
    addInt(int value)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use add(value) with auto-boxing instead.
    Returns the relative complement of this array and another array.
    boolean
    Checks if all of the values in the specified array is contained in this array.
    boolean
    Checks if one or more of the values in the specified array is contained in this array.
    boolean
    containsIndex(int index)
    Checks if the specified index is defined in this array, i.e.
    boolean
    Checks if the specified value is contained in this array.
    Creates a copy of this array.
    boolean
    Checks if this array is identical to another one.
    static Array
    from(Iterable<?> iter)
    Creates a new array containing all elements in an iterable.
    static Array
    from(Iterator<?> iter)
    Creates a new array containing all elements in an iterator.
    static Array
    from(Stream<?> stream)
    Creates a new array containing all elements in a stream.
    get(int index)
    Returns the array value at the specified index.
    <T> T
    get(int index, Class<T> clazz)
    Returns the array value at the specified index.
    <T> T
    get(int index, Class<T> clazz, T defaultValue)
    Returns the array value at the specified index.
    get(int index, Object defaultValue)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use get(index, Object.class, defaultValue) instead.
    getArray(int index)
    Returns the array array value for the specified index.
    boolean
    getBoolean(int index, boolean defaultValue)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use get(index, Boolean.class, defaultValue) instead.
    getDate(int index, Date defaultValue)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use get(index, Date.class, defaultValue) instead.
    getDict(int index)
    Returns the array dictionary value for the specified index.
    int
    getInt(int index, int defaultValue)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use get(index, Integer.class, defaultValue) instead.
    getString(int index, String defaultValue)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use get(index, String.class, defaultValue) instead.
    int
    Returns a hash code for this object.
    int
    indexOf(Object value)
    Returns the first array index having the specified value.
    Returns the intersection of this array and another array.
    boolean
    Checks if this array is sealed.
    Returns an iterator for all elements in the array.
    static Array
    of(Object... values)
    Creates a new array from an array of elements.
    remove(int index)
    Deletes the specified array index and its value.
    remove(Object value)
    Deletes the first array index having the specified value.
    void
    seal(boolean recursive)
    Seals this array and prohibits any further modifications.
    set(int index, Object value)
    Modifies or defines the array value for the specified index.
    setBoolean(int index, boolean value)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use set(index, value) with auto-boxing instead.
    setInt(int index, int value)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use set(index, value) with auto-boxing instead.
    int
    Returns the size of the array, i.e.
    Sorts all values in this array according to their natural ordering.
    sort(String key)
    Sorts all values in this array according to the natural ordering of the specified dictionary key.
    Sorts all values in this array according to the comparator specified.
    Returns a stream of all elements in the array.
    <T> Stream<T>
    stream(Class<T> clazz)
    Returns a stream of all elements in the array.
    Returns a string representation of this object.
    union(Array arr)
    Returns the union of this array and another array.
    Returns an array with all the values in this array.
    <T> T[]
    values(T[] arr)
    Returns an array with all the values in this array.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface java.lang.Iterable

    forEach, spliterator
  • Constructor Details

    • Array

      public Array()
      Creates a new empty array.
    • Array

      public Array(int initialCapacity)
      Creates a new empty array. By default an array is created with a null value list, but if this constructor is used the list will be initialized with the specified capacity.
      Parameters:
      initialCapacity - the initial array capacity
  • Method Details

    • from

      public static Array from(Iterable<?> iter)
      Creates a new array containing all elements in an iterable. All contained iterable or map elements will be converted to Array or Dict recursively.
      Parameters:
      iter - the iterable to read
      Returns:
      a new array with all elements
    • from

      public static Array from(Iterator<?> iter)
      Creates a new array containing all elements in an iterator. All contained iterable or map elements will be converted to Array or Dict recursively.
      Parameters:
      iter - the iterator to read
      Returns:
      a new array with all elements
    • from

      public static Array from(Stream<?> stream)
      Creates a new array containing all elements in a stream. All contained iterable or map elements will be converted to Array or Dict recursively.
      Parameters:
      stream - the stream to read
      Returns:
      a new array with all elements
    • of

      public static Array of(Object... values)
      Creates a new array from an array of elements.
      Parameters:
      values - the values to add to the array
      Returns:
      a new array with the specified elements
    • equals

      public boolean equals(Object obj)
      Checks if this array is identical to another one. The two arrays will be considered equal if they have the same length and all elements are equal.
      Overrides:
      equals in class Object
      Parameters:
      obj - the object to compare with
      Returns:
      true if the two arrays are equal, or false otherwise
    • hashCode

      public int hashCode()
      Returns a hash code for this object.
      Overrides:
      hashCode in class Object
      Returns:
      a hash code for this object
    • toString

      public String toString()
      Returns a string representation of this object.
      Overrides:
      toString in class Object
      Returns:
      a string representation of this object
    • iterator

      public Iterator<Object> iterator()
      Returns an iterator for all elements in the array.
      Specified by:
      iterator in interface Iterable<Object>
      Returns:
      the object iterator
    • stream

      public Stream<Object> stream()
      Returns a stream of all elements in the array.
      Returns:
      the object stream
    • stream

      public <T> Stream<T> stream(Class<T> clazz)
      Returns a stream of all elements in the array.
      Type Parameters:
      T - the object type to return
      Parameters:
      clazz - the object class
      Returns:
      the object stream
      Throws:
      ClassCastException - if the wasn't possible to cast to the specified object class
      NumberFormatException - if the value wasn't possible to parse as a number
      See Also:
    • copy

      public Array copy()
      Creates a copy of this array. The copy is a "deep copy", as all dictionary and array values will be recursively copied.
      Returns:
      a deep copy of this array
    • isSealed

      public boolean isSealed()
      Checks if this array is sealed.
      Returns:
      true if this array has been sealed, or false otherwise
    • seal

      public void seal(boolean recursive)
      Seals this array and prohibits any further modifications. If the seal is applied recursively, any dictionary or array values in this object will also be sealed. Once sealed, this instance is an immutable read-only object.
      Parameters:
      recursive - the recursive flag
    • size

      public int size()
      Returns the size of the array, i.e. the number of elements in it.
      Returns:
      the length of the array, or zero (0) if empty
    • containsIndex

      public boolean containsIndex(int index)
      Checks if the specified index is defined in this array, i.e. if the index is in a valid range. Note that an index may be defined but still contain a null value.
      Parameters:
      index - the array index
      Returns:
      true if the array index is defined, or false otherwise
    • containsValue

      public boolean containsValue(Object value)
      Checks if the specified value is contained in this array. Note that equals() comparison is used, so only simple values may be checked.
      Parameters:
      value - the value to check for
      Returns:
      true if the value exists, or false otherwise
    • containsAll

      public boolean containsAll(Array arr)
      Checks if all of the values in the specified array is contained in this array. Note that equals() comparison is used, so only simple values may be checked. If the specified array is empty or null, true will be returned.
      Parameters:
      arr - the array with values to check
      Returns:
      true if all values exist, or false otherwise
    • containsAny

      public boolean containsAny(Array arr)
      Checks if one or more of the values in the specified array is contained in this array. Note that equals() comparison is used, so only simple values may be checked. If the specified array is empty or null, false will be returned.
      Parameters:
      arr - the array with values to check
      Returns:
      true if at least one value exists, or false otherwise
    • indexOf

      public int indexOf(Object value)
      Returns the first array index having the specified value. Note that equals() comparison is used, so only simple values may be checked.
      Parameters:
      value - the value to check for
      Returns:
      the array index, or -1 if the value wasn't found
    • values

      public Object[] values()
      Returns an array with all the values in this array.
      Returns:
      an array with all values
    • values

      public <T> T[] values(T[] arr)
      Returns an array with all the values in this array. If the provided array is too small, a new one of the same type is allocated.
      Type Parameters:
      T - the base type for all values
      Parameters:
      arr - the array to store the values
      Returns:
      an array with all values
    • get

      public Object get(int index)
      Returns the array value at the specified index.
      Parameters:
      index - the array index
      Returns:
      the array element value, or null if the index or value is not defined
    • get

      public <T> T get(int index, Class<T> clazz)
      Returns the array value at the specified index. The value is either converted or casted to a specified object class.
      Type Parameters:
      T - the object type to return
      Parameters:
      index - the array index
      clazz - the object class
      Returns:
      the array element value, or null if the index or value is not defined
      Throws:
      ClassCastException - if the wasn't possible to cast to the specified object class
      NumberFormatException - if the value wasn't possible to parse as a number
      See Also:
    • get

      @Deprecated(forRemoval=true) public Object get(int index, Object defaultValue)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use get(index, Object.class, defaultValue) instead.
      Returns the array value at the specified index. If the index is not defined or if the value is set to null, a default value will be returned instead.
      Parameters:
      index - the array index
      defaultValue - the default value
      Returns:
      the array element value, or the default value if the index or value is not defined
    • get

      public <T> T get(int index, Class<T> clazz, T defaultValue)
      Returns the array value at the specified index. The value is either converted or casted to a specified object class. If the index is not defined or if the value is set to null, a default value will be returned instead.
      Type Parameters:
      T - the object type to return
      Parameters:
      index - the array index
      clazz - the object class
      defaultValue - the default value
      Returns:
      the array element value, or null if the index or value is not defined
      Throws:
      ClassCastException - if the wasn't possible to cast to the specified object class
      NumberFormatException - if the value wasn't possible to parse as a number
      See Also:
    • getString

      @Deprecated(forRemoval=true) public String getString(int index, String defaultValue)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use get(index, String.class, defaultValue) instead.
      Returns the array string value for the specified index. If the index is not defined or if the value is set to null, a default value will be returned instead. If the value object is not a string, the toString() method will be called.
      Parameters:
      index - the array index
      defaultValue - the default value
      Returns:
      the array element value, or the default value if the index or value is not defined
    • getBoolean

      @Deprecated(forRemoval=true) public boolean getBoolean(int index, boolean defaultValue)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use get(index, Boolean.class, defaultValue) instead.
      Returns the array boolean value for the specified index. If the index is not defined or if the value is set to null, a default value will be returned instead. If the value object is not a boolean, any object that does not equal "", "0", "f", "false", "no" or "off" is considered true.
      Parameters:
      index - the array index
      defaultValue - the default value
      Returns:
      the array element value, or the default value if the index or value is not defined
    • getInt

      @Deprecated(forRemoval=true) public int getInt(int index, int defaultValue)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use get(index, Integer.class, defaultValue) instead.
      Returns the array integer value for the specified index. If the index is not defined or if the value is set to null, a default value will be returned instead. If the value object is not a number, a conversion of the toString() value of the object will be attempted.
      Parameters:
      index - the array index
      defaultValue - the default value
      Returns:
      the array element value, or the default value if the index or value is not defined
      Throws:
      NumberFormatException - if the value didn't contain a valid integer
    • getDate

      @Deprecated(forRemoval=true) public Date getDate(int index, Date defaultValue)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use get(index, Date.class, defaultValue) instead.
      Returns the array date value for the specified key. If the key is not defined or if the value is set to null, a default value will be returned instead. If the value object is not a date, a numeric conversion of the string value (excluding any '@' prefix) will be attempted.
      Parameters:
      index - the array index
      defaultValue - the default value
      Returns:
      the array element value, or the default value if the index or value is not defined
      Throws:
      NumberFormatException - if the value didn't contain a valid date, number or numeric string
    • getDict

      public Dict getDict(int index) throws ClassCastException
      Returns the array dictionary value for the specified index. If the value is not a dictionary, an exception will be thrown.
      Parameters:
      index - the array index
      Returns:
      the array element value, or an empty dictionary if the index or value is not defined
      Throws:
      ClassCastException - if the value is not a dictionary
    • getArray

      public Array getArray(int index) throws ClassCastException
      Returns the array array value for the specified index. If the value is not a dictionary, an exception will be thrown.
      Parameters:
      index - the array index
      Returns:
      the array element value, or an empty array if the index or value is not defined
      Throws:
      ClassCastException - if the value is not an array
    • set

      public Array set(int index, Object value) throws IndexOutOfBoundsException, UnsupportedOperationException
      Modifies or defines the array value for the specified index. The array will automatically be padded with null values to accommodate an index beyond the current valid range.
      Parameters:
      index - the array index
      value - the array value
      Returns:
      this array for chained operations
      Throws:
      IndexOutOfBoundsException - if index is negative
      UnsupportedOperationException - if this object has been sealed
    • setBoolean

      @Deprecated(forRemoval=true) public Array setBoolean(int index, boolean value) throws IndexOutOfBoundsException, UnsupportedOperationException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use set(index, value) with auto-boxing instead.
      Modifies or defines the boolean array value for the specified index. The array will automatically be padded with null values to accommodate an index beyond the current valid range.
      Parameters:
      index - the array index
      value - the array value
      Returns:
      this array for chained operations
      Throws:
      IndexOutOfBoundsException - if index is negative
      UnsupportedOperationException - if this object has been sealed
    • setInt

      @Deprecated(forRemoval=true) public Array setInt(int index, int value) throws IndexOutOfBoundsException, UnsupportedOperationException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use set(index, value) with auto-boxing instead.
      Modifies or defines the integer array value for the specified index. The array will automatically be padded with null values to accommodate an index beyond the current valid range.
      Parameters:
      index - the array index
      value - the array value
      Returns:
      this array for chained operations
      Throws:
      IndexOutOfBoundsException - if index is negative
      UnsupportedOperationException - if this object has been sealed
    • add

      public Array add(Object value) throws UnsupportedOperationException
      Adds an array value to the end of the list. This method will increase the array size by one.
      Parameters:
      value - the array value
      Returns:
      this array for chained operations
      Throws:
      UnsupportedOperationException - if this object has been sealed
    • addBoolean

      @Deprecated(forRemoval=true) public Array addBoolean(boolean value) throws UnsupportedOperationException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use add(value) with auto-boxing instead.
      Adds a boolean array value to the end of the list. This method will increase the array size by one.
      Parameters:
      value - the array value
      Returns:
      this array for chained operations
      Throws:
      UnsupportedOperationException - if this object has been sealed
    • addInt

      @Deprecated(forRemoval=true) public Array addInt(int value) throws UnsupportedOperationException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use add(value) with auto-boxing instead.
      Adds an integer array value to the end of the list. This method will increase the array size by one.
      Parameters:
      value - the array value
      Returns:
      this array for chained operations
      Throws:
      UnsupportedOperationException - if this object has been sealed
    • addAll

      public Array addAll(Array arr)
      Adds all entries from another array into this one.
      Parameters:
      arr - the array to add elements from
      Returns:
      this array for chained operations
      Throws:
      UnsupportedOperationException - if this object has been sealed
    • remove

      public Array remove(int index) throws UnsupportedOperationException
      Deletes the specified array index and its value. All subsequent array values will be shifted forward by one step.
      Parameters:
      index - the array index
      Returns:
      this array for chained operations
      Throws:
      UnsupportedOperationException - if this object has been sealed
    • remove

      public Array remove(Object value)
      Deletes the first array index having the specified value. All subsequent array values will be shifted forward by one step.
      Parameters:
      value - the array value
      Returns:
      this array for chained operations
      Throws:
      UnsupportedOperationException - if this object has been sealed
    • complement

      public Array complement(Array arr)
      Returns the relative complement of this array and another array. The resulting array will contain all elements from the other array that weren't found in this one. None of the two arrays will be modified, but a new array will only be created if some elements exist in both arrays.
      Parameters:
      arr - the array to filter
      Returns:
      the complement of this array, or null if the specified array was null
    • intersection

      public Array intersection(Array arr)
      Returns the intersection of this array and another array. The resulting array will only contain those elements that were found in both arrays. None of the two arrays will be modified, but a new array will not be created if either is empty.
      Parameters:
      arr - the array to intersect with
      Returns:
      the intersection of the two arrays, or null if the specified array was null
    • union

      public Array union(Array arr)
      Returns the union of this array and another array. The resulting array will contain all elements from this array and all elements from the other array that weren't in this one. None of the two arrays will be modified, but a new array will not be created if either is empty or the overlap is 100%.
      Parameters:
      arr - the array to combine with
      Returns:
      the union of the two arrays
    • sort

      Sorts all values in this array according to their natural ordering. Note that the array MUST NOT contain dictionaries, arrays or other objects that are not comparable (will result in a ClassCastException). Also, all entries must be comparable with each other, as the natural order of different data types is undefined.
      Returns:
      this array for chained operations
      Throws:
      UnsupportedOperationException - if this object has been sealed
      ClassCastException - if the array values are not comparable with each other
      See Also:
    • sort

      Sorts all values in this array according to the natural ordering of the specified dictionary key. Note that the array MUST contain dictionaries with comparable key values if this method is used, or a ClassCastException will be thrown.
      Parameters:
      key - the dictionary key name
      Returns:
      this array for chained operations
      Throws:
      UnsupportedOperationException - if this object has been sealed
      ClassCastException - if the array values are not dictionaries
      See Also:
    • sort

      Sorts all values in this array according to the comparator specified.
      Parameters:
      c - the object comparator to use
      Returns:
      this array for chained operations
      Throws:
      UnsupportedOperationException - if this object has been sealed
      ClassCastException - if the array values were not comparable