Sitemap

 

Description

The List Class

Implements doubly or singly linked lists.

Throughout the documentation, the following prefixes will be used:

Global_

The library prefix: for applications, this is typically empty, for an xyz-Library, this is either XYZ_, xyz_ or Xyz, depending on the identifier in occurs in.

	Template		Instantiation
	Global_LIST_OK		XYZ_LIST_OK
	Global_list_new		xyz_list_new

List_

This is equivalent to Global_list_oType, or the name that was set with -name=... for this data structure. The case and underbar convention is adjusted, too.

Assuming a library prefix xyz and oType == int, you get:

	Template		Instantiation
	List_t		xyz_list_int_t
	List_ALLOW_NULL		XYZ_LIST_INT_ALLOW_NULL

List_class

This is the name of the data structure type in C++: capitalised and with underbars removed:

	List_t		List_class
	list_int_t		ListInt

Members

Detailed Descriptions

static void * operator new (size_t)

static void operator delete (void *, size_t)

static void * operator new[] (size_t)

static void operator delete[] (void *, size_t)

[constructor] List ()

Creation

static List_t const & static_zero ()

[constructor] List (oTypeTouched)

void _constructor ()

void _destructor ()

int get_errno () const

void clear_errno () const

If you compiled Erwin with Global_ERWIN_THREAD_SAFE, this is the way to get the status code of a given list.

If you do not have a thread-safe Erwin library, there is a macro with the same name as this function.

Error Codes (Global_list_errno)

• In case of operation, Global_LIST_OK is signalled.

static int get_errno ()

static void clear_errno ()

List_t & clear ()

Deletes everything in the list and the list structure itself. List_delete is NULL safe (self may be NULL without crash or failed assertion).

List_t & operator= (List_t const &)

Assignment

List_t & operator= (List_t const *)

[destructor] ~List ()

Destruction

operator List_t const * () const

Conversion to C type

operator List_t * ()

Global_list_key_t front () const

Returns the position of the first element or List_KEY_ZERO if the list is empty

Global_list_key_t back () const

Returns the position of the last element or List_KEY_ZERO if the list is empty

Global_list_key_t previous (Global_list_key_t k) const

Returns the previous element in the list or NULL if non exists.

If key == Global_LIST_KEY_ZERO, List_back() is returned.

Global_list_key_t prev (Global_list_key_t k) const

Global_list_key_t next (Global_list_key_t k) const

Returns the next element in the list or NULL if non exists

If key == Global_LIST_KEY_ZERO, List_front() is returned.

Global_list_key_t nth_key (int k) const

Returns the key of the nth element or the zero element. Returns LIST_ZERO if the element does not exist.

oTypeResult nth (int k) const

Returns the nth element or the zero element.

void erase (Global_list_key_t k)

Erases an new element from the list. NEVER use this function to modify a list you are currently iterating! Use List_erase_in_loop for that.

Invocation is only valid for key != Global_LIST_KEY_ZERO.

After this invocation, the key handle becomes invalid. Do not use it anymore!

void erase (Global_list_key_t & iter, Global_list_key_t k, bool reverse = false)

Erases an new element from the list when you are inside an iterator. A pointer to an iterator is provided to this function for changing if necessary. The 'reverse' argument specifies whether you are running forward (false) or backward (true) over the list.

The pointer to the iterator must be != NULL.

Invocation is only valid for key != Global_LIST_KEY_ZERO.

Note that this function not only works in the standard iterators defined in this file, but also in your own loops that you implement using e.g. List_front(), List_next() or List_back(), List_previous(). In these lists, too, you can pass the iterator to List_erase_in_loop().

After this invocation, the key handle becomes invalid. Do not use it anymore!

void erase_in_loop (Global_list_key_t & iter, Global_list_key_t k, bool reverse = false)

Erases an new element from the list when you are inside an iterator. A pointer to an iterator is provided to this function for changing if necessary. The 'reverse' argument specifies whether you are running forward (false) or backward (true) over the list.

The pointer to the iterator must be != NULL.

Invocation is only valid for key != Global_LIST_KEY_ZERO.

Note that this function not only works in the standard iterators defined in this file, but also in your own loops that you implement using e.g. List_front(), List_next() or List_back(), List_previous(). In these lists, too, you can pass the iterator to List_erase_in_loop().

After this invocation, the key handle becomes invalid. Do not use it anymore!

oTypeResult value (Global_list_key_t k) const

Returns the value for the given key or the zero element.

Invocation is only valid for key != Global_LIST_KEY_ZERO.

oTypeResult first () const

Returns the first element or the zero element if no first element exists.

oTypeResult last () const

Returns the last element or the zero element.

List_element_ptr_t value_ptr (Global_list_key_t k)

Returns a pointer to the value for the given key or NULL.

Invocation is only valid for key != Global_LIST_KEY_ZERO.

List_element_ref_t value_ref (Global_list_key_t k)

Returns a pointer to the value for the given key or NULL.

