The Slide Game in Python

In this assignment, you will be writing Python code for the Slide Game. Instead of using colourful pictures of squares on a game board (as we saw in the last section), in our Python code we will use text to represent the squares (i.e., Python's str type). In the rest of this section, we provide some details to help you understand how to approach the code you need to write.

Representing the game board

A game board can be thought of as a table with rows (see the constant N_ROWS) and columns (N_COLUMNS). The size of a game board does not change during the course of a game. For example, here is an empty game board with 4 rows and 5 columns:

1 2 3 4 5

1 # | # | # | # | #

2 # | # | # | # | #

3 # | # | # | # | #

4 # | # | # | # | #

A location in the game board can be described by indicating the row and then the column. For example, using the empty game board above, (1, 1) indicates the location at the top-left of the game board. And (4, 5) indicates the bottom-right of the game board.

We will use strings (i.e., the str type) to represent the squares on a game board:

- The black squares will be: '#' (BLACK_SQUARE).

- The red squares will be: 'R' (RED_SQUARE).

- The yellow squares will be: 'Y' (YELLOW_SQUARE).

We have not yet studied how to store 2-dimensional information in Python programs, so we will need a different way to represent our game board. The approach that we will take for this assignment is to store the rows one after another, starting with the first row.

- Using our empty (all black squares) game board example, this is: '####################'.

- Using a slightly more interesting example:

1 2 3 4 5

1 R | # | # | # | #

2 # | # | # | # | Y

3 R | # | # | # | #

4 Y | # | # | # | #

Would be represented as 'R########YR####Y####'.

Accessing a square in the game board

We have used row and column indices to describe the position of each square in the grid representation of a game board. But each character in a Python str is in a position that is described by a single index. How is the Python program going to translate between row and column indices and str indices? To answer this question, we will have to determine a formula!

Consider the following concrete example:

1 2 3 4 5

1 A | B | C | D | E

2 F | G | H | I | J

3 K | L | M | N | O

4 P | Q | R | S | T

Which, as a string, is: 'ABCDEFGHIJKLMNOPQRST'. Let us use the table below to derive a formula that calculates the index based on: the location (i.e., row and column) and game board size (i.e., N_ROWS and/or N_COLUMNS).

Location	Index	Character
(1, 1)	0	A
(1, 2)	1	B
(1, 3)	2	C
(1, 4)	3	D
(1, 5)	4	E
(2, 1)	5	F
(2, 2)	6	G
(2, 3)	7	H
(2, 4)	8	I
(2, 5)	9	J
(3, 1)	10	K
(3, 2)	11	L
(3, 3)	12	M
(3, 4)	13	N
(3, 5)	14	O
(4, 1)	15	P
(4, 2)	16	Q
(4, 3)	17	R
(4, 4)	18	S
(4, 5)	19	T

From the table above, we see that the character in the square with position (2, 1) (i.e., the square at row 2 and column 1) has index 5. The other squares in that row have indices 6, 7, 8 and 9. We conclude that when moving one square across a row, the index increases by 1.

The squares in column 3 have indices 2, 7, 12 and 17. Moving one square down a column increases the index by 5, which is the number of columns of the game board. We conclude that when moving one square down a column, the index increases by the game board's number of columns.

Let us now introduce variables that will allow us to express the formula explicitly. Let a variable named str_index refer to the position of a square in the str representation of a game board with size N_ROWS rows and N_COLUMNS columns. Let variables row and col refer to the position of the same square in the grid representation of a game board. From what we have seen, we can conclude that str_index depends on row, col, and N_COLUMNS. That is, the following formula will compute str_index:

(row - 1) * N_COLUMNS + (col - 1)

The minus 1's are needed for the arithmetic to work out. This is because we chose to index our rows and columns starting at 1 (as a thought exercise, what would the formula be if we chose to index the rows and columns starting at 0?).

The functions listed below do not need to be completed in order -- if you get stuck on one, try another!

Functions to write for A1

Function name: (Parameter types) -> Return type	Specifications
create_empty_board () -> str	This function has no parameters. This function returns a string for storing information about a game board that has N_ROWS rows and N_COLUMNS columns. Each character in the returned string is to have been set to the BLACK_SQUARE character.
is_board_full (str) -> bool	This function has one parameter that refers to a valid game board. This function returns True if and only if all of the squares in the game board are not black. That is, True is returned if and only if there are no BLACK_SQUARE characters in the game board.
between (str, int, int) -> bool	The first parameter refers to a str value, the second to the minimum value for a range of values, and the third to the maximum value for a range of values. Assume that the str value can be converted to an integer. Assume that the value of the second parameter is less than or equal to the value of the third parameter. This function returns True if and only if the converted integer value of the first parameter is not less than the second parameter and not more than the third parameter. In other words, True is returned if and only if the first parameter is between the second and third parameters, or equal to one or both of them.
calculate_str_index (int, int) -> int	The first and second parameters refer to the row and column, respectively, of a location in a valid game board whose size is given by constants N_ROWS and N_COLUMNS. This function returns the index in the string representation of the game board corresponding to the given row and column location.
calculate_increment (str) -> int	The parameter refers to a string that describes one of the four directions: down, across, down-right, or down-left. Assume that the str value is one of: DOWN, ACROSS, DOWN_RIGHT, or DWON_LEFT. The game board size is given by the constants N_ROWS and N_COLUMNS. This function returns the difference between the string indices of two adjacent squares on a line that goes in the direction specified by the first parameter.
get_row (int, str) -> str	The first parameter is a row number and the second parameter is the string representation of a game board. Assume that the row number and game board are valid. The game board size is given by the constants N_ROWS and N_COLUMNS. This function returns only the characters in the game board found at the given row in the same left-to-right order as they appear in the row.
get_column (int, str) -> str	The first parameter is a column number and the second parameter is the string representation of a game board. Assume that the column number and game board are valid. The game board size is given by the constants N_ROWS and N_COLUMNS. This function returns only the characters in the game board found at the given column in the same top-to-bottom order as they appear in the column.
slide_right (str, int, str) -> str	The first parameter is the square being added to the game board. The second parameter is a row number and the third parameter is the string representation of a game board. Assume that the square, row number, and game board are valid. This function returns a string that is like the original game board, except that: - the square from the first parameter has been slid into the "beginning" (i.e., first column) of the given row number; - the square at the "end" (i.e., last column) has slid off the game board; - the remaining squares have slid to the right.
slide_left (str, int, str) -> str	The first parameter is the square being added to the game board. The second parameter is a row and the third parameter is the string representation of a game board. Assume that the square, row number, and game board are valid. This function returns a string that is like the original game board, except that: - the square from the first parameter has been slid into the "end" (i.e., last column) of the given row number; - the square at the "beginning" (i.e., first column) has slid off the game board; - the remaining squares have slid to the left.