Board Position

Chess board state management, FEN serialisation, move execution, and legality queries.

Types

	Name
enum	scid_position_limits { SCID_MAX_LEGAL_MOVES = 256} Maximum theoretical legal moves possible in any valid chess position.
typedef struct scid_position	scid_position Opaque handle representing a chess board position state.

Functions

	Name
scid_error	scid_position_to_fen(const scid_position * position, char * out_fen, size_t out_fen_capacity, size_t * out_fen_size) Formats the board position as a standard Forsyth–Edwards Notation (FEN) string.
scid_error	scid_position_side_to_move_get(const scid_position * position, scid_colour * out_side_to_move) Retrieves the colour of the player whose turn it is to move.
scid_error	scid_position_piece_at_get(const scid_position * position, scid_square square, scid_piece * out_piece) Retrieves the piece residing on a specified board square.
scid_error	scid_position_legal_moves(const scid_position * position, scid_movespec * out_moves, size_t out_moves_capacity, size_t * out_moves_size) Generates all strictly legal moves available in the current position.
scid_error	scid_position_is_start(const scid_position * position, int * out_is_start) Checks if the position is identical to the standard chess starting position.
scid_error	scid_position_is_legal(const scid_position * position, int * out_is_legal) Validates whether the board position satisfies all chess rules and invariants.
scid_error	scid_position_is_checkmate(const scid_position * position, int * out_is_checkmate) Checks if the position is in checkmate (king in check with no legal moves).
scid_error	scid_position_is_check(const scid_position * position, int * out_is_check) Checks if the king of the side to move is currently in check.
scid_error	scid_position_halfmove_clock_get(const scid_position * position, unsigned * out_halfmove_clock) Retrieves the halfmove clock for the 50-move draw rule.
scid_error	scid_position_fullmove_number_get(const scid_position * position, unsigned * out_fullmove_number) Retrieves the 1-based fullmove number.
void	scid_position_free(scid_position * position) Releases a board position handle and all associated resources.
scid_error	scid_position_create_with_uci(const scid_position * position, const char * uci, scid_position ** out_position) Creates a new board position by cloning an existing position and applying a UCI move.
scid_error	scid_position_create_with_san(const scid_position * position, const char * san, scid_position ** out_position) Creates a new board position by cloning an existing position and applying a SAN move.
scid_error	scid_position_create_from_fen(const char * fen, scid_position ** out_position) Creates a new board position initialised from a FEN string.
scid_error	scid_position_apply_uci(scid_position * position, const char * uci) Applies a coordinate UCI move in-place to the position.
scid_error	scid_position_apply_san(scid_position * position, const char * san) Applies a Standard Algebraic Notation (SAN) move in-place to the position.

Defines

	Name
	SCID_POSITION_TYPEDEF

Types Documentation

enum scid_position_limits

Enumerator	Value	Description
SCID_MAX_LEGAL_MOVES	256

Maximum theoretical legal moves possible in any valid chess position.

typedef scid_position

typedef struct scid_position scid_position;

Opaque handle representing a chess board position state.

See:

Encapsulates piece placement, active colour, castling availability rights, en passant target square, halfmove clock (50-move rule), and fullmove counter.

Instances are created using scid_position_create_from_fen(), scid_position_create_with_san(), or scid_position_create_with_uci(), and must be released when no longer needed using scid_position_free().

Functions Documentation

function scid_position_to_fen

scid_error scid_position_to_fen(
    const scid_position * position,
    char * out_fen,
    size_t out_fen_capacity,
    size_t * out_fen_size
)

Formats the board position as a standard Forsyth–Edwards Notation (FEN) string.

Parameters:

position Pointer to the board position. Must not be NULL.
out_fen Caller-allocated buffer receiving the null-terminated FEN string. May be NULL if out_fen_capacity is 0 to query required capacity.
out_fen_capacity Capacity of out_fen in bytes (at least 100 bytes recommended).
out_fen_size Pointer receiving the number of bytes written (excluding null terminator), or required capacity if the buffer is too small. Must not be NULL.

Returns:

SCID_OK FEN string emitted successfully.
SCID_ERROR_BAD_ARG If position or out_fen_size is NULL.
SCID_ERROR_BUFFER_FULL If out_fen_capacity is insufficient.

See: scid_position_create_from_fen()

Emits the complete 6-field FEN representation including piece placement, active colour, castling availability, en passant square, halfmove clock, and fullmove number.

function scid_position_side_to_move_get

scid_error scid_position_side_to_move_get(
    const scid_position * position,
    scid_colour * out_side_to_move
)

