Linked Lists
[Common]

Classes
struct	Gan_List_Node
	Doubly-linked list node. More...
struct	Gan_List
	Doubly-linked list type. More...
Defines
#define	TYPE   int
Typedefs
typedef Gan_List_Node	Gan_List_Node
	Doubly-linked list node.
typedef Gan_List	Gan_List
	Doubly-linked list type.
Functions
Gan_List *	gan_list_new (void)
	Makes a new singly linked list containing no elements.
Gan_List *	gan_list_form (Gan_List *list)
	Forms a new singly linked list containing no elements.
Gan_List *	gan_list_new_from_array (void **array, unsigned n)
	Makes a new linked list containing nodes with data from array.
void	gan_list_free (Gan_List *list, Gan_FreeFunc free_func)
	Frees the list, nodes and data contained in the list.
Gan_Bool	gan_list_insert_first (Gan_List *list, void *data)
	Inserts a new node at the head of the list.
Gan_Bool	gan_list_insert_next (Gan_List *list, void *data)
	Inserts a new node in the position following the current one.
Gan_Bool	gan_list_insert_prev (Gan_List *list, void *data)
	Inserts a new node in the position before current one.
Gan_Bool	gan_list_insert_last (Gan_List *list, void *data)
	Inserts a new node at the tail of the list.
Gan_Bool	gan_list_insert_at (Gan_List *list, void *data, int pos)
	Inserts a new node at a specified position (0 = head).
Gan_Bool	gan_list_delete_first (Gan_List *list, Gan_FreeFunc free_func)
	Deletes the node at the head of the list.
Gan_Bool	gan_list_delete_next (Gan_List *list, Gan_FreeFunc free_func)
	Deletes the node following the current position.
Gan_Bool	gan_list_delete_current (Gan_List *list, Gan_FreeFunc free_func)
	Deletes the node in the current position in a linked list.
Gan_Bool	gan_list_delete_prev (Gan_List *list, Gan_FreeFunc free_func)
	Deletes the node in the position previous to the current one.
Gan_Bool	gan_list_delete_at (Gan_List *list, Gan_FreeFunc free_func, int pos)
	Deletes the node with the specified position (0 = head).
Gan_Bool	gan_list_delete_last (Gan_List *list, Gan_FreeFunc free_func)
	Deletes the node at the tail of the list.
void	gan_list_delete_all (Gan_List *list, Gan_FreeFunc free_func)
	Deletes all the nodes in the list and frees their data.
void	gan_list_goto_head (Gan_List *list)
	Moves the current position to the position before the head.
Gan_Bool	gan_list_goto_pos (Gan_List *list, int pos)
	Moves the current position to the specified position.
void	gan_list_goto_tail (Gan_List *list)
	Moves the current position to the tail of the list.
void *	gan_list_get_prev_node (Gan_List *list)
	Not a user function.
void *	gan_list_get_current_node (Gan_List *list)
	Not a user function.
void *	gan_list_get_next_node (Gan_List *list)
	Not a user function.
void *	gan_list_set_prev (Gan_List *list, void *new_data)
	Sets the previous data pointer, decrements the current position.
void *	gan_list_set_current (Gan_List *list, void *new_data)
	Sets the value of the data pointer in the current node.
void *	gan_list_set_next (Gan_List *list, void *new_data)
	Sets the next data pointer, increments the current position.
void	gan_list_push_current (Gan_List *list)
	Pushes the current position of the data pointer onto the stack.
void	gan_list_pop_current (Gan_List *list)
	Pops the current position of the data pointer from the stack.
int	gan_list_get_pos (Gan_List *list)
	Returns the current position in the list.
int	gan_list_get_size (Gan_List *list)
	Returns the current number of nodes in the list.
void	gan_list_process_data (Gan_List *list, void(*process_func)(void *, void *), void *data)
	Processes all elements in the list.
Gan_List *	gan_list_concat (Gan_List *list1, Gan_List *list2)
	Concatanates two lists, creating a new list.
void	gan_list_reverse (Gan_List *list)
	Reverses the order of the elements in the list.
int	gan_list_to_array (Gan_List *list, void ***array_ptr)
	Creates an array of pointers to the objects in a list.
Gan_List *	gan_list_copy (Gan_List *list)
	Copies all the nodes of a list, creating a new list.
Gan_List *	gan_list_copy_with_data (Gan_List *list, Gan_CopyFunc copy_func)
	Copies all the nodes of a list, creating a new list.
void	gan_list_sort_asc (Gan_List *list, int(*compare)(const void *, const void *))
	Sorts the nodes in the list in ascending order.
void	gan_list_make_straight (Gan_List *list)
	Makes a doubly linked list behave like a straight linked list.
void	gan_list_make_circular (Gan_List *list)
	Makes a doubly linked list behave like a circular linked list.
Gan_Bool	gan_list_is_circular (Gan_List *list)
	Returns GAN_TRUE is the doubly linked list is circular.
Gan_Bool	gan_list_contains (Gan_List *list, void *data)
	Returns GAN_TRUE is the doubly linked list contains 'data'.
TYPE *	gan_list_get_prev (Gan_List *list, TYPE node_type)
	Returns previous data pointer, decrements the current position.
TYPE *	gan_list_get_current (Gan_List *list, TYPE node_type)
	Returns the data pointed to by the current node.
TYPE *	gan_list_get_next (Gan_List *list, TYPE node_type)
	Macro: Returns the next data pointer, increments the current position.

---

Function Documentation

Gan_List * gan_list_concat (  Gan_List *  List1, Gan_List *  List2 )

Concatanates two lists, creating a new list. Parameters: list1  The first linked list list2  The second linked list Returns: The concatenated list as a new list. Concatanates lists list1 and list2, creating a new list that contains the nodes of list1 followed by the nodes of list2.

Gan_Bool gan_list_contains (  Gan_List *  List, void *  data )

Returns GAN_TRUE is the doubly linked list contains 'data'. Parameters: list  The linked list data  The element to look for Returns GAN_TRUE is the doubly linked list contains 'data', GAN_FALSE otherwise.

Gan_List * gan_list_copy (  Gan_List *  List  )

Copies all the nodes of a list, creating a new list. Parameters: list  The linked list Returns: The copy of the list, or NULL on failure. Copies all the nodes of a list, creating a new list. Data pointed to by the nodes is not copied.

Gan_List * gan_list_copy_with_data (  Gan_List *  list, Gan_CopyFunc  copy_func )

Copies all the nodes of a list, creating a new list. Parameters: list  The linked list copy_func  The function used to copy each node Returns: The copy of the list, or NULL on failure. Copies all the nodes of a list, creating a new list, creating copies of each node using the provided function copy_func.

void gan_list_delete_all (  Gan_List *  List, Gan_FreeFunc  free_func )

Deletes all the nodes in the list and frees their data. Parameters: list  The linked list free_func  The function to be called to free the nodes Returns: No value. Deletes all the nodes in the list and frees the data they point to using the function free_func. Pass NULL for free_func if the data pointed to by the nodes should not to be freed

Gan_Bool gan_list_delete_at (  Gan_List *  List, Gan_FreeFunc  free_func, int  pos )

Deletes the node with the specified position (0 = head). Parameters: list  The linked list free_func  The function to be called to free the node pos  Position of node to delete Returns: GAN_TRUE on success, GAN_FALSE on failure. Deletes the node with the specified position pos (0 = head). Pass NULL for free_func if data pointed to by the node should not to be freed.

Gan_Bool gan_list_delete_current (  Gan_List *  List, Gan_FreeFunc  free_func )

Deletes the node in the current position in a linked list. Parameters: list  The linked list free_func  The function to be called to free the node Returns: GAN_TRUE on success, GAN_FALSE on failure. Deletes the node in the current position in a doubly linked list. Moves the current position to the next node in the list.

Gan_Bool gan_list_delete_first (  Gan_List *  List, Gan_FreeFunc  free_func )

Deletes the node at the head of the list. Parameters: list  The linked list free_func  The function to be called to free the node Returns: GAN_TRUE on success, GAN_FALSE on failure. Deletes the node at the head of the list. Pass NULL if data pointed to by the node should not to be freed

Gan_Bool gan_list_delete_last (  Gan_List *  List, Gan_FreeFunc  free_func )

Deletes the node at the tail of the list. Parameters: list  The linked list free_func  The function to be called to free the node Returns: GAN_TRUE on success, GAN_FALSE on failure. Deletes the node at the tail of the list. Pass NULL if data pointed to by the node should not to be freed.

Gan_Bool gan_list_delete_next (  Gan_List *  List, Gan_FreeFunc  free_func )

Deletes the node following the current position. Parameters: list  The linked list free_func  The function to be called to free the node Returns: GAN_TRUE on success, GAN_FALSE on failure. Deletes the node following the current position. The current position can be queried by calling gan_list_get_pos(). If the current position is -1 then the node at the head is deleted, if the current position is the tail the list is a doubly linked circular list then the node at the head is deleted. Pass NULL as the free_func if data pointed to by the node should not to be freed.

Gan_Bool gan_list_delete_prev (  Gan_List *  List, Gan_FreeFunc  free_func )

Deletes the node in the position previous to the current one. Parameters: list  The linked list free_func  The function to be called to free the node Returns: GAN_TRUE on success, GAN_FALSE on failure. Deletes the node in the position previous to the current position in a doubly linked list.

Gan_List * gan_list_form (  Gan_List *  List  )

Forms a new singly linked list containing no elements. Returns: The newly formed list, or NULL on failure. Forms a new singly linked list containing no elements. Memory for the list is provided in the given pointer list.

void gan_list_free (  Gan_List *  List, Gan_FreeFunc  free_func )

Frees the list, nodes and data contained in the list. Parameters: list  The list to free free_func  The function to free each node of the list Returns: No value. Frees the list, nodes and data contained in the list. The list and the function free_func to be used to deallocate the data contained in the nodes are passed as parameters. Pass NULL for free_func if data pointed to by the node should not to be freed.

TYPE* gan_list_get_current (  Gan_List *  list, TYPE  node_type )

Returns the data pointed to by the current node. Parameters: list  The linked list node_type  The type of object the returned pointer points to Returns: Data pointer. Returns the data pointed to by the current node. TYPE is the type the data returned should be cast to, e.g. int.

void * gan_list_get_current_node (  Gan_List *  List  )

Not a user function. Use the gan_list_get_current() macro instead.

TYPE* gan_list_get_next (  Gan_List *  list, TYPE  node_type )

Macro: Returns the next data pointer, increments the current position. Parameters: list  The linked list. node_type  The type of object the returned pointer points to Returns: Data pointer. Returns the data pointed to by the next node and increments the current position such that gan_list_get_next() can be called repeatedly in order to iterate through the list. Call gan_list_goto_head() or another gan_goto_...() function to set the current position in the list first. TYPE is the type the data returned should be cast to, e.g. int.

void * gan_list_get_next_node (  Gan_List *  List  )

Not a user function. Use the gan_list_get_next() macro instead.

int gan_list_get_pos (  Gan_List *  List  )

Returns the current position in the list. Parameters: list  The linked list Returns: Integer position. Returns the current position in the list.

TYPE* gan_list_get_prev (  Gan_List *  list, TYPE  node_type )

Returns previous data pointer, decrements the current position. Parameters: list  List pointer node_type  Type of object in list Returns: Data pointer. Returns the data pointed to by the previous node and decrements the current position such that gan_list_get_prev() can be called repeatedly in order to iterate through the list. Call gan_list_goto_head() or another gan_goto_...() function to set the current position in the list first. TYPE is the type the data returned should be cast to, e.g. int.

void * gan_list_get_prev_node (  Gan_List *  List  )

Not a user function. Use the gan_list_get_prev() macro instead.

int gan_list_get_size (  Gan_List *  List  )

Returns the current number of nodes in the list. Parameters: list  The linked list Returns: Integer number of nodes. Returns the current number of nodes in the list.

void gan_list_goto_head (  Gan_List *  List  )

Moves the current position to the position before the head. Parameters: list  The linked list Returns: No value. Moves the current position to the position before the head. The current position becomes -1 such that the first node in the list becomes the next node and the gan_list_get_next() and gan_list_set_next() functions can be used to iterate through the list.

Gan_Bool gan_list_goto_pos (  Gan_List *  List, int  pos )

Moves the current position to the specified position. Parameters: list  The linked list pos  The position to move to Returns: GAN_TRUE on success, GAN_FALSE on failure. Moves the current position to the specified position. -1 = position before the first element 0 = head of the list

void gan_list_goto_tail (  Gan_List *  List  )

Moves the current position to the tail of the list. Parameters: list  The linked list Returns: No value. Moves the current position to the tail of the list.

Gan_Bool gan_list_insert_at (  Gan_List *  List, void *  data, int  pos )

Inserts a new node at a specified position (0 = head). Parameters: list  The linked list data  The data pointer to insert pos  The position at which to insert the data pointer Returns: GAN_TRUE on success, GAN_FALSE on failure. Inserts a new data node at a specified position pos (0 = head). If the specified position is larger than the current number of nodes the new node is inserted at the tail of the list.

Gan_Bool gan_list_insert_first (  Gan_List *  List, void *  data )

Inserts a new node at the head of the list. Parameters: list  The list data  The data pointer to insert in the list Returns: GAN_TRUE on success, GAN_FALSE on failure. Inserts a new node at the head of the list that points to the object pointed to by the data parameter. See also: gan_list_insert_next(), gan_list_insert_prev(), gan_list_insert_last().

Gan_Bool gan_list_insert_last (  Gan_List *  List, void *  data )

Inserts a new node at the tail of the list. Parameters: list  The list data  The data pointer to insert in the list Returns: GAN_TRUE on success, GAN_FALSE on failure. Inserts a new data node at the tail of the list. See also: gan_list_insert_first(), gan_list_insert_next(), gan_list_insert_prev().

