Package civitas.celestis.util.array

Interface SafeArray<E>

Type Parameters:
E - The type of element this array should hold
All Superinterfaces:
BaseArray<E>, Iterable<E>, Serializable
All Known Implementing Classes:
AtomicArray, FastArray, SyncArray
public interface SafeArray<E> extends BaseArray<E>
A type-safe array. Different implementations of type-safe arrays have different approaches to thread safety. Fast arrays drop all thread-safety measures in pursuit of the best possible performance, while synchronized and atomized arrays provide thread-safety at the cost of reduced performance. The implementation should be chosen according to the specific needs of the corresponding application.

Primitive types are supported by specialized array instances such as DoubleArray or FloatArray. Primitive array instances can be obtained either through factory methods such as DoubleArray.of(double...) or primitive mapper methods wuch as mapToDouble(ToDoubleFunction)} or mapToFloat(ToFloatFunction).

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    default SafeArray<E>
    append(SafeArray<? extends E> a)
    Append the provided array a to the end of this array, then returns the resulting array.
    E[]
    array()
    Returns a primitive array containing the elements of this array in their proper order.
    static <E> AtomicArray<E>
    atomicCopyOf(SafeArray<? extends E> a)
    Creates a new atomic copy of the provided array a.
    static <E> SafeArray<E>
    atomicOf(E... elements)
    Creates a new atomic array from the provided array of elements.
    boolean
    contains(Object obj)
    Returns whether this array contains the provided object obj.
    boolean
    containsAll(Iterable<?> i)
    Returns whether this array contains multiple objects.
    static <E> SafeArray<E>
    copyOf(SafeArray<? extends E> a)
    Creates a new thread-unsafe copy of the provided array a.
    boolean
    equals(Object obj)
    Checks for equality between this array and the provided object obj.
    void
    fill(E v)
    Fills this array with the provided value v.
    void
    fillEmpty(E v)
    Fills every empty slot of this array with the provided value v.
    void
    fillRange(int s, int e, E v)
    Fills every slot of this array between the range of [s, e) with the provided value v.
    default SafeArray<E>
    filter(Predicate<? super E> f)
    Tests each element of this array using the provided predicate f, collects all elements the predicate returns true to, then returns a new array containing only the filtered elements.
    void
    forEach(BiConsumer<? super Integer,? super E> a)
    Executes the provided action a once for each element of this array.
    void
    forEach(Consumer<? super E> a)
    Executes the provided action a once for each element of this array.
    static <E> SafeArray<E>
    from(Stream<E> s)
    Creates a new type-safe array from a stream of values.
    E
    get(int i)
    Returns the ith element of this array.
    E
    getOrDefault(int i, E e)
    Returns the ith element of this array, but returns the provided fallback value e instead of the value at the specified index is null.
    Iterator<E>
    iterator()
    Returns an iterator over every element of this array.
    int
    length()
    Returns the length of this array.
    List<E>
    list()
    Returns an unmodifiable list containing the elements of this array in their proper order.
    <F> SafeArray<F>
    map(Function<? super E,? extends F> f)
    Applies the provided mapper function f to each element of this array, then returns a new array containing the return values of the function f.
    DoubleArray
    mapToDouble(ToDoubleFunction<? super E> f)
    Applies the provided mapper function f to each element of this array, then returns a new double array containing the return values of the function f.
    FloatArray
    mapToFloat(ToFloatFunction<? super E> f)
    Applies the provided mapper function f to each element of this array, then returns a new float array containing the return values of the function f.
    IntArray
    mapToInt(ToIntFunction<? super E> f)
    Applies the provided mapper function f to each element of this array, then returns a new integer array containing the return values of the function f.
    LongArray
    mapToLong(ToLongFunction<? super E> f)
    Applies the provided mapper function f to each element of this array, then returns a new long array containing the return values of the function f.
    <F, G> SafeArray<G>
    merge(SafeArray<F> a, BiFunction<? super E,? super F,? extends G> f)
    Between this array and the provided array a, this applies the merger function f to each corresponding pair of elements, then returns a new array containing the return values of the merger function f.
    static <E> SafeArray<E>
    of(E... elements)
    Creates a new type-safe array from the provided array of elements.
    default SafeArray<E>
    prepend(SafeArray<? extends E> a)
    Prepends the provided array a to the front of this array, then returns the resulting array.
    static <E> SafeArray<E>
    referenceOf(SafeArray<E> a)
    Creates a new reference to the provided array a.
    static <E> SafeArray<E>
    referenceOf(E[] elements)
    Creates a new type-safe reference array from the provided array of elements.
    void
    replaceAll(E oldValue, E newValue)
    Replaces all instances of the old value to the new value.
    void
    replaceFirst(E oldValue, E newValue)
    Replaces only the first instance of the old value to the new value.
    void
    replaceLast(E oldValue, E newValue)
    Replaces only the last instance of the old value to the new value.
    SafeArray<E>
    resize(int size)
    Returns a resized array whose elements are mapped from that of this array's elements.
    void
    set(int i, E e)
    Sets the ith element of this array.
    void
    setRange(int s, int e, SafeArray<? extends E> a)
    Sets a sub-array of this array to the values of the provided sub-array a.
    void
    shuffle()
    Shuffles this array, randomizing its elements' order.
    void
    sort()
    Sorts this array by its natural ascending order.
    void
    sort(Comparator<? super E> c)
    Sorts this array using the provided comparator function c.
    Stream<E>
    stream()
    Returns a stream whose source is the elements of this array.
    SafeArray<E>
    subArray(int s, int e)
    Returns a sub-array of this array which represents a portion of this array between the range of [s, e).
    static <E> SafeArray<E>
    syncCopyOf(SafeArray<? extends E> a)
    Creates a new thread-safe copy of the provided array a.
    static <E> SafeArray<E>
    syncOf(E... elements)
    Creates a new synchronized array from the provided array of elements.
    String
    toString()
    Serializes this array into a string.
    Tuple<E>
    tuple()
    Returns a tuple containing the elements of this array in their proper order.
    void
    update(int i, UnaryOperator<E> f)
    Updates the ith element of this array with the provided update function f.
    void
    update(BiFunction<? super Integer,? super E,E> f)
    Applies the provided update function f to each element of this array, then assigns the return value of the function to the corresponding index of this array.
    void
    update(UnaryOperator<E> f)
    Applies the provided update function f to each element of this array, then assigns the return value of the function to the corresponding index of this array.

    Methods inherited from interface java.lang.Iterable

    spliterator

  • Method Details

    • of

      @Nonnull @SafeVarargs static <E> SafeArray<E> of(@Nonnull E... elements)
      Creates a new type-safe array from the provided array of elements.
      Type Parameters:
      E - The type of element to contain in the array
      Parameters:
      elements - The elements to contain in the array
      Returns:
      A new type-safe array containing the provided elements

    • syncOf

      @Nonnull @SafeVarargs static <E> SafeArray<E> syncOf(@Nonnull E... elements)
      Creates a new synchronized array from the provided array of elements.
      Type Parameters:
      E - The type of element to contain in the array
      Parameters:
      elements - The elements to contain in the array
      Returns:
      A new thread-safe array containing the provided elements

    • atomicOf

      @Nonnull @SafeVarargs static <E> SafeArray<E> atomicOf(@Nonnull E... elements)
      Creates a new atomic array from the provided array of elements.
      Type Parameters:
      E - The type of element to contain in the array
      Parameters:
      elements - The elements to contain in the array
      Returns:
      A new thread-safe array containing the provided elements

    • referenceOf

      @Nonnull static <E> SafeArray<E> referenceOf(@Nonnull E[] elements)
      Creates a new type-safe reference array from the provided array of elements. Changes in the type-safe array will be reflected to the original array, as well as from the original array to the type-safe array.
      Type Parameters:
      E - The type of element to reference
      Parameters:
      elements - The elements the array should reference
      Returns:
      A new type-safe reference array referencing the provided elements

    • copyOf

      @Nonnull static <E> SafeArray<E> copyOf(@Nonnull SafeArray<? extends E> a)
      Creates a new thread-unsafe copy of the provided array a.
      Type Parameters:
      E - The type of element to copy
      Parameters:
      a - The array of which to copy value from
      Returns:
      A new thread-unsafe copy of the provided array a

    • syncCopyOf

      @Nonnull static <E> SafeArray<E> syncCopyOf(@Nonnull SafeArray<? extends E> a)
      Creates a new thread-safe copy of the provided array a.
      Type Parameters:
      E - The type of element to copy
      Parameters:
      a - The array of which to copy value from
      Returns:
      A new thread-safe copy of the provided array a

    • atomicCopyOf

      @Nonnull static <E> AtomicArray<E> atomicCopyOf(@Nonnull SafeArray<? extends E> a)
      Creates a new atomic copy of the provided array a.
      Type Parameters:
      E - The type of element to copy
      Parameters:
      a - The array of which to copy value from
      Returns:
      A new atomic copy of the provided array a

    • referenceOf

      @Nonnull static <E> SafeArray<E> referenceOf(@Nonnull SafeArray<E> a)
      Creates a new reference to the provided array a. Changes will be reflected between the two arrays.
      Type Parameters:
      E - The type of element to reference
      Parameters:
      a - The array of which to reference values from
      Returns:
      A new type-safe reference array referencing the provided array a

    • from

      @Nonnull static <E> SafeArray<E> from(@Nonnull Stream<E> s)
      Creates a new type-safe array from a stream of values.
      Type Parameters:
      E - The type of element to contain
      Parameters:
      s - The stream of which to use as the source of the array
      Returns:
      A new type-safe array containing the stream's values

    • length

      int length()
      Returns the length of this array.
      Specified by:
      length in interface BaseArray<E>
      Returns:
      The number of elements this array contains

    • contains

      boolean contains(@Nullable Object obj)
      Returns whether this array contains the provided object obj.
      Parameters:
      obj - The object of which to check for containment
      Returns:
      true if at least one element of this array is equal to the provided object obj

    • containsAll

      boolean containsAll(@Nonnull Iterable<?> i)
      Returns whether this array contains multiple objects.
      Parameters:
      i - The iterable object of which to check for containment
      Returns:
      true if this array contains every element of the iterable object

    • get

      E get(int i) throws IndexOutOfBoundsException
      Returns the ith element of this array.
      Parameters:
      i - The index of the element to get
      Returns:
      The ith element of this array
      Throws:
      IndexOutOfBoundsException - When the index i is out of bounds

    • getOrDefault

      E getOrDefault(int i, E e) throws IndexOutOfBoundsException
      Returns the ith element of this array, but returns the provided fallback value e instead of the value at the specified index is null.
      Parameters:
      i - The index of the element to get
      e - The fallback value to default to when the value is null
      Returns:
      The ith element of this array if present, the fallback value e otherwise
      Throws:
      IndexOutOfBoundsException - When the index i is out of bounds

    • set

      void set(int i, E e) throws IndexOutOfBoundsException
      Sets the ith element of this array.
      Parameters:
      i - The index of the element to set
      e - The element of which to set to
      Throws:
      IndexOutOfBoundsException - When the index i is out of bounds

    • update

      void update(int i, @Nonnull UnaryOperator<E> f) throws IndexOutOfBoundsException
      Updates the ith element of this array with the provided update function f.
      Parameters:
      i - The index of the element to update
      f - The update function of which to apply to the element
      Throws:
      IndexOutOfBoundsException - When the index i is out of bounds

    • fill

      void fill(E v)
      Fills this array with the provided value v. Every element will be reassigned.
      Parameters:
      v - The value to fill this array with

    • fillEmpty

      void fillEmpty(E v)
      Fills every empty slot of this array with the provided value v. All occurrences of null will be replaced with the provided value.
      Parameters:
      v - The value to fill empty slots of this array with

    • fillRange

      void fillRange(int s, int e, E v)
      Fills every slot of this array between the range of [s, e) with the provided value v.
      Parameters:
      s - The starting index at which to start assigning values from
      e - The ending index at which to stop assigning values at
      v - The value of which to assign to every slot within the specified range
      Throws:
      IndexOutOfBoundsException - When the indices are out of bounds

    • update

      void update(@Nonnull UnaryOperator<E> f)
      Applies the provided update function f to each element of this array, then assigns the return value of the function to the corresponding index of this array.
      Parameters:
      f - The function of which to apply to each element of this array

    • update

      void update(@Nonnull BiFunction<? super Integer,? super E,E> f)
      Applies the provided update function f to each element of this array, then assigns the return value of the function to the corresponding index of this array. The first parameter is the index of the value which was provided.
      Parameters:
      f - The function of which to apply to each element of this array

    • replaceAll

      void replaceAll(E oldValue, E newValue)
      Replaces all instances of the old value to the new value.
      Parameters:
      oldValue - The old value to replace
      newValue - The new value to replace to

    • replaceFirst

      void replaceFirst(E oldValue, E newValue)
      Replaces only the first instance of the old value to the new value. (starting from index 0, and incrementing upwards)
      Parameters:
      oldValue - The old value to replace
      newValue - The new value to replace to

    • replaceLast

      void replaceLast(E oldValue, E newValue)
      Replaces only the last instance of the old value to the new value. (starting from the last index, and decrementing downwards)
      Parameters:
      oldValue - The old value to replace
      newValue - The new value to replace to

    • subArray

      @Nonnull SafeArray<E> subArray(int s, int e) throws IndexOutOfBoundsException
      Returns a sub-array of this array which represents a portion of this array between the range of [s, e). Changes in the sub-array will be reflected to this array. For example, calling a.subArray(1, 3).fill(null); will have the same effect as setting the values of indices 1, 2 of the original array to null.
      Parameters:
      s - The starting index at which to start creating the sub-array (inclusive)
      e - The ending index at which to stop creating the sub-array (exclusive)
      Returns:
      The sub-array representing the index range of [s, e)
      Throws:
      IndexOutOfBoundsException - When the range is invalid, or is out of bounds

    • setRange

      void setRange(int s, int e, @Nonnull SafeArray<? extends E> a) throws IndexOutOfBoundsException
      Sets a sub-array of this array to the values of the provided sub-array a.
      Parameters:
      s - The starting index at which to start copying values from (inclusive)
      e - The ending index at which to stop copying values from (exclusive)
      a - The sub-array containing the values to assign to this array
      Throws:
      IndexOutOfBoundsException - When the range is invalid, or is out of bounds

    • resize

      @Nonnull SafeArray<E> resize(int size)
      Returns a resized array whose elements are mapped from that of this array's elements. If the new array is larger than this array, the unmappable part will not be populated, leaving it uninitialized as null.
      Parameters:
      size - The size to resize this array to
      Returns:
      The resized array

    • shuffle

      void shuffle()
      Shuffles this array, randomizing its elements' order.
      Specified by:
      shuffle in interface BaseArray<E>

    • sort

      void sort() throws UnsupportedOperationException
      Sorts this array by its natural ascending order. This operation will only succeed if the element E is an instance of Comparable.
      Specified by:
      sort in interface BaseArray<E>
      Throws:
      UnsupportedOperationException - When at least one element cannot be cast to Comparable

    • sort

      void sort(@Nonnull Comparator<? super E> c)
      Sorts this array using the provided comparator function c.
      Specified by:
      sort in interface BaseArray<E>
      Parameters:
      c - The comparator function of which to sort this array with

    • filter

      @Nonnull default SafeArray<E> filter(@Nonnull Predicate<? super E> f)
      Tests each element of this array using the provided predicate f, collects all elements the predicate returns true to, then returns a new array containing only the filtered elements.
      Parameters:
      f - The predicate to use to filter this array
      Returns:
      The filtered array

    • map

      @Nonnull <F> SafeArray<F> map(@Nonnull Function<? super E,? extends F> f)
      Applies the provided mapper function f to each element of this array, then returns a new array containing the return values of the function f.
      Type Parameters:
      F - The type of element to map this array to
      Parameters:
      f - The function of which to apply to each element of this array
      Returns:
      The resulting array

    • mapToDouble

      @Nonnull DoubleArray mapToDouble(@Nonnull ToDoubleFunction<? super E> f)
      Applies the provided mapper function f to each element of this array, then returns a new double array containing the return values of the function f.
      Parameters:
      f - The function of which to apply to each element of this array
      Returns:
      The resulting array
      See Also:

    • mapToFloat

      @Nonnull FloatArray mapToFloat(@Nonnull ToFloatFunction<? super E> f)
      Applies the provided mapper function f to each element of this array, then returns a new float array containing the return values of the function f.
      Parameters:
      f - The function of which to apply to each element of this array
      Returns:
      The resulting array
      See Also:

    • mapToLong

      @Nonnull LongArray mapToLong(@Nonnull ToLongFunction<? super E> f)
      Applies the provided mapper function f to each element of this array, then returns a new long array containing the return values of the function f.
      Parameters:
      f - The function of which to apply to each element of this array
      Returns:
      The resulting array
      See Also:

    • mapToInt

      @Nonnull IntArray mapToInt(@Nonnull ToIntFunction<? super E> f)
      Applies the provided mapper function f to each element of this array, then returns a new integer array containing the return values of the function f.
      Parameters:
      f - The function of which to apply to each element of this array
      Returns:
      The resulting array
      See Also:

    • merge

      @Nonnull <F, G> SafeArray<G> merge(@Nonnull SafeArray<F> a, @Nonnull BiFunction<? super E,? super F,? extends G> f) throws IllegalArgumentException
      Between this array and the provided array a, this applies the merger function f to each corresponding pair of elements, then returns a new array containing the return values of the merger function f. In other words, this merges the two arrays into a new array using the provided merger function f.
      Type Parameters:
      F - The type of element to merge this array with
      G - The type of element to merge the two arrays to
      Parameters:
      a - The array of which to merge this array with
      f - The merger function to handle the merging of the two arrays
      Returns:
      The resulting array
      Throws:
      IllegalArgumentException - When the provided array a's length is different from that of this array's length

    • append

      @Nonnull default SafeArray<E> append(@Nonnull SafeArray<? extends E> a)
      Append the provided array a to the end of this array, then returns the resulting array.
      Parameters:
      a - The array of which to append to the end of this array
      Returns:
      The appended array

    • prepend

      @Nonnull default SafeArray<E> prepend(@Nonnull SafeArray<? extends E> a)
      Prepends the provided array a to the front of this array, then returns the resulting array.
      Parameters:
      a - The array of which to prepend to the front of this array
      Returns:
      The prepended array

    • iterator

      @Nonnull Iterator<E> iterator()
      Returns an iterator over every element of this array.
      Specified by:
      iterator in interface BaseArray<E>
      Specified by:
      iterator in interface Iterable<E>
      Returns:
      An iterator over every element of this array

    • forEach

      void forEach(@Nonnull Consumer<? super E> a)
      Executes the provided action a once for each element of this array. A reference to the element is provided as the first parameter of the action.
      Specified by:
      forEach in interface BaseArray<E>
      Specified by:
      forEach in interface Iterable<E>
      Parameters:
      a - The action to be performed for each element

    • forEach

      void forEach(@Nonnull BiConsumer<? super Integer,? super E> a)
      Executes the provided action a once for each element of this array. The index of the element is provided as the first parameter of the action, and a reference to the element is provided as the second parameter of the action.
      Specified by:
      forEach in interface BaseArray<E>
      Parameters:
      a - The action to be performed for each element

    • array

      @Nonnull E[] array()
      Returns a primitive array containing the elements of this array in their proper order.
      Returns:
      The primitive array representation of this array

    • stream

      @Nonnull Stream<E> stream()
      Returns a stream whose source is the elements of this array.
      Returns:
      A stream whose source is the elements of this array
      See Also:

    • list

      @Nonnull List<E> list()
      Returns an unmodifiable list containing the elements of this array in their proper order.
      Specified by:
      list in interface BaseArray<E>
      Returns:
      The list representation of this array
      Throws:
      NullPointerException - When this array contains at least one instance of null
      See Also:

    • tuple

      @Nonnull Tuple<E> tuple()
      Returns a tuple containing the elements of this array in their proper order. Unlike list(), this operation cannot fail as tuples inherently support the usage of null as their values.
      Returns:
      The tuple representation of this array
      See Also:

    • equals

      boolean equals(@Nullable Object obj)
      Checks for equality between this array and the provided object obj.
      Overrides:
      equals in class Object
      Parameters:
      obj - The object to compare to
      Returns:
      true if the object is also a type-safe array, and the number of elements, the order of the elements, and the elements' values are all equal

    • toString

      @Nonnull String toString()
      Serializes this array into a string.
      Overrides:
      toString in class Object
      Returns:
      The string representation of this array