tribble.util
Class GridList2D

java.lang.Object
  tribble.util.GridList2D

public class GridList2D
extends java.lang.Object

Provides methods for arranging 1-dimensional array elements into a 2-dimensional grid.

Consider a 1-dimensional array containing 14 elements, as shown here:

0	1	2	3	4	5	6	7	8	9	10	11	12	13

We wish to display the elements in a 2-dimensional grid with four columns, so that the elements are arranged in order from top to bottom down each row, and then from left to right across rows. Any left-over cells in the grid that do not correspond to any elements in the array are left empty. Every cell in each row, except possibly the last row, are filled; any remaining unfilled cells will be the right-most cells of the last row. The diagram below illustrates:

Columns (x)

Rows
(y)

	0	1	2	3	4
0	0	4	8	11	−1
1	1	5	9	12	−1
2	2	6	10	13	−1
3	3	7	−1	−1	−1
4	−1	−1	−1	−1	−1

Note that cells within the 2-dimensional grid that do not have a corresponding element in the 1-dimensional source array, as well as cells outside the grid, have an index of −1.

Determing the array indices for each grid cell is accomplished with code similar to the following:

    int         nCols =   4;
    boolean     printed = true;

    for (int y = 0;  printed;  y++)
    {
        printed = false;
        for (int x = 0;  x < nCols;  x++)
        {
            int     i;

            i = GridList2D.indexFor(x, y, nCols, arr.length);
            if (i < 0)
                break;

            out.print(arr[i]);
            printed = true;
        }
        if (printed)
            out.println();
    } 

An alternative approach is to initialize a GridList2D object with the size of the 2-dimensional grid and the length of the 1-dimensional source array:

    int         nCols =   4;
    GridList2D  grid;

    grid = new GridList2D(nCols, arr.length);

The indexFor() method of the object can then be called for each grid cell coordinate to determine its corresponding index in the source array:

    boolean     printed = true;

    for (int y = 0;  printed;  y++)
    {
        printed = false;
        for (int x = 0;  ;  x++)
        {
            int     i;

            i = grid.indexFor(x, y);
            if (i < 0)
                break;

            out.print(arr[i]);
            printed = true;
        }
        if (printed)
            out.println();
    } 

Source code:

http://david.tribble.com/src/java/tribble/util/GridList2D.java

Documentation:

http://david.tribble.com/docs/tribble/util/GridList2D.html

Since:

2010-10-17

Version:

$Revision: 1.3 $ $Date: 2010/10/20 22:41:32 $

Author:

David R. Tribble (david@tribble.com)

Copyright ©2010 by David R. Tribble, all rights reserved.
Permission is granted to any person or entity except those designated by by the United States Department of State as a terrorist, or terrorist government or agency, to use and distribute this source code provided that the original copyright notice remains present and unaltered.

Constructor Summary

GridList2D(int cols, int elems)
Construct an object to determine the indices of the elements in a 1-dimensional array that are located at particular (x, y) coordinates within a 2-dimensional grid.

Method Summary

int	getArrayLength() Retrieve the number of elements in the 1-dimensional source array.
int	getColumns() Retrieve the number of columns in the 2-dimensional grid.
int	getRows() Retrieve the number of rows in the 2-dimensional grid.
int	indexFor(int x, int y) Determine the index of an element in a 1-dimensional array that is located at a particular (x, y) cell coordinate within a 2-dimensional grid.
static int	indexFor(int x, int y, int cols, int elems) Determine the index of an element in a 1-dimensional array that is located at a particular (x, y) coordinate within a 2-dimensional grid.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GridList2D

public GridList2D(int cols,
                  int elems)

Construct an object to determine the indices of the elements in a 1-dimensional array that are located at particular (x, y) coordinates within a 2-dimensional grid.

Parameters:

cols - Width of the 2-dimensional grid, i.e., the number of columns it contains.

elems - Number of elements in the 1-dimensional array.

Since:

1.1, 2010-10-17

Method Detail

indexFor

public static int indexFor(int x,
                           int y,
                           int cols,
                           int elems)

Determine the index of an element in a 1-dimensional array that is located at a particular (x, y) coordinate within a 2-dimensional grid.

Parameters:

x - X (horizontal) coordinate within the 2-dimensional grid.

y - Y (vertical) coordinate within the 2-dimensional grid.

cols - Width of the 2-dimensional grid, i.e., the number of columns it contains.

elems - Number of elements in the 1-dimensional array.

Returns:

The index of the element of the 1-dimensional array that is located at the (x, y) cell coordinate within the 2-dimensional grid, or −1 if the grid cell does not contain any array element (i.e., the cell is empty). This also returns −1 if the (x, y) cell coordinates do not lie within the grid.

Since:

1.1, 2010-10-17

indexFor

public int indexFor(int x,
                    int y)

Determine the index of an element in a 1-dimensional array that is located at a particular (x, y) cell coordinate within a 2-dimensional grid.

Parameters:

x - X (horizontal) coordinate within the 2-dimensional grid.

y - Y (vertical) coordinate within the 2-dimensional grid.

Returns:

The index of the element of the 1-dimensional array that is located at the (x, y) cell coordinate within the 2-dimensional grid, or −1 if the grid cell does not contain any array element (i.e., the cell is empty). This also returns −1 if the (x, y) cell coordinates do not lie within the grid.

Since:

1.1, 2010-10-17

getColumns

public int getColumns()

Retrieve the number of columns in the 2-dimensional grid.

Returns:

Width of the 2-dimensional grid, i.e., the number of columns it contains.

Since:

1.2, 2010-10-18

getRows

public int getRows()

Retrieve the number of rows in the 2-dimensional grid.

Returns:

Height of the 2-dimensional grid, i.e., the number of rows it contains. Note that the last row may contain empty cells.

Since:

1.2, 2010-10-18

getArrayLength

public int getArrayLength()

Retrieve the number of elements in the 1-dimensional source array.

Returns:

Number of elements in the 1-dimensional array.

Since:

1.2, 2010-10-18