Primitive Types & Error Codes

Foundational scalar types, error return codes, chess colours, squares, pieces, and NAG annotations.

Types

	Name
typedef unsigned	scid_square Board square coordinate index (0..63, corresponding to a1..h8).
enum	scid_piece_type { SCID_PIECE_WHITE_ROOK = 3, SCID_PIECE_WHITE_QUEEN = 2, SCID_PIECE_WHITE_PAWN = 6, SCID_PIECE_WHITE_KNIGHT = 5, SCID_PIECE_WHITE_KING = 1, SCID_PIECE_WHITE_BISHOP = 4, SCID_PIECE_ROOK = 3, SCID_PIECE_QUEEN = 2, SCID_PIECE_PAWN = 6, SCID_PIECE_NONE = 0, SCID_PIECE_KNIGHT = 5, SCID_PIECE_KING = 1, SCID_PIECE_BLACK_ROOK = 11, SCID_PIECE_BLACK_QUEEN = 10, SCID_PIECE_BLACK_PAWN = 14, SCID_PIECE_BLACK_KNIGHT = 13, SCID_PIECE_BLACK_KING = 9, SCID_PIECE_BLACK_BISHOP = 12, SCID_PIECE_BISHOP = 4} Chess piece enumerators.
typedef unsigned	scid_piece Chess piece type indicator.
typedef unsigned char	scid_nag Numeric Annotation Glyph (NAG) code (1..255).
enum	scid_error_code { SCID_WARNING_NAME_DATA_LOSS = 206, SCID_OK = 0, SCID_ERROR_USER_CANCEL = 2, SCID_ERROR_INVALID_MOVE = 302, SCID_ERROR_INVALID_FEN = 301, SCID_ERROR_FILE_READ_ONLY = 111, SCID_ERROR_FILE_OPEN = 101, SCID_ERROR_CORRUPT = 152, SCID_ERROR_BUFFER_FULL = 601, SCID_ERROR_BAD_ARG = 3, SCID_ERROR = 1} Status and error code enumerators.
typedef unsigned short	scid_error Numeric status code returned by public API functions.
enum	scid_colour_type { SCID_WHITE = 0, SCID_BLACK = 1} Player colour enumerators.
typedef int	scid_colour Player colour indicator.

Functions

	Name
scid_error	scid_square_to_string(scid_square square, char * out_text, size_t out_text_capacity, size_t * out_text_size) Formats a square index into a two-character coordinate string.
scid_error	scid_square_from_string(const char * text, scid_square * out_square) Parses standard two-character coordinate string into a square index.
scid_error	scid_piece_type_from_string(const char * text, scid_piece * out_piece) Parses a single character piece symbol into an uncoloured piece kind.
scid_error	scid_nag_to_string(scid_nag nag, int as_symbol, char * out_text, size_t out_text_capacity, size_t * out_text_size) Formats a NAG code as a dollar string or typographical symbol.
scid_error	scid_nag_create_from_string(const char * text, scid_nag * out_nag) Parses a NAG string or glyph symbol into a numeric NAG code.
int	scid_is_warning(scid_error status) Evaluates whether a status code represents a non-fatal, recoverable warning.
int	scid_is_error(scid_error status) Evaluates whether a status code represents a fatal failure.

Types Documentation

typedef scid_square

typedef unsigned scid_square;

Board square coordinate index (0..63, corresponding to a1..h8).

Squares are ordered rank by rank from a1 (0) to h8 (63):

• a1 = 0, b1 = 1, ..., h1 = 7
• a2 = 8, b2 = 9, ..., h2 = 15
• ...
• a8 = 56, b8 = 57, ..., h8 = 63

enum scid_piece_type

Enumerator	Value	Description
SCID_PIECE_WHITE_ROOK	3	White Rook.
SCID_PIECE_WHITE_QUEEN	2	White Queen.
SCID_PIECE_WHITE_PAWN	6	White Pawn.
SCID_PIECE_WHITE_KNIGHT	5	White Knight.
SCID_PIECE_WHITE_KING	1	White King.
SCID_PIECE_WHITE_BISHOP	4	White Bishop.
SCID_PIECE_ROOK	3	Uncoloured Rook.
SCID_PIECE_QUEEN	2	Uncoloured Queen.
SCID_PIECE_PAWN	6	Uncoloured Pawn.
SCID_PIECE_NONE	0	Empty square or absence of a piece.
SCID_PIECE_KNIGHT	5	Uncoloured Knight.
SCID_PIECE_KING	1	Uncoloured King.
SCID_PIECE_BLACK_ROOK	11	Black Rook.
SCID_PIECE_BLACK_QUEEN	10	Black Queen.
SCID_PIECE_BLACK_PAWN	14	Black Pawn.
SCID_PIECE_BLACK_KNIGHT	13	Black Knight.
SCID_PIECE_BLACK_KING	9	Black King.
SCID_PIECE_BLACK_BISHOP	12	Black Bishop.
SCID_PIECE_BISHOP	4	Uncoloured Bishop.

Chess piece enumerators.

typedef scid_piece

typedef unsigned scid_piece;

Chess piece type indicator.

Represents uncoloured piece kinds (1..6), white pieces (1..6), or black pieces (9..14).

typedef scid_nag

typedef unsigned char scid_nag;

Numeric Annotation Glyph (NAG) code (1..255).

Represents move evaluations (e.g. ! = 1, ? = 2, !! = 3, ?? = 4, !? = 5, ?! = 6) and positional assessments according to the PGN standard.

enum scid_error_code

