Iterator system

Iterators are objects that enable sequential, ordered traversal of object contents, allowing to read up to 2 variables at each position: the key and the value.

The C API has several functions used to deal with iterators. There are essentially three kinds of functions: initialization ( sgs_PushIterator, sgs_GetIterator ), advancing ( sgs_IterAdvance ) and data retrieval ( sgs_IterPushData, sgs_IterGetData ).

Iterator starts at the pre-first position (-1 in terms of indices), so nothing can be read initially, before the first advance. This allows to implement iterator handling with rather simple code:

initialize;
while( advance > 0 )
{
    retrieve key and/or value;
    ..do something else..;
}
free;

A more real example follows:

// assuming iterable object is at the top of the stack
sgs_PushIterator( C, sgs_StackItem( C, -1 ) );
while( sgs_IterAdvance( C, sgs_StackItem( C, -1 ) ) > 0 )
{
    sgs_StackIdx ssz = sgs_StackSize( C );
    
    sgs_IterPushData( C, sgs_StackItem( C, -1 ), 1, 1 ); // push both key and value
    
    sgs_SetStackSize( C, ssz ); // restore stack to have iterator at -1 again
}
sgs_Pop( C, 1 ); // pop the iterator

Another example using pointers:

sgs_Variable iterator, iterable, key, value;
// .. assuming iterable is initalized here ..
sgs_GetIterator( C, iterable, &iterator );
while( sgs_IterAdvance( C, iterator ) > 0 )
{
    sgs_IterGetData( C, iterator, NULL, &value );
    // .. use value ..
    sgs_Release( C, &value );
    
    sgs_IterGetData( C, iterator, &key, &value );
    // .. use key and value ..
    sgs_Release( C, &key );
    sgs_Release( C, &value );
}
sgs_Release( C, &iterator );
// .. release the iterable or not, depending on how it was initialized ..