libtcoddocumentation

6.5. Iterators

You can iterate through the elements of the list using an iterator. begin() returns the address of the first element of the list. You go to the next element using the increment operator ++. When the iterator's value is equal to end(), you've gone through all the elements. Warning ! You cannot insert elements in the list while iterating through it. Inserting elements can result in reallocation of the list and your iterator will not longer be valid.

template <class T> T * TCODList::begin() const
template
<class T> T * TCODList::end() const

void ** TCOD_list_begin(TCOD_list_t l)
void
** TCOD_list_end(TCOD_list_t l)

ParameterDescription
lIn the C version, the list handler, returned by a constructor.
Example:

TCODList<int> intList; // the list is empty (contains 0 elements)
intList.push(5); // the list contains 1 element at position 0, value = 5
intList.push(2); // the list contains 2 elements : 5,2
for ( int * iterator = intList.begin(); iterator != intList.end(); iterator ++ ) {
    int
currentValue=*iterator;
    printf("value : %d\n", currentValue );
}

TCOD_list_t intList = TCOD_list_new();
TCOD_list_push(intList,(const void *)5);
TCOD_list_push(intList,(const void *)2);
for
( int * iterator = (int *)TCOD_list_begin(intList); iterator != (int *)TCOD_list_end(intList); iterator ++ ) {
    int
currentValue=*iterator;
    printf("value : %d\n", currentValue );
}


You can remove an element from the list while iterating. The element at the iterator position will be removed. The function returns the new iterator. The _fast versions replace the element to remove with the last element of the list. They're faster, but do not preserve the list order.

template <class T> T *TCODList::remove(T *iterator)
template
<class T> T *TCODList::removeFast(T *iterator)

void **TCOD_list_remove_iterator(TCOD_list_t l, void **iterator)
void
**TCOD_list_remove_iterator_fast(TCOD_list_t l, void **iterator)

ParameterDescription
iteratorThe list iterator.
lIn the C version, the list handler, returned by a constructor.
Example:

TCODList<int> intList; // the list is empty (contains 0 elements)
intList.push(5); // the list contains 1 element at position 0, value = 5
intList.push(2); // the list contains 2 elements : 5,2
intList.push(3); // the list contains 3 elements : 5,2,3
for ( int * iterator = intList.begin(); iterator != intList.end(); iterator ++ ) {
    int
currentValue=*iterator;
    if
( currentValue == 2 ) {
        // remove this value from the list and keep iterating on next element (value == 3)
        
iterator = intList.remove(iterator);
    }

    printf("value : %d\n", currentValue ); // all 3 values will be printed : 5,2,3
}

TCOD_list_t intList = TCOD_list_new();
TCOD_list_push(intList,(const void *)5);
TCOD_list_push(intList,(const void *)2);
TCOD_list_push(intList,(const void *)3);
for
( int * iterator = (int *)TCOD_list_begin(intList); iterator != (int *)TCOD_list_end(intList); iterator ++ ) {
    int
currentValue=*iterator;
    if
( currentValue == 2 ) {
        iterator = (int *)TCOD_list_remove_iterator(intList,(void **)iterator);
    }

    printf("value : %d\n", currentValue );
}