List class - doubly linked list, a standard ooc container. More...

#include "ooc.h"

Include dependency graph for list.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	list_new_type(pClass, manage) _list_new_type( & pClass ## Class, manage )
	Convenient macro for creating typed List. More...

#define	list_new_of_nodes(pNode, manage) _list_new_of_nodes( & pNode ## Class, manage )
	Convenient macro for creating a List of a given type of ListNodes. More...

#define	list_use_of_nodes(location, pNode, manage) _list_use_of_nodes( location, & pNode ## Class, manage )
	Convenient macro for creating a List of a given type of ListNodes at a preallocated location. More...

Typedefs
typedef struct ListObject *	List
	List class declaration.

typedef ListNode	ListIterator
	List iterator. More...

typedef void(*	list_item_destroyer )(void *item)
	Destroy function prototype for the list items. More...

typedef void(*	list_item_executor )(void item, void param)
	Execution function prototype for the list items. More...

typedef int(*	list_item_checker )(void item, void param)
	Boolean function prototype for the list items. More...

Functions
List	list_new (list_item_destroyer destroyer)
	Creates a new List. More...

List	_list_new_type (Class type, int manage)
	Creates a new List of a given type. More...

List	_list_new_of_nodes (Class node, int manage)
	Creates a new List of a given type of ListNodes. More...

void	_list_use_of_nodes (void *location, Class node, int manage)
	Creates a new List of a given type of ListNodes at location. More...

ListIterator	list_append (List list, void *item)
	Appends an item to the end of the list. More...

ListIterator	list_prepend (List list, void *item)
	Prepends an item at the beginning of the list. More...

ListIterator	list_insert_before (List list, ListIterator position, void *item)
	Inserts an item before the given position of the list. More...

ListIterator	list_insert_after (List list, ListIterator position, void *item)
	Inserts an item after the given position of the list. More...

void *	list_remove_item (List list, ListIterator position)
	Removes an item from the list. More...

void *	list_remove_first_item (List list)
	Removes the first item from the list. More...

void *	list_remove_last_item (List list)
	Removes the last item from the list. More...

void	list_delete_item (List list, ListIterator position)
	Deletes an item in the list. More...

ListIterator	list_first (List list)
	Gets the iterator for the first item in the list. More...

ListIterator	list_last (List list)
	Gets the iterator for the last item in the list. More...

void *	list_get_item (ListIterator listiterator)
	Gets an item in the list. More...

ListIterator	list_next (List list, ListIterator listiterator)
	Gets the iterator of the next item in the list. More...

ListIterator	list_previous (List list, ListIterator listiterator)
	Gets the iterator of the previous item in the list. More...

void	list_swap (List list, ListIterator listiterator1, ListIterator listiterator2)
	Changes two items' position in the list. More...

void	list_foreach (List list, list_item_executor method, void *param)
	Executes a method for each items in the list. More...

ListIterator	list_foreach_until_true (List list, ListIterator from, list_item_checker method, void *param)
	Executes a method for each items in the list until it returns `TRUE`. More...

void	list_foreach_delete_if (List list, list_item_checker criteria, void *param)
	Deletes each items in the list that match the criteria. More...

ListIterator	list_find_item (List list, ListIterator position, list_item_checker criteria, void *param)
	Finds the first matching item in the list. More...

ListIterator	list_find_item_reverse (List list, ListIterator position, list_item_checker criteria, void *param)
	Finds the first matching item in the list in reverse order. More...

Class	list_get_type (List list)
	Get the type of the list. More...

int	list_get_managed (List list)
	Check if the list is managed. More...

Detailed Description

List class - doubly linked list, a standard ooc container.

List is a container class, that can hold pointers to any kind of data. Every item stored in the list must work perfectly with the supplied list item destroyer! In practice this means, that you can only store items in the list that has the same deletion method.

Note: List implementation is thread safe, in the manner, that adding items to, or deleting from the List will not mesh up the List. But the ListIterators may become invalid if multiple threads modify the same List object. As a consecvence the foreach and find methods may behave unexpectedly if an other thread is modifying the List! Make your own locking if needed! The same applies to the ooc_duplicate() method for List (uses list_foreach() internally)!

Macro Definition Documentation

#define list_new_of_nodes	(	pNode,
		manage
	)	_list_new_of_nodes( & pNode ## Class, manage )

Convenient macro for creating a List of a given type of ListNodes.

Parameters

pNode	The type of the ListNodes. It is guaranteed, that the list holds this type of Objects only. Trying to put different Object into the List will cause throwing an `Exception` with `err_bad_cast` error code. pNode must be a sublass of ListNode.
manage	`TRUE` if the List must manage the Objects put in the List, `FALSE` if not.

Returns: The List.

See Also: _list_new_of_nodes()

Note: The List created with this method is more powerful, than a normal typed list, because the chaining information is held by the stored object itself.

#define list_new_type	(	pClass,
		manage
	)	_list_new_type( & pClass ## Class, manage )

Convenient macro for creating typed List.

Parameters

pClass	The type of the List. It is guaranteed, that the list holds this type of Objects only. Trying to put different Object into the List will cause throwing an `Exception` with `err_bad_cast` error code.
manage	`TRUE` if the List must manage the Objects put in the List, `FALSE` if not.

Returns: The List.

See Also: _list_new_type()

#define list_use_of_nodes	(	location,
		pNode,
		manage
	)	_list_use_of_nodes( location, & pNode ## Class, manage )

Convenient macro for creating a List of a given type of ListNodes at a preallocated location.

Parameters

location	The location where the preallocated List must be created. The location must be large enough to hold a ListObject.
pNode	The type of the ListNodes. It is guaranteed, that the list holds this type of Objects only. Trying to put different Object into the List will cause throwing an `Exception` with `err_bad_cast` error code. pNode must be a sublass of ListNode.
manage	OOC_MANAGE if the List must manage the Objects put in the List, !OOC_MANAGE if not.

See Also: _list_use_of_nodes()

Note: The List created with this method is more powerful, than a normal typed list, because the chaining information is held by the stored object itself.

Typedef Documentation

typedef int(* list_item_checker)(void *item, void *param)

Boolean function prototype for the list items.

This function is called by some of the list_for_each...() method.

Parameters

item	The item.
param	The parameter passed to the list_for_each() function.

Returns: Must return TRUE or FALSE.

See Also: list_foreach_until_true(), list_foreach_delete_if(), list_find_item(), list_find_item_reverse()

typedef void( * list_item_destroyer)(void *item)

Destroy function prototype for the list items.

This function must clean up the item that was stored in the list and must free all resources (memory) that was allocated by this item.

Parameters

item	The item that shuold be destroyed.

Note: Usually ooc_delete() or ooc_free() is used as list_item_destroyer.

See Also: list_new()

typedef void(* list_item_executor)(void *item, void *param)

Execution function prototype for the list items.

This function is called by the list_for_each() method.

Parameters

item	The item.
param	The parameter passed to the list_for_each() function.

See Also: list_foreach()

typedef ListNode ListIterator

List iterator.

This iterator can be used as an identifier of a list node in the list.

Note: This is not idenctical to the item stored in the list!

See Also: list_next(), list_previous()

Function Documentation

List _list_new_of_nodes	(	Class	node,
		int	manage
	)

Creates a new List of a given type of ListNodes.

Creates an empty List of listNodes.

Parameters

node	The type of the ListNodes. It is guaranteed, that the list holds this type of Objects only. Trying to put different Object into the List will cause throwing an `Exception` with `err_bad_cast` error code. node must be a sublass of ListNode.
manage	`TRUE` if the List must manage the Objects put in the List, `FALSE` if not.

Returns: The List.

See Also: list_new_of_nodes()

List _list_new_type	(	Class	type,
		int	manage
	)

Creates a new List of a given type.

Creates an empty typed List.

Parameters

type	The type of the List. It is guaranteed, that the list holds this type of Objects only. Trying to put different Object into the List will cause throwing an `Exception` with `err_bad_cast` error code.
manage	`TRUE` if the List must manage the Objects put in the List, `FALSE` if not.

Returns: The List.

See Also: list_new_type()

void _list_use_of_nodes	(	void *	location,
		Class	node,
		int	manage
	)

Creates a new List of a given type of ListNodes at location.

Creates an empty List of listNodes at a preallocated location.

Parameters

location	The location where the preallocated List must be created. The location must be large enough to hold a ListObject.
node	The type of the ListNodes. It is guaranteed, that the list holds this type of Objects only. Trying to put different Object into the List will cause throwing an `Exception` with `err_bad_cast` error code. node must be a sublass of ListNode.
manage	OOC_MANAGE if the List must manage the Objects put in the List, !OOC_MANAGE if not.

See Also: list_use_of_nodes()

ListIterator list_append	(	List	list,
		void *	item
	)

Appends an item to the end of the list.

Parameters

list	The list
item	The item to be appended. The list takes over the ownership of the item if you have created the list with a list item destroyer.

Returns: The position of the inserted item in the list.

void list_delete_item	(	List	list,
		ListIterator	position
	)

Deletes an item in the list.

This method removes and destroys the positioned item in the list.

Parameters

list	The list
position	The position of the item to be removed.

Returns: The item that was removed from the list.

Note: If you passed NULL as item destroyer for list_new(), then actually no deletion occurs.

ListIterator list_find_item	(	List	list,
		ListIterator	position,
		list_item_checker	criteria,
		void *	param
	)

Finds the first matching item in the list.

This is a forward search (in the direction from the first item to the last item.)

Parameters

list	The list.
position	The position from where to start the search. It must be a valid list iterator, otherwise will throw `err_wrong_position` exception. Passing `NULL` will start from the beginning of the List.
criteria	The method that is used to decide which items find.
param	The parameter to be passed for the executed method.

Returns: The ListIterator of the first matching item in the list, or NULL if there was no match.

Note: This is a simple linear search, may take long for large lists.

ListIterator list_find_item_reverse	(	List	list,
		ListIterator	position,
		list_item_checker	criteria,
		void *	param
	)

Finds the first matching item in the list in reverse order.

This is a backward search (in the direction from the last item to the first item.)

Parameters

list	The list.
position	The position from where to start the search. It must be a valid list iterator, otherwise will throw `err_wrong_position` exception. Passing `NULL` will start from the end of the List.
criteria	The method that is used to decide which items find.
param	The parameter to be passed for the executed method.

Returns: The ListIterator of the first matching item in the list, or NULL if there was no match.

Note: This is a simple linear search, may take long for large lists.

ListIterator list_first ( List list )

Gets the iterator for the first item in the list.

Parameters

list The list

Returns: The iterator for the first item in the list, or NULL if the list is empty.

void list_foreach	(	List	list,
		list_item_executor	method,
		void *	param
	)

Executes a method for each items in the list.

Parameters

list	The list.
method	The method to be executed for each items.
param	The parameter to be passed for the executed method.

void list_foreach_delete_if	(	List	list,
		list_item_checker	criteria,
		void *	param
	)

Deletes each items in the list that match the criteria.

Parameters

list	The list.
criteria	The method that is used to decide which items to delete. The item is deleted if the method returns `TRUE` for it.
param	The parameter to be passed for the executed method.

ListIterator list_foreach_until_true	(	List	list,
		ListIterator	from,
		list_item_checker	method,
		void *	param
	)

Executes a method for each items in the list until it returns TRUE.

Parameters

list	The list.
from	The position of the first item to be checked, or `NULL` if must start from the first item in the list.
method	The method to be executed for each items.
param	The parameter to be passed for the executed method.

Returns: The ListIterator of the first item that matches the condition, or &c NULL if there was no match.

void* list_get_item ( ListIterator listiterator )

Gets an item in the list.

Parameters

listiterator The position of the item in the list. It must be a valid list iterator, passing NULL will throw err_wrong_position exception.

Returns: The item

Note: This method does not change the ownership of the item. It just returns a pointer to the item, you must not delete or free it!

int list_get_managed ( List list )

Check if the list is managed.

Check is the items in the list are managed by the list.

Parameters

list The list.

Returns: OOC_MANAGE if managed list, !OOC_MANAGE if not.

See Also: list_new(), list_new_type(), list_new_of_nodes().

Class list_get_type ( List list )

Get the type of the list.

Returns the type of the list in case of a typed list.

Parameters

list The list.

Returns: The Class pointer in case of a typed list, otherwise NULL;

See Also: list_new_type(), list_new_of_nodes().

ListIterator list_insert_after	(	List	list,
		ListIterator	position,
		void *	item
	)

Inserts an item after the given position of the list.

Parameters

list	The list
position	The positon
item	The item to be inserted. The list takes over the ownership of the item if you have created the list with a list item destroyer.

Returns: The position of the inserted item in the list.

ListIterator list_insert_before	(	List	list,
		ListIterator	position,
		void *	item
	)

Inserts an item before the given position of the list.

Parameters

list	The list
position	The positon
item	The item to be inserted. The list takes over the ownership of the item if you have created the list with a list item destroyer.

Returns: The position of the inserted item in the list.

ListIterator list_last ( List list )

Gets the iterator for the last item in the list.

Parameters

list The list

Returns: The iterator for the last item in the list, or NULL if the list is empty.

List list_new ( list_item_destroyer destroyer )

Creates a new List.

Creates an empty List.

Parameters

destroyer The destroy function for the list items. It is usually ooc_free(), ooc_delete() or ooc_delete_and_null() depending on the type of the items stored in the List. For static List items (that do not need the release of the occupied memory) you can pass NULL as well.

Returns: The List.

ListIterator list_next	(	List	list,
		ListIterator	listiterator
	)

Gets the iterator of the next item in the list.

Parameters

list	The list
listiterator	The position of the current item in the list. It must be a valid list iterator, passing `NULL` will throw `err_wrong_position` exception.

Returns: The ListIterator of the next item in the list, or NULL if there are no more items.

Note: For "noded" Lists (those that was made by list_new_of_nodes()) this function just returns the listiterator itself. Noded Lists consider the ListNodes as items.

ListIterator list_prepend	(	List	list,
		void *	item
	)

Prepends an item at the beginning of the list.

Parameters

list	The list
item	The item to be prepended. The list takes over the ownership of the item if you have created the list with a list item destroyer.

Returns: The position of the inserted item in the list.

ListIterator list_previous	(	List	list,
		ListIterator	listiterator
	)

Gets the iterator of the previous item in the list.

Parameters

list	The list
listiterator	The position of the current item in the list. It must be a valid list iterator, passing `NULL` will throw `err_wrong_position` exception.

Returns: The ListIterator of the previous item in the list, or NULL if there are no more items.

void* list_remove_first_item ( List list )

Removes the first item from the list.

Parameters

list The list

Returns: The item that was removed from the list, NULL if the list was empty.

Note: This method does not delete the item! You are responsible to destroy the item when it is no longer needed!

void* list_remove_item	(	List	list,
		ListIterator	position
	)

Removes an item from the list.

Parameters

list	The list
position	The position of the item to be removed.

Returns: The item that was removed from the list.

Note: This method does not delete the item! You are responsible to destroy the item when it is no longer needed!

void* list_remove_last_item ( List list )

Removes the last item from the list.

Parameters

list The list

Returns: The item that was removed from the list, NULL if the list was empty.

Note: This method does not delete the item! You are responsible to destroy the item when it is no longer needed!

void list_swap	(	List	list,
		ListIterator	listiterator1,
		ListIterator	listiterator2
	)

Changes two items' position in the list.

Parameters

list	The list.
listiterator1	The list iterator of the first item
listiterator2	The list iterator of the second item

Note: Both parameters must be a valid list iterator, passing NULL will throw err_wrong_position exception.

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation