ooc 1.3
Object Oriented tollkit fo ANSI C

list.h File Reference

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:

Defines

#define list_new_type(pClass, manage)   _list_new_type( & pClass ## Class, manage )
 Convenient macro for creating typed List.
#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.
#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.

Typedefs

typedef struct ListObject * List
 List class declaration.
typedef ListNode ListIterator
 List iterator.
typedef void(* list_item_destroyer )(void *item)
 Destroy function prototype for the list items.
typedef void(* list_item_executor )(void *item, void *param)
 Execution function prototype for the list items.
typedef int(* list_item_checker )(void *item, void *param)
 Boolean function prototype for the list items.

Functions

List list_new (list_item_destroyer destroyer)
 Creates a new List.
List _list_new_type (Class type, int manage)
 Creates a new List of a given type.
List _list_new_of_nodes (Class node, int manage)
 Creates a new List of a given type of ListNodes.
void _list_use_of_nodes (void *location, Class node, int manage)
 Creates a new List of a given type of ListNodes at location.
ListIterator list_append (List list, void *item)
 Appends an item to the end of the list.
ListIterator list_prepend (List list, void *item)
 Prepends an item at the beginning of the list.
ListIterator list_insert_before (List list, ListIterator position, void *item)
 Inserts an item before the given position of the list.
ListIterator list_insert_after (List list, ListIterator position, void *item)
 Inserts an item after the given position of the list.
void * list_remove_item (List list, ListIterator position)
 Removes an item from the list.
void * list_remove_first_item (List list)
 Removes the first item from the list.
void * list_remove_last_item (List list)
 Removes the last item from the list.
void list_delete_item (List list, ListIterator position)
 Deletes an item in the list.
ListIterator list_first (List list)
 Gets the iterator for the first item in the list.
ListIterator list_last (List list)
 Gets the iterator for the last item in the list.
void * list_get_item (ListIterator listiterator)
 Gets an item in the list.
ListIterator list_next (List list, ListIterator listiterator)
 Gets the iterator of the next item in the list.
ListIterator list_previous (List list, ListIterator listiterator)
 Gets the iterator of the previous item in the list.
void list_swap (List list, ListIterator listiterator1, ListIterator listiterator2)
 Changes two items' position in the list.
void list_foreach (List list, list_item_executor method, void *param)
 Executes a method for each items in the list.
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.
void list_foreach_delete_if (List list, list_item_checker criteria, void *param)
 Deletes each items in the list that match the criteria.
ListIterator list_find_item (List list, ListIterator position, list_item_checker criteria, void *param)
 Finds the first matching item in the list.
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.

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)!

Define 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:
pNodeThe 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.
manageTRUE 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:
pClassThe 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.
manageTRUE 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:
locationThe location where the preallocated List must be created. The location must be large enough to hold a ListObject.
pNodeThe 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.
manageOOC_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:
itemThe item.
paramThe 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:
itemThe 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:
itemThe item.
paramThe parameter passed to the list_for_each() function.
See also:
list_foreach()

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:
nodeThe 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.
manageTRUE 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:
typeThe 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.
manageTRUE 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:
locationThe location where the preallocated List must be created. The location must be large enough to hold a ListObject.
nodeThe 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.
manageOOC_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:
listThe list
itemThe 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:
listThe list
positionThe 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:
listThe list.
positionThe 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.
criteriaThe method that is used to decide which items find.
paramThe 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:
listThe list.
positionThe 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.
criteriaThe method that is used to decide which items find.
paramThe 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:
listThe 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:
listThe list.
methodThe method to be executed for each items.
paramThe 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:
listThe list.
criteriaThe method that is used to decide which items to delete. The item is deleted if the method returns TRUE for it.
paramThe 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:
listThe list.
fromThe position of the first item to be checked, or NULL if must start from the first item in the list.
methodThe method to be executed for each items.
paramThe 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:
listiteratorThe 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!
ListIterator list_insert_after ( List  list,
ListIterator  position,
void *  item 
)

Inserts an item after the given position of the list.

Parameters:
listThe list
positionThe positon
itemThe 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:
listThe list
positionThe positon
itemThe 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:
listThe 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:
destroyerThe 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:
listThe list
listiteratorThe 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:
listThe list
itemThe 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:
listThe list
listiteratorThe 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:
listThe 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:
listThe list
positionThe 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:
listThe 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:
listThe list.
listiterator1The list iterator of the first item
listiterator2The list iterator of the second item
Note:
Both parameters must be a valid list iterator, passing NULL will throw err_wrong_position exception.
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines