Game Movetext Cursor

Hierarchical movetext tree traversal, ply positioning, commentary, NAG annotations, and variation manipulation.

Types

	Name
typedef struct scid_game_cursor	scid_game_cursor Opaque handle representing a navigational position within a game's movetext tree.
typedef struct scid_game	scid_game

Functions

	Name
scid_error	scid_game_cursor_variation_promote_to_mainline(scid_game * game, const scid_game_cursor * cursor, int * out_promoted, scid_game_cursor ** out_mainline_cursor) Promotes the current sub-variation all the way up to become the new mainline of the game.
scid_error	scid_game_cursor_variation_promote_to_first(scid_game * game, const scid_game_cursor * cursor, int * out_promoted, scid_game_cursor ** out_promoted_cursor) Promotes the current sub-variation to become the first (primary) variation at its fork.
scid_error	scid_game_cursor_variation_index_get(const scid_game_cursor * cursor, size_t * out_index) Retrieves the index of the current variation among sibling variations at the parent fork.
scid_error	scid_game_cursor_variation_exit(const scid_game_cursor * cursor, int * out_exited, scid_game_cursor ** out_parent_cursor) Exits the current sub-variation back to its parent line.
scid_error	scid_game_cursor_variation_enter(const scid_game_cursor * cursor, size_t index, int * out_entered, scid_game_cursor ** out_variation_cursor) Enters a sub-variation branching from the current position.
scid_error	scid_game_cursor_variation_depth_get(const scid_game_cursor * cursor, size_t * out_depth) Retrieves the variation nesting depth at this cursor node.
scid_error	scid_game_cursor_variation_delete(scid_game * game, const scid_game_cursor * cursor, int * out_deleted, scid_game_cursor ** out_parent_cursor) Deletes the current sub-variation and all its descendant moves from the game tree.
scid_error	scid_game_cursor_variation_count_get(const scid_game_cursor * cursor, size_t * out_count) Retrieves the number of sub-variations branching from the upcoming move at this cursor node.
scid_error	scid_game_cursor_variation_add(scid_game * game, const scid_game_cursor * cursor, const char * initial_comment, int * out_added, scid_game_cursor ** out_variation_cursor) Creates a new sub-variation branching from the current position.
scid_error	scid_game_cursor_truncate_before_cursor(scid_game * game, const scid_game_cursor * cursor, scid_game_cursor ** out_cursor) Truncates the beginning of the current line by removing all moves preceding the cursor position.
scid_error	scid_game_cursor_truncate(scid_game * game, const scid_game_cursor * cursor, scid_game_cursor ** out_cursor) Truncates the current line by removing all moves subsequent to the cursor position.
scid_error	scid_game_cursor_to_start(const scid_game_cursor * cursor, scid_game_cursor ** out_start_cursor) Creates a new cursor positioned at the beginning of the entire game.
scid_error	scid_game_cursor_to_ply(const scid_game_cursor * cursor, size_t ply, int * out_moved, scid_game_cursor ** out_ply_cursor) Creates a new cursor positioned at a specified ply within the current line.
scid_error	scid_game_cursor_to_end(const scid_game_cursor * cursor, scid_game_cursor ** out_end_cursor) Creates a new cursor positioned at the end of the mainline.
scid_error	scid_game_cursor_previous_movespec_get(const scid_game_cursor * cursor, scid_movespec * out_move) Retrieves the incoming move (leading into this cursor node) as a scid_movespec.
scid_error	scid_game_cursor_previous_move_san_get(const scid_game_cursor * cursor, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves the incoming move formatted in Standard Algebraic Notation (SAN).
scid_error	scid_game_cursor_previous_move_nag_count_get(const scid_game_cursor * cursor, size_t * out_count) Retrieves the count of Numeric Annotation Glyphs (NAGs) attached to the incoming move.
scid_error	scid_game_cursor_previous_move_nag_at_get(const scid_game_cursor * cursor, size_t index, scid_nag * out_nag) Retrieves a NAG code from the incoming move by zero-based index.
scid_error	scid_game_cursor_previous_move_comment_get(const scid_game_cursor * cursor, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves commentary text attached to the incoming move.
scid_error	scid_game_cursor_previous(const scid_game_cursor * cursor, int * out_moved, scid_game_cursor ** out_previous_cursor) Steps one ply backward towards the start of the current line.
scid_error	scid_game_cursor_position_get(const scid_game_cursor * cursor, scid_position * out_position) Populates a board position handle with the board state at the cursor location.
scid_error	scid_game_cursor_ply_get(const scid_game_cursor * cursor, size_t * out_ply) Retrieves the 0-based ply count from the start of the current line to this cursor node.
scid_error	scid_game_cursor_next_movespec_get(const scid_game_cursor * cursor, scid_movespec * out_move) Retrieves the upcoming move (departing from this cursor node) as a scid_movespec.
scid_error	scid_game_cursor_next_move_san_get(const scid_game_cursor * cursor, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves the upcoming move formatted in Standard Algebraic Notation (SAN).
scid_error	scid_game_cursor_next_move_nag_count_get(const scid_game_cursor * cursor, size_t * out_count) Retrieves the count of Numeric Annotation Glyphs (NAGs) attached to the upcoming move.
scid_error	scid_game_cursor_next_move_nag_at_get(const scid_game_cursor * cursor, size_t index, scid_nag * out_nag) Retrieves a NAG code from the upcoming move by zero-based index.
scid_error	scid_game_cursor_next_move_comment_get(const scid_game_cursor * cursor, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves commentary text attached to the upcoming move.
scid_error	scid_game_cursor_next(const scid_game_cursor * cursor, int * out_moved, scid_game_cursor ** out_next_cursor) Advances one ply forward along the current line.
scid_error	scid_game_cursor_nag_remove(scid_game * game, const scid_game_cursor * cursor, int is_move_nag, int * out_removed) Removes a NAG annotation from the incoming move.
scid_error	scid_game_cursor_nag_clear(scid_game * game, const scid_game_cursor * cursor) Removes all NAG annotations from the incoming move.
scid_error	scid_game_cursor_nag_add(scid_game * game, const scid_game_cursor * cursor, scid_nag nag, int * out_added) Adds a Numeric Annotation Glyph (NAG) to the incoming move.
scid_error	scid_game_cursor_move_add(scid_game * game, const scid_game_cursor * cursor, scid_movespec move, scid_game_cursor ** out_next_cursor) Appends a chess move to the current line at the cursor position.
scid_error	scid_game_cursor_is_variation_start(const scid_game_cursor * cursor, int * out_is_variation_start) Checks if the cursor is at the starting position of a sub-variation (depth > 0).
scid_error	scid_game_cursor_is_variation_end(const scid_game_cursor * cursor, int * out_is_variation_end) Checks if the cursor is at the terminal end of a sub-variation (depth > 0).
scid_error	scid_game_cursor_is_variation_empty(const scid_game_cursor * cursor, int * out_is_variation_empty) Checks if the current variation contains zero moves (empty branch containing only comments).
scid_error	scid_game_cursor_is_line_start(const scid_game_cursor * cursor, int * out_is_line_start) Checks if the cursor is at the beginning of the current line or variation.
scid_error	scid_game_cursor_is_line_end(const scid_game_cursor * cursor, int * out_is_line_end) Checks if the cursor is at the terminal end of the current line or variation (no subsequent move).
scid_error	scid_game_cursor_is_game_start(const scid_game_cursor * cursor, int * out_is_game_start) Checks if the cursor is at the very beginning of the entire game (start of mainline).
scid_error	scid_game_cursor_is_game_end(const scid_game_cursor * cursor, int * out_is_game_end) Checks if the cursor is at the final position of the mainline.
void	scid_game_cursor_free(scid_game_cursor * cursor) Releases a cursor handle and all associated resources.
scid_error	scid_game_cursor_create(scid_game * game, scid_game_cursor ** out_cursor) Creates a new cursor initialised at the starting position of a game.
scid_error	scid_game_cursor_comment_set(scid_game * game, const scid_game_cursor * cursor, const char * comment) Sets or updates the commentary text at the current cursor node.
scid_error	scid_game_cursor_comment_get(const scid_game_cursor * cursor, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves commentary text attached directly to the current cursor position.
scid_error	scid_game_cursor_clone(scid_game * game, const scid_game_cursor * source_cursor, scid_game_cursor ** out_cursor) Clones an existing cursor to duplicate its exact location within the game tree.

Types Documentation

typedef scid_game_cursor

typedef struct scid_game_cursor scid_game_cursor;

Opaque handle representing a navigational position within a game's movetext tree.

See:

Points to a specific node (ply, mainline or sub-variation branch) inside a scid_game. Navigation operations produce newly allocated cursors pointing to target locations, maintaining immutable value semantics for cursor traversal.

Cursors are created using scid_game_cursor_create() or navigation functions, and must be released when no longer needed using scid_game_cursor_free().

typedef scid_game

typedef struct scid_game scid_game;

Functions Documentation

function scid_game_cursor_variation_promote_to_mainline

scid_error scid_game_cursor_variation_promote_to_mainline(
    scid_game * game,
    const scid_game_cursor * cursor,
    int * out_promoted,
    scid_game_cursor ** out_mainline_cursor
)

Promotes the current sub-variation all the way up to become the new mainline of the game.

Parameters:

game Pointer to the game to mutate. Must not be NULL.
cursor Pointer to the cursor in the variation to promote. Must not be NULL.
out_promoted Pointer receiving non-zero (1) if promoted; 0 if already on mainline. Must not be NULL.
out_mainline_cursor Pointer to a handle pointer receiving a newly allocated cursor at the equivalent position in the new mainline on success. Must not be NULL.

Returns:

SCID_OK Promotion completed successfully.
SCID_ERROR_BAD_ARG If any argument is NULL.

See: scid_game_cursor_variation_promote_to_first()

Note: The caller acquires ownership of out_mainline_cursor and must release it with scid_game_cursor_free().

The former mainline is converted into a sub-variation branching from the same position.

function scid_game_cursor_variation_promote_to_first

scid_error scid_game_cursor_variation_promote_to_first(
    scid_game * game,
    const scid_game_cursor * cursor,
    int * out_promoted,
    scid_game_cursor ** out_promoted_cursor
)

Promotes the current sub-variation to become the first (primary) variation at its fork.

Parameters:

game Pointer to the game to mutate. Must not be NULL.
cursor Pointer to the cursor in the variation to promote. Must not be NULL.
out_promoted Pointer receiving non-zero (1) if promoted; 0 if already first or mainline. Must not be NULL.
out_promoted_cursor Pointer to a handle pointer receiving a newly allocated cursor at the equivalent position in the promoted variation on success. Must not be NULL.

Returns:

SCID_OK Promotion completed successfully.
SCID_ERROR_BAD_ARG If any argument is NULL.

See: scid_game_cursor_variation_promote_to_mainline()

Note: The caller acquires ownership of out_promoted_cursor and must release it with scid_game_cursor_free().

function scid_game_cursor_variation_index_get

scid_error scid_game_cursor_variation_index_get(
    const scid_game_cursor * cursor,
    size_t * out_index
)

Retrieves the index of the current variation among sibling variations at the parent fork.

Parameters:

cursor Pointer to the cursor. Must not be NULL.
out_index Pointer receiving the sibling variation index. Must not be NULL.

Returns:

SCID_OK Index retrieved successfully.
SCID_ERROR_BAD_ARG If cursor or out_index is NULL.

Returns 0 if the cursor is on the first variation (or mainline), 1 for the second variation, etc.

function scid_game_cursor_variation_exit

scid_error scid_game_cursor_variation_exit(
    const scid_game_cursor * cursor,
    int * out_exited,
    scid_game_cursor ** out_parent_cursor
)

Exits the current sub-variation back to its parent line.

Parameters:

cursor Pointer to the source cursor in the variation. Must not be NULL.
out_exited Pointer receiving non-zero (1) if exited; 0 if already on mainline. Must not be NULL.
out_parent_cursor Pointer to a handle pointer receiving the newly allocated parent cursor. Must not be NULL.

Returns:

SCID_OK Operation completed successfully.
SCID_ERROR_BAD_ARG If any argument is NULL.

See: scid_game_cursor_variation_enter()

Note: The caller acquires ownership of out_parent_cursor and must release it with scid_game_cursor_free().

Returns a cursor positioned at the fork node in the parent line.

function scid_game_cursor_variation_enter

scid_error scid_game_cursor_variation_enter(
    const scid_game_cursor * cursor,
    size_t index,
    int * out_entered,
    scid_game_cursor ** out_variation_cursor
)

Enters a sub-variation branching from the current position.

Parameters:

cursor Pointer to the source cursor at the branching node. Must not be NULL.
index Zero-based index of the sub-variation to enter (0..variation_count - 1).
out_entered Pointer receiving non-zero (1) if variation entered; 0 if index is invalid. Must not be NULL.
out_variation_cursor Pointer to a handle pointer receiving the newly allocated cursor at the start of the sub-variation. Must not be NULL.

Returns:

SCID_OK Operation completed successfully.
SCID_ERROR_BAD_ARG If any argument is NULL.

See:

Note: The caller acquires ownership of out_variation_cursor and must release it with scid_game_cursor_free().

function scid_game_cursor_variation_depth_get

scid_error scid_game_cursor_variation_depth_get(
    const scid_game_cursor * cursor,
    size_t * out_depth
)

Retrieves the variation nesting depth at this cursor node.

Parameters:

cursor Pointer to the cursor. Must not be NULL.
out_depth Pointer receiving the nesting depth. Must not be NULL.

Returns:

SCID_OK Depth retrieved successfully.
SCID_ERROR_BAD_ARG If cursor or out_depth is NULL.

Returns 0 for the mainline, 1 for direct sub-variations off the mainline, 2 for variations within variations, etc.

function scid_game_cursor_variation_delete

scid_error scid_game_cursor_variation_delete(
    scid_game * game,
    const scid_game_cursor * cursor,
    int * out_deleted,
    scid_game_cursor ** out_parent_cursor
)

Deletes the current sub-variation and all its descendant moves from the game tree.

Parameters:

game Pointer to the game to mutate. Must not be NULL.
cursor Pointer to the cursor inside the variation to delete. Must not be NULL.
out_deleted Pointer receiving non-zero (1) if deleted; 0 if on mainline. Must not be NULL.
out_parent_cursor Pointer to a handle pointer receiving a newly allocated cursor positioned at the parent fork node on success. Must not be NULL.

Returns:

SCID_OK Deletion completed successfully.
SCID_ERROR_BAD_ARG If any argument is NULL.

See: scid_game_cursor_variation_add()

Note: The caller acquires ownership of out_parent_cursor and must release it with scid_game_cursor_free().

function scid_game_cursor_variation_count_get

scid_error scid_game_cursor_variation_count_get(
    const scid_game_cursor * cursor,
    size_t * out_count
)

Retrieves the number of sub-variations branching from the upcoming move at this cursor node.

Parameters:

cursor Pointer to the cursor. Must not be NULL.
out_count Pointer receiving the number of branching variations. Must not be NULL.

Returns:

SCID_OK Count retrieved successfully.
SCID_ERROR_BAD_ARG If cursor or out_count is NULL.

See: scid_game_cursor_variation_enter()

function scid_game_cursor_variation_add

scid_error scid_game_cursor_variation_add(
    scid_game * game,
    const scid_game_cursor * cursor,
    const char * initial_comment,
    int * out_added,
    scid_game_cursor ** out_variation_cursor
)

Creates a new sub-variation branching from the current position.

Parameters:

game Pointer to the game to mutate. Must not be NULL.
cursor Pointer to the cursor at the branch point. Must not be NULL.
initial_comment Optional comment attached to the start of the variation (may be NULL).
out_added Pointer receiving non-zero (1) if variation was created; 0 otherwise. Must not be NULL.
out_variation_cursor Pointer to a handle pointer receiving a newly allocated cursor at the start of the new variation on success. Must not be NULL.

Returns:

SCID_OK Variation created successfully.
SCID_ERROR_BAD_ARG If game, cursor, out_added, or out_variation_cursor is NULL, or if cursor is at the end of the line.

See: scid_game_cursor_variation_delete()

Note: The caller acquires ownership of out_variation_cursor and must release it with scid_game_cursor_free().

Requires the cursor to have an upcoming move to branch away from.

function scid_game_cursor_truncate_before_cursor

scid_error scid_game_cursor_truncate_before_cursor(
    scid_game * game,
    const scid_game_cursor * cursor,
    scid_game_cursor ** out_cursor
)

Truncates the beginning of the current line by removing all moves preceding the cursor position.

Parameters:

game Pointer to the game to mutate. Must not be NULL.
cursor Pointer to the cursor indicating the new start node. Must not be NULL.
out_cursor Pointer to a handle pointer receiving a newly allocated cursor at the new start position. Must not be NULL.

Returns:

SCID_OK Truncation completed successfully.
SCID_ERROR_BAD_ARG If any argument is NULL.

See: scid_game_cursor_truncate()

Note: The caller acquires ownership of out_cursor and must release it with scid_game_cursor_free().

Sets the starting position of the line or game to the board state at the cursor.

function scid_game_cursor_truncate

scid_error scid_game_cursor_truncate(
    scid_game * game,
    const scid_game_cursor * cursor,
    scid_game_cursor ** out_cursor
)

Truncates the current line by removing all moves subsequent to the cursor position.

Parameters:

game Pointer to the game to mutate. Must not be NULL.
cursor Pointer to the cursor indicating the truncation point. Must not be NULL.
out_cursor Pointer to a handle pointer receiving a newly allocated cursor at the new terminal position. Must not be NULL.

Returns:

SCID_OK Truncation completed successfully.
SCID_ERROR_BAD_ARG If any argument is NULL.

See: scid_game_cursor_truncate_before_cursor()

Note: The caller acquires ownership of out_cursor and must release it with scid_game_cursor_free().

function scid_game_cursor_to_start

scid_error scid_game_cursor_to_start(
    const scid_game_cursor * cursor,
    scid_game_cursor ** out_start_cursor
)

Creates a new cursor positioned at the beginning of the entire game.

Parameters:

cursor Pointer to the source cursor. Must not be NULL.
out_start_cursor Pointer to a handle pointer receiving the newly allocated cursor. Must not be NULL.

Returns:

SCID_OK Cursor created successfully.
SCID_ERROR_BAD_ARG If cursor or out_start_cursor is NULL.

See: scid_game_cursor_to_end()

Note: The caller acquires ownership of out_start_cursor and must release it with scid_game_cursor_free().

function scid_game_cursor_to_ply

scid_error scid_game_cursor_to_ply(
    const scid_game_cursor * cursor,
    size_t ply,
    int * out_moved,
    scid_game_cursor ** out_ply_cursor
)

Creates a new cursor positioned at a specified ply within the current line.

Parameters:

cursor Pointer to the source cursor. Must not be NULL.
ply Target 0-based ply index within the line.
out_moved Pointer receiving non-zero (1) if navigation succeeded; 0 if ply is out of range. Must not be NULL.
out_ply_cursor Pointer to a handle pointer receiving the newly allocated cursor on success. Must not be NULL.

Returns:

SCID_OK Navigation completed successfully.
SCID_ERROR_BAD_ARG If any argument is NULL.

Note: The caller acquires ownership of out_ply_cursor and must release it with scid_game_cursor_free().

function scid_game_cursor_to_end

scid_error scid_game_cursor_to_end(
    const scid_game_cursor * cursor,
    scid_game_cursor ** out_end_cursor
)

Creates a new cursor positioned at the end of the mainline.

Parameters:

cursor Pointer to the source cursor. Must not be NULL.
out_end_cursor Pointer to a handle pointer receiving the newly allocated cursor. Must not be NULL.

Returns:

SCID_OK Cursor created successfully.
SCID_ERROR_BAD_ARG If cursor or out_end_cursor is NULL.

See: scid_game_cursor_to_start()

Note: The caller acquires ownership of out_end_cursor and must release it with scid_game_cursor_free().

function scid_game_cursor_previous_movespec_get

scid_error scid_game_cursor_previous_movespec_get(
    const scid_game_cursor * cursor,
    scid_movespec * out_move
)

Retrieves the incoming move (leading into this cursor node) as a scid_movespec.

Parameters:

cursor Pointer to the cursor. Must not be NULL.
out_move Pointer receiving the previous move specification. Must not be NULL.

Returns:

SCID_OK Move retrieved successfully.
SCID_ERROR_BAD_ARG If cursor or out_move is NULL, or if cursor is at line start.

See: scid_game_cursor_next_movespec_get()

function scid_game_cursor_previous_move_san_get

scid_error scid_game_cursor_previous_move_san_get(
    const scid_game_cursor * cursor,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves the incoming move formatted in Standard Algebraic Notation (SAN).

Parameters:

cursor Pointer to the cursor. Must not be NULL.
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.
out_text_size Pointer receiving bytes written (excluding null terminator), or required capacity. Must not be NULL.

Returns:

SCID_OK SAN string retrieved successfully.
SCID_ERROR_BAD_ARG If cursor or out_text_size is NULL, or if cursor is at line start.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

See: scid_game_cursor_next_move_san_get()

function scid_game_cursor_previous_move_nag_count_get

scid_error scid_game_cursor_previous_move_nag_count_get(
    const scid_game_cursor * cursor,
    size_t * out_count
)

Retrieves the count of Numeric Annotation Glyphs (NAGs) attached to the incoming move.

Parameters:

cursor Pointer to the cursor. Must not be NULL.
out_count Pointer receiving the NAG count. Must not be NULL.

Returns:

SCID_OK Count retrieved successfully.
SCID_ERROR_BAD_ARG If cursor or out_count is NULL, or if cursor is at line start.

See: scid_game_cursor_previous_move_nag_at_get()

function scid_game_cursor_previous_move_nag_at_get

scid_error scid_game_cursor_previous_move_nag_at_get(
    const scid_game_cursor * cursor,
    size_t index,
    scid_nag * out_nag
)

Retrieves a NAG code from the incoming move by zero-based index.

Parameters:

cursor Pointer to the cursor. Must not be NULL.
index Zero-based index of the NAG to retrieve.
out_nag Pointer receiving the scid_nag code. Must not be NULL.

Returns:

SCID_OK NAG retrieved successfully.
SCID_ERROR_BAD_ARG If cursor or out_nag is NULL, or if index is out of bounds.

See: scid_game_cursor_previous_move_nag_count_get()

function scid_game_cursor_previous_move_comment_get

scid_error scid_game_cursor_previous_move_comment_get(
    const scid_game_cursor * cursor,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves commentary text attached to the incoming move.

Parameters:

cursor Pointer to the cursor. Must not be NULL.
out_text Caller-allocated buffer receiving the null-terminated comment 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 Comment retrieved successfully.
SCID_ERROR_BAD_ARG If cursor or out_text_size is NULL, or if cursor is at line start.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

function scid_game_cursor_previous

scid_error scid_game_cursor_previous(
    const scid_game_cursor * cursor,
    int * out_moved,
    scid_game_cursor ** out_previous_cursor
)

Steps one ply backward towards the start of the current line.

Parameters:

cursor Pointer to the source cursor. Must not be NULL.
out_moved Pointer receiving non-zero (1) if stepped backward; 0 if already at line start. Must not be NULL.
out_previous_cursor Pointer to a handle pointer receiving the newly allocated cursor on success. Must not be NULL.

Returns:

SCID_OK Step completed successfully.
SCID_ERROR_BAD_ARG If any argument is NULL.

See: scid_game_cursor_next()

Note: The caller acquires ownership of out_previous_cursor and must release it with scid_game_cursor_free().

function scid_game_cursor_position_get

scid_error scid_game_cursor_position_get(
    const scid_game_cursor * cursor,
    scid_position * out_position
)

Populates a board position handle with the board state at the cursor location.

Parameters:

cursor Pointer to the cursor. Must not be NULL.
out_position Pointer to an existing scid_position handle to populate. Must not be NULL.

Returns:

SCID_OK Position populated successfully.
SCID_ERROR_BAD_ARG If cursor or out_position is NULL.
SCID_ERROR_INVALID_MOVE If the game contains an invalid move leading up to this node.

function scid_game_cursor_ply_get

scid_error scid_game_cursor_ply_get(
    const scid_game_cursor * cursor,
    size_t * out_ply
)

Retrieves the 0-based ply count from the start of the current line to this cursor node.

Parameters:

cursor Pointer to the cursor. Must not be NULL.
out_ply Pointer receiving the ply index. Must not be NULL.

Returns:

SCID_OK Ply count retrieved successfully.
SCID_ERROR_BAD_ARG If cursor or out_ply is NULL.

function scid_game_cursor_next_movespec_get

scid_error scid_game_cursor_next_movespec_get(
    const scid_game_cursor * cursor,
    scid_movespec * out_move
)

Retrieves the upcoming move (departing from this cursor node) as a scid_movespec.

Parameters:

cursor Pointer to the cursor. Must not be NULL.
out_move Pointer receiving the next move specification. Must not be NULL.

Returns:

SCID_OK Move retrieved successfully.
SCID_ERROR_BAD_ARG If cursor or out_move is NULL, or if cursor is at line end.

See: scid_game_cursor_previous_movespec_get()

function scid_game_cursor_next_move_san_get

scid_error scid_game_cursor_next_move_san_get(
    const scid_game_cursor * cursor,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves the upcoming move formatted in Standard Algebraic Notation (SAN).

Parameters:

cursor Pointer to the cursor. Must not be NULL.
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.
out_text_size Pointer receiving bytes written (excluding null terminator), or required capacity. Must not be NULL.

Returns:

SCID_OK SAN string retrieved successfully.
SCID_ERROR_BAD_ARG If cursor or out_text_size is NULL, or if cursor is at line end.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

See: scid_game_cursor_previous_move_san_get()

function scid_game_cursor_next_move_nag_count_get

scid_error scid_game_cursor_next_move_nag_count_get(
    const scid_game_cursor * cursor,
    size_t * out_count
)

Retrieves the count of Numeric Annotation Glyphs (NAGs) attached to the upcoming move.

Parameters:

cursor Pointer to the cursor. Must not be NULL.
out_count Pointer receiving the NAG count. Must not be NULL.

Returns:

SCID_OK Count retrieved successfully.
SCID_ERROR_BAD_ARG If cursor or out_count is NULL, or if cursor is at line end.

See: scid_game_cursor_next_move_nag_at_get()

function scid_game_cursor_next_move_nag_at_get

scid_error scid_game_cursor_next_move_nag_at_get(
    const scid_game_cursor * cursor,
    size_t index,
    scid_nag * out_nag
)

Retrieves a NAG code from the upcoming move by zero-based index.

Parameters:

cursor Pointer to the cursor. Must not be NULL.
index Zero-based index of the NAG to retrieve.
out_nag Pointer receiving the scid_nag code. Must not be NULL.

Returns:

SCID_OK NAG retrieved successfully.
SCID_ERROR_BAD_ARG If cursor or out_nag is NULL, or if index is out of bounds.

See: scid_game_cursor_next_move_nag_count_get()

function scid_game_cursor_next_move_comment_get

scid_error scid_game_cursor_next_move_comment_get(
    const scid_game_cursor * cursor,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves commentary text attached to the upcoming move.

Parameters:

cursor Pointer to the cursor. Must not be NULL.
out_text Caller-allocated buffer receiving the null-terminated comment 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 Comment retrieved successfully.
SCID_ERROR_BAD_ARG If cursor or out_text_size is NULL, or if cursor is at line end.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

function scid_game_cursor_next

scid_error scid_game_cursor_next(
    const scid_game_cursor * cursor,
    int * out_moved,
    scid_game_cursor ** out_next_cursor
)

Advances one ply forward along the current line.

Parameters:

cursor Pointer to the source cursor. Must not be NULL.
out_moved Pointer receiving non-zero (1) if advanced forward; 0 if already at line end. Must not be NULL.
out_next_cursor Pointer to a handle pointer receiving the newly allocated cursor on success. Must not be NULL.

Returns:

SCID_OK Step completed successfully.
SCID_ERROR_BAD_ARG If any argument is NULL.

See: scid_game_cursor_previous()

Note: The caller acquires ownership of out_next_cursor and must release it with scid_game_cursor_free().

function scid_game_cursor_nag_remove

scid_error scid_game_cursor_nag_remove(
    scid_game * game,
    const scid_game_cursor * cursor,
    int is_move_nag,
    int * out_removed
)

Removes a NAG annotation from the incoming move.

Parameters:

game Pointer to the game to mutate. Must not be NULL.
cursor Pointer to the cursor situated immediately after the target move. Must not be NULL.
is_move_nag Non-zero (1) to remove move assessment NAGs (1..6); zero (0) for positional NAGs.
out_removed Pointer receiving non-zero (1) if a NAG was removed; 0 otherwise. Must not be NULL.

Returns:

SCID_OK Removal processed successfully.
SCID_ERROR_BAD_ARG If game, cursor, or out_removed is NULL, or cursor is at line start.

See: scid_game_cursor_nag_add()

function scid_game_cursor_nag_clear

scid_error scid_game_cursor_nag_clear(
    scid_game * game,
    const scid_game_cursor * cursor
)

Removes all NAG annotations from the incoming move.

Parameters:

game Pointer to the game to mutate. Must not be NULL.
cursor Pointer to the cursor situated immediately after the target move. Must not be NULL.

Returns:

SCID_OK NAGs cleared successfully.
SCID_ERROR_BAD_ARG If game or cursor is NULL, or cursor is at line start.

function scid_game_cursor_nag_add

scid_error scid_game_cursor_nag_add(
    scid_game * game,
    const scid_game_cursor * cursor,
    scid_nag nag,
    int * out_added
)

Adds a Numeric Annotation Glyph (NAG) to the incoming move.

Parameters:

game Pointer to the game to mutate. Must not be NULL.
cursor Pointer to the cursor situated immediately after the target move. Must not be NULL.
nag NAG code to attach (1..255).
out_added Pointer receiving non-zero (1) if NAG added; 0 if already present. Must not be NULL.

Returns:

SCID_OK NAG added successfully.
SCID_ERROR_BAD_ARG If game, cursor, or out_added is NULL, or cursor is at line start.

See:

function scid_game_cursor_move_add

scid_error scid_game_cursor_move_add(
    scid_game * game,
    const scid_game_cursor * cursor,
    scid_movespec move,
    scid_game_cursor ** out_next_cursor
)

Appends a chess move to the current line at the cursor position.

Parameters:

game Pointer to the game to mutate. Must not be NULL.
cursor Pointer to the cursor indicating the insertion node. Must not be NULL.
move Move specification to execute and record.
out_next_cursor Pointer to a handle pointer receiving the newly allocated cursor positioned after the added move. Must not be NULL.

Returns:

SCID_OK Move appended successfully.
SCID_ERROR_BAD_ARG If any argument is NULL, cursor is not at line end, or move is invalid.
SCID_ERROR_INVALID_MOVE If move is illegal in the current board position.

See: scid_game_cursor_variation_add()

Note: The caller acquires ownership of out_next_cursor and must release it with scid_game_cursor_free().

If the cursor is at the end of the line, the move extends the line. If the cursor is before existing moves, an error is returned (use scid_game_cursor_variation_add() to branch).

function scid_game_cursor_is_variation_start

scid_error scid_game_cursor_is_variation_start(
    const scid_game_cursor * cursor,
    int * out_is_variation_start
)

Checks if the cursor is at the starting position of a sub-variation (depth > 0).

Parameters:

cursor Pointer to the cursor. Must not be NULL.
out_is_variation_start Pointer receiving non-zero (1) if at variation start; 0 otherwise. Must not be NULL.

Returns:

SCID_OK Check completed successfully.
SCID_ERROR_BAD_ARG If cursor or out_is_variation_start is NULL.

function scid_game_cursor_is_variation_end

scid_error scid_game_cursor_is_variation_end(
    const scid_game_cursor * cursor,
    int * out_is_variation_end
)

Checks if the cursor is at the terminal end of a sub-variation (depth > 0).

Parameters:

cursor Pointer to the cursor. Must not be NULL.
out_is_variation_end Pointer receiving non-zero (1) if at variation end; 0 otherwise. Must not be NULL.

Returns:

SCID_OK Check completed successfully.
SCID_ERROR_BAD_ARG If cursor or out_is_variation_end is NULL.

function scid_game_cursor_is_variation_empty

scid_error scid_game_cursor_is_variation_empty(
    const scid_game_cursor * cursor,
    int * out_is_variation_empty
)

Checks if the current variation contains zero moves (empty branch containing only comments).

Parameters:

cursor Pointer to the cursor. Must not be NULL.
out_is_variation_empty Pointer receiving non-zero (1) if variation has no moves; 0 otherwise. Must not be NULL.

Returns:

SCID_OK Check completed successfully.
SCID_ERROR_BAD_ARG If cursor or out_is_variation_empty is NULL.

function scid_game_cursor_is_line_start

scid_error scid_game_cursor_is_line_start(
    const scid_game_cursor * cursor,
    int * out_is_line_start
)

Checks if the cursor is at the beginning of the current line or variation.

Parameters:

cursor Pointer to the cursor. Must not be NULL.
out_is_line_start Pointer receiving non-zero (1) if at line start; 0 otherwise. Must not be NULL.

Returns:

SCID_OK Check completed successfully.
SCID_ERROR_BAD_ARG If cursor or out_is_line_start is NULL.

function scid_game_cursor_is_line_end

scid_error scid_game_cursor_is_line_end(
    const scid_game_cursor * cursor,
    int * out_is_line_end
)

Checks if the cursor is at the terminal end of the current line or variation (no subsequent move).

Parameters:

cursor Pointer to the cursor. Must not be NULL.
out_is_line_end Pointer receiving non-zero (1) if at line end; 0 otherwise. Must not be NULL.

Returns:

SCID_OK Check completed successfully.
SCID_ERROR_BAD_ARG If cursor or out_is_line_end is NULL.

function scid_game_cursor_is_game_start

scid_error scid_game_cursor_is_game_start(
    const scid_game_cursor * cursor,
    int * out_is_game_start
)

Checks if the cursor is at the very beginning of the entire game (start of mainline).

Parameters:

cursor Pointer to the cursor. Must not be NULL.
out_is_game_start Pointer receiving non-zero (1) if at game start; 0 otherwise. Must not be NULL.

Returns:

SCID_OK Check completed successfully.
SCID_ERROR_BAD_ARG If cursor or out_is_game_start is NULL.

function scid_game_cursor_is_game_end

scid_error scid_game_cursor_is_game_end(
    const scid_game_cursor * cursor,
    int * out_is_game_end
)

Checks if the cursor is at the final position of the mainline.

Parameters:

cursor Pointer to the cursor. Must not be NULL.
out_is_game_end Pointer receiving non-zero (1) if at mainline end; 0 otherwise. Must not be NULL.

Returns:

SCID_OK Check completed successfully.
SCID_ERROR_BAD_ARG If cursor or out_is_game_end is NULL.

function scid_game_cursor_free

void scid_game_cursor_free(
    scid_game_cursor * cursor
)

Releases a cursor handle and all associated resources.

Parameters:

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

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

function scid_game_cursor_create

scid_error scid_game_cursor_create(
    scid_game * game,
    scid_game_cursor ** out_cursor
)

Creates a new cursor initialised at the starting position of a game.

Parameters:

game Pointer to the game entity. Must not be NULL.
out_cursor Pointer to a handle pointer receiving the newly allocated cursor. Must not be NULL.

Returns:

SCID_OK Cursor created successfully.
SCID_ERROR_BAD_ARG If game or out_cursor is NULL.

See: scid_game_cursor_free()

Note: Ownership of the created cursor is transferred to the caller. The caller must release it using scid_game_cursor_free().

function scid_game_cursor_comment_set

scid_error scid_game_cursor_comment_set(
    scid_game * game,
    const scid_game_cursor * cursor,
    const char * comment
)

Sets or updates the commentary text at the current cursor node.

Parameters:

game Pointer to the game to mutate. Must not be NULL.
cursor Pointer to the cursor indicating the node to update. Must not be NULL.
comment Null-terminated comment string (or "" to clear). Must not be NULL.

Returns:

SCID_OK Comment updated successfully.
SCID_ERROR_BAD_ARG If game, cursor, or comment is NULL.

See: scid_game_cursor_comment_get()

function scid_game_cursor_comment_get

scid_error scid_game_cursor_comment_get(
    const scid_game_cursor * cursor,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves commentary text attached directly to the current cursor position.

Parameters:

cursor Pointer to the cursor. Must not be NULL.
out_text Caller-allocated buffer receiving the null-terminated comment 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 the number of bytes written (excluding null terminator), or required capacity if the buffer is too small. Must not be NULL.

Returns:

SCID_OK Comment retrieved successfully.
SCID_ERROR_BAD_ARG If cursor or out_text_size is NULL.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

See: scid_game_cursor_comment_set()

function scid_game_cursor_clone

scid_error scid_game_cursor_clone(
    scid_game * game,
    const scid_game_cursor * source_cursor,
    scid_game_cursor ** out_cursor
)

Clones an existing cursor to duplicate its exact location within the game tree.

Parameters:

game Pointer to the game entity bound to source_cursor. Must not be NULL.
source_cursor Pointer to the cursor to clone. Must not be NULL.
out_cursor Pointer to a handle pointer receiving the newly allocated duplicate cursor. Must not be NULL.

Returns:

SCID_OK Cursor cloned successfully.
SCID_ERROR_BAD_ARG If game, source_cursor, or out_cursor is NULL, or if source_cursor belongs to a different game.

Note: The caller acquires ownership of out_cursor and must release it with scid_game_cursor_free().

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