< index < 8. All purposes container < 8.2 Basic array operations | ===================================== 8.3 Basic list operations ===================================== | > 8.4 Basic stack operations

You can insert a value inside the list.

    C++ : template <class T> void TCODList::insertBefore(const T elt,int before)
    C   : void TCOD_list_insert_before(TCOD_list_t l,const void *elt,int before)

Parameter | Description
--- | ---
elt | Element to insert in the list.
idx | Index of the element after the insertion. 0 <= idx < list size
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.set(0,5); // the list contains 1 element at position 0, value = 5
          intList.insertBefore(2,0); // the list contains 2 elements : 2,5
    C   : TCOD_list_t intList = TCOD_list_new();
          TCOD_list_set(intList,0,(const void *)5);
          TCOD_list_insert_before(intList,(const void *)2,0);

You can remove an element from the list.

    C++ : template <class T> void TCODList::remove(const T elt)
          template <class T> void TCODList::removeFast(const T elt)
    C   : void TCOD_list_remove(TCOD_list_t l, const void * elt)
          void TCOD_list_remove_fast(TCOD_list_t l, const void * elt)

Parameter | Description
--- | ---
elt | The element to remove
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.set(0,5); // the list contains 1 element at position 0, value = 5
          intList.remove(5); // the list is empty
    C   : TCOD_list_t intList = TCOD_list_new();
          TCOD_list_set(intList,0,(const void *)5);
          TCOD_list_remove(intList,(const void *)5);

You can concatenate two lists. Every element of l2 will be added to current list (or l in the C version) :

    C++ : template <class T> void TCODList::addAll(const TCODList &l2)
    C   : void TCOD_list_add_all(TCOD_list_t l, TCOD_list_t l2)

Parameter | Description
--- | ---
l | The list inside which elements will be added.
l2 | the list handler containing elements to insert.

Example :

    C++ : TCODList<int> intList;
          intList.set(1,3); // intList contains 2 elements : 0, 3
          TCODList<int> intList2; // intList2 is empty
          intList2.set(0,1); // intList2 contains 1 element : 1
          intList2.addAll(intList); // intList2 contains 3 elements : 1, 0, 3
    C   : TCOD_list_t intList = TCOD_list_new();
          TCOD_list_set(intList,1,(const void *)3);
          TCOD_list_t intList2 = TCOD_list_new();
          TCOD_list_set(intList2,0,(const void *)1);
          TCOD_list_add_all(intList2,intList);

You can empty a list with clear :

    C++ : template <class T> void TCODList::clear()
    C   : void TCOD_list_clear(TCOD_list_t l)

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

Example :

    C++ : TCODList<int> intList;
          intList.set(0,3); // intList contains 1 element
          intList.clear(); // intList is empty
    C   : TCOD_list_t intList = TCOD_list_new();
          TCOD_list_set(intList,0,(const void *)5);
          TCOD_list_clear(intList);

For lists containing pointers, you can clear the list and delete (free) the elements :

    C++ : template <class T> void TCODList::clearAndDelete()
    C   : void TCOD_list_clear_and_delete(TCOD_list_t l)

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

Example :

    C++ : TCODList<MyClass *> intList;
          MyClass * cl=new MyClass(); // new instance of MyClass allocated here
          intList.set(0,cl);
          intList.clear(); // the list is empty. cl is always valid
          intList.set(0,cl);
          intList.clearAndDelete(); // the list is empty. delete cl has been called. The address cl is no longer valid.
    C   : TCOD_list_t intList = TCOD_list_new();
          void *data=calloc(10,1); /* some memory allocation here */
          TCOD_list_set(intList,0,(const void *)data);
          TCOD_list_clear(intList); /* the list is empty, but data is always valid */
          TCOD_list_set(intList,0,(const void *)data);
          TCOD_list_clear_and_delete(intList); /* the list is empty, free(data) has been called. The address data is no longer valid */