Invocation is only valid for key != Global_LIST_KEY_ZERO.

Global_list_key_t append (oTypeTouched o)

Appends a new element to the list (and copies it if necessary)

Global_list_key_t prepend (oTypeTouched o)

Preprends a new element to the list (and copies it if necessary)

Global_list_key_t insert_before (Global_list_key_t k, oTypeTouched o)

Inserts a new element into the list after the given one. If pos is List_KEY_ZERO, then List_prepend is invoked.

Global_list_key_t insert_after (Global_list_key_t k, oTypeTouched o)

Inserts a new element into the list after the given one. If pos is List_KEY_ZERO, then List_append is invoked.

void overwrite (Global_list_key_t k, oTypeTouched o)

Sets the values of the given key. This overwrites the old value.

Invocation is only valid for key != Global_LIST_KEY_ZERO.

Global_list_key_t insert (Global_list_key_t k, oTypeTouched o, bool backwards)

Inserts a new element into the list after or before a given one. If pos is List_KEY_ZERO, then List_append or List_prepend is invoked. This is the combined functionality of append, prepend, insert_after, insert_before.

List_t & operator<< (oTypeTouched o)

Appends a new element to the list (and copies it if necessary)

List_t & append_list (List_t const * x)

Appends a new element to the list (and copies it if necessary)

List_t & append_list (List_t const & x)

Appends a new element to the list (and copies it if necessary)

List_t & prepend_list (List_t const * x)

Preprends a new element to the list (and copies it if necessary)

List_t & prepend_list (List_t const & x)

Preprends a new element to the list (and copies it if necessary)

List_t & insert_list_before (Global_list_key_t k, List_t const * x)

Inserts a new element into the list after the given one. If pos is List_KEY_ZERO, then List_prepend is invoked.

List_t & insert_list_before (Global_list_key_t k, List_t const & x)

Inserts a new element into the list after the given one. If pos is List_KEY_ZERO, then List_prepend is invoked.

List_t & insert_list_after (Global_list_key_t k, List_t const * x)

Inserts a new element into the list after the given one. If pos is List_KEY_ZERO, then List_append is invoked.

List_t & insert_list_after (Global_list_key_t k, List_t const & x)

Inserts a new element into the list after the given one. If pos is List_KEY_ZERO, then List_append is invoked.

List_t & insert_list (Global_list_key_t k, List_t const * x, bool backwards)

Inserts a new element into the list after the given one. If pos is List_KEY_ZERO, then List_prepend is invoked.

List_t & insert_list (Global_list_key_t k, List_t const & x, bool backwards)

Inserts a new element into the list after the given one. If pos is List_KEY_ZERO, then List_prepend is invoked.

List_t & append (List_t const * x)

Appends a new element to the list (and copies it if necessary)

List_t & append (List_t const & x)

Appends a new element to the list (and copies it if necessary)

List_t & prepend (List_t const * x)

Preprends a new element to the list (and copies it if necessary)

List_t & prepend (List_t const & x)

Preprends a new element to the list (and copies it if necessary)

List_t & insert_before (Global_list_key_t k, List_t const * x)

Inserts a new element into the list after the given one. If pos is List_KEY_ZERO, then List_prepend is invoked.

List_t & insert_before (Global_list_key_t k, List_t const & x)

Inserts a new element into the list after the given one. If pos is List_KEY_ZERO, then List_prepend is invoked.

List_t & insert_after (Global_list_key_t k, List_t const * x)

Inserts a new element into the list after the given one. If pos is List_KEY_ZERO, then List_append is invoked.

List_t & insert_after (Global_list_key_t k, List_t const & x)

Inserts a new element into the list after the given one. If pos is List_KEY_ZERO, then List_append is invoked.

List_t & insert (Global_list_key_t k, List_t const * x, bool backwards)

Inserts a new element into the list after the given one. If pos is List_KEY_ZERO, then List_prepend is invoked.

List_t & insert (Global_list_key_t k, List_t const & x, bool backwards)

Inserts a new element into the list after the given one. If pos is List_KEY_ZERO, then List_prepend is invoked.

Global_list_key_t init_iterator () const

Global_list_key_t init_iterator_reverse () const

bool next_iteration (Global_list_key_t * a, oType * b) const

bool next_iteration_ptr (Global_list_key_t * a, oTypeVar * * b)

bool next_iteration_reverse (Global_list_key_t * a, oType * b) const

bool next_iteration_ptr_reverse (Global_list_key_t * a, oTypeVar * * b)

int nentries () const

Returns the number of entries in the list.

Note

If you compile lists to use minimal space, then no element counter is implemented. In this case, this is slow, it has to iterate the whole list.

The #define to determine whether an element counter is not implemented is List_SLOW_NENTRIES, which is 0 by default.

bool empty () const

Returns whether the list contains no elements.

bool non_empty () const

Returns whether the list contains no elements.

Occurrences of List_t

November 26th, 2007

Comments? Suggestions? Corrections? You can drop me a line.

zpentrabvagiktu@theiling.de