Package org.rapidcontext.core.data
Class Array
java.lang.Object
org.rapidcontext.core.data.Array
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.
- Version:
- 1.0
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionAdds 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.complement
(Array arr) Returns the relative complement of this array and another array.boolean
containsAll
(Array arr) Checks if all of the values in the specified array is contained in this array.boolean
containsAny
(Array arr) 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
containsValue
(Object value) Checks if the specified value is contained in this array.copy()
Creates a copy of this array.boolean
Checks if this array is identical to another one.static Array
Creates a new array containing all elements in an iterable.static Array
Creates a new array containing all elements in an iterator.static Array
Creates a new array containing all elements in a stream.get
(int index) Returns the array value at the specified index.<T> T
Returns the array value at the specified index.<T> T
Returns the array value at the specified index.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.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.Deprecated, for removal: This API element is subject to removal in a future version.Use get(index, String.class, defaultValue) instead.int
hashCode()
Returns a hash code for this object.int
Returns the first array index having the specified value.intersection
(Array arr) Returns the intersection of this array and another array.boolean
isSealed()
Checks if this array is sealed.iterator()
Returns an iterator for all elements in the array.static Array
Creates a new array from an array of elements.remove
(int index) Deletes the specified array index and its value.Deletes the first array index having the specified value.void
seal
(boolean recursive) Seals this array and prohibits any further modifications.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
size()
Returns the size of the array, i.e.sort()
Sorts all values in this array according to their natural ordering.Sorts all values in this array according to the natural ordering of the specified dictionary key.sort
(Comparator<Object> c) Sorts all values in this array according to the comparator specified.stream()
Returns a stream of all elements in the array.<T> Stream
<T> Returns a stream of all elements in the array.toString()
Returns a string representation of this object.Returns the union of this array and another array.Object[]
values()
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
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
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
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
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
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. -
hashCode
public int hashCode()Returns a hash code for this object. -
toString
Returns a string representation of this object. -
iterator
Returns an iterator for all elements in the array. -
stream
Returns a stream of all elements in the array.- Returns:
- the object stream
-
stream
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 classNumberFormatException
- if the value wasn't possible to parse as a number- See Also:
-
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
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
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
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
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
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
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
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 indexclazz
- 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 classNumberFormatException
- if the value wasn't possible to parse as a number- See Also:
-
get
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 indexdefaultValue
- the default value- Returns:
- the array element value, or the default value if the index or value is not defined
-
get
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 indexclazz
- the object classdefaultValue
- 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 classNumberFormatException
- if the value wasn't possible to parse as a number- See Also:
-
getString
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 indexdefaultValue
- the default value- Returns:
- the array element value, or the default value if the index or value is not defined
-
getBoolean
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 indexdefaultValue
- the default value- Returns:
- the array element value, or the default value if the index or value is not defined
-
getInt
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 indexdefaultValue
- 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, 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 indexdefaultValue
- 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
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
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 indexvalue
- the array value- Returns:
- this array for chained operations
- Throws:
IndexOutOfBoundsException
- if index is negativeUnsupportedOperationException
- 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 indexvalue
- the array value- Returns:
- this array for chained operations
- Throws:
IndexOutOfBoundsException
- if index is negativeUnsupportedOperationException
- 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 indexvalue
- the array value- Returns:
- this array for chained operations
- Throws:
IndexOutOfBoundsException
- if index is negativeUnsupportedOperationException
- if this object has been sealed
-
add
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, 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
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
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
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
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
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
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 sealedClassCastException
- 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 sealedClassCastException
- 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 sealedClassCastException
- if the array values were not comparable
-