Enumerator	Value	Description
SCID_WARNING_NAME_DATA_LOSS	206	Non-fatal warning: database was opened in degraded mode due to unresolvable name records. The database handle is valid and populated for read-only inspection. Direct mutations are rejected until the database is compacted or repaired.
SCID_OK	0	Operation completed successfully.
SCID_ERROR_USER_CANCEL	2	Operation was cancelled by user request or progress callback.
SCID_ERROR_INVALID_MOVE	302	Move is illegal in current position or not recognized.
SCID_ERROR_INVALID_FEN	301	Malformed or syntactically invalid Forsyth–Edwards Notation (FEN) string.
SCID_ERROR_FILE_READ_ONLY	111	Attempted write operation on a read-only database or file.
SCID_ERROR_FILE_OPEN	101	Failed to open specified file on disk.
SCID_ERROR_CORRUPT	152	Corrupted database index, header, or data record encountered.
SCID_ERROR_BUFFER_FULL	601	Destination buffer capacity is insufficient to receive output text or items.
SCID_ERROR_BAD_ARG	3	Invalid argument or NULL pointer supplied to function.
SCID_ERROR	1	Generic unspecified error occurred.

Status and error code enumerators.

typedef scid_error

typedef unsigned short scid_error;

Numeric status code returned by public API functions.

A value of SCID_OK indicates complete success. Warning codes (such as SCID_WARNING_NAME_DATA_LOSS) indicate that an operation succeeded in a degraded but usable state. Error codes represent fatal failures.

enum scid_colour_type

Enumerator	Value	Description
SCID_WHITE	0	White player.
SCID_BLACK	1	Black player.

Player colour enumerators.

typedef scid_colour

typedef int scid_colour;

Player colour indicator.

Functions Documentation

function scid_square_to_string

scid_error scid_square_to_string(
    scid_square square,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Formats a square index into a two-character coordinate string.

Parameters:

• square Square index to format (0..63).
• out_text Caller-allocated buffer receiving the null-terminated coordinate string (e.g. "e4"). May be NULL if out_text_capacity is 0 to probe required size.
• out_text_capacity Capacity of out_text in bytes (at least 3 bytes recommended).
• out_text_size Pointer receiving bytes written (excluding null terminator), or required capacity. Must not be NULL.

Returns:

• SCID_OK Square formatted successfully.
• SCID_ERROR_BAD_ARG If square is out of range (> 63) or out_text_size is NULL.
• SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

See: scid_square_from_string()

function scid_square_from_string

scid_error scid_square_from_string(
    const char * text,
    scid_square * out_square
)

Parses standard two-character coordinate string into a square index.

Parameters:

• text Null-terminated coordinate string (e.g. "e4", "a1", "h8"). Must not be NULL.
• out_square Pointer receiving the parsed square index (0..63). Must not be NULL.

Returns:

• SCID_OK Coordinate parsed successfully.
• SCID_ERROR_BAD_ARG If text or out_square is NULL, or if syntax is not a valid square name.

See: scid_square_to_string()

function scid_piece_type_from_string

scid_error scid_piece_type_from_string(
    const char * text,
    scid_piece * out_piece
)

Parses a single character piece symbol into an uncoloured piece kind.

Parameters:

• text Null-terminated single-character string (e.g. "Q", "n"). Must not be NULL.
• out_piece Pointer receiving the parsed uncoloured piece type. Must not be NULL.

Returns:

• SCID_OK Piece parsed successfully.
• SCID_ERROR_BAD_ARG If text or out_piece is NULL, or character is unrecognised.

Recognises standard English piece letters ("'K,'Q','R','B','N','P'`, case-insensitive).

function scid_nag_to_string

scid_error scid_nag_to_string(
    scid_nag nag,
    int as_symbol,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Formats a NAG code as a dollar string or typographical symbol.

Parameters:

• nag The NAG code to format (1..255).
• as_symbol Non-zero to format as typographical glyph (e.g. "!", "+="), or zero to emit dollar notation (e.g. "$1", "$14").
• out_text Caller-allocated buffer receiving the null-terminated formatted text. May be NULL if out_text_capacity is 0 to query required capacity.
• out_text_capacity Capacity of out_text in bytes.
• 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 NAG formatted successfully.
• SCID_ERROR_BAD_ARG If out_text_size is NULL.
• SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

See: scid_nag_create_from_string()

function scid_nag_create_from_string

scid_error scid_nag_create_from_string(
    const char * text,
    scid_nag * out_nag
)

Parses a NAG string or glyph symbol into a numeric NAG code.

Parameters:

• text Null-terminated NAG string or symbol. Must not be NULL.
• out_nag Pointer receiving the parsed NAG code (1..255). Must not be NULL.

Returns:

• SCID_OK NAG parsed successfully.
• SCID_ERROR_BAD_ARG If text or out_nag is NULL, or if the string is unrecognised.

See: scid_nag_to_string()

Accepts numeric strings (e.g. "$1", "1"), punctuation glyphs (e.g. "!", "?", "!?"), or standard symbol annotations (e.g. "+=", "-+", "=\\"</tt>, <tt>"D").

function scid_is_warning

int scid_is_warning(
    scid_error status
)

Evaluates whether a status code represents a non-fatal, recoverable warning.

Parameters:

• status Status code to inspect.

Return: Non-zero (1) if status is a warning; zero (0) otherwise.

function scid_is_error

int scid_is_error(
    scid_error status
)

Evaluates whether a status code represents a fatal failure.

Parameters:

• status Status code to inspect.

Return: Non-zero (1) if status is a fatal error; zero (0) otherwise.

---

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