Interface for list implementations. More...

#include "common.h"
#include "collection.h"

Data Structures
struct	cx_list_s
	Structure for holding the base data of a list. More...

struct	cx_list_class_s
	The class definition for arbitrary lists. More...

Typedefs
typedef struct cx_list_class_s	cx_list_class
	List class type.

typedef struct cx_list_s	CxList
	Common type for all list implementations.

Functions
void	cxListStoreObjects (CxList *list)
	Advises the list to store copies of the objects (default mode of operation).

void	cxListStorePointers (CxList *list)
	Advises the list to only store pointers to the objects.

static bool	cxListIsStoringPointers (CxList const *list)
	Returns true, if this list is storing pointers instead of the actual data.

static size_t	cxListSize (CxList const *list)
	Returns the number of elements currently stored in the list.

static int	cxListAdd (CxList list, void const elem)
	Adds an item to the end of the list.

static size_t	cxListAddArray (CxList list, void const array, size_t n)
	Adds multiple items to the end of the list.

static int	cxListInsert (CxList list, size_t index, void const elem)
	Inserts an item at the specified index.

static size_t	cxListInsertArray (CxList list, size_t index, void const array, size_t n)
	Inserts multiple items to the list at the specified index.

static int	cxListInsertAfter (CxMutIterator iter, void const elem)
	Inserts an element after the current location of the specified iterator.

static int	cxListInsertBefore (CxMutIterator iter, void const elem)
	Inserts an element before the current location of the specified iterator.

static int	cxListRemove (CxList *list, size_t index)
	Removes the element at the specified index.

static void	cxListClear (CxList *list)
	Removes all elements from this list.

static int	cxListSwap (CxList *list, size_t i, size_t j)
	Swaps two items in the list.

static void *	cxListAt (CxList *list, size_t index)
	Returns a pointer to the element at the specified index.

static CxIterator	cxListIteratorAt (CxList const *list, size_t index)
	Returns an iterator pointing to the item at the specified index.

static CxIterator	cxListBackwardsIteratorAt (CxList const *list, size_t index)
	Returns a backwards iterator pointing to the item at the specified index.

CxMutIterator	cxListMutIteratorAt (CxList *list, size_t index)
	Returns a mutating iterator pointing to the item at the specified index.

CxMutIterator	cxListMutBackwardsIteratorAt (CxList *list, size_t index)
	Returns a mutating backwards iterator pointing to the item at the specified index.

static CxIterator	cxListIterator (CxList const *list)
	Returns an iterator pointing to the first item of the list.

static CxMutIterator	cxListMutIterator (CxList *list)
	Returns a mutating iterator pointing to the first item of the list.

static CxIterator	cxListBackwardsIterator (CxList const *list)
	Returns a backwards iterator pointing to the last item of the list.

static CxMutIterator	cxListMutBackwardsIterator (CxList *list)
	Returns a mutating backwards iterator pointing to the last item of the list.

static ssize_t	cxListFind (CxList const list, void const elem)
	Returns the index of the first element that equals `elem`.

static void	cxListSort (CxList *list)
	Sorts the list in-place.

static void	cxListReverse (CxList *list)
	Reverses the order of the items.

int	cxListCompare (CxList const list, CxList const other)
	Compares a list to another list of the same type.

void	cxListDestroy (CxList *list)
	Deallocates the memory of the specified list structure.

Variables
CxList *const	cxEmptyList
	A shared instance of an empty list.

Detailed Description

Interface for list implementations.

Author: Mike Becker; Olaf Wintermann

Version: 3.0

Copyright: 2-Clause BSD License

Function Documentation

◆ cxListAdd()

static int cxListAdd	(	CxList *	list,
		void const *	elem
	)

inlinestatic

Adds an item to the end of the list.

Parameters

list	the list
elem	a pointer to the element to add

Returns: zero on success, non-zero on memory allocation failure

See also: cxListAddArray()

◆ cxListAddArray()

static size_t cxListAddArray	(	CxList *	list,
		void const *	array,
		size_t	n
	)

inlinestatic

Adds multiple items to the end of the list.

This method is more efficient than invoking cxListAdd() multiple times.

If there is not enough memory to add all elements, the returned value is less than n.

If this list is storing pointers instead of objects array is expected to be an array of pointers.

Parameters

list	the list
array	a pointer to the elements to add
n	the number of elements to add

Returns: the number of added elements

◆ cxListAt()

static void * cxListAt	(	CxList *	list,
		size_t	index
	)

inlinestatic

Returns a pointer to the element at the specified index.

Parameters

list	the list
index	the index of the element

Returns: a pointer to the element or NULL if the index is out of bounds

