Package io.github.xrickastley.sevenelements.util

Class Array<T>

java.lang.Object
io.github.xrickastley.sevenelements.util.Array<T>
All Implemented Interfaces:
Iterable<T>, Collection<T>, List<T>
public class Array<T> extends Object implements List<T>
Wraps a CopyOnWriteArrayList around the JavaScript Array API, bringing the implementation of JavaScript's array methods to Java.

  • Field Details

  • Constructor Details

    • Array

      public Array()

    • Array

      public Array(T... elements)
      Creates an Array with the specified elements.
      Parameters:
      elements - The elements of the array.

    • Array

      public Array(Iterable<T> iterable)
      Creates an Array from the specified Iterable.
      Parameters:
      iterable - The Iterable to create the array from.

    • Array

      public Array(Stream<T> stream)
      Creates an Array from the specified Stream. This consumes all the elements of the stream.
      Parameters:
      stream - The Stream to create the array from.

    • Array

      public Array(Iterator<T> iterator)
      Creates an Array from the specified Iterator. This consumes all the elements in the iterator.
      Parameters:
      iterator - The Iterator to create the array from.

    • Array

      public Array(Collection<T> collection)
      Creates an Array from the specified Collection.
      Parameters:
      collection - The Collection to create the array from.

    • Array

      public Array(Array<T> array)
      Creates an Array from another Array.

      This array will have all the elements of array, but any changes made to this array will not reflect in the original array.
      Parameters:
      array - The Array to create the array from.

  • Method Details

    • add

      public boolean add(T e)
      A CopyOnWriteArrayList method, appends the specified element to the end of this Array.
      Specified by:
      add in interface Collection<T>
      Specified by:
      add in interface List<T>

    • add

      public void add(int index, T e)
      A CopyOnWriteArrayList method, inserts the specified element at the specified position in this Array. Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).
      Specified by:
      add in interface List<T>

    • addAll

      public boolean addAll(@NotNull @NotNull Collection<? extends T> c)
      A CopyOnWriteArrayList method, appends all the elements in the specified collection to the end of this list, in the order that they are returned by the specified collection's iterator.
      Specified by:
      addAll in interface Collection<T>
      Specified by:
      addAll in interface List<T>

    • addAll

      public boolean addAll(int index, @NotNull @NotNull Collection<? extends T> c)
      A CopyOnWriteArrayList method, inserts all the elements in the specified collection into this list, starting at the specified position. Shifts the element currently at that position (if any) and any subsequent elements to the right (increases their indices). The new elements will appear in this list in the order that they are returned by the specified collection's iterator.
      Specified by:
      addAll in interface List<T>

    • set

      public T set(int index, T element)
      Specified by:
      set in interface List<T>

    • size

      public int size()
      A CopyOnWriteArrayList method and an alias for length(), returns the length (the number of elements) in this Array. This is a number one higher than the highest index in the array.
      Specified by:
      size in interface Collection<T>
      Specified by:
      size in interface List<T>
      See Also:

    • at

      public T at(int index)
      Returns the element located at the specified index.
      Parameters:
      index - The zero-based index of the desired element. A negative index will count back from the last element.

    • clear

      public void clear()
      An CopyOnWriteArrayList method, removes all the elements from this Array. The Array will be empty after this call returns.
      Specified by:
      clear in interface Collection<T>
      Specified by:
      clear in interface List<T>

    • concat

      public Array<T> concat(T... items)
      Combines two or more arrays. This returns a new Array without modifying any existing Arrays.
      Parameters:
      items - Additional items to add to the end of the array.

    • concat

      public Array<T> concat(T[]... arrays)
      Combines two or more arrays. This returns a new Array without modifying any existing Arrays.
      Parameters:
      arrays - Additional arrays with the items to add at the end of the array. These arrays are iterated over, with their inner elements being added as elements of the array.

    • contains

      public boolean contains(Object object)
      Alias for includes(java.lang.Object), returns true if this Array contains the specified element. More formally, returns true if and only if this Array contains at least one element e such that Objects.equals(o, e).
      Specified by:
      contains in interface Collection<T>
      Specified by:
      contains in interface List<T>
      Parameters:
      object - The element to search for in this Array.

    • containsAll

      public boolean containsAll(@NotNull @NotNull Collection<?> c)
      A CopyOnWriteArrayList method, returns true if this Array contains all the elements of the specified collection.
      Specified by:
      containsAll in interface Collection<T>
      Specified by:
      containsAll in interface List<T>

    • every

      public boolean every(Predicate<? super T> predicate)
      Determines whether any elements of this Array satisfy the specified predicate.
      Parameters:
      predicate - The predicate to apply to the elements of this Array.
      See Also:

    • allMatch

      public boolean allMatch(Predicate<? super T> predicate)
      Alias for every(java.util.function.Predicate<? super T>), determines whether all the members of this Array satisfy the specified predicate.
      Parameters:
      predicate - The predicate to apply to the elements of this Array.
      See Also:

    • anyMatch

      public boolean anyMatch(Predicate<T> predicate)
      Alias for some(java.util.function.Predicate<T>), determines whether at least one element of this Array satisfy the specified predicate.
      Parameters:
      predicate - The predicate to apply to the elements of this Array.
      See Also:

    • fill

      public Array<T> fill(T value)
      Changes all array elements to value and returns the modified array.
      Parameters:
      value - The value to fill this array with.

    • fill

      public Array<T> fill(T value, int start)
      Changes all array elements from start to array.length() - 1 into value and returns the modified array.
      Parameters:
      value - The value to fill this array with.
      start - The starting fill point of the array.

    • fill

      public Array<T> fill(T value, int start, int end)
      Changes all array elements from start to end into value and returns the modified array.

      Parameters:
      value - The value to fill this array with.
      start - The starting fill index point of the array. If this value is negative, it is treated as length + start
      end - The ending fill index point of the array. This element at this index is included and is also changed to value. If this value is negative, it is treated as length + end

    • filter

      public Array<T> filter(Predicate<? super T> predicate)
      Returns a new Array consisting of all the elements of this Array that satisfy the specified predicate.
      Parameters:
      predicate - The predicate to apply to the elements of this Array.

    • find

      public T find(Predicate<? super T> predicate)
      Returns the value of the first element in this Array that satisfies the given predicate, and null otherwise.
      Parameters:
      predicate - The predicate to apply in finding an element from this Array.
      See Also:

    • findAsOptional

      public Optional<T> findAsOptional(Predicate<? super T> predicate)
      Returns the value of the first element in this Array that satisfies the given predicate as an Optional.
      Parameters:
      predicate - The predicate to apply in finding an element from this Array.
      See Also:

    • findFirst

      public Optional<T> findFirst()
      A Stream method, returns an Optional describing the first element of this Array, or an empty Optional if the this Array is empty.

    • findIndex

      public int findIndex(Predicate<? super T> predicate)
      Returns the index of the first element in this Array that satisfies the given predicate, and -1 otherwise.
      Parameters:
      predicate - The predicate to apply in finding an element from this Array.
      See Also:

    • findIndexAsOptional

      public Optional<Integer> findIndexAsOptional(Predicate<? super T> predicate)
      Returns the index of the first element in this Array that satisfies the given predicate as an Optional.
      Parameters:
      predicate - The predicate to apply in finding an element from this Array.
      See Also:

    • findLast

      public T findLast(Predicate<? super T> predicate)
      Returns the value of the last element in this Array that satisfies the given predicate, and null otherwise.
      Parameters:
      predicate - The predicate to apply in finding an element from this Array.
      See Also:

    • findLastAsOptional

      public Optional<T> findLastAsOptional(Predicate<? super T> predicate)
      Returns the value of the last element in this Array that satisfies the given predicate as an Optional.
      Parameters:
      predicate - The predicate to apply in finding an element from this Array.
      See Also:

    • findLastIndex

      public int findLastIndex(Predicate<? super T> predicate)
      Returns the index of the last element in this Array that satisfies the given predicate, and -1 otherwise.
      Parameters:
      predicate - The predicate to apply in finding an element from this Array.
      See Also:

    • get

      public T get(int index)
      A CopyOnWriteArrayList method and an alias for at(int), returns the element located at the specified index.
      Specified by:
      get in interface List<T>
      See Also:

    • includes

      public boolean includes(Object object)
      Returns true if this Array contains the specified element. More formally, returns true if and only if this Array contains at least one element e such that Objects.equals(o, e).
      Parameters:
      object - The element to search for in this Array.

    • indexOf

      public int indexOf(Object object)
      Returns the index of the first occurrence of the specified element in this Array, or -1 if this Array does not contain the element. More formally, returns the lowest index i such that Objects.equals(o, get(i)), or -1 if there is no such index.
      Specified by:
      indexOf in interface List<T>
      Parameters:
      object - The value to locate in this Array.

    • iterator

      @NotNull public @NotNull Iterator<T> iterator()
      A CopyOnWriteArrayList method, returns an iterator over the elements in this list in proper sequence.

      The returned iterator provides a snapshot of the state of the list when the iterator was constructed. No synchronization is needed while traversing the iterator. The iterator does NOT support the remove method.
      Specified by:
      iterator in interface Collection<T>
      Specified by:
      iterator in interface Iterable<T>
      Specified by:
      iterator in interface List<T>

    • isEmpty

      public boolean isEmpty()
      A CopyOnWriteArrayList method, returns true if this list contains no elements.
      Specified by:
      isEmpty in interface Collection<T>
      Specified by:
      isEmpty in interface List<T>

    • join

      public String join()
      Joins all the elements of this Array into a String, separated by commas.

    • join

      public String join(String separator)
      Joins all the elements of this Array into a String, separated by the specified separator string.
      Parameters:
      separator - A string used to separate one element of the array from the next in the resulting string.

    • lastIndexOf

      public int lastIndexOf(Object object)
      Returns the index of the last occurrence of the specified element in this Array, or -1 if this Array does not contain the element. More formally, returns the highest index i such that Objects.equals(o, get(i)), or -1 if there is no such index.
      Specified by:
      lastIndexOf in interface List<T>
      Parameters:
      object - The value to locate in the array.

    • length

      public int length()
      Returns the length (the number of elements) in this Array. This is a number one higher than the highest index in the array.

    • listIterator

      @NotNull public @NotNull ListIterator<T> listIterator()
      Specified by:
      listIterator in interface List<T>

    • listIterator

      @NotNull public @NotNull ListIterator<T> listIterator(int index)
      Specified by:
      listIterator in interface List<T>

    • toArray

      public T @NotNull [] toArray()
      Specified by:
      toArray in interface Collection<T>
      Specified by:
      toArray in interface List<T>

    • toArray

      public <U> U @NotNull [] toArray(U @NotNull [] a)
      Specified by:
      toArray in interface Collection<T>
      Specified by:
      toArray in interface List<T>

    • map

      public <R> Array<R> map(Function<? super T,? extends R> mapper)
      Returns a new Array consisting of the results of applying the given function to the elements of this Array.
      Type Parameters:
      R - The element type of the new Array.
      Parameters:
      mapper - A function that takes an element and returns a value.

    • peek

      public Array<T> peek(Consumer<? super T> consumer)
      A Stream method, performs the specified action for each element in an array, then returns the Array.
      Parameters:
      consumer - The action to be performed for each element.
      See Also:

    • pop

      public T pop()
      Removes the element at the end of this Array and returns it.

      If the array is empty, null is returned and the Array is not modified.

    • push

      public int push(T... elements)
      Appends new elements to the end of this Array and returns the new length of this Array.
      Parameters:
      elements - The new elements to add to this Array.

    • reduce

      public <U> U reduce(BiFunction<U,T,U> accumulator, U initialValue)
      Performs a reduction on the elements of this Array, using the provided initialValue and accumulator function. This is equivalent to: 
      
