Mosaic: game.h File Reference

Basic Game Functions. More...

#include <stdbool.h>

Macros
#define	DEFAULT_SIZE 5
	Size of the default game grid.

Typedefs
typedef unsigned int	uint
	Standard unsigned integer type.

typedef struct game_s *	game
	The structure pointer that stores the game state.

typedef const struct game_s *	cgame
	The structure constant pointer that stores the game state. More...

Enumerations
enum	color { EMPTY , WHITE , BLACK }

enum	constraint { UNCONSTRAINED = -1 , MIN_CONSTRAINT = -1 , MAX_CONSTRAINT = 9 }

enum	status { ERROR , UNSATISFIED , SATISFIED }

enum	direction { HERE , UP , DOWN , LEFT , RIGHT , UP_LEFT , UP_RIGHT , DOWN_LEFT , DOWN_RIGHT }
	All possible directions in the game grid to explore the neighbourhood of a given square.

Functions
game	game_new (constraint constraints, color colors)
	Creates a new game with default size and initializes it. More...

game	game_new_empty (void)
	Creates a new empty game with defaut size. More...

game	game_copy (cgame g)
	Duplicates a game. More...

bool	game_equal (cgame g1, cgame g2)
	Tests if two games are equal. More...

void	game_delete (game g)
	Deletes the game and frees the allocated memory. More...

void	game_set_constraint (game g, uint i, uint j, constraint n)
	Sets the constraint of a given square. More...

void	game_set_color (game g, uint i, uint j, color c)
	Sets the color of a given square. More...

constraint	game_get_constraint (cgame g, uint i, uint j)
	Gets the constraint of a given square. More...

color	game_get_color (cgame g, uint i, uint j)
	Gets the color of a given square. More...

bool	game_get_next_square (cgame g, uint i, uint j, direction dir, uint pi_next, uint pj_next)
	Gets the coordinate of the next square in a given direction. More...

status	game_get_status (cgame g, uint i, uint j)
	Gets the square status. More...

int	game_nb_neighbors (cgame g, uint i, uint j, color c)
	Returns the number of neighbors of the same color. More...

void	game_play_move (game g, uint i, uint j, color c)
	Plays a move in a given square. More...

bool	game_won (cgame g)
	Checks if the game is won. More...

void	game_restart (game g)
	Restarts a game. More...

Detailed Description

Basic Game Functions.

See Mosaic for further details.

Copyright: University of Bordeaux. All rights reserved, 2023.

Typedef Documentation

◆ cgame

typedef const struct game_s* cgame

The structure constant pointer that stores the game state.

That means that it is not possible to modify the game using this pointer.

Enumeration Type Documentation

◆ color

enum color

square colors

Enumerator
EMPTY	empty square
WHITE	white square
BLACK	blacksquare

◆ constraint

enum constraint

square constraints

These constants are numerical constraints that indicate the expected number of black squares in the 3x3 neighborhood of a given square (including itself). All valid constant numbers are between 0 and 9. The special constant UNCONSTRAINED (-1) indicates that there is no particular constraint on a square, i.e. there can be any number of black squares in its neighborhood.

Warning: Values from 0 to 9 are not explicitly listed here, but can be used normally with this enumeration type. For example, constraint n = 3 is correct.

Enumerator
UNCONSTRAINED	unconstrained square
MIN_CONSTRAINT	minimum square constraint
MAX_CONSTRAINT	maximum square constraint

◆ status

enum status

square status

These constants are used to indicate the status of a square in the grid, that can be either ERROR, SATISFIED or UNSATISFIED depending on the colors of its 3x3 neighborhood (including the square itself). More precisely, the ERROR status indicates that the number of black (or white) squares in the neighborhood is too high, so that the numerical square constraint cannot be met. The SATISFIED status indicates that the number of black squares in the neighborhood is equal to the numerical square constraint, and that the other squares are white, i.e. there are no more EMPTY squares in the 3x3 neighborhood. Finally, the status UNSATISFIED indicates that the numerical constraint has not yet been satisfied, but may still be. In this case, there are still EMPTY squares in the neighborhood, but there are no obvious errors.

Warning: All theses statuses are mutually exclusive, i.e. a square cannot be both ERROR and UNSATISFIED.

Enumerator
ERROR	error status
UNSATISFIED	unsatisfied status
SATISFIED	satisfied status

Function Documentation

◆ game_copy()

game game_copy ( cgame g )

Duplicates a game.

Parameters

g	the game to copy

Returns: the copy of the game

Precondition: g must be a valid pointer toward a game structure.

◆ game_delete()

void game_delete ( game g )

Deletes the game and frees the allocated memory.

Parameters

g	the game to delete

Precondition: g must be a valid pointer toward a game structure.

◆ game_equal()

bool game_equal	(	cgame	g1,
		cgame	g2
	)

Tests if two games are equal.

Parameters

g1	the first game
g2	the second game

Returns: true if the two games are equal, false otherwise