Gan_Bool gan_list_insert_next (  Gan_List *  List, void *  data )

Inserts a new node in the position following the current one. Parameters: list  The list data  The data pointer to insert in the list Returns: GAN_TRUE on success, GAN_FALSE on failure. Inserts a new node in the position following the current position. The current position can be queried by calling gan_list_get_pos(). See also: gan_list_insert_first(), gan_list_insert_prev(), gan_list_insert_last().

Gan_Bool gan_list_insert_prev (  Gan_List *  List, void *  data )

Inserts a new node in the position before current one. Parameters: list  The list data  The data pointer to insert in the list Returns: GAN_TRUE on success, GAN_FALSE on failure. Inserts a new data node in the position before the current position. The current position can be queried by calling gan_list_get_pos(). See also: gan_list_insert_first(), gan_list_insert_next(), gan_list_insert_last().

Gan_Bool gan_list_is_circular (  Gan_List *  List  )

Returns GAN_TRUE is the doubly linked list is circular. Parameters: list  The linked list Returns GAN_TRUE is the doubly linked list is circular, GAN_FALSE otherwise.

void gan_list_make_circular (  Gan_List *  List  )

Makes a doubly linked list behave like a circular linked list. Parameters: list  The linked list Returns: No value. Makes a doubly linked list behave like a circular linked list.

void gan_list_make_straight (  Gan_List *  List  )

Makes a doubly linked list behave like a straight linked list. Parameters: list  The linked list Returns: No value. Makes a doubly linked list behave like a straight linked list

Gan_List * gan_list_new (  void   )

Makes a new singly linked list containing no elements. Returns: The new list, or NULL on ailure. Makes a new singly linked list containing no elements. Memory for the list is allocated using gan_malloc_object().

Gan_List * gan_list_new_from_array (  void **  array, unsigned  n )

Makes a new linked list containing nodes with data from array. Returns: The new list, or NULL on failure. Makes a new singly linked list containing nodes with data from array. The array and the number of elements in the array are passed as parameters.

void gan_list_pop_current (  Gan_List *  List  )

Pops the current position of the data pointer from the stack. Parameters: list  The linked list Returns: No value. Pops the current position of the data pointer in the list from the stack.

void gan_list_process_data (  Gan_List *  List, void(*)(void *, void *)  process_func, void *  data )

Processes all elements in the list. Parameters: list  The linked list process_func  Function to call on each element of the list data  Pointer passed to process_func Returns: No value. Processes all elements in the list by calling the process_func. As arguments to the function the pointer to a nodes data object and the data pointer are passed.

void gan_list_push_current (  Gan_List *  List  )

Pushes the current position of the data pointer onto the stack. Parameters: list  The linked list Returns: No value. Pushes the current position of the data pointer in the list onto the stack.

void gan_list_reverse (  Gan_List *  List  )

Reverses the order of the elements in the list. Parameters: list  The linked list Returns: No value. Reverses the order of the elements in the list.

void * gan_list_set_current (  Gan_List *  List, void *  new_data )

Sets the value of the data pointer in the current node. Parameters: list  The linked list new_data  Data pointer Returns: Data pointer. Sets the value of the data pointer in the current node. A pointer to the old data is returned.

void * gan_list_set_next (  Gan_List *  List, void *  new_data )

Sets the next data pointer, increments the current position. Parameters: list  The linked list new_data  Data pointer Returns: Data pointer. Sets the value of the data pointer in the next node of a linked list and increments the current position. A pointer to the old data is returned.

void * gan_list_set_prev (  Gan_List *  List, void *  new_data )

Sets the previous data pointer, decrements the current position. Parameters: list  The linked list new_data  Data pointer Returns: Data pointer. Sets the value of the data pointer in the previous node and decrements the current position in a doubly linked list. A pointer to the old data is returned.

void gan_list_sort_asc (  Gan_List *  List, int(*)(const void *, const void *)  compare )

Sorts the nodes in the list in ascending order. Parameters: list  The linked list compare  Function to use to compare the list elements Returns: GAN_TRUE on success, GAN_FALSE on failure. Sorts the nodes in the list in ascending order. A pointer to a comparison function compare used to evaluate the order of two data objects must be passed. See documentation for qsort().

int gan_list_to_array (  Gan_List *  List, void ***  array_ptr )

Creates an array of pointers to the objects in a list. Parameters: list  The linked list array_ptr  Pointer to the allocated and filled array Returns: Number of nodes in the list, or -1 on failure. Creates an array of pointers to the objects pointed to by the nodes.

---