proposed hex board API

hex.h

#ifndef HEX_HEX_H
#define HEX_HEX_H

#include <stdlib.h>

enum hex_err_e {
  HEX_OK,
  HEX_ENOMEM,
  HEX_EBOUNDS,
  HEX_EBADSPACE,
  HEX_ESIZEMISMATCH,
  HEX_ERRS_MAX
};

enum hex_color_e {
  HEX_COLOR_NONE,
  HEX_COLOR_RED,
  HEX_COLOR_BLUE,
  HEX_COLORS_MAX
} __attribute__ ((__packed__));

struct hex_board_s;

typedef enum hex_err_e hex_err;
typedef enum hex_color_e hex_color;
typedef struct hex_board_s hex_board;

typedef void *hex_alloc(size_t nmemb, size_t size);

// Creates a new hex board of the given size. In the case of hex_board_init, the
// pointer returned can be freed as usual for memory allocated with the given
// allocator function. Returns HEX_ENOMEM if allocation fails.
hex_err hex_board_init(hex_board **board, int size, hex_alloc *alloc);
void hex_board_initat(hex_board *board, int size);

// Gets the number of bytes necessary to store a board of the given size. Can be
// used to allocate memory for use with hex_board_initat.
size_t hex_board_sizeof(int size);

// Gets a pointer to the board data, in column-major order, i.e. columns are
// contiguous.
hex_color *hex_board_data(hex_board *board, size_t *data_len);
const hex_color *hex_board_rodata(const hex_board *board, size_t *data_len);

// Gets a pointer to a space on the board. Returns HEX_EBOUNDS if row, col are
// out-of-bounds.
hex_err hex_board_space(
  hex_board *board,
  int row, int col,
  hex_color **space);
hex_err hex_board_rospace(
  const hex_board *board,
  int row, int col,
  const hex_color **space);

// Gets the coordinates of the given space. Returns HEX_EBADSPACE if the given
// space is not part of the given board.
hex_err hex_board_coords(
  const hex_board *board,
  const hex_color *space,
  int *row, int *col);

// Given a space on a board, gets the corresponding space on another board.
// Returns HEX_EBADSPACE if src_space is not from src_board.
hex_err hex_board_correlate(
  const hex_board *dest_board,
  hex_color **dest_space,
  const hex_board *src_board,
  const hex_color *src_space);

// Populates the 'neighbors' array with the coordinates of the neighbors of the
// given square, with alternating row and column values, and stores the number
// of neighbors. The neighbors array is assumed to have enough room to store six
// neighbors, i.e. it should be of length 12. Returns HEX_EBOUNDS if row, col
// are out-of-bounds.
hex_err hex_board_neighborcoords(
  const hex_board *board,
  int row, int col,
  int *neighbors,
  int *neighbor_count);

// Populates the 'neighbors' array with pointers to the spaces neighboring the
// given space. Returns HEX_EBADSPACE if the given space is not part of the
// given board.
hex_err hex_board_neighbors(
  const hex_board *board,
  const hex_color *space,
  hex_color **neighbors,
  int *neighbor_count);

// Gets the winner of the board, if any. Returns HEX_COLOR_NONE if there is no
// winner.
hex_color hex_board_getwinner(const hex_board *board);

// Clears the given board, resetting it to its initial state.
void hex_board_clear(hex_board *board);

// Copies the data from one board to another board. Returns HEX_ESIZEMISMATCH if
// the boards are not the same size.
hex_err hex_board_copy(hex_board *dest, const hex_board *src);

#endif