org.joda.collect.grid
Interface Grid<V>

Type Parameters:

V - the type of the value

All Known Implementing Classes:

DenseGrid, ImmutableGrid, SparseGrid

public interface Grid<V>

A data structure representing a grid keyed by int row and int column.

A grid has a fixed number of rows and columns, but not all cells must be occupied. Dense and sparse implementations are provided that handle high and low numbers of cells relative to the potential capacity.

rowCount

int rowCount()

Gets the number of rows in the grid.

A grid has a fixed number of rows and columns, but not all cells must be occupied. This returns the row capacity, not the number of occupied rows. It is guaranteed that contains(int, int) will return false for indices larger than the row count.

Returns:

the number of rows, zero or greater

columnCount

int columnCount()

Gets the number of columns in the grid.

A grid has a fixed number of rows and columns, but not all cells must be occupied. This returns the column capacity, not the number of occupied columns. It is guaranteed that contains(int, int) will return false for indices larger than the column count.

Returns:

the number of columns, zero or greater

exists

boolean exists(int row,
               int column)

Checks if the specified row-column exists.

This simply checks that the row and column indices are between zero and the row and column counts.

Parameters:

row - the row

column - the column

Returns:

true if the row-column exists

isFull

boolean isFull()

Checks if the grid is full.

A full grid has a cell at every combination of row and column.

Returns:

true if full

isEmpty

boolean isEmpty()

Checks if the grid is empty.

Returns:

true if empty

size

int size()

Gets the number of cells that are present.

Returns:

the size of the set of cells

contains

boolean contains(int row,
                 int column)

Checks if a value is present at the specified row-column.

If either index does not exist, false is returned.

Parameters:

row - the row

column - the column

Returns:

true if there is a value at the row-column

containsValue

boolean containsValue(Object valueToFind)

Checks if the specified value is contained in the grid.

Parameters:

valueToFind - the value to find, null returns false

Returns:

true if the grid contains the value

get

V get(int row,
      int column)

Gets the value at the specified row-column.

If either index does not exist, null is returned.

Parameters:

row - the row

column - the column

Returns:

the value at the row-column, null if not found

cell

Grid.Cell<V> cell(int row,
                  int column)

Gets the cell at the specified row-column.

If either index does not exist, null is returned.

Parameters:

row - the row

column - the column

Returns:

the cell at the row-column, null if not found

equals

boolean equals(Object obj)

Checks if this grid equals another grid.

Two grids are equal if they are the same size and contain the same set of cells.

Overrides:

equals in class Object

Parameters:

obj - the object to compare to, null returns false

Returns:

true if equal

hashCode

int hashCode()

Gets a suitable hash code.

The hash code is rowCount ^ Integer.rotateLeft(columnCount, 16) ^ cells.hashCode().

Overrides:

hashCode in class Object

Returns:

the hash code

clear

void clear()

Clears the grid.

The grid will be empty after calling this method.

Throws:

UnsupportedOperationException - if read-only

put

void put(int row,
         int column,
         V value)

Puts a value into this grid.

The value at the specified row-column is set. Any previous value at the row-column is replaced.

If either index does not exist, IndexOutOfBoundsException is thrown.

Parameters:

row - the row, zero or greater

column - the column, zero or greater

value - the value to put into the grid, not null

Throws:

IndexOutOfBoundsException - if either index does not exist

UnsupportedOperationException - if read-only

putAll

void putAll(Grid<? extends V> grid)

Puts all cells from a grid into this grid.

The value at the specified row-column is set. Any previous value at the row-column is replaced.

Parameters:

grid - the grid to put into this grid, not null

Throws:

IndexOutOfBoundsException - if a cell has an invalid index

UnsupportedOperationException - if read-only

remove

boolean remove(int row,
               int column)

Removes the value at the specified row-column.

If either index does not exist, no action occurs and false is returned.

Parameters:

row - the row

column - the column

Returns:

true if the grid is altered

Throws:

UnsupportedOperationException - if read-only

cells

Set<Grid.Cell<V>> cells()

Gets the complete set of cells.

If the grid is mutable then cells may be added or removed from the set. The cells are returned in order, looping around rows, then columns.

The cell returned from the set iterator may be a mutable Cell implementation that cannot be stored beyond the lifetime of an iteration.

Returns:

the set of all cells, not null

values

com.google.common.collect.ImmutableCollection<V> values()

Gets the values in order through rows, then columns.

The returned data structure is an ordered collection. The values are returned in order, looping around rows, then columns.

Returns:

the collection of all values, not null

row

List<V> row(int row)

Gets the columns of a single row.

The list will contain all columns from zero to columnCount. Where there is no value for a cell, the list will contain null.

The returned list is immutable, except for List.set(int, Object), which adds, updates or deletes from the underlying grid.

Parameters:

row - the row, zero or greater

Returns:

the columns of the specified row, not null

Throws:

IndexOutOfBoundsException - if the row is invalid

rows

List<List<V>> rows()

Gets the entire grid of values, by row then column.

The outer list contains all rows from zero to rowCount. Each inner list contains all columns from zero to columnCount. Where there is no value for a cell, the value is null.

The returned list is immutable, except for the List.set(int, Object) method on the inner list, which adds, updates or deletes from the underlying grid.

Returns:

the entire grid, by row then column, not null

column

List<V> column(int column)

Gets the rows of a single column.

The list will contain all rows from zero to rowCount. Where data is not present, the list will contain null.

The returned list is immutable, except for List.set(int, Object), which adds, updates or deletes from the underlying grid.

Parameters:

column - the column, zero or greater

Returns:

the rows of the specified column, not null

Throws:

IndexOutOfBoundsException - if the column is invalid

columns

List<List<V>> columns()

Gets the entire grid of values, by column then row.

The outer list contains all columns from zero to columnCount. Each inner list contains all rows from zero to rowCount. Where there is no value for a cell, the value is null.

The returned list is immutable, except for the List.set(int, Object) method on the inner list, which adds, updates or deletes from the underlying grid.

Returns:

the entire grid, by row then column, not null