C Standard Library Extensions 1.2.6
Functions
Singly Linked Lists

Functions

cx_slist_iterator cx_slist_begin (const cx_slist *list)
 Get list iterator to the beginning of a list.
 
cx_slist_iterator cx_slist_end (const cx_slist *list)
 Get a list iterator to the end of a list.
 
cx_slist_iterator cx_slist_next (const cx_slist *list, cx_slist_const_iterator position)
 Get a list iterator to the next list element.
 
void cx_slist_clear (cx_slist *list)
 Remove all elements from a list.
 
cxbool cx_slist_empty (const cx_slist *list)
 Check whether a list is empty.
 
cx_slist * cx_slist_new (void)
 Create a new list without any elements.
 
void cx_slist_delete (cx_slist *list)
 Destroy a list.
 
void cx_slist_destroy (cx_slist *list, cx_free_func deallocate)
 Destroy a list and all its elements.
 
cxsize cx_slist_size (const cx_slist *list)
 Get the actual number of list elements.
 
cxsize cx_slist_max_size (const cx_slist *list)
 Get the maximum number of list elements possible.
 
void cx_slist_swap (cx_slist *list1, cx_slist *list2)
 Swap the data of two lists.
 
cxptr cx_slist_assign (cx_slist *list, cx_slist_iterator position, cxcptr data)
 Assign data to a list position.
 
cxptr cx_slist_front (const cx_slist *list)
 Get the first element of a list.
 
cxptr cx_slist_back (const cx_slist *list)
 Get the last element of a list.
 
cxptr cx_slist_get (const cx_slist *list, cx_slist_const_iterator position)
 Get the data at a given iterator position.
 
cx_slist_iterator cx_slist_insert (cx_slist *list, cx_slist_iterator position, cxcptr data)
 Insert data into a list at a given iterator position.
 
void cx_slist_push_front (cx_slist *list, cxcptr data)
 Insert data at the beginning of a list.
 
void cx_slist_push_back (cx_slist *list, cxcptr data)
 Append data at the end of a list.
 
cx_slist_iterator cx_slist_erase (cx_slist *list, cx_slist_iterator position, cx_free_func deallocate)
 Erase a list list element.
 
cxptr cx_slist_extract (cx_slist *list, cx_slist_iterator position)
 Extract a list element.
 
cxptr cx_slist_pop_front (cx_slist *list)
 Remove the first list element.
 
cxptr cx_slist_pop_back (cx_slist *list)
 Remove the last element of a list.
 
void cx_slist_remove (cx_slist *list, cxcptr data)
 Remove all elements with a given value from a list.
 
void cx_slist_unique (cx_slist *list, cx_compare_func compare)
 Remove duplicates of consecutive elements.
 
void cx_slist_splice (cx_slist *tlist, cx_slist_iterator position, cx_slist *slist, cx_slist_iterator first, cx_slist_iterator last)
 Move a range of list elements in front of a given position.
 
void cx_slist_merge (cx_slist *list1, cx_slist *list2, cx_compare_func compare)
 Merge two sorted lists.
 
void cx_slist_sort (cx_slist *list, cx_compare_func compare)
 Sort all elements of a list using the given comparison function.
 
void cx_slist_reverse (cx_slist *list)
 Reverse the order of all list elements.
 

Detailed Description

The module implements a linked list object restricted to iterations in just one direction and methods to create, destroy and manipulate it.

Synopsis:
#include <cxslist.h>

Function Documentation

◆ cx_slist_assign()

cxptr cx_slist_assign ( cx_slist *  list,
cx_slist_iterator  position,
cxcptr  data 
)

Assign data to a list position.

Parameters
listA list.
positionList position where the data will be stored
dataData to store.
Returns
Handle to the previously stored data object.

The function assigns the data object reference data to the iterator position position of the list list.

◆ cx_slist_back()

cxptr cx_slist_back ( const cx_slist *  list)

Get the last element of a list.

Parameters
listThe list to query.
Returns
Handle to the data object stored as the last list element.

The function returns a reference to the last data item in the list list.

References cx_slist_empty().

◆ cx_slist_begin()

cx_slist_iterator cx_slist_begin ( const cx_slist *  list)

Get list iterator to the beginning of a list.

Parameters
listA list.
Returns
Iterator for the first element in the list, or cx_slist_end() if the list is empty.

The function returns a handle to the first element of list. The handle cannot be used directly to access the element data, but only through the appropriate functions.

Referenced by cx_strsplit().

◆ cx_slist_clear()

void cx_slist_clear ( cx_slist *  list)

Remove all elements from a list.

Parameters
listList to be cleared.
Returns
Nothing.

The list list is cleared, i.e. all elements are removed from the list. The removed data objects are left untouched, in particular they are not deallocated. It is the responsibility of the caller to ensure that there still are other references to the removed data objects. After calling cx_slist_clear() the list list is empty.

◆ cx_slist_delete()

