Database Filters & Sorting

Dynamic game filtering, selection bitsets, multi-criteria sorting, and paginated row mapping.

Types

	Name
typedef int	scid_filter_id Numeric identifier for a database game filter / subset view.
enum	scid_filter_constants { SCID_FILTER_PRIMARY = -2, SCID_FILTER_ALL_GAMES = -1} Special filter constants for universal and primary database views.
typedef struct scid_database	scid_database Forward declaration of database handle.

Functions

	Name
scid_error	scid_database_filter_game_row_for_index_get(const scid_database * database, scid_filter_id filter_id, const char * sort_criteria, size_t game_index, size_t * out_row) Translates a database game index to its display row position under the sorted filter.
scid_error	scid_database_filter_game_indices_get(const scid_database * database, scid_filter_id filter_id, const char * sort_criteria, size_t start_row, size_t row_count, size_t * out_game_indices, size_t out_game_indices_capacity, size_t * out_game_indices_count) Retrieves a contiguous window of sorted game indices matching a filter.
scid_error	scid_database_filter_game_index_at_row_get(const scid_database * database, scid_filter_id filter_id, const char * sort_criteria, size_t row, size_t * out_game_index) Translates a sorted display row index to its underlying database game index.
scid_error	scid_database_filter_game_count_get(const scid_database * database, scid_filter_id filter_id, size_t * out_count) Retrieves the number of games currently matched by the filter.
scid_error	scid_database_filter_delete(scid_database * database, scid_filter_id filter_id) Deletes a previously created user filter and releases its resources.
scid_error	scid_database_filter_create(scid_database * database, scid_filter_id * out_filter_id) Allocates and registers a new, empty user filter within the database.

Types Documentation

typedef scid_filter_id

typedef int scid_filter_id;

Numeric identifier for a database game filter / subset view.

User-created filters have positive integer identifiers (> 0). Predefined pseudo-filters use negative sentinel values (SCID_FILTER_ALL_GAMES, SCID_FILTER_PRIMARY).

enum scid_filter_constants

Enumerator	Value	Description
SCID_FILTER_PRIMARY	-2	Primary default filter used for interactive search results and active selections.
SCID_FILTER_ALL_GAMES	-1	Pseudo-filter matching all games in the database without exclusion.

Special filter constants for universal and primary database views.

typedef scid_database

typedef struct scid_database scid_database;

Forward declaration of database handle.

See: scid_database

Functions Documentation

function scid_database_filter_game_row_for_index_get

scid_error scid_database_filter_game_row_for_index_get(
    const scid_database * database,
    scid_filter_id filter_id,
    const char * sort_criteria,
    size_t game_index,
    size_t * out_row
)

Translates a database game index to its display row position under the sorted filter.

Parameters:

database Pointer to the database. Must not be NULL.
filter_id Filter identifier to query.
sort_criteria Sort criteria string. Must not be NULL.
game_index Zero-based database game index to look up.
out_row Pointer receiving the 0-based sorted display row position. Must not be NULL.

Returns:

SCID_OK Translation completed successfully.
SCID_ERROR_BAD_ARG If any mandatory pointer is NULL, or game_index is not in the filter.

See: scid_database_filter_game_index_at_row_get()

function scid_database_filter_game_indices_get

scid_error scid_database_filter_game_indices_get(
    const scid_database * database,
    scid_filter_id filter_id,
    const char * sort_criteria,
    size_t start_row,
    size_t row_count,
    size_t * out_game_indices,
    size_t out_game_indices_capacity,
    size_t * out_game_indices_count
)

Retrieves a contiguous window of sorted game indices matching a filter.

Parameters:

database Pointer to the database. Must not be NULL.
filter_id Filter identifier to query.
sort_criteria Sort criteria string (e.g. "", "Date", "White", "ECO"). Must not be NULL.
start_row Zero-based starting row in the sorted filter view.
row_count Requested number of rows to retrieve.
out_game_indices Caller-allocated array receiving the 0-based database game indices. Must hold at least row_count elements.
out_game_indices_capacity Capacity of out_game_indices in elements.
out_game_indices_count Pointer receiving the actual number of indices written. Must not be NULL.

Returns:

SCID_OK Game indices retrieved successfully.
SCID_ERROR_BAD_ARG If any mandatory pointer is NULL, or filter_id is invalid.
SCID_ERROR_BUFFER_FULL If out_game_indices_capacity is less than row_count.

Allows paginated display of database views according to custom sort criteria (e.g. "", "Date", "White", "ECO").

function scid_database_filter_game_index_at_row_get

scid_error scid_database_filter_game_index_at_row_get(
    const scid_database * database,
    scid_filter_id filter_id,
    const char * sort_criteria,
    size_t row,
    size_t * out_game_index
)

Translates a sorted display row index to its underlying database game index.

Parameters:

database Pointer to the database. Must not be NULL.
filter_id Filter identifier to query.
sort_criteria Sort criteria string. Must not be NULL.
row Zero-based sorted row position to look up.
out_game_index Pointer receiving the 0-based database game index. Must not be NULL.

Returns:

SCID_OK Translation completed successfully.
SCID_ERROR_BAD_ARG If any mandatory pointer is NULL, or row is out of range.

See: scid_database_filter_game_row_for_index_get()

function scid_database_filter_game_count_get

scid_error scid_database_filter_game_count_get(
    const scid_database * database,
    scid_filter_id filter_id,
    size_t * out_count
)

Retrieves the number of games currently matched by the filter.

Parameters:

database Pointer to the database. Must not be NULL.
filter_id Filter identifier to query (scid_filter_id).
out_count Pointer receiving the matched game count. Must not be NULL.

Returns:

SCID_OK Count retrieved successfully.
SCID_ERROR_BAD_ARG If database or out_count is NULL, or filter_id is invalid.

function scid_database_filter_delete

scid_error scid_database_filter_delete(
    scid_database * database,
    scid_filter_id filter_id
)

Deletes a previously created user filter and releases its resources.

Parameters:

database Pointer to the open database. Must not be NULL.
filter_id Identifier of the user filter to delete (> 0).

Returns:

SCID_OK Filter deleted successfully.
SCID_ERROR_BAD_ARG If database is NULL, filter_id is invalid (<= 0), or filter is not found.

See: scid_database_filter_create()

Predefined filters (SCID_FILTER_ALL_GAMES, SCID_FILTER_PRIMARY) cannot be deleted.

function scid_database_filter_create

scid_error scid_database_filter_create(
    scid_database * database,
    scid_filter_id * out_filter_id
)

Allocates and registers a new, empty user filter within the database.

Parameters:

database Pointer to the open database. Must not be NULL.
out_filter_id Pointer receiving the newly assigned positive filter ID. Must not be NULL.

Returns:

SCID_OK Filter created successfully.
SCID_ERROR_BAD_ARG If database or out_filter_id is NULL, or database is closed.

See: scid_database_filter_delete()

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