◆ cxListBackwardsIterator()

static CxIterator cxListBackwardsIterator ( CxList const * list )

inlinestatic

Returns a backwards iterator pointing to the last item of the list.

The returned iterator is position-aware.

If the list is empty, a past-the-end iterator will be returned.

Parameters

list the list

Returns: a new iterator

◆ cxListBackwardsIteratorAt()

static CxIterator cxListBackwardsIteratorAt	(	CxList const *	list,
		size_t	index
	)

inlinestatic

Returns a backwards iterator pointing to the item at the specified index.

The returned iterator is position-aware.

If the index is out of range, a past-the-end iterator will be returned.

Parameters

list	the list
index	the index where the iterator shall point at

Returns: a new iterator

◆ cxListClear()

static void cxListClear ( CxList * list )

inlinestatic

Removes all elements from this list.

If an element destructor function is specified, it is called for each element before removing them.

Parameters

list the list

◆ cxListCompare()

int cxListCompare	(	CxList const *	list,
		CxList const *	other
	)

Compares a list to another list of the same type.

First, the list sizes are compared. If they match, the lists are compared element-wise.

Parameters

list	the list
other	the list to compare to

Returns: zero, if both lists are equal element wise, negative if the first list is smaller, positive if the first list is larger

◆ cxListDestroy()

void cxListDestroy ( CxList * list )

Deallocates the memory of the specified list structure.

Also calls content a destructor function, depending on the configuration in CxList.content_destructor_type.

This function itself is a destructor function for the CxList.

Parameters

list	the list which shall be destroyed

◆ cxListFind()

static ssize_t cxListFind	(	CxList const *	list,
		void const *	elem
	)

inlinestatic

Returns the index of the first element that equals elem.

Determining equality is performed by the list's comparator function.

Parameters

list	the list
elem	the element to find

Returns: the index of the element or a negative value when the element is not found

◆ cxListInsert()

static int cxListInsert	(	CxList *	list,
		size_t	index,
		void const *	elem
	)

inlinestatic

Inserts an item at the specified index.

If index equals the list size, this is effectively cxListAdd().

Parameters

list	the list
index	the index the element shall have
elem	a pointer to the element to add

Returns: zero on success, non-zero on memory allocation failure or when the index is out of bounds

See also: cxListInsertAfter(); cxListInsertBefore()

◆ cxListInsertAfter()

static int cxListInsertAfter	(	CxMutIterator *	iter,
		void const *	elem
	)

inlinestatic

Inserts an element after the current location of the specified iterator.

The used iterator remains operational, but all other active iterators should be considered invalidated.

If iter is not a list iterator, the behavior is undefined. If iter is a past-the-end iterator, the new element gets appended to the list.

Parameters

iter	an iterator
elem	the element to insert

Returns: zero on success, non-zero on memory allocation failure

See also: cxListInsert(); cxListInsertBefore()

◆ cxListInsertArray()

static size_t cxListInsertArray	(	CxList *	list,
		size_t	index,
		void const *	array,
		size_t	n
	)

inlinestatic

Inserts multiple items to the list at the specified index.

If index equals the list size, this is effectively cxListAddArray().

This method is usually more efficient than invoking cxListInsert() multiple times.

If there is not enough memory to add all elements, the returned value is less than n.

If this list is storing pointers instead of objects array is expected to be an array of pointers.

Parameters

list	the list
index	the index where to add the elements
array	a pointer to the elements to add
n	the number of elements to add

Returns: the number of added elements

◆ cxListInsertBefore()

static int cxListInsertBefore	(	CxMutIterator *	iter,
		void const *	elem
	)

inlinestatic

Inserts an element before the current location of the specified iterator.

The used iterator remains operational, but all other active iterators should be considered invalidated.

If iter is not a list iterator, the behavior is undefined. If iter is a past-the-end iterator, the new element gets appended to the list.

Parameters

iter	an iterator
elem	the element to insert

Returns: zero on success, non-zero on memory allocation failure

See also: cxListInsert(); cxListInsertAfter()

◆ cxListIsStoringPointers()

static bool cxListIsStoringPointers ( CxList const * list )

inlinestatic

Returns true, if this list is storing pointers instead of the actual data.

Parameters

list

Returns: true, if this list is storing pointers

See also: cxListStorePointers()

◆ cxListIterator()

static CxIterator cxListIterator ( CxList const * list )

inlinestatic

Returns an iterator pointing to the first item of the list.

The returned iterator is position-aware.

If the list is empty, a past-the-end iterator will be returned.

Parameters

list the list

Returns: a new iterator

◆ cxListIteratorAt()

static CxIterator cxListIteratorAt	(	CxList const *	list,
		size_t	index
	)

inlinestatic

Returns an iterator pointing to the item at the specified index.

The returned iterator is position-aware.

If the index is out of range, a past-the-end iterator will be returned.

Parameters

list	the list
index	the index where the iterator shall point at

Returns: a new iterator

◆ cxListMutBackwardsIterator()

static CxMutIterator cxListMutBackwardsIterator ( CxList * list )

inlinestatic

Returns a mutating backwards iterator pointing to the last item of the list.

The returned iterator is position-aware.

If the list is empty, a past-the-end iterator will be returned.

Parameters

list the list

Returns: a new iterator

◆ cxListMutBackwardsIteratorAt()

CxMutIterator cxListMutBackwardsIteratorAt	(	CxList *	list,
		size_t	index
	)

Returns a mutating backwards iterator pointing to the item at the specified index.

The returned iterator is position-aware.

If the index is out of range, a past-the-end iterator will be returned.

Parameters

list	the list
index	the index where the iterator shall point at

Returns: a new iterator

◆ cxListMutIterator()

static CxMutIterator cxListMutIterator ( CxList * list )

inlinestatic

Returns a mutating iterator pointing to the first item of the list.

The returned iterator is position-aware.

If the list is empty, a past-the-end iterator will be returned.

Parameters

list the list

Returns: a new iterator

◆ cxListMutIteratorAt()

CxMutIterator cxListMutIteratorAt	(	CxList *	list,
		size_t	index
	)

Returns a mutating iterator pointing to the item at the specified index.

The returned iterator is position-aware.

If the index is out of range, a past-the-end iterator will be returned.

Parameters

list	the list
index	the index where the iterator shall point at

Returns: a new iterator

◆ cxListRemove()

static int cxListRemove	(	CxList *	list,
		size_t	index
	)

inlinestatic

Removes the element at the specified index.

If an element destructor function is specified, it is called before removing the element.

Parameters

list	the list
index	the index of the element

Returns: zero on success, non-zero if the index is out of bounds

◆ cxListReverse()

static void cxListReverse ( CxList * list )

inlinestatic

Reverses the order of the items.

Parameters

list the list

◆ cxListSize()

static size_t cxListSize ( CxList const * list )

inlinestatic

Returns the number of elements currently stored in the list.

Parameters

list the list

Returns: the number of currently stored elements

◆ cxListSort()

static void cxListSort ( CxList * list )

inlinestatic

Sorts the list in-place.

Remarks: The underlying sort algorithm is implementation defined.

Parameters

list the list

◆ cxListStoreObjects()

void cxListStoreObjects ( CxList * list )

Advises the list to store copies of the objects (default mode of operation).

Retrieving objects from this list will yield pointers to the copies stored within this list.

Parameters

list the list

See also: cxListStorePointers()

◆ cxListStorePointers()

void cxListStorePointers ( CxList * list )

Advises the list to only store pointers to the objects.

Retrieving objects from this list will yield the original pointers stored.

Note: This function forcibly sets the element size to the size of a pointer. Invoking this function on a non-empty list that already stores copies of objects is undefined.

Parameters

list the list

See also: cxListStoreObjects()

◆ cxListSwap()

static int cxListSwap	(	CxList *	list,
		size_t	i,
		size_t	j
	)

inlinestatic

Swaps two items in the list.

Implementations should only allocate temporary memory for the swap, if it is necessary.

Parameters

list	the list
i	the index of the first element
j	the index of the second element

Returns: zero on success, non-zero if one of the indices is out of bounds

Variable Documentation

◆ cxEmptyList

CxList* const cxEmptyList

extern

A shared instance of an empty list.

Writing to that list is undefined.

Data Structures

Typedefs

Functions

Variables

Detailed Description

Function Documentation

◆ cxListAdd()

◆ cxListAddArray()

◆ cxListAt()

◆ cxListBackwardsIterator()

◆ cxListBackwardsIteratorAt()

◆ cxListClear()

◆ cxListCompare()

◆ cxListDestroy()

◆ cxListFind()

◆ cxListInsert()

◆ cxListInsertAfter()

◆ cxListInsertArray()

◆ cxListInsertBefore()

◆ cxListIsStoringPointers()

◆ cxListIterator()

◆ cxListIteratorAt()

◆ cxListMutBackwardsIterator()

◆ cxListMutBackwardsIteratorAt()

◆ cxListMutIterator()

◆ cxListMutIteratorAt()

◆ cxListRemove()

◆ cxListReverse()

◆ cxListSize()

◆ cxListSort()

◆ cxListStoreObjects()

◆ cxListStorePointers()

◆ cxListSwap()

Variable Documentation

◆ cxEmptyList