void cx_slist_delete ( cx_slist *  list)

Destroy a list.

Parameters
listThe list to delete.
Returns
Nothing.

The function deallocates the list object, but not the data objects currently stored in the list.

References cx_free(), and cx_slist_empty().

Referenced by cx_strsplit().

◆ cx_slist_destroy()

void cx_slist_destroy ( cx_slist *  list,
cx_free_func  deallocate 
)

Destroy a list and all its elements.

Parameters
listList container to destroy.
deallocateData deallocator.
Returns
Nothing.

The function deallocates all data objects referenced by the list using the data deallocation function deallocate and finally dealocates the list object itself.

References cx_free(), and cx_slist_empty().

◆ cx_slist_empty()

cxbool cx_slist_empty ( const cx_slist *  list)

Check whether a list is empty.

Parameters
listA list.
Returns
The function returns TRUE if the list is empty, and FALSE otherwise.

The function tests if the list list contains data. A call to this function is equivalent to the statement:

return (cx_slist_size(list) == 0);
cxsize cx_slist_size(const cx_slist *list)
Get the actual number of list elements.
Definition cxslist.c:803

Referenced by cx_slist_back(), cx_slist_delete(), cx_slist_destroy(), and cx_slist_front().

◆ cx_slist_end()

cx_slist_iterator cx_slist_end ( const cx_slist *  list)

Get a list iterator to the end of a list.

Parameters
listA list.
Returns
Iterator for the end of the list.

The function returns an iterator for the position one past the last element of the list list. The handle cannot be used to directly access the element data, but only through the appropriate functions.

Referenced by cx_strsplit().

◆ cx_slist_erase()

cx_slist_iterator cx_slist_erase ( cx_slist *  list,
cx_slist_iterator  position,
cx_free_func  deallocate 
)

Erase a list list element.

Parameters
listThe list to update.
positionList iterator position.
deallocateData deallocator.
Returns
The iterator for the list position after position.

The function removes the data object stored at position position from the list list. The data object is deallocated bz calling the data deallocator deallocate.

◆ cx_slist_extract()

cxptr cx_slist_extract ( cx_slist *  list,
cx_slist_iterator  position 
)

Extract a list element.

Parameters
listA list.
positionList iterator position.
Returns
Handle to the previously stored data object.

The function removes a data object from the list list located at the iterator position position without destroying the data object.

See also
cx_slist_erase(), cx_slist_remove()

◆ cx_slist_front()

cxptr cx_slist_front ( const cx_slist *  list)

Get the first element of a list.

Parameters
listThe list to query.
Returns
Handle to the data object stored as the first list element.

The function returns a reference to the first data item in the list list.

References cx_slist_empty().

◆ cx_slist_get()

cxptr cx_slist_get ( const cx_slist *  list,
cx_slist_const_iterator  position 
)

Get the data at a given iterator position.

Parameters
listA list.
positionList position the data is retrieved from.
Returns
Handle to the data object.

The function returns a reference to the data item stored in the list list at the iterator position position.

Referenced by cx_strsplit().

◆ cx_slist_insert()

cx_slist_iterator cx_slist_insert ( cx_slist *  list,
cx_slist_iterator  position,
cxcptr  data 
)

Insert data into a list at a given iterator position.

Parameters
listThe list to update.
positionList iterator position.
dataData item to insert.
Returns
List iterator position of the inserted data item.

The function inserts the data handle data into the list list at the list position given by the list iterator position.

References cx_slist_max_size().

◆ cx_slist_max_size()

cxsize cx_slist_max_size ( const cx_slist *  list)

Get the maximum number of list elements possible.

Parameters
listA list.
Returns
The maximum number of elements that can be stored in the list.

Retrieves the lists capacity, i.e. the maximum possible number of data items a list can hold.

Referenced by cx_slist_insert().

◆ cx_slist_merge()

void cx_slist_merge ( cx_slist *  list1,
cx_slist *  list2,
cx_compare_func  compare 
)

Merge two sorted lists.

Parameters
list1First list to merge.
list2Second list to merge.
compareFunction comparing the list elements.
Returns
Nothing.

The function combines the two lists list1 and list2 by moving all elements from list2 into list1, so that all elements are still sorted. The function requires that both input lists are already sorted. The sorting order in which the elements of list2 are inserted into list1 is determined by the comparison function compare. The comparison function compare must return an integer less than, equal or greater than zero if the first argument passed to it is found, respectively, to be less than, match, or be greater than the second argument.

The list list2 is consumed by this process, i.e. after the successful merging of the two lists, list list2 will be empty.

◆ cx_slist_new()

cx_slist * cx_slist_new ( void  )

Create a new list without any elements.

Returns
Handle to the newly allocated list.

The function allocates memory for the list object and initializes it to a empty list.

References cx_malloc().

Referenced by cx_strsplit().

◆ cx_slist_next()

cx_slist_iterator cx_slist_next ( const cx_slist *  list,
cx_slist_const_iterator  position 
)

Get a list iterator to the next list element.

Parameters
listA list.
positionCurrent iterator position.
Returns
Iterator for the next list element.

The function returns an iterator for the next element in the list list with respect to the current iterator position position. If the list list is empty or position points to the list end the function returns cx_slist_end().

See also
cx_slist_empty()

Referenced by cx_strsplit().

◆ cx_slist_pop_back()

cxptr cx_slist_pop_back ( cx_slist *  list)

Remove the last element of a list.

Parameters
listThe list to update.
Returns
Handle to the data object previously stored as the last list element.

The function removes the last element from the list list returning a handle to the previously stored data.

◆ cx_slist_pop_front()

cxptr cx_slist_pop_front ( cx_slist *  list)

Remove the first list element.

Parameters
listThe list to update.
Returns
Handle to the data object previously stored as the last list element.

The function removes the first element from the list list returning a handle to the previously stored data.

◆ cx_slist_push_back()

void cx_slist_push_back ( cx_slist *  list,
cxcptr  data 
)

Append data at the end of a list.

Parameters
listThe list to update.
dataData to append.
Returns
Nothing.

The data data is inserted into the list list after the last element, so that it becomes the new list tail.

It is equivalent to the statement

cx_slist_insert(list, cx_slist_end(list), data);
cx_slist_iterator cx_slist_end(const cx_slist *list)
Get a list iterator to the end of a list.
Definition cxslist.c:604
cx_slist_iterator cx_slist_insert(cx_slist *list, cx_slist_iterator position, cxcptr data)
Insert data into a list at a given iterator position.
Definition cxslist.c:990

◆ cx_slist_push_front()

void cx_slist_push_front ( cx_slist *  list,
cxcptr  data 
)

Insert data at the beginning of a list.

Parameters
listThe list to update.
dataData to add to the list.
Returns
Nothing

The data data is inserted into the list list before the first element of the list, so that it becomes the new list head.

It is equivalent to the statement

cx_slist_insert(list, cx_slist_begin(list), data);
cx_slist_iterator cx_slist_begin(const cx_slist *list)
Get list iterator to the beginning of a list.
Definition cxslist.c:580

Referenced by cx_strsplit().

◆ cx_slist_remove()

void cx_slist_remove ( cx_slist *  list,
cxcptr  data 
)

Remove all elements with a given value from a list.

Parameters
listA list object.
dataData to remove.
Returns
Nothing.

The value data is searched in the list list. If the data is found it is removed from the list. The data object itself is not deallocated.

◆ cx_slist_reverse()

void cx_slist_reverse ( cx_slist *  list)

Reverse the order of all list elements.

Parameters
listThe list to reverse.
Returns
Nothing.

The order of the elements of the list list is reversed.

◆ cx_slist_size()

cxsize cx_slist_size ( const cx_slist *  list)

Get the actual number of list elements.

Parameters
listA list.
Returns
The current number of elements the list contains, or 0 if the list is empty.

Retrieves the number of elements currently stored in the list list.

◆ cx_slist_sort()

void cx_slist_sort ( cx_slist *  list,
cx_compare_func  compare 
)

Sort all elements of a list using the given comparison function.

Parameters
listThe list to sort.
compareFunction comparing the list elements.
Returns
Nothing.

The input list list is sorted using the comparison function compare to determine the order of two list elements. The comparison function compare must return an integer less than, equal or greater than zero if the first argument passed to it is found, respectively, to be less than, match, or be greater than the second argument.

◆ cx_slist_splice()

void cx_slist_splice ( cx_slist *  tlist,
cx_slist_iterator  position,
cx_slist *  slist,
cx_slist_iterator  first,
cx_slist_iterator  last 
)

Move a range of list elements in front of a given position.

Parameters
tlistTarget list.
positionTarget iterator position.
slistSource list.
firstPosition of the first element to move.
lastPosition of the last element to move.
Returns
Nothing.

The range of list elements from the iterator position first to last, but not including last, is moved from the source list slist in front of the position position of the target list tlist. Target and source list may be identical, provided that the target position position does not fall within the range of list elements to move.

◆ cx_slist_swap()

void cx_slist_swap ( cx_slist *  list1,
cx_slist *  list2 
)

Swap the data of two lists.

Parameters
list1First list.
list2Second list.
Returns
Nothing.

The contents of the first list list1 will be moved to the second list list2, while the contents of list2 is moved to list1.

◆ cx_slist_unique()

void cx_slist_unique ( cx_slist *  list,
cx_compare_func  compare 
)

Remove duplicates of consecutive elements.

Parameters
listA list.
compareFunction comparing the list elements.
Returns
Nothing.

The function removes duplicates of consecutive list elements, i.e. list elements with the same value, from the list list. The equality of the list elements is checked using the comparison function compare. The comparison function compare must return an integer less than, equal or greater than zero if the first argument passed to it is found, respectively, to be less than, match, or be greater than the second argument.