Retrieves the colour of the player whose turn it is to move.

Parameters:

position Pointer to the board position. Must not be NULL.
out_side_to_move Pointer receiving SCID_WHITE or SCID_BLACK. Must not be NULL.

Returns:

SCID_OK Side retrieved successfully.
SCID_ERROR_BAD_ARG If position or out_side_to_move is NULL.

function scid_position_piece_at_get

scid_error scid_position_piece_at_get(
    const scid_position * position,
    scid_square square,
    scid_piece * out_piece
)

Retrieves the piece residing on a specified board square.

Parameters:

position Pointer to the board position. Must not be NULL.
square Square index to query (0..63).
out_piece Pointer receiving the coloured piece identifier (SCID_PIECE_WHITE_PAWN, SCID_PIECE_BLACK_KING, etc.), or SCID_PIECE_NONE if the square is empty. Must not be NULL.

Returns:

SCID_OK Piece retrieved successfully.
SCID_ERROR_BAD_ARG If position or out_piece is NULL, or square > 63.

function scid_position_legal_moves

scid_error scid_position_legal_moves(
    const scid_position * position,
    scid_movespec * out_moves,
    size_t out_moves_capacity,
    size_t * out_moves_size
)

Generates all strictly legal moves available in the current position.

Parameters:

position Pointer to the board position. Must not be NULL.
out_moves Caller-allocated array receiving the generated scid_movespec values. Must not be NULL.
out_moves_capacity Maximum number of move items out_moves can hold (recommend SCID_MAX_LEGAL_MOVES).
out_moves_size Pointer receiving the total count of legal moves written. Must not be NULL.

Returns:

SCID_OK Legal moves generated successfully.
SCID_ERROR_BAD_ARG If position, out_moves, or out_moves_size is NULL.
SCID_ERROR_BUFFER_FULL If out_moves_capacity is less than the number of legal moves.

function scid_position_is_start

scid_error scid_position_is_start(
    const scid_position * position,
    int * out_is_start
)

Checks if the position is identical to the standard chess starting position.

Parameters:

position Pointer to the board position. Must not be NULL.
out_is_start Pointer receiving non-zero (1) if standard start position; 0 otherwise. Must not be NULL.

Returns:

SCID_OK Check completed successfully.
SCID_ERROR_BAD_ARG If position or out_is_start is NULL.

function scid_position_is_legal

scid_error scid_position_is_legal(
    const scid_position * position,
    int * out_is_legal
)

Validates whether the board position satisfies all chess rules and invariants.

Parameters:

position Pointer to the board position. Must not be NULL.
out_is_legal Pointer receiving non-zero (1) if position is strictly legal; 0 otherwise. Must not be NULL.

Returns:

SCID_OK Validation completed successfully.
SCID_ERROR_BAD_ARG If position or out_is_legal is NULL.

Verifies that both kings exist, the non-active player is not in check, no pawns occupy the 1st or 8th ranks, and piece counts do not violate chess constraints.

function scid_position_is_checkmate

scid_error scid_position_is_checkmate(
    const scid_position * position,
    int * out_is_checkmate
)

Checks if the position is in checkmate (king in check with no legal moves).

Parameters:

position Pointer to the board position. Must not be NULL.
out_is_checkmate Pointer receiving non-zero (1) if active player is checkmated; 0 otherwise. Must not be NULL.

Returns:

SCID_OK Check completed successfully.
SCID_ERROR_BAD_ARG If position or out_is_checkmate is NULL.

See: scid_position_is_check()

function scid_position_is_check

scid_error scid_position_is_check(
    const scid_position * position,
    int * out_is_check
)

Checks if the king of the side to move is currently in check.

Parameters:

position Pointer to the board position. Must not be NULL.
out_is_check Pointer receiving non-zero (1) if active player is in check; 0 otherwise. Must not be NULL.

Returns:

SCID_OK Check completed successfully.
SCID_ERROR_BAD_ARG If position or out_is_check is NULL.

See: scid_position_is_checkmate()

function scid_position_halfmove_clock_get

scid_error scid_position_halfmove_clock_get(
    const scid_position * position,
    unsigned * out_halfmove_clock
)

Retrieves the halfmove clock for the 50-move draw rule.

Parameters:

position Pointer to the board position. Must not be NULL.
out_halfmove_clock Pointer receiving the halfmove clock count. Must not be NULL.

Returns:

SCID_OK Halfmove clock retrieved successfully.
SCID_ERROR_BAD_ARG If position or out_halfmove_clock is NULL.

Counts the number of halfmoves (ply) since the last pawn advance or piece capture.

function scid_position_fullmove_number_get

