ECO Classification

Opening classification, ECO code codecs, and opening book lookup.

Types

	Name
enum	scid_eco_formats { SCID_ECO_FORMAT_EXTENDED = 1, SCID_ECO_FORMAT_BASIC = 0} ECO string format specifiers.
typedef int	scid_eco_format Output formatting mode for ECO code string serialisation.
enum	scid_eco_constants { SCID_ECO_STRING_CAPACITY = 6, SCID_ECO_NONE = 0} ECO code constants and capacity limits.
typedef unsigned short	scid_eco_code Compact numeric representation of an ECO opening code.
typedef struct scid_eco_book	scid_eco_book Opaque handle representing a loaded ECO opening classification book.

Functions

	Name
scid_error	scid_eco_code_to_string(scid_eco_code code, scid_eco_format format, char * out_text, size_t out_text_capacity, size_t * out_text_size) Formats a numeric ECO code into an alphanumeric string.
scid_error	scid_eco_code_from_string(const char * text, scid_eco_code * out_code) Parses an alphanumeric ECO string into a compact numeric ECO code.
scid_error	scid_eco_book_name_find(const scid_eco_book * book, const scid_position * position, char * out_text, size_t out_text_capacity, size_t * out_text_size) Looks up the opening name corresponding to an exact board position.
scid_error	scid_eco_book_load(const char * path, scid_eco_book ** out_book) Loads an ECO classification book from a file on disk.
void	scid_eco_book_free(scid_eco_book * book) Releases an ECO classification book handle and all associated memory.
scid_error	scid_eco_book_code_find(const scid_eco_book * book, const scid_position * position, scid_eco_code * out_code) Looks up the ECO code corresponding to an exact board position.

Types Documentation

enum scid_eco_formats

Enumerator	Value	Description
SCID_ECO_FORMAT_EXTENDED	1	Extended format including optional sub-variation suffixes (e.g. "B91a4", "C50a").
SCID_ECO_FORMAT_BASIC	0	Basic 3-character format without sub-variations (e.g. "B20", "C84").

ECO string format specifiers.

typedef scid_eco_format

typedef int scid_eco_format;

Output formatting mode for ECO code string serialisation.

enum scid_eco_constants

Enumerator	Value	Description
SCID_ECO_STRING_CAPACITY	6	Maximum buffer size required to store any formatted ECO code string including null terminator.
SCID_ECO_NONE	0	Sentinel value indicating no ECO classification or an unclassified position.

ECO code constants and capacity limits.

typedef scid_eco_code

typedef unsigned short scid_eco_code;

Compact numeric representation of an ECO opening code.

See:

Encodes standard alphanumeric opening classifications (such as "B20" or "C50a1") into a compact 16-bit integer value suitable for storage, sorting, and indexing.

typedef scid_eco_book

typedef struct scid_eco_book scid_eco_book;

Opaque handle representing a loaded ECO opening classification book.

See:

Note: Instances are thread-safe for concurrent read-only queries (scid_eco_book_code_find() and scid_eco_book_name_find()).

An ECO book contains position-to-code and position-to-name mapping tables loaded from a Scid .eco database file on disk.

Instances are loaded using scid_eco_book_load() and must be released when no longer needed using scid_eco_book_free().

Functions Documentation

function scid_eco_code_to_string

scid_error scid_eco_code_to_string(
    scid_eco_code code,
    scid_eco_format format,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Formats a numeric ECO code into an alphanumeric string.

Parameters:

code The numeric ECO code to format.
format Formatting mode (SCID_ECO_FORMAT_BASIC or SCID_ECO_FORMAT_EXTENDED).
out_text Caller-allocated buffer receiving the null-terminated 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 SCID_ECO_STRING_CAPACITY 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 String formatted successfully.
SCID_ERROR_BAD_ARG If format is invalid or out_text_size is NULL.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

See: scid_eco_code_from_string()

Note: If code is SCID_ECO_NONE, an empty string "" with size 0 is emitted.

Writes the formatted code into the caller-provided buffer according to the requested formatting style (format).

function scid_eco_code_from_string

scid_error scid_eco_code_from_string(
    const char * text,
    scid_eco_code * out_code
)

Parses an alphanumeric ECO string into a compact numeric ECO code.

Parameters:

text Null-terminated ASCII/UTF-8 ECO string. Must not be NULL.
out_code Pointer to the scid_eco_code receiving the parsed code value. Must not be NULL.

Returns:

SCID_OK String parsed successfully.
SCID_ERROR_BAD_ARG If text or out_code is NULL.

See: scid_eco_code_to_string()

Converts standard notation such as "B20" or "C50a1" into a scid_eco_code. If the input string is not a valid ECO designator, SCID_ECO_NONE is written to out_code and SCID_OK is returned.

function scid_eco_book_name_find

scid_error scid_eco_book_name_find(
    const scid_eco_book * book,
    const scid_position * position,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Looks up the opening name corresponding to an exact board position.

Parameters:

book Pointer to the loaded ECO book. Must not be NULL.
position Pointer to the board position to classify. Must not be NULL.
out_text Caller-allocated buffer receiving the null-terminated opening name. 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 Lookup completed successfully.
SCID_ERROR_BAD_ARG If book, position, or out_text_size is NULL.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

See: scid_eco_book_code_find()

Searches the loaded opening book for an exact match of the given board state and writes the opening name string (e.g. "Sicilian Defence", "Italian Game") into out_text. If the position is not classified, an empty string "" is written.

function scid_eco_book_load

scid_error scid_eco_book_load(
    const char * path,
    scid_eco_book ** out_book
)

Loads an ECO classification book from a file on disk.

Parameters:

path Path to the .eco book file on disk. Must not be NULL.
out_book Pointer to a handle pointer receiving the newly allocated scid_eco_book instance on success. Must not be NULL.

Returns:

SCID_OK Book successfully loaded.
SCID_ERROR_BAD_ARG If path or out_book is NULL.
SCID_ERROR_FILE_OPEN If the file does not exist or cannot be opened.
SCID_ERROR_CORRUPT If file parsing fails due to syntax corruption.

See: scid_eco_book_free()

Note: Ownership of the loaded book is transferred to the caller. The caller must release it using scid_eco_book_free().

Reads and parses a Scid .eco book file, indexing all defined position entries for fast lookup.

function scid_eco_book_free

void scid_eco_book_free(
    scid_eco_book * book
)

Releases an ECO classification book handle and all associated memory.

Parameters:

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

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

function scid_eco_book_code_find

scid_error scid_eco_book_code_find(
    const scid_eco_book * book,
    const scid_position * position,
    scid_eco_code * out_code
)

Looks up the ECO code corresponding to an exact board position.

Parameters:

book Pointer to the loaded ECO book. Must not be NULL.
position Pointer to the board position to classify. Must not be NULL.
out_code Pointer receiving the matching numeric ECO code, or SCID_ECO_NONE if unclassified. Must not be NULL.

Returns:

SCID_OK Lookup completed successfully.
SCID_ERROR_BAD_ARG If book, position, or out_code is NULL.

See: scid_eco_book_name_find()

Searches the loaded opening book for an exact match of the given board state. If the position is not present in the book, SCID_ECO_NONE is written to out_code.

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