Database Search Engine

Multi-criteria header filters, position and material pattern queries, board configuration matching, and search execution.

Types

	Name
typedef int()(void user_data)	scid_should_cancel_fn Function pointer type for querying early cooperative cancellation of search execution.
typedef struct scid_search_header_criteria	scid_search_header_criteria Opaque handle representing game header search criteria.
typedef struct scid_search_board_criteria	scid_search_board_criteria Opaque handle representing board pattern and position search criteria.
typedef void()(size_t done, size_t total, const char message, void *user_data)	scid_progress_report_callback Function pointer type for long-running asynchronous progress notifications.
typedef struct scid_database	scid_database Forward declaration of database handle.
enum	scid_board_search_match_modes { SCID_BOARD_SEARCH_MATCH_PAWNS = 1, SCID_BOARD_SEARCH_MATCH_FILES = 2, SCID_BOARD_SEARCH_MATCH_EXACT = 0} Matching algorithms for board configuration search.
typedef int	scid_board_search_match Board search matching mode specifying the strictness of position comparison.

Functions

	Name
scid_error	scid_search_header_criteria_white_set(scid_search_header_criteria * criteria, const char * white) Sets the White player name substring filter.
scid_error	scid_search_header_criteria_white_get(const scid_search_header_criteria * criteria, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves the current White player name filter.
scid_error	scid_search_header_criteria_white_elo_range_set(scid_search_header_criteria * criteria, size_t min, size_t max) Sets the White player Elo rating range filter.
scid_error	scid_search_header_criteria_white_elo_range_get(const scid_search_header_criteria * criteria, size_t * out_min, size_t * out_max) Retrieves the current White Elo rating range filter.
scid_error	scid_search_header_criteria_site_set(scid_search_header_criteria * criteria, const char * site) Sets the Site location substring filter.
scid_error	scid_search_header_criteria_site_get(const scid_search_header_criteria * criteria, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves the current Site location filter.
scid_error	scid_search_header_criteria_site_country_set(scid_search_header_criteria * criteria, const char * site_country) Sets the Site country code filter.
scid_error	scid_search_header_criteria_site_country_get(const scid_search_header_criteria * criteria, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves the current Site country code filter.
scid_error	scid_search_header_criteria_round_set(scid_search_header_criteria * criteria, const char * round) Sets the Round number/identifier filter.
scid_error	scid_search_header_criteria_round_get(const scid_search_header_criteria * criteria, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves the current Round filter.
scid_error	scid_search_header_criteria_result_set(scid_search_header_criteria * criteria, const char * result) Sets the outcome result filter string (`"1-0"`, `"0-1"`, `"1/2-1/2"`, `"="`, `"*"`, or combinations).
scid_error	scid_search_header_criteria_result_get(const scid_search_header_criteria * criteria, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves the current outcome result filter string.
scid_error	scid_search_header_criteria_player_set(scid_search_header_criteria * criteria, const char * player) Sets a player name filter matching either White or Black.
scid_error	scid_search_header_criteria_player_get(const scid_search_header_criteria * criteria, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves the current player name filter.
scid_error	scid_search_header_criteria_has_variations_set(scid_search_header_criteria * criteria, int enabled) Configures the requirement for games containing alternative move variations.
scid_error	scid_search_header_criteria_has_variations_get(const scid_search_header_criteria * criteria, int * out_enabled) Checks if games containing variations are required.
scid_error	scid_search_header_criteria_has_nags_set(scid_search_header_criteria * criteria, int enabled) Configures the requirement for games containing Numeric Annotation Glyphs (NAGs).
scid_error	scid_search_header_criteria_has_nags_get(const scid_search_header_criteria * criteria, int * out_enabled) Checks if games containing NAG annotations are required.
scid_error	scid_search_header_criteria_has_comments_set(scid_search_header_criteria * criteria, int enabled) Configures the requirement for games containing text commentary / annotations.
scid_error	scid_search_header_criteria_has_comments_get(const scid_search_header_criteria * criteria, int * out_enabled) Checks if games containing text commentary are required.
scid_error	scid_search_header_criteria_halfmove_count_range_set(scid_search_header_criteria * criteria, size_t min, size_t max) Sets the game length (halfmove/ply count) range filter.
scid_error	scid_search_header_criteria_halfmove_count_range_get(const scid_search_header_criteria * criteria, size_t * out_min, size_t * out_max) Retrieves the current game length range filter.
scid_error	scid_search_header_criteria_game_number_range_set(scid_search_header_criteria * criteria, size_t min, size_t max) Sets the 1-based sequential game number range filter (`min..max`).
scid_error	scid_search_header_criteria_game_number_range_get(const scid_search_header_criteria * criteria, size_t * out_min, size_t * out_max) Retrieves the current game number range filter.
void	scid_search_header_criteria_free(scid_search_header_criteria * criteria) Releases a header search criteria handle.
scid_error	scid_search_header_criteria_event_set(scid_search_header_criteria * criteria, const char * event) Sets the Event name substring filter.
scid_error	scid_search_header_criteria_event_get(const scid_search_header_criteria * criteria, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves the current Event name filter.
scid_error	scid_search_header_criteria_event_date_range_set(scid_search_header_criteria * criteria, const char * event_date_min, const char * event_date_max) Sets the event date range filter (`"YYYY.MM.DD"`).
scid_error	scid_search_header_criteria_event_date_range_get(const scid_search_header_criteria * criteria, char * out_event_date_min, size_t out_event_date_min_capacity, size_t * out_event_date_min_size, char * out_event_date_max, size_t out_event_date_max_capacity, size_t * out_event_date_max_size) Retrieves the current event date range filter.
scid_error	scid_search_header_criteria_elo_difference_range_set(scid_search_header_criteria * criteria, int min, int max) Sets the Elo difference (`White Elo - Black Elo`) range filter.
scid_error	scid_search_header_criteria_elo_difference_range_get(const scid_search_header_criteria * criteria, int * out_min, int * out_max) Retrieves the current Elo difference range filter.
scid_error	scid_search_header_criteria_eco_range_set(scid_search_header_criteria * criteria, const char * eco_min, const char * eco_max) Sets the ECO code classification range filter (e.g.
scid_error	scid_search_header_criteria_eco_range_get(const scid_search_header_criteria * criteria, char * out_eco_min, size_t out_eco_min_capacity, size_t * out_eco_min_size, char * out_eco_max, size_t out_eco_max_capacity, size_t * out_eco_max_size) Retrieves the current ECO code range filter.
scid_error	scid_search_header_criteria_date_range_set(scid_search_header_criteria * criteria, const char * date_min, const char * date_max) Sets the played date range filter (`"YYYY.MM.DD"`).
scid_error	scid_search_header_criteria_date_range_get(const scid_search_header_criteria * criteria, char * out_date_min, size_t out_date_min_capacity, size_t * out_date_min_size, char * out_date_max, size_t out_date_max_capacity, size_t * out_date_max_size) Retrieves the current played date range filter.
scid_error	scid_search_header_criteria_create(scid_search_header_criteria ** out_criteria) Allocates and initialises a new header search criteria handle with default (unrestricted) values.
scid_error	scid_search_header_criteria_black_set(scid_search_header_criteria * criteria, const char * black) Sets the Black player name substring filter.
scid_error	scid_search_header_criteria_black_get(const scid_search_header_criteria * criteria, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves the current Black player name filter.
scid_error	scid_search_header_criteria_black_elo_range_set(scid_search_header_criteria * criteria, size_t min, size_t max) Sets the Black player Elo rating range filter.
scid_error	scid_search_header_criteria_black_elo_range_get(const scid_search_header_criteria * criteria, size_t * out_min, size_t * out_max) Retrieves the current Black Elo rating range filter.
scid_error	scid_search_board_criteria_position_set(scid_search_board_criteria * criteria, const scid_position * position) Sets the target chess position pattern to search for.
scid_error	scid_search_board_criteria_position_get(const scid_search_board_criteria * criteria, scid_position * out_position) Retrieves the target position pattern configured in the board criteria.
scid_error	scid_search_board_criteria_match_set(scid_search_board_criteria * criteria, scid_board_search_match match) Configures the matching algorithm strictness (scid_board_search_match).
scid_error	scid_search_board_criteria_match_get(const scid_search_board_criteria * criteria, scid_board_search_match * out_match) Retrieves the current board matching mode.
scid_error	scid_search_board_criteria_include_variations_set(scid_search_board_criteria * criteria, int enabled) Configures whether position searches traverse sub-variations in addition to the mainline.
scid_error	scid_search_board_criteria_include_variations_get(const scid_search_board_criteria * criteria, int * out_enabled) Checks if variation traversal is enabled for board search.
scid_error	scid_search_board_criteria_include_flipped_set(scid_search_board_criteria * criteria, int enabled) Configures whether board search matches horizontally/vertically flipped mirror configurations.
scid_error	scid_search_board_criteria_include_flipped_get(const scid_search_board_criteria * criteria, int * out_enabled) Checks if flipped mirror matching is enabled for board search.
void	scid_search_board_criteria_free(scid_search_board_criteria * criteria) Releases a board search criteria handle.
scid_error	scid_search_board_criteria_create(scid_search_board_criteria ** out_criteria) Allocates and initialises a new board search criteria handle with default values.
scid_error	scid_database_search_position(scid_database * database, scid_filter_id source_filter_id, scid_filter_id destination_filter_id, const scid_position * position, scid_progress_report_callback progress_report, void * progress_report_user_data, scid_should_cancel_fn should_cancel, void * should_cancel_user_data) Searches the database for occurrences of an exact board position state.
scid_error	scid_database_search_headers(scid_database * database, scid_filter_id source_filter_id, scid_filter_id destination_filter_id, const scid_search_header_criteria * criteria, scid_progress_report_callback progress_report, void * progress_report_user_data, scid_should_cancel_fn should_cancel, void * should_cancel_user_data) Executes a header metadata search over games in a source filter, populating a destination filter.
scid_error	scid_database_search_board(scid_database * database, scid_filter_id source_filter_id, scid_filter_id destination_filter_id, const scid_search_board_criteria * criteria, scid_progress_report_callback progress_report, void * progress_report_user_data, scid_should_cancel_fn should_cancel, void * should_cancel_user_data) Executes a board pattern / pawn / file configuration search across games in the database.

Types Documentation

typedef scid_should_cancel_fn

typedef int(* scid_should_cancel_fn) (void *user_data);

Function pointer type for querying early cooperative cancellation of search execution.

Parameters:

user_data User context pointer passed to the search function.

Return: Non-zero (1) to request immediate cooperative abort; zero (0) to proceed.

typedef scid_search_header_criteria

typedef struct scid_search_header_criteria scid_search_header_criteria;

Opaque handle representing game header search criteria.

See:

Encapsulates text matchers (player names, events, sites), date/ECO ranges, rating limits, game lengths, results, and structural movetext flags (has comments, variations, NAGs).

typedef scid_search_board_criteria

typedef struct scid_search_board_criteria scid_search_board_criteria;

Opaque handle representing board pattern and position search criteria.

See:

Encapsulates target board layout, match strictness, variation traversal, and color-flipped matching.

typedef scid_progress_report_callback

typedef void(* scid_progress_report_callback) (size_t done, size_t total, const char *message, void *user_data);

Function pointer type for long-running asynchronous progress notifications.

Parameters:

done Count of items completed so far (e.g. games examined).
total Total expected item count, or 0 if unknown.
message Optional descriptive phase message (may be NULL).
user_data User context pointer passed to the search function.

typedef scid_database

typedef struct scid_database scid_database;

Forward declaration of database handle.

See: scid_database

enum scid_board_search_match_modes

Enumerator	Value	Description
SCID_BOARD_SEARCH_MATCH_PAWNS	1	Pawn structure and material: exact pawn placement and matching overall piece balance.
SCID_BOARD_SEARCH_MATCH_FILES	2	File configurations: matching piece count per vertical file.
SCID_BOARD_SEARCH_MATCH_EXACT	0	Exact piece placement: all pieces and pawns on identical squares.

Matching algorithms for board configuration search.

typedef scid_board_search_match

typedef int scid_board_search_match;

Board search matching mode specifying the strictness of position comparison.

Functions Documentation

function scid_search_header_criteria_white_set

scid_error scid_search_header_criteria_white_set(
    scid_search_header_criteria * criteria,
    const char * white
)

Sets the White player name substring filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
white White player substring (or NULL/"" to clear).

Returns:

SCID_OK Filter updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_header_criteria_white_get

scid_error scid_search_header_criteria_white_get(
    const scid_search_header_criteria * criteria,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves the current White player name filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
out_text Caller-allocated buffer receiving the filter string.
out_text_capacity Capacity of out_text in bytes.
out_text_size Pointer receiving bytes written (excluding null terminator), or required capacity. Must not be NULL.

Returns:

SCID_OK Filter string retrieved successfully.
SCID_ERROR_BAD_ARG If criteria or out_text_size is NULL.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

function scid_search_header_criteria_white_elo_range_set

scid_error scid_search_header_criteria_white_elo_range_set(
    scid_search_header_criteria * criteria,
    size_t min,
    size_t max
)

Sets the White player Elo rating range filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
min Minimum Elo rating (0 for unrestricted start).
max Maximum Elo rating (0 for unrestricted end).

Returns:

SCID_OK Range updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_header_criteria_white_elo_range_get

scid_error scid_search_header_criteria_white_elo_range_get(
    const scid_search_header_criteria * criteria,
    size_t * out_min,
    size_t * out_max
)

Retrieves the current White Elo rating range filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
out_min Pointer receiving the minimum White Elo. Must not be NULL.
out_max Pointer receiving the maximum White Elo. Must not be NULL.

Returns:

SCID_OK Range retrieved successfully.
SCID_ERROR_BAD_ARG If any mandatory pointer is NULL.

function scid_search_header_criteria_site_set

scid_error scid_search_header_criteria_site_set(
    scid_search_header_criteria * criteria,
    const char * site
)

Sets the Site location substring filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
site Site substring (or NULL/"" to clear).

Returns:

SCID_OK Filter updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_header_criteria_site_get

scid_error scid_search_header_criteria_site_get(
    const scid_search_header_criteria * criteria,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves the current Site location filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
out_text Caller-allocated buffer receiving the filter string.
out_text_capacity Capacity of out_text in bytes.
out_text_size Pointer receiving bytes written (excluding null terminator), or required capacity. Must not be NULL.

Returns:

SCID_OK Filter string retrieved successfully.
SCID_ERROR_BAD_ARG If criteria or out_text_size is NULL.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

function scid_search_header_criteria_site_country_set

scid_error scid_search_header_criteria_site_country_set(
    scid_search_header_criteria * criteria,
    const char * site_country
)

Sets the Site country code filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
site_country ISO/IOC country code string (or NULL/"" to clear).

Returns:

SCID_OK Filter updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_header_criteria_site_country_get

scid_error scid_search_header_criteria_site_country_get(
    const scid_search_header_criteria * criteria,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves the current Site country code filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
out_text Caller-allocated buffer receiving the country filter string.
out_text_capacity Capacity of out_text in bytes.
out_text_size Pointer receiving bytes written (excluding null terminator), or required capacity. Must not be NULL.

Returns:

SCID_OK Filter string retrieved successfully.
SCID_ERROR_BAD_ARG If criteria or out_text_size is NULL.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

function scid_search_header_criteria_round_set

scid_error scid_search_header_criteria_round_set(
    scid_search_header_criteria * criteria,
    const char * round
)

Sets the Round number/identifier filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
round Round string (or NULL/"" to clear).

Returns:

SCID_OK Filter updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_header_criteria_round_get

scid_error scid_search_header_criteria_round_get(
    const scid_search_header_criteria * criteria,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves the current Round filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
out_text Caller-allocated buffer receiving the round filter string.
out_text_capacity Capacity of out_text in bytes.
out_text_size Pointer receiving bytes written (excluding null terminator), or required capacity. Must not be NULL.

Returns:

SCID_OK Filter string retrieved successfully.
SCID_ERROR_BAD_ARG If criteria or out_text_size is NULL.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

function scid_search_header_criteria_result_set

scid_error scid_search_header_criteria_result_set(
    scid_search_header_criteria * criteria,
    const char * result
)

Sets the outcome result filter string ("1-0", "0-1", "1/2-1/2", "=", "*", or combinations).

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
result Result pattern string (or NULL/"" to clear).

Returns:

SCID_OK Filter updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_header_criteria_result_get

scid_error scid_search_header_criteria_result_get(
    const scid_search_header_criteria * criteria,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves the current outcome result filter string.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
out_text Caller-allocated buffer receiving the result filter.
out_text_capacity Capacity of out_text in bytes.
out_text_size Pointer receiving bytes written (excluding null terminator), or required capacity. Must not be NULL.

Returns:

SCID_OK Filter string retrieved successfully.
SCID_ERROR_BAD_ARG If criteria or out_text_size is NULL.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

function scid_search_header_criteria_player_set

scid_error scid_search_header_criteria_player_set(
    scid_search_header_criteria * criteria,
    const char * player
)

Sets a player name filter matching either White or Black.

Parameters:

criteria Pointer to the header criteria handle. Must not be NULL.
player Player substring pattern (or empty string/NULL to clear).

Returns:

SCID_OK Filter updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_header_criteria_player_get

scid_error scid_search_header_criteria_player_get(
    const scid_search_header_criteria * criteria,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves the current player name filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
out_text Caller-allocated buffer receiving the player filter string. 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 bytes written (excluding null terminator), or required capacity. Must not be NULL.

Returns:

SCID_OK Filter string retrieved successfully.
SCID_ERROR_BAD_ARG If criteria or out_text_size is NULL.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

function scid_search_header_criteria_has_variations_set

scid_error scid_search_header_criteria_has_variations_set(
    scid_search_header_criteria * criteria,
    int enabled
)

Configures the requirement for games containing alternative move variations.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
enabled 1 to require variations; 0 to exclude this requirement.

Returns:

SCID_OK Filter updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_header_criteria_has_variations_get

scid_error scid_search_header_criteria_has_variations_get(
    const scid_search_header_criteria * criteria,
    int * out_enabled
)

Checks if games containing variations are required.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
out_enabled Pointer receiving non-zero (1) if required; zero (0) otherwise. Must not be NULL.

Returns:

SCID_OK Query completed successfully.
SCID_ERROR_BAD_ARG If criteria or out_enabled is NULL.

function scid_search_header_criteria_has_nags_set

scid_error scid_search_header_criteria_has_nags_set(
    scid_search_header_criteria * criteria,
    int enabled
)

Configures the requirement for games containing Numeric Annotation Glyphs (NAGs).

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
enabled 1 to require NAGs; 0 to exclude this requirement.

Returns:

SCID_OK Filter updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_header_criteria_has_nags_get

scid_error scid_search_header_criteria_has_nags_get(
    const scid_search_header_criteria * criteria,
    int * out_enabled
)

Checks if games containing NAG annotations are required.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
out_enabled Pointer receiving non-zero (1) if required; zero (0) otherwise. Must not be NULL.

Returns:

SCID_OK Query completed successfully.
SCID_ERROR_BAD_ARG If criteria or out_enabled is NULL.

function scid_search_header_criteria_has_comments_set

scid_error scid_search_header_criteria_has_comments_set(
    scid_search_header_criteria * criteria,
    int enabled
)

Configures the requirement for games containing text commentary / annotations.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
enabled 1 to require comments; 0 to exclude this requirement.

Returns:

SCID_OK Filter updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_header_criteria_has_comments_get

scid_error scid_search_header_criteria_has_comments_get(
    const scid_search_header_criteria * criteria,
    int * out_enabled
)

Checks if games containing text commentary are required.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
out_enabled Pointer receiving non-zero (1) if required; zero (0) otherwise. Must not be NULL.

Returns:

SCID_OK Query completed successfully.
SCID_ERROR_BAD_ARG If criteria or out_enabled is NULL.

function scid_search_header_criteria_halfmove_count_range_set

scid_error scid_search_header_criteria_halfmove_count_range_set(
    scid_search_header_criteria * criteria,
    size_t min,
    size_t max
)

Sets the game length (halfmove/ply count) range filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
min Minimum halfmove count (0 for unrestricted start).
max Maximum halfmove count (0 for unrestricted end).

Returns:

SCID_OK Range updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_header_criteria_halfmove_count_range_get

scid_error scid_search_header_criteria_halfmove_count_range_get(
    const scid_search_header_criteria * criteria,
    size_t * out_min,
    size_t * out_max
)

Retrieves the current game length range filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
out_min Pointer receiving the minimum halfmove count. Must not be NULL.
out_max Pointer receiving the maximum halfmove count. Must not be NULL.

Returns:

SCID_OK Range retrieved successfully.
SCID_ERROR_BAD_ARG If any mandatory pointer is NULL.

function scid_search_header_criteria_game_number_range_set

scid_error scid_search_header_criteria_game_number_range_set(
    scid_search_header_criteria * criteria,
    size_t min,
    size_t max
)

Sets the 1-based sequential game number range filter (min..max).

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
min Minimum 1-based game number (0 or 1 for unrestricted start).
max Maximum 1-based game number (0 for unrestricted end).

Returns:

SCID_OK Range updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_header_criteria_game_number_range_get

scid_error scid_search_header_criteria_game_number_range_get(
    const scid_search_header_criteria * criteria,
    size_t * out_min,
    size_t * out_max
)

Retrieves the current game number range filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
out_min Pointer receiving the minimum game number. Must not be NULL.
out_max Pointer receiving the maximum game number. Must not be NULL.

Returns:

SCID_OK Range retrieved successfully.
SCID_ERROR_BAD_ARG If any mandatory pointer is NULL.

function scid_search_header_criteria_free

void scid_search_header_criteria_free(
    scid_search_header_criteria * criteria
)

Releases a header search criteria handle.

Parameters:

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

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

function scid_search_header_criteria_event_set

scid_error scid_search_header_criteria_event_set(
    scid_search_header_criteria * criteria,
    const char * event
)

Sets the Event name substring filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
event Event substring (or NULL/"" to clear).

Returns:

SCID_OK Filter updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_header_criteria_event_get

scid_error scid_search_header_criteria_event_get(
    const scid_search_header_criteria * criteria,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves the current Event name filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
out_text Caller-allocated buffer receiving the filter string.
out_text_capacity Capacity of out_text in bytes.
out_text_size Pointer receiving bytes written (excluding null terminator), or required capacity. Must not be NULL.

Returns:

SCID_OK Filter string retrieved successfully.
SCID_ERROR_BAD_ARG If criteria or out_text_size is NULL.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

function scid_search_header_criteria_event_date_range_set

scid_error scid_search_header_criteria_event_date_range_set(
    scid_search_header_criteria * criteria,
    const char * event_date_min,
    const char * event_date_max
)

Sets the event date range filter ("YYYY.MM.DD").

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
event_date_min Minimum event date (or NULL/"" for open lower bound).
event_date_max Maximum event date (or NULL/"" for open upper bound).

Returns:

SCID_OK Range updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_header_criteria_event_date_range_get

scid_error scid_search_header_criteria_event_date_range_get(
    const scid_search_header_criteria * criteria,
    char * out_event_date_min,
    size_t out_event_date_min_capacity,
    size_t * out_event_date_min_size,
    char * out_event_date_max,
    size_t out_event_date_max_capacity,
    size_t * out_event_date_max_size
)

Retrieves the current event date range filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
out_event_date_min Caller-allocated buffer receiving the minimum event date.
out_event_date_min_capacity Capacity of out_event_date_min in bytes.
out_event_date_min_size Pointer receiving min event date bytes written. Must not be NULL.
out_event_date_max Caller-allocated buffer receiving the maximum event date.
out_event_date_max_capacity Capacity of out_event_date_max in bytes.
out_event_date_max_size Pointer receiving max event date bytes written. Must not be NULL.

Returns:

SCID_OK Range retrieved successfully.
SCID_ERROR_BAD_ARG If any mandatory pointer is NULL.
SCID_ERROR_BUFFER_FULL If either buffer capacity is insufficient.

function scid_search_header_criteria_elo_difference_range_set

scid_error scid_search_header_criteria_elo_difference_range_set(
    scid_search_header_criteria * criteria,
    int min,
    int max
)

Sets the Elo difference (White Elo - Black Elo) range filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
min Minimum Elo difference (signed integer, e.g. -400).
max Maximum Elo difference (signed integer, e.g. +400).

Returns:

SCID_OK Range updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_header_criteria_elo_difference_range_get

scid_error scid_search_header_criteria_elo_difference_range_get(
    const scid_search_header_criteria * criteria,
    int * out_min,
    int * out_max
)

Retrieves the current Elo difference range filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
out_min Pointer receiving the minimum Elo difference. Must not be NULL.
out_max Pointer receiving the maximum Elo difference. Must not be NULL.

Returns:

SCID_OK Range retrieved successfully.
SCID_ERROR_BAD_ARG If any mandatory pointer is NULL.

function scid_search_header_criteria_eco_range_set

scid_error scid_search_header_criteria_eco_range_set(
    scid_search_header_criteria * criteria,
    const char * eco_min,
    const char * eco_max
)

Sets the ECO code classification range filter (e.g.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
eco_min Minimum ECO code string (or NULL/"" for "A00").
eco_max Maximum ECO code string (or NULL/"" for "E99").

Returns:

SCID_OK Range updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

"B00" to "B99").

function scid_search_header_criteria_eco_range_get

scid_error scid_search_header_criteria_eco_range_get(
    const scid_search_header_criteria * criteria,
    char * out_eco_min,
    size_t out_eco_min_capacity,
    size_t * out_eco_min_size,
    char * out_eco_max,
    size_t out_eco_max_capacity,
    size_t * out_eco_max_size
)

Retrieves the current ECO code range filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
out_eco_min Caller-allocated buffer receiving the minimum ECO code.
out_eco_min_capacity Capacity of out_eco_min in bytes.
out_eco_min_size Pointer receiving min ECO bytes written. Must not be NULL.
out_eco_max Caller-allocated buffer receiving the maximum ECO code.
out_eco_max_capacity Capacity of out_eco_max in bytes.
out_eco_max_size Pointer receiving max ECO bytes written. Must not be NULL.

Returns:

SCID_OK Range retrieved successfully.
SCID_ERROR_BAD_ARG If any mandatory pointer is NULL.
SCID_ERROR_BUFFER_FULL If either buffer capacity is insufficient.

function scid_search_header_criteria_date_range_set

scid_error scid_search_header_criteria_date_range_set(
    scid_search_header_criteria * criteria,
    const char * date_min,
    const char * date_max
)

Sets the played date range filter ("YYYY.MM.DD").

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
date_min Minimum date (or NULL/"" for open lower bound).
date_max Maximum date (or NULL/"" for open upper bound).

Returns:

SCID_OK Range updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_header_criteria_date_range_get

scid_error scid_search_header_criteria_date_range_get(
    const scid_search_header_criteria * criteria,
    char * out_date_min,
    size_t out_date_min_capacity,
    size_t * out_date_min_size,
    char * out_date_max,
    size_t out_date_max_capacity,
    size_t * out_date_max_size
)

Retrieves the current played date range filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
out_date_min Caller-allocated buffer receiving the minimum date string.
out_date_min_capacity Capacity of out_date_min in bytes.
out_date_min_size Pointer receiving min date bytes written. Must not be NULL.
out_date_max Caller-allocated buffer receiving the maximum date string.
out_date_max_capacity Capacity of out_date_max in bytes.
out_date_max_size Pointer receiving max date bytes written. Must not be NULL.

Returns:

SCID_OK Range retrieved successfully.
SCID_ERROR_BAD_ARG If any mandatory pointer is NULL.
SCID_ERROR_BUFFER_FULL If either buffer capacity is insufficient.

function scid_search_header_criteria_create

scid_error scid_search_header_criteria_create(
    scid_search_header_criteria ** out_criteria
)

Allocates and initialises a new header search criteria handle with default (unrestricted) values.

Parameters:

out_criteria Pointer receiving the newly allocated criteria handle. Must not be NULL.

Returns:

SCID_OK Handle allocated successfully.
SCID_ERROR_BAD_ARG If out_criteria is NULL.

Note: The caller acquires ownership of out_criteria and must release it with scid_search_header_criteria_free().

function scid_search_header_criteria_black_set

scid_error scid_search_header_criteria_black_set(
    scid_search_header_criteria * criteria,
    const char * black
)

Sets the Black player name substring filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
black Black player substring (or NULL/"" to clear).

Returns:

SCID_OK Filter updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_header_criteria_black_get

scid_error scid_search_header_criteria_black_get(
    const scid_search_header_criteria * criteria,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves the current Black player name filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
out_text Caller-allocated buffer receiving the filter string.
out_text_capacity Capacity of out_text in bytes.
out_text_size Pointer receiving bytes written (excluding null terminator), or required capacity. Must not be NULL.

Returns:

SCID_OK Filter string retrieved successfully.
SCID_ERROR_BAD_ARG If criteria or out_text_size is NULL.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

function scid_search_header_criteria_black_elo_range_set

scid_error scid_search_header_criteria_black_elo_range_set(
    scid_search_header_criteria * criteria,
    size_t min,
    size_t max
)

Sets the Black player Elo rating range filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
min Minimum Elo rating (0 for unrestricted start).
max Maximum Elo rating (0 for unrestricted end).

Returns:

SCID_OK Range updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_header_criteria_black_elo_range_get

scid_error scid_search_header_criteria_black_elo_range_get(
    const scid_search_header_criteria * criteria,
    size_t * out_min,
    size_t * out_max
)

Retrieves the current Black Elo rating range filter.

Parameters:

criteria Pointer to the header criteria. Must not be NULL.
out_min Pointer receiving the minimum Black Elo. Must not be NULL.
out_max Pointer receiving the maximum Black Elo. Must not be NULL.

Returns:

SCID_OK Range retrieved successfully.
SCID_ERROR_BAD_ARG If any mandatory pointer is NULL.

function scid_search_board_criteria_position_set

scid_error scid_search_board_criteria_position_set(
    scid_search_board_criteria * criteria,
    const scid_position * position
)

Sets the target chess position pattern to search for.

Parameters:

criteria Pointer to the board criteria. Must not be NULL.
position Pointer to the target position entity. Must not be NULL.

Returns:

SCID_OK Position pattern updated successfully.
SCID_ERROR_BAD_ARG If criteria or position is NULL.

function scid_search_board_criteria_position_get

scid_error scid_search_board_criteria_position_get(
    const scid_search_board_criteria * criteria,
    scid_position * out_position
)

Retrieves the target position pattern configured in the board criteria.

Parameters:

criteria Pointer to the board criteria. Must not be NULL.
out_position Pointer to an allocated scid_position receiving the copied state. Must not be NULL.

Returns:

SCID_OK Position copied successfully.
SCID_ERROR_BAD_ARG If criteria or out_position is NULL.

function scid_search_board_criteria_match_set

scid_error scid_search_board_criteria_match_set(
    scid_search_board_criteria * criteria,
    scid_board_search_match match
)

Configures the matching algorithm strictness (scid_board_search_match).

Parameters:

criteria Pointer to the board criteria. Must not be NULL.
match Matching mode (SCID_BOARD_SEARCH_MATCH_EXACT, SCID_BOARD_SEARCH_MATCH_PAWNS, or SCID_BOARD_SEARCH_MATCH_FILES).

Returns:

SCID_OK Match mode updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL or match is invalid.

function scid_search_board_criteria_match_get

scid_error scid_search_board_criteria_match_get(
    const scid_search_board_criteria * criteria,
    scid_board_search_match * out_match
)

Retrieves the current board matching mode.

Parameters:

criteria Pointer to the board criteria. Must not be NULL.
out_match Pointer receiving the scid_board_search_match value. Must not be NULL.

Returns:

SCID_OK Query completed successfully.
SCID_ERROR_BAD_ARG If criteria or out_match is NULL.

function scid_search_board_criteria_include_variations_set

scid_error scid_search_board_criteria_include_variations_set(
    scid_search_board_criteria * criteria,
    int enabled
)

Configures whether position searches traverse sub-variations in addition to the mainline.

Parameters:

criteria Pointer to the board criteria. Must not be NULL.
enabled 1 to search inside variations; 0 for mainline only.

Returns:

SCID_OK Setting updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_board_criteria_include_variations_get

scid_error scid_search_board_criteria_include_variations_get(
    const scid_search_board_criteria * criteria,
    int * out_enabled
)

Checks if variation traversal is enabled for board search.

Parameters:

criteria Pointer to the board criteria. Must not be NULL.
out_enabled Pointer receiving non-zero (1) if enabled; zero (0) otherwise. Must not be NULL.

Returns:

SCID_OK Query completed successfully.
SCID_ERROR_BAD_ARG If criteria or out_enabled is NULL.

function scid_search_board_criteria_include_flipped_set

scid_error scid_search_board_criteria_include_flipped_set(
    scid_search_board_criteria * criteria,
    int enabled
)

Configures whether board search matches horizontally/vertically flipped mirror configurations.

Parameters:

criteria Pointer to the board criteria. Must not be NULL.
enabled 1 to match flipped board configurations; 0 for standard orientation only.

Returns:

SCID_OK Setting updated successfully.
SCID_ERROR_BAD_ARG If criteria is NULL.

function scid_search_board_criteria_include_flipped_get

scid_error scid_search_board_criteria_include_flipped_get(
    const scid_search_board_criteria * criteria,
    int * out_enabled
)

Checks if flipped mirror matching is enabled for board search.

Parameters:

criteria Pointer to the board criteria. Must not be NULL.
out_enabled Pointer receiving non-zero (1) if enabled; zero (0) otherwise. Must not be NULL.

Returns:

SCID_OK Query completed successfully.
SCID_ERROR_BAD_ARG If criteria or out_enabled is NULL.

function scid_search_board_criteria_free

void scid_search_board_criteria_free(
    scid_search_board_criteria * criteria
)

Releases a board search criteria handle.

Parameters:

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

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

function scid_search_board_criteria_create

scid_error scid_search_board_criteria_create(
    scid_search_board_criteria ** out_criteria
)

Allocates and initialises a new board search criteria handle with default values.

Parameters:

out_criteria Pointer receiving the newly allocated criteria handle. Must not be NULL.

Returns:

SCID_OK Handle allocated successfully.
SCID_ERROR_BAD_ARG If out_criteria is NULL.

Note: The caller acquires ownership of out_criteria and must release it with scid_search_board_criteria_free().

function scid_database_search_position

scid_error scid_database_search_position(
    scid_database * database,
    scid_filter_id source_filter_id,
    scid_filter_id destination_filter_id,
    const scid_position * position,
    scid_progress_report_callback progress_report,
    void * progress_report_user_data,
    scid_should_cancel_fn should_cancel,
    void * should_cancel_user_data
)

Searches the database for occurrences of an exact board position state.

Parameters:

database Pointer to the open database. Must not be NULL.
source_filter_id Filter ID restricting games to scan.
destination_filter_id Filter ID to receive matching game indices.
position Target chess position to match. Must not be NULL.
progress_report Optional progress callback (may be NULL).
progress_report_user_data Context pointer passed to progress_report.
should_cancel Optional cancellation callback (may be NULL).
should_cancel_user_data Context pointer passed to should_cancel.

Returns:

SCID_OK Search executed successfully.
SCID_ERROR_BAD_ARG If database or position is NULL, or filter IDs are invalid.
SCID_ERROR_CANCEL If search was aborted early by should_cancel.

function scid_database_search_headers

scid_error scid_database_search_headers(
    scid_database * database,
    scid_filter_id source_filter_id,
    scid_filter_id destination_filter_id,
    const scid_search_header_criteria * criteria,
    scid_progress_report_callback progress_report,
    void * progress_report_user_data,
    scid_should_cancel_fn should_cancel,
    void * should_cancel_user_data
)

Executes a header metadata search over games in a source filter, populating a destination filter.

Parameters:

database Pointer to the open database. Must not be NULL.
source_filter_id Filter ID restricting games to scan (scid_filter_id).
destination_filter_id Filter ID to receive matching game indices.
criteria Pointer to configured header search criteria. Must not be NULL.
progress_report Optional callback for progress notifications (may be NULL).
progress_report_user_data Context pointer passed to progress_report.
should_cancel Optional cancellation callback (may be NULL).
should_cancel_user_data Context pointer passed to should_cancel.

Returns:

SCID_OK Search executed successfully.
SCID_ERROR_BAD_ARG If database or criteria is NULL, or filter IDs are invalid.
SCID_ERROR_CANCEL If search was aborted early by should_cancel.

function scid_database_search_board

scid_error scid_database_search_board(
    scid_database * database,
    scid_filter_id source_filter_id,
    scid_filter_id destination_filter_id,
    const scid_search_board_criteria * criteria,
    scid_progress_report_callback progress_report,
    void * progress_report_user_data,
    scid_should_cancel_fn should_cancel,
    void * should_cancel_user_data
)

Executes a board pattern / pawn / file configuration search across games in the database.

Parameters:

database Pointer to the open database. Must not be NULL.
source_filter_id Filter ID restricting games to scan.
destination_filter_id Filter ID to receive matching game indices.
criteria Configured board search criteria. Must not be NULL.
progress_report Optional progress callback (may be NULL).
progress_report_user_data Context pointer passed to progress_report.
should_cancel Optional cancellation callback (may be NULL).
should_cancel_user_data Context pointer passed to should_cancel.

Returns:

SCID_OK Search executed successfully.
SCID_ERROR_BAD_ARG If database or criteria is NULL, or filter IDs are invalid.
SCID_ERROR_CANCEL If search was aborted early by should_cancel.

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