scid_error scid_position_fullmove_number_get(
    const scid_position * position,
    unsigned * out_fullmove_number
)

Retrieves the 1-based fullmove number.

Parameters:

position Pointer to the board position. Must not be NULL.
out_fullmove_number Pointer receiving the fullmove number. Must not be NULL.

Returns:

SCID_OK Fullmove number retrieved successfully.
SCID_ERROR_BAD_ARG If position or out_fullmove_number is NULL.

Starts at 1 and increments after each move by Black.

function scid_position_free

void scid_position_free(
    scid_position * position
)

Releases a board position handle and all associated resources.

Parameters:

position Pointer to the position handle to release. If NULL, this function performs no action.

Note: Passing NULL is guaranteed to be a safe no-op.

function scid_position_create_with_uci

scid_error scid_position_create_with_uci(
    const scid_position * position,
    const char * uci,
    scid_position ** out_position
)

Creates a new board position by cloning an existing position and applying a UCI move.

Parameters:

position Pointer to the source board position. Must not be NULL.
uci Null-terminated coordinate UCI move string (e.g. "e2e4", "a7a8q"). Must not be NULL.
out_position Pointer to a handle pointer receiving the newly allocated position. Must not be NULL.

Returns:

SCID_OK Position cloned and move applied successfully.
SCID_ERROR_BAD_ARG If position, uci, or out_position is NULL.
SCID_ERROR_INVALID_MOVE If uci is illegal in position.

See: scid_position_apply_uci()

Leaves the source position unmodified and returns a freshly allocated position reflecting the move.

function scid_position_create_with_san

scid_error scid_position_create_with_san(
    const scid_position * position,
    const char * san,
    scid_position ** out_position
)

Creates a new board position by cloning an existing position and applying a SAN move.

Parameters:

position Pointer to the source board position. Must not be NULL.
san Null-terminated Standard Algebraic Notation move (e.g. "Nf3", "O-O"). Must not be NULL.
out_position Pointer to a handle pointer receiving the newly allocated position. Must not be NULL.

Returns:

SCID_OK Position cloned and move applied successfully.
SCID_ERROR_BAD_ARG If position, san, or out_position is NULL.
SCID_ERROR_INVALID_MOVE If san is illegal or ambiguous in position.

See: scid_position_apply_san()

Leaves the source position unmodified and returns a freshly allocated position reflecting the move.

function scid_position_create_from_fen

scid_error scid_position_create_from_fen(
    const char * fen,
    scid_position ** out_position
)

Creates a new board position initialised from a FEN string.

Parameters:

fen Null-terminated Forsyth–Edwards Notation (FEN) string. Must not be NULL.
out_position Pointer to a handle pointer receiving the newly allocated scid_position instance on success. Must not be NULL.

Returns:

SCID_OK Position created successfully.
SCID_ERROR_BAD_ARG If fen or out_position is NULL.
SCID_ERROR_INVALID_FEN If fen is malformed or invalid.

See:

Note: Ownership of the created position is transferred to the caller. The caller must release it using scid_position_free().

function scid_position_apply_uci

scid_error scid_position_apply_uci(
    scid_position * position,
    const char * uci
)

Applies a coordinate UCI move in-place to the position.

Parameters:

position Pointer to the board position to mutate. Must not be NULL.
uci Null-terminated coordinate UCI move string (e.g. "e2e4", "a7a8q"). Must not be NULL.

Returns:

SCID_OK Move applied successfully.
SCID_ERROR_BAD_ARG If position or uci is NULL.
SCID_ERROR_INVALID_MOVE If uci is illegal in the current position.

See: scid_position_apply_san()

Updates piece positions, active colour, castling rights, en passant state, halfmove clock, and fullmove number.

function scid_position_apply_san

scid_error scid_position_apply_san(
    scid_position * position,
    const char * san
)

Applies a Standard Algebraic Notation (SAN) move in-place to the position.

Parameters:

position Pointer to the board position to mutate. Must not be NULL.
san Null-terminated SAN move string (e.g. "e4", "Nf3", "O-O"). Must not be NULL.

Returns:

SCID_OK Move applied successfully.
SCID_ERROR_BAD_ARG If position or san is NULL.
SCID_ERROR_INVALID_MOVE If san is illegal or ambiguous in the current position.

See: scid_position_apply_uci()

Updates piece positions, active colour, castling rights, en passant state, halfmove clock, and fullmove number.

Macros Documentation

define SCID_POSITION_TYPEDEF

#define SCID_POSITION_TYPEDEF

Updated on 2026-09-02 at 15:26:09 +0000