< index
< 8. All purposes container
< 8.4 Basic stack operations

=====================================
8.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.

C++ : template <class T> T * TCODList::begin() const
      template <class T> T * TCODList::end() const
C   : void ** TCOD_list_begin(TCOD_list_t l)
      void ** TCOD_list_end(TCOD_list_t l)

Parameter	Description
l	In the C version, the list handler, returned by a constructor.

Example :

C++ : 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 );
      }
C   : 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 );
      }

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.

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.

C++ : template <class T> T *TCODList::remove(T *iterator)
      template <class T> T *TCODList::removeFast(T *iterator)
C   : void **TCOD_list_remove_iterator(TCOD_list_t l, void **iterator)
      void **TCOD_list_remove_iterator_fast(TCOD_list_t l, void **iterator)

Parameter	Description
iterator	The list iterator.
l	In the C version, the list handler, returned by a constructor.

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.
Example :

C++ : 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
      }
      // now the list contains only two elements : 5,3
C   : 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 );
      }

insert a comment