Move Representation & Codecs

Chess move specification value type, UCI codecs, and SAN notation parser/formatter.

Classes

	Name
struct	scid_movespec Move specification record.

Types

	Name
typedef struct scid_position	scid_position Forward declaration of position handle.
typedef struct scid_movespec	scid_movespec Move specification record.

Functions

	Name
scid_error	scid_movespec_to_uci(scid_movespec move, char * out_text, size_t out_text_capacity, size_t * out_text_size) Formats a move specification as a coordinate UCI string.
scid_error	scid_movespec_to_san(const scid_position * position, scid_movespec move, char * out_text, size_t out_text_capacity, size_t * out_text_size) Formats a move specification as Standard Algebraic Notation (SAN).
scid_error	scid_movespec_create_from_uci(const char * text, scid_movespec * out_move) Parses a coordinate UCI string into a move specification.
scid_error	scid_movespec_create_from_san(const scid_position * position, const char * text, scid_movespec * out_move) Parses a Standard Algebraic Notation (SAN) string into a move specification.
scid_error	scid_movespec_create(scid_square from, scid_square to, scid_piece promotion, int is_castling, scid_movespec * out_move) Constructs a move specification value from raw primitives.

Types Documentation

typedef scid_position

typedef struct scid_position scid_position;

Forward declaration of position handle.

See: scid_position

typedef scid_movespec

typedef struct scid_movespec scid_movespec;

Move specification record.

See:

A self-contained, register-passable value type representing a move from an origin square to a destination square, along with the moving piece, captured piece, optional pawn promotion piece, and castling flag. It is passed by value across the C API.

A null move (used in chess engine analysis and pass-turn variants) is represented with from == 0, to == 0, promotion == SCID_PIECE_NONE, and is_castling == 0.

Functions Documentation

function scid_movespec_to_uci

scid_error scid_movespec_to_uci(
    scid_movespec move,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Formats a move specification as a coordinate UCI string.

Parameters:

move The move specification to format.
out_text Caller-allocated buffer receiving the null-terminated UCI string. May be NULL if out_text_capacity is 0 to query required capacity.
out_text_capacity Capacity of out_text in bytes (at least 6 bytes recommended).
out_text_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 UCI string formatted successfully.
SCID_ERROR_BAD_ARG If out_text_size is NULL, or if move contains an invalid square index or unsupported promotion piece.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

See: scid_movespec_create_from_uci()

Emits coordinate notation such as "e2e4", "a7a8q", or "0000" (null move) into the caller-provided buffer.

function scid_movespec_to_san

scid_error scid_movespec_to_san(
    const scid_position * position,
    scid_movespec move,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Formats a move specification as Standard Algebraic Notation (SAN).

Parameters:

position Pointer to the board position context. Must not be NULL.
move The move specification to format.
out_text Caller-allocated buffer receiving the null-terminated SAN string. May be NULL if out_text_capacity is 0 to query required capacity.
out_text_capacity Capacity of out_text in bytes (at least 10 bytes recommended).
out_text_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 SAN string formatted successfully.
SCID_ERROR_BAD_ARG If position or out_text_size is NULL, or if move contains invalid square or promotion values.
SCID_ERROR_INVALID_MOVE If move is not a legal move in the given position.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

See: scid_movespec_create_from_san()

Generates standard chess notation (e.g. "Nf3", "exd5", "O-O", "Rad1", "e8=Q#") including necessary piece disambiguation, capture indicators (x), checks (+), and checkmates (#) evaluated against the board position.

function scid_movespec_create_from_uci

scid_error scid_movespec_create_from_uci(
    const char * text,
    scid_movespec * out_move
)

Parses a coordinate UCI string into a move specification.

Parameters:

text Null-terminated ASCII/UTF-8 UCI move string. Must not be NULL.
out_move Pointer to the scid_movespec receiving the parsed move. Must not be NULL.

Returns:

SCID_OK UCI string parsed successfully.
SCID_ERROR_BAD_ARG If text or out_move is NULL, or if the string syntax is malformed (invalid coordinates, illegal length, or unrecognised promotion character).

See: scid_movespec_to_uci()

Parses standard coordinate notation such as "e2e4", "a7a8q", or the null move "0000". UCI moves are purely coordinate-based and do not require a board position context for disambiguation.

function scid_movespec_create_from_san

scid_error scid_movespec_create_from_san(
    const scid_position * position,
    const char * text,
    scid_movespec * out_move
)

Parses a Standard Algebraic Notation (SAN) string into a move specification.

Parameters:

position Pointer to the board position context. Must not be NULL.
text Null-terminated ASCII/UTF-8 SAN move string. Must not be NULL.
out_move Pointer to the scid_movespec receiving the parsed move. Must not be NULL.

Returns:

SCID_OK SAN move parsed and validated successfully.
SCID_ERROR_BAD_ARG If position, text, or out_move is NULL.
SCID_ERROR_INVALID_MOVE If the move text is unrecognised, ambiguous, or illegal in the given position.

See: scid_movespec_to_san()

Resolves standard chess notation (e.g. "Nf3", "exd5", "O-O", "Rad1", "e8=Q#") against the provided board position to establish legal move disambiguation.

function scid_movespec_create

scid_error scid_movespec_create(
    scid_square from,
    scid_square to,
    scid_piece promotion,
    int is_castling,
    scid_movespec * out_move
)

Constructs a move specification value from raw primitives.

Parameters:

from Origin square index (0..63).
to Destination square index (0..63).
promotion Promotion piece type or SCID_PIECE_NONE.
is_castling Non-zero if the move is a castling move; 0 otherwise.
out_move Pointer to the scid_movespec receiving the initialised struct. Must not be NULL.

Returns:

SCID_OK Move specification initialised successfully.
SCID_ERROR_BAD_ARG If out_move is NULL.

See:

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