23.4 Iterating through the trees

Mutator function: int marpa_t_next ( Marpa_Tree t)

On success, positions t at the next parse tree in the iteration.

Tree iterators are initialized to the position before the first parse tree, so this method must be called before creating a valuator from a tree.

If a tree iterator is positioned after the last parse, the tree is said to be “exhausted”. A tree iterator for a bocage with no parse trees is considered to be “exhausted” when initialized.

If the tree iterator is exhausted, soft fails, and sets the error code to MARPA_ERR_TREE_EXHAUSTED. See Orthogonal treatment of soft failures.

It the tree iterator is paused, hard fails, and sets the error code to MARPA_ERR_TREE_PAUSED. This hard failure is fully recoverable. See marpa_v_new().

Return value: On success, a non-negative value. On soft failure, -1. On hard failure, -2. The hard failure with error code MARPA_ERR_TREE_PAUSED is fully recoverable.

Accessor function: int marpa_t_parse_count ( Marpa_Tree t)

Returns the count of the number of parse trees traversed so far. The count includes the current iteration of the tree. A value of 0 indicates that the tree iterator is at its initialized position, before the first parse tree.

Return value: The number of parses traversed so far. Always succeeds.