Package civitas.celestis.util.grid

Interface Grid<E>

Type Parameters:
E - The type of element this grid should hold
All Superinterfaces:
BaseGrid<E>, Iterable<E>, Serializable
All Known Subinterfaces:
DynamicGrid<E>
All Known Implementing Classes:
ArrayGrid, AtomicGrid, HashGrid, SyncGrid
public interface Grid<E> extends BaseGrid<E>
A two-dimensional structure of elements. Grids can be traversed by providing two indices: one for the row, and one for the column.

Static grids which use two-dimensional arrays as their underlying data structure are fixed-size, meaning the dimensions cannot be changed without re-instantiation.

On the other hand, dynamic grids use a more flexible underlying data structure, allowing the resizing of the grid without re-instantiation. Note that dynamic grids have more overhead in terms of memory consumption, and primitive types are not supported. (the boxed object types such as Doubles are used)

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    E[]
    array()
    Returns an array containing every element within this grid.
    static <E> Grid<E>
    atomicCopyOf(Grid<? extends E> g)
    Creates an atomic copy of an existing grid.
    static <E> Grid<E>
    atomicOf(E[][] values)
    Creates a new atomic grid form a two-dimensional array of values.
    Collection<E>
    collect()
    Returns a collection containing every element within this grid.
    int
    columns()
    Returns the number of columns (the width) of this grid.
    boolean
    contains(Object obj)
    Checks if this grid contains the provided object obj.
    boolean
    containsAll(Iterable<?> i)
    Checks if this grid contains multiple objects.
    static <E> Grid<E>
    copyOf(Grid<? extends E> g)
    Creates a copy of an existing grid.
    static <E> Grid<E>
    dynamicCopyOf(Grid<? extends E> g)
    Creates a dynamic copy of an existing grid.
    static <E> Grid<E>
    dynamicOf(E[][] values)
    Creates a new dynamic grid from a two-dimensional array of values.
    boolean
    equals(Object obj)
    Checks for equality between this grid and the provided object obj.
    void
    fill(E v)
    Fills this grid, populating every index with the provided value v.
    void
    fillEmpty(E v)
    Fills this grid, but only does so if the original element currently occupying the corresponding slot is null.
    void
    fillRange(int r1, int c1, int r2, int c2, E v)
    Fills this grid, but only does so within the specified range.
    void
    forEach(TriConsumer<Integer,Integer,? super E> a)
    Executes the provided action for each element of this grid.
    void
    forEach(Consumer<? super E> a)
    Executes the provided action for each element of this grid.
    E
    get(int r, int c)
    Returns the element at the specified index.
    E
    getOrDefault(int r, int c, E fallback)
    Returns the element at the specified index, but returns the fallback value if the existing element is null.
    Iterator<E>
    iterator()
    Returns an iterator of every element of this grid.
    <F> Grid<F>
    map(Function<? super E,? extends F> f)
    Applies the provided mapper function f to every element of this grid, then returns a new grid whose values are populated from that of the provided function's return values.
    DoubleGrid
    mapToDouble(ToDoubleFunction<? super E> f)
    Applies the provided mapper function f to every element of this grid, then returns a new double grid whose values are populated from that of the provided function's return values.
    FloatGrid
    mapToFloat(ToFloatFunction<? super E> f)
    Applies the provided mapper function f to every element of this grid, then returns a new float grid whose values are populated from that of the provided function's return values.
    IntGrid
    mapToInt(ToIntFunction<? super E> f)
    Applies the provided mapper function f to every element of this grid, then returns a new integer grid whose values are populated from that of the provided function's return values.
    LongGrid
    mapToLong(ToLongFunction<? super E> f)
    Applies the provided mapper function f to every element of this grid, then returns a new long grid whose values are populated from that of the provided function's return values.
    <F, G> Grid<G>
    merge(Grid<F> g, BiFunction<? super E,? super F,G> f)
    Between this grid and the provided grid g, this applies the merger function f for each corresponding pair of elements, then returns a new grid whose elements are populated from that of the return values of the merger function f.
    static <E> Grid<E>
    of(E[][] values)
    Creates a new grid from a two-dimensional array of values.
    void
    replaceAll(E oldValue, E newValue)
    Replaces all instances of the old value with the new value within this grid.
    Grid<E>
    resize(int rows, int columns)
    Returns a resized grid, whose elements are populated from that of this grid's elements.
    int
    rows()
    Returns the number of rows (the height) of this grid.
    Set<E>
    set()
    Returns a set containing every element of this grid.
    void
    set(int r, int c, E v)
    Sets the value of the specified index.
    void
    setRange(int r1, int c1, int r2, int c2, Grid<? extends E> g)
    Sets a sub-grid of this grid, copying values from the provided sub-grid g.
    int
    size()
    Returns the size (the geometric area) of this grid.
    Stream<E>
    stream()
    Returns a stream whose source is the elements of this grid.
    Grid<E>
    subGrid(int r1, int c1, int r2, int c2)
    Returns a sub-grid of this grid, whose values are populated from that of this grid's elements within the specified range.
    static <E> Grid<E>
    syncCopyOf(Grid<? extends E> g)
    Creates a thread-safe copy of an existing grid.
    static <E> Grid<E>
    syncOf(E[][] values)
    Creates a new thread-safe grid from a two-dimensional array of values.
    String
    toString()
    Serializes this grid into a string.
    Grid<E>
    transpose()
    Returns the transpose of this grid.
    void
    update(TriFunction<? super Integer,? super Integer,? super E,E> f)
    Applies the provided update function f to every element of this grid, assigning the return value of the function to the corresponding index of this grid.
    void
    update(Function<? super E,E> f)
    Applies the provided update function f to every element of this grid, assigning the return value of the function to the corresponding index of this grid.

    Methods inherited from interface java.lang.Iterable

    spliterator

  • Method Details

    • of

      @Nonnull static <E> Grid<E> of(@Nonnull E[][] values)
      Creates a new grid from a two-dimensional array of values.
      Type Parameters:
      E - The type of element to contain
      Parameters:
      values - The values of which to contain in the grid
      Returns:
      The constructed grid instance

    • dynamicOf

      @Nonnull static <E> Grid<E> dynamicOf(@Nonnull E[][] values)
      Creates a new dynamic grid from a two-dimensional array of values.
      Type Parameters:
      E - The type of element to contain
      Parameters:
      values - The values of which to contain in the grid
      Returns:
      The constructed dynamic grid instance
      See Also:

    • syncOf

      @Nonnull static <E> Grid<E> syncOf(@Nonnull E[][] values)
      Creates a new thread-safe grid from a two-dimensional array of values.
      Type Parameters:
      E - The type of element to contain
      Parameters:
      values - The values of which to contain in the grid
      Returns:
      The constructed thread-safe grid instance
      See Also:

    • atomicOf

      @Nonnull static <E> Grid<E> atomicOf(@Nonnull E[][] values)
      Creates a new atomic grid form a two-dimensional array of values.
      Type Parameters:
      E - The type of element to contain
      Parameters:
      values - The values of which to contain in the grid
      Returns:
      The constructed atomic grid instance
      See Also:

    • copyOf

      @Nonnull static <E> Grid<E> copyOf(@Nonnull Grid<? extends E> g)
      Creates a copy of an existing grid.
      Type Parameters:
      E - The type of element to contain
      Parameters:
      g - The grid of which to copy elements from
      Returns:
      A shallow copy of the provided grid g

    • dynamicCopyOf

      @Nonnull static <E> Grid<E> dynamicCopyOf(@Nonnull Grid<? extends E> g)
      Creates a dynamic copy of an existing grid.
      Type Parameters:
      E - The type of element to contain
      Parameters:
      g - The grid of which to copy elements from
      Returns:
      A dynamic shallow copy of the provided grid g
      See Also:

    • syncCopyOf

      @Nonnull static <E> Grid<E> syncCopyOf(@Nonnull Grid<? extends E> g)
      Creates a thread-safe copy of an existing grid.
      Type Parameters:
      E - The type of element to contain
      Parameters:
      g - The grid of which to copy elements from
      Returns:
      A thread-safe shallow copy of the provided grid g
      See Also:

    • atomicCopyOf

      @Nonnull static <E> Grid<E> atomicCopyOf(@Nonnull Grid<? extends E> g)
      Creates an atomic copy of an existing grid.
      Type Parameters:
      E - The type of element to contain
      Parameters:
      g - The grid of which to copy elements from
      Returns:
      An atomic shallow copy of the provided grid g
      See Also:

    • rows

      int rows()
      Returns the number of rows (the height) of this grid.
      Specified by:
      rows in interface BaseGrid<E>
      Returns:
      The number of rows this grid has

    • columns

      int columns()
      Returns the number of columns (the width) of this grid.
      Specified by:
      columns in interface BaseGrid<E>
      Returns:
      The number of columns this grid has

    • size

      int size()
      Returns the size (the geometric area) of this grid. In other words, this return the maximum capacity of this grid.
      Specified by:
      size in interface BaseGrid<E>
      Returns:
      The number of element this gird can potentially hold

    • contains

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

    • containsAll

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

    • get

      E get(int r, int c) throws IndexOutOfBoundsException
      Returns the element at the specified index.
      Parameters:
      r - The index of the row to get
      c - The index of the column to get
      Returns:
      The element at the specified index
      Throws:
      IndexOutOfBoundsException - When the indices are out of bounds

    • getOrDefault

      E getOrDefault(int r, int c, E fallback) throws IndexOutOfBoundsException
      Returns the element at the specified index, but returns the fallback value if the existing element is null.
      Parameters:
      r - The index of the row to get
      c - The index of the column to get
      fallback - The fallback value of which to return if the element is null
      Returns:
      The element at the specified index, or the fallback value if the existing element is equal to null
      Throws:
      IndexOutOfBoundsException - When the indices are out of bounds

    • set

      void set(int r, int c, E v) throws IndexOutOfBoundsException
      Sets the value of the specified index.
      Parameters:
      r - The index of the row to set
      c - The index of the column to set
      v - The value of which to assign to the specified index
      Throws:
      IndexOutOfBoundsException - When the indices are out of bounds

    • fill

      void fill(E v)
      Fills this grid, populating every index with the provided value v.
      Parameters:
      v - The value of which to fill this grid with

    • fillEmpty

      void fillEmpty(E v)
      Fills this grid, but only does so if the original element currently occupying the corresponding slot is null.
      Parameters:
      v - The values of which to selectively fill this grid with

    • fillRange

      void fillRange(int r1, int c1, int r2, int c2, E v) throws IndexOutOfBoundsException
      Fills this grid, but only does so within the specified range.
      Parameters:
      r1 - The starting position's row index
      c1 - The starting position's column index
      r2 - The ending position's row index
      c2 - The ending position's column index
      v - The value of which to fill the specified range with
      Throws:
      IndexOutOfBoundsException - When the range is out of bounds

    • update

      void update(@Nonnull Function<? super E,E> f)
      Applies the provided update function f to every element of this grid, assigning the return value of the function to the corresponding index of this grid.
      Parameters:
      f - The function of which to apply to each element of this grid

    • update

      void update(@Nonnull TriFunction<? super Integer,? super Integer,? super E,E> f)
      Applies the provided update function f to every element of this grid, assigning the return value of the function to the corresponding index of this grid. The row and column indices are provided as the first and second parameter of the function respectively, and the original element is provided as the third parameter of ths function.
      Parameters:
      f - The function of which to apply to each element of this grid

    • replaceAll

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

    • subGrid

      @Nonnull Grid<E> subGrid(int r1, int c1, int r2, int c2) throws IndexOutOfBoundsException
      Returns a sub-grid of this grid, whose values are populated from that of this grid's elements within the specified range. This is not a direct reference to this grid, and changes in the sub-grid will not be reflected to the original grid.
      Parameters:
      r1 - The starting position's row index
      c1 - The starting position's column index
      r2 - The ending position's row index
      c2 - The ending position's column index
      Returns:
      The sub-grid of this grid corresponding to the specified range
      Throws:
      IndexOutOfBoundsException - When the range is out of bounds

    • setRange

      void setRange(int r1, int c1, int r2, int c2, @Nonnull Grid<? extends E> g) throws IndexOutOfBoundsException
      Sets a sub-grid of this grid, copying values from the provided sub-grid g. This is not a direct reference to this grid, and changes in the sub-grid will not be reflected to the original grid.
      Parameters:
      r1 - The starting position's row index
      c1 - The starting position's column index
      r2 - The ending position's row index
      c2 - The ending position's column index
      g - The sub-grid of this grid containing the values to assign
      Throws:
      IndexOutOfBoundsException - When the range is out of bounds

    • resize

      @Nonnull Grid<E> resize(int rows, int columns)
      Returns a resized grid, whose elements are populated from that of this grid's elements. If the requested size is larger than that of this grid's size, the oversized portion will not be populated, leaving it uninitialized as null.
      Parameters:
      rows - The number of rows the resized grid should have
      columns - The number of columns the resized grid should have
      Returns:
      A new grid with the specified dimensions

    • transpose

      @Nonnull Grid<E> transpose()
      Returns the transpose of this grid. The transpose is a grid whose rows and columns are inverted from that os this grid's rows and columns. The elements are mapped according to the function f({r, c}) -> {c, r}, where r represents the row index, and c represents the column index. In simple terms, the rows and columns are inverted.
      Returns:
      The transpose of this grid

    • map

      @Nonnull <F> Grid<F> map(@Nonnull Function<? super E,? extends F> f)
      Applies the provided mapper function f to every element of this grid, then returns a new grid whose values are populated from that of the provided function's return values.
      Type Parameters:
      F - The type of element to map this grid to
      Parameters:
      f - The function of which to apply to each element of this grid
      Returns:
      The resulting grid

    • mapToDouble

      @Nonnull DoubleGrid mapToDouble(@Nonnull ToDoubleFunction<? super E> f)
      Applies the provided mapper function f to every element of this grid, then returns a new double grid whose values are populated from that of the provided function's return values.
      Parameters:
      f - The function of which to apply to each element of this grid
      Returns:
      The resulting double grid

    • mapToFloat

      @Nonnull FloatGrid mapToFloat(@Nonnull ToFloatFunction<? super E> f)
      Applies the provided mapper function f to every element of this grid, then returns a new float grid whose values are populated from that of the provided function's return values.
      Parameters:
      f - The function of which to apply to each element of this grid
      Returns:
      The resulting float grid

    • mapToLong

      @Nonnull LongGrid mapToLong(@Nonnull ToLongFunction<? super E> f)
      Applies the provided mapper function f to every element of this grid, then returns a new long grid whose values are populated from that of the provided function's return values.
      Parameters:
      f - The function of which to apply to each element of this grid
      Returns:
      The resulting long grid

    • mapToInt

      @Nonnull IntGrid mapToInt(@Nonnull ToIntFunction<? super E> f)
      Applies the provided mapper function f to every element of this grid, then returns a new integer grid whose values are populated from that of the provided function's return values.
      Parameters:
      f - The function of which to apply to each element of this grid
      Returns:
      The resulting integer grid

    • merge

      @Nonnull <F, G> Grid<G> merge(@Nonnull Grid<F> g, @Nonnull BiFunction<? super E,? super F,G> f) throws IllegalArgumentException
      Between this grid and the provided grid g, this applies the merger function f for each corresponding pair of elements, then returns a new grid whose elements are populated from that of the return values of the merger function f.
      Type Parameters:
      F - The type of element to merge this grid with
      G - The type of element to merge the two grids to
      Parameters:
      g - The grid of which to merge this grid with
      f - The merger function to handle the merging of the two grids
      Returns:
      The resulting grid
      Throws:
      IllegalArgumentException - When the provided grid g's dimensions are different from that of this grid's dimensions

    • iterator

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

    • forEach

      void forEach(@Nonnull Consumer<? super E> a)
      Executes the provided action for each element of this grid. The order of execution is not guaranteed to be consistent.
      Specified by:
      forEach in interface BaseGrid<E>
      Specified by:
      forEach in interface Iterable<E>
      Parameters:
      a - The action of which to execute for each element of this grid

    • forEach

      void forEach(@Nonnull TriConsumer<Integer,Integer,? super E> a)
      Executes the provided action for each element of this grid. The row and column indices are provided as the first and second parameter of the function respectively, and the current element is provided as the third parameter of the function. The order of execution is not guaranteed to be consistent.
      Specified by:
      forEach in interface BaseGrid<E>
      Parameters:
      a - The action of which to execute for each element of this grid

    • array

      @Nonnull E[] array()
      Returns an array containing every element within this grid. The length of the array is not guaranteed to be equal to the size of this grid, and the order is not guaranteed to be consistent.
      Returns:
      The array representation of this grid

    • stream

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

    • collect

      @Nonnull Collection<E> collect()
      Returns a collection containing every element within this grid. The size of the collection is not guaranteed to be equal to the size of this grid, and the order is not guaranteed to be consistent, if there even is one.
      Specified by:
      collect in interface BaseGrid<E>
      Returns:
      The collection representation of this grid
      See Also:

    • set

      @Nonnull Set<E> set()
      Returns a set containing every element of this grid. Due to the nature of sets, every duplicate element will be counted as one element. This property can be useful for certain applications.
      Specified by:
      set in interface BaseGrid<E>
      Returns:
      The set representation of this grid
      See Also:

    • equals

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

    • toString

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