Traversal

Core traversal is the operational model for walking and editing a game's recursive movetext tree. scid::core::GameCursor is the read-only view: it moves between moves, enters and exits variations, captures restorable locations, and can replay the path to produce a Position. MovetextCursor uses the same location model, but it edits the tree owned by Game.

The traversal model is built around a cursor position between moves. The cursor's previousMove() is immediately before that position, and nextMove() is immediately after it. Entering a variation records a parent-frame and moves the cursor to the start of the child line; exiting restores the parent line and the same between-moves position that opened the branch.

MovetextLocation is the portable bookmark. It stores a path of variation steps from the mainline plus the nextIndex in the active line. Restoring a location validates that every indexed move and variation still exists before the cursor state is changed.

Domain Model

This diagram expands traversal into the public cursor and location types, plus the tree state they point into. It is intentionally loose: it shows the shared between-moves model and the important operations programmers use, while omitting the many convenience predicates that report whether a cursor is at a line, variation, or game edge.

GameCursor and MovetextCursor both hold a current line, a nextIndex, and a stack of parent frames. The parent stack is an implementation detail, but it is the key to understanding variation traversal: each frame remembers the parent line, the move that owns the selected variation, and the selected variation index. MovetextLocation stores the same idea without pointers, so it can be captured from either cursor and later restored if the tree shape still matches.

The read-only cursor is the only traversal type that reconstructs board state: it collects movesToCursor() and applies each stored MoveSpec from the game's start position. The mutable cursor instead concentrates on structural edits: inserting moves, attaching or deleting variations, changing comments and NAGs, promoting variations, and truncating lines.