GRIDS: LISTS OF LISTS

A list can hold anything, and that includes other lists. A list whose items are lists is a grid: rows and columns, like a spreadsheet, a times table, a crossword or a game board. satellite reaches into one with two numbers, grid[x][y].

Your first grid

Write a grid the way you write any list, with braces, and put a list at each position: {{1, 2, 3}, {4, 5, 6}} is a list of two rows, and each row holds three numbers.

To say what it holds, put one list type inside another: satellite.container.list<satellite.container.list<satellite.variable.number>> is a list of lists of numbers, and satl checks every number that goes in.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.container.list<satellite.container.list<satellite.variable.number>> grid = {{1, 2, 3}, {4, 5, 6}}
    satellite.console.display(grid)
    satellite.console.display(grid[2])
    satellite.console.display(grid[2][3])

    grid[1][2] = 20
    grid[2].append(7)
    grid.append({8})
    satellite.console.display(grid)
    satellite.console.display(grid.size)
    satellite.console.display(grid[2].size)
    satellite.console.display(grid[2].sum)
    satellite.return(satellite)
}

{{1, 2, 3}, {4, 5, 6}}
{4, 5, 6}
6
{{1, 20, 3}, {4, 5, 6, 7}, {8}}
3
4
22

Read grid[2][3] from left to right:

1. grid[2] is the second item of the grid, which is the row {4, 5, 6}.
2. [3] is the third item of that row, which is 6.

Everything a list can do, a row can do too. grid[2].append(7) adds to the end of row 2, grid[2].sum adds up row 2, and grid.append({8}) adds a whole new row. Rows do not have to be the same length: after these lines the grid has rows of 3, 4 and 1 items. Like every list, a grid counts from 1.

Building a grid with loops

Most grids are built rather than typed. Start with an empty list, add an empty row, then fill the row. Two satellite.statement.for loops, one inside the other, do the whole job: the outer loop makes the rows, and the inner loop fills each one.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.container.list<satellite.container.list<satellite.variable.number>> table = satellite.container.list()
    satellite.statement.for(satellite.variable.number row = 1; row <= 4; row++)
    {
        table.append(satellite.container.list())
        satellite.statement.for(satellite.variable.number column = 1; column <= 4; column++)
        {
            table[row].append(row * column)
        }
    }

    satellite.statement.for(satellite.variable.number row = 1; row <= table.size; row++)
    {
        satellite.console.display(table[row].join("  "))
    }
    satellite.console.display(table[3][4])
    satellite.return(satellite)
}

1  2  3  4
2  4  6  8
3  6  9  12
4  8  12  16
12

satellite.container.list() is an empty list, the same as {}. table[row].join(" ") turns one row into one line of text, with two spaces between the numbers, so the grid prints as a table.

A grid of words: a game board

A grid can hold text just as well. Here is a noughts and crosses board, three rows of three squares, where "." is an empty square.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.container.list<satellite.container.list<satellite.variable.string>> board = {{".", ".", "."}, {".", ".", "."}, {".", ".", "."}}
    board[2][2] = "X"
    board[1][3] = "O"
    board[3][1] = "X"

    satellite.statement.for(satellite.variable.number row = 1; row <= 3; row++)
    {
        satellite.console.display(board[row].join(" "))
    }
    satellite.console.display(board[2].contains("X"))
    satellite.console.display(board[2].index_of("X"))

    satellite.container.list<satellite.container.list<satellite.variable.string>> saved = board
    saved[1][1] = "O"
    satellite.console.display(board[1].join(" "))
    satellite.console.display(saved[1].join(" "))
    satellite.return(satellite)
}

. . O
. X .
X . .
true
2
. . O
O . O

board[2].index_of("X") answers the position of the first "X" in row 2, or 0 when there is none.

The last four lines show that a grid is a value, like every list: saved = board makes a copy of the whole grid, rows and all. Changing a square of saved leaves board as it was. Copying costs nothing until one of them is changed.

Squares that are not there

Writing to a square past the end of a row does not make the row longer, and satl stops with a report that names the square and says how many items the row really holds. Use .append to grow a row.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.container.list<satellite.container.list<satellite.variable.number>> grid = {{1, 2}, {3, 4}}
    grid[2][3] = 9
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S501: LINE_PAST_THE_END
satl(run): in grid[...] = ..., grid[2][3] = ...: there is no such item -- the
list holds 2 items, counting from 1. Writing past the end does not make the list
longer

directory: outside.satl:6
syntax: grid[2][3] = 9
            /\

a line was read by its number and the file has no line with that number. Lines
count from 1, and the last one is the file's size.
machine code 47 line_past_the_end -- satl exits with this.

--------------------------------------------------------------------------------

Where next

The FULL REFERENCE lists every list word, and every one of them works on a row. For the basics of a single list, see LISTS. Lists can sit inside other containers too, such as a list filed under a name: see MAPS.