Precondition: g1 must be a valid pointer toward a game structure.; g2 must be a valid pointer toward a game structure.

◆ game_get_color()

color game_get_color	(	cgame	g,
		uint	i,
		uint	j
	)

Gets the color of a given square.

Parameters

g	the game
i	row index
j	column index

Precondition: g must be a valid pointer toward a game structure.; i < game height; j < game width

Returns: the square color

◆ game_get_constraint()

constraint game_get_constraint	(	cgame	g,
		uint	i,
		uint	j
	)

Gets the constraint of a given square.

Parameters

g	the game
i	row index
j	column index

Precondition: g must be a valid pointer toward a game structure.; i < game height; j < game width

Returns: the square constraint or -1 if unconstrained square

◆ game_get_next_square()

bool game_get_next_square	(	cgame	g,
		uint	i,
		uint	j,
		direction	dir,
		uint *	pi_next,
		uint *	pj_next
	)

Gets the coordinate of the next square in a given direction.

Parameters

	g	the game
	i	row index
	j	column index
	dir	the direction
[out]	pi_next	the row index of the next square (output)
[out]	pj_next	the column index of the next square (output)

Precondition: g must be a valid pointer toward a game structure.; i < game height; j < game width

Returns: true if the next square is inside the grid, false otherwise

◆ game_get_status()

status game_get_status	(	cgame	g,
		uint	i,
		uint	j
	)

Gets the square status.

Parameters

g	the game
i	the row index
j	the column index

Returns: the square status, either ERROR, UNSATISFIED or SATISFIED.

◆ game_nb_neighbors()

int game_nb_neighbors	(	cgame	g,
		uint	i,
		uint	j,
		color	c
	)

Returns the number of neighbors of the same color.

This function counts the number of squares of color c in the 3x3 neighborhood of the square at coordinate (i, j), including the square itself in this count.

Parameters

g	the game
i	row index
j	column index
c	the choosen color

Precondition: g must be a valid pointer toward a game structure.; i < game height; j < game width

Returns: the number of neighbors of the same color

◆ game_new()

game game_new	(	constraint *	constraints,
		color *	colors
	)

Creates a new game with default size and initializes it.

Parameters

constraints	an array describing the initial constraint of each square using row-major storage (of size DEFAULT_SIZE squared)
colors	an array describing the initial color of each square using row-major storage (of size DEFAULT_SIZE squared) or NULL to set all colors as EMPTY

Precondition: constraints must be an initialized array of default size squared; colors must be an initialized array of default size squared or NULL

Returns: the created game

◆ game_new_empty()

game game_new_empty ( void )

Creates a new empty game with defaut size.

All squares are initialized with unconstrained squares, with empty color.

Returns: the created game

◆ game_play_move()

void game_play_move	(	game	g,
		uint	i,
		uint	j,
		color	c
	)

Plays a move in a given square.

Parameters

g	the game
i	row index
j	column index
c	the color to play

Precondition: g must be a valid pointer toward a game structure.; i < game height; j < game width; c must be a valid color (BLACK, WHITE or EMPTY)

◆ game_restart()

void game_restart ( game g )

Restarts a game.

All the game is reset to its initial state. In particular, all the colors are removed.

Parameters

g the game

Precondition: g must be a valid pointer toward a game structure.

◆ game_set_color()

void game_set_color	(	game	g,
		uint	i,
		uint	j,
		color	c
	)

Sets the color of a given square.

This function is useful for initializing the squares of an empty game.

Parameters

g	the game
i	row index
j	column index
c	the square color

Precondition: g must be a valid pointer toward a game structure.; i < game height; j < game width; c must be a valid color (BLACK, WHITE or EMPTY)

◆ game_set_constraint()

void game_set_constraint	(	game	g,
		uint	i,
		uint	j,
		constraint	n
	)

Sets the constraint of a given square.

This function is useful for initializing the squares of an empty game.

Parameters

g	the game
i	row index
j	column index
n	the square constraint (or -1 if unconstrained square)

Precondition: g must be a valid pointer toward a game structure.; i < game height; j < game width; n >= MIN_CONSTRAINT and n <= MAX_CONSTRAINT

◆ game_won()

bool game_won ( cgame g )

Checks if the game is won.

Parameters

g the game

This function checks that all the game rules are satisfied, i.e. all squares have color WHITE or BLACK with status SATISFIED.

Returns: true if the game is won, false otherwise

Precondition: g must be a valid pointer toward a game structure.; i < game height; j < game width

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ cgame

Enumeration Type Documentation

◆ color

◆ constraint

◆ status

Function Documentation

◆ game_copy()

◆ game_delete()

◆ game_equal()

◆ game_get_color()

◆ game_get_constraint()

◆ game_get_next_square()

◆ game_get_status()

◆ game_nb_neighbors()

◆ game_new()

◆ game_new_empty()

◆ game_play_move()

◆ game_restart()

◆ game_set_color()

◆ game_set_constraint()

◆ game_won()