U result = initialValue;
for (T element : this.array)
	result = accumulator.apply(result, element);
return result;
      Type Parameters:
      U - The type of the initial value, and the value reducer must return.
      Parameters:
      accumulator - A function that combines both the value and the current element.
      initialValue - The initial value for the reducer function.
      See Also:

    • reduceRight

      public <U> U reduceRight(BiFunction<U,T,U> accumulator, U initialValue)
      A right-sided version of reduce(java.util.function.BiFunction<U, T, U>, U), performs a reduction on the elements of this Array starting from the last element to the first element, using the provided initialValue and accumulator function.
      Type Parameters:
      U - The type of the initial value, and the value reducer must return.
      Parameters:
      accumulator - A function that combines both the value and the current element.
      initialValue - The initial value for the reducer function.
      See Also:

    • retainAll

      public boolean retainAll(@NotNull @NotNull Collection<?> c)
      Specified by:
      retainAll in interface Collection<T>
      Specified by:
      retainAll in interface List<T>

    • removeAll

      public boolean removeAll(@NotNull @NotNull Collection<?> c)
      Specified by:
      removeAll in interface Collection<T>
      Specified by:
      removeAll in interface List<T>

    • remove

      public boolean remove(Object o)
      A CopyOnWriteArrayList method, removes the first occurrence of the specified element from this Array, if it is present.

      Specified by:
      remove in interface Collection<T>
      Specified by:
      remove in interface List<T>

    • remove

      public T remove(int index)
      A CopyOnWriteArrayList method, removes the element at the specified position in this list and shifts any subsequent elements to the left (subtracts one from their indices).

      Specified by:
      remove in interface List<T>

    • reverse

      public Array<T> reverse()
      Reverses the order of elements of this Array. This method mutates the current Array.
      See Also:

    • shift

      public T shift()
      Removes the first element from an array and returns it.

      If the array is empty, null is returned and the array is not modified.

    • slice

      public Array<T> slice()
      Returns a copy of a section of an Array from 0 to array.length() - 1. This is returned as a new Array, meaning that any modifications made to the returned Array are not reflected in the original Array.

    • slice

      public Array<T> slice(int start)
      Returns a copy of a section of an Array from start to array.length() - 1. This is returned as a new Array, meaning that any modifications made to the returned Array are not reflected in the original Array.

      For both start and end, a negative index can be used to indicate an offset from the end of the array. For example, -2 refers to the second to last element of the array.
      Parameters:
      start - The beginning index of the specified portion of the array.

    • slice

      public Array<T> slice(int start, int end)
      Returns a copy of a section of an Array. This is returned as a new Array, meaning that any modifications made to the returned Array are not made in the original Array.

      For both start and end, a negative index can be used to indicate an offset from the end of the array. For example, -2 refers to the second to last element of the array.
      Parameters:
      start - The beginning index of the specified portion of the array.
      end - The end index of the specified portion of the array.

    • some

      public boolean some(Predicate<T> predicate)
      Determines whether at least one element of this Array satisfy the specified predicate.
      Parameters:
      predicate - The predicate to apply to the elements of this Array.
      See Also:

    • sortElements

      public Array<T> sortElements()
      A renamed implementation of Array.prototype.sort(), sorts an array's elements' string value in ascending, ASCII character order.

    • sortElements

      public Array<T> sortElements(BiFunction<T,T,Integer> compareFn)
      A renamed implementation of Array.prototype.sort(), sorts this Array in place according to the order induced by the specified BiFunction. The sort is stable: this method must not reorder equal elements.

      The resulting sort will be based on the value of compareFn(a, b).
      • If compareFn(a, b) < 0, then a > b.
      • If compareFn(a, b) = 0, then a = b.
      • If compareFn(a, b) > 0, then a < b.


      This method mutates the original Array.
      Parameters:
      compareFn - The function used to compare Array elements.

    • stream

      @NotNull public @NotNull Stream<T> stream()
      A CopyOnWriteArrayList method, returns a sequential Stream with this Array as its source.

      Specified by:
      stream in interface Collection<T>

    • subList

      @NotNull public @NotNull List<T> subList(int fromIndex, int toIndex)
      A CopyOnWriteArrayList method, returns a view of the portion of this list between fromIndex, inclusive, and toIndex, exclusive. The returned list is backed by this list, so changes in the returned list are reflected in this list.

      The semantics of the list returned by this method become undefined if the backing list (i.e., this list) is modified in any way other than via the returned list.
      Specified by:
      subList in interface List<T>

    • toReversed

      public Array<T> toReversed()
      Reverses the order of elements of this Array. Unlike reverse(), this method returns a new Array with the reversed elements.
      See Also:

    • toSorted

      public Array<T> toSorted(BiFunction<T,T,Integer> compareFn)
      Sorts this Array according to the order induced by the specified Comparator. The sort is stable: this method must not reorder equal elements. Unlike List.sort(java.util.Comparator<? super E>), this method returns a new Array with the sorted elements.
      Parameters:
      compareFn - The function used to compare Array elements.

    • normalizeIndex

      private int normalizeIndex(int index)
      Normalizes index inputs, resolving negative and positive array indexes.
      Parameters:
      index - The index to normalize.
      Returns:
      The normalized index.

    • toString

      public String toString()
      Overrides:
      toString in class Object