Singly-linked list

A linked list allowing traversal in the forward direction. More...

Data Structures
struct	cstl_slist_node
	Node to anchor an element within a list. More...
struct	cstl_slist
	List object. More...

Macros
#define	CSTL_SLIST_INITIALIZER(NAME, TYPE, MEMB)
	Constant initialization of a slist object.
#define	DECLARE_CSTL_SLIST(NAME, TYPE, MEMB)    struct cstl_slist NAME = CSTL_SLIST_INITIALIZER(NAME, TYPE, MEMB)
	(Statically) declare and initialize a list

Functions
static void	cstl_slist_init (struct cstl_slist *const sl, const size_t off)
	Initialize a slist object.
static size_t	cstl_slist_size (const struct cstl_slist *sl)
	Get the number of objects in the list.
void	cstl_slist_insert_after (struct cstl_slist *sl, void *before, void *obj)
	Insert a new object into the list.
void *	cstl_slist_erase_after (struct cstl_slist *sl, void *bef)
	Remove an object from the list.
void	cstl_slist_push_front (struct cstl_slist *sl, void *obj)
	Insert a new object at the front of the list.
void	cstl_slist_push_back (struct cstl_slist *sl, void *obj)
	Insert a new object at the back of the list.
void *	cstl_slist_pop_front (struct cstl_slist *sl)
	Remove the first item in the list and return it.
void *	cstl_slist_front (const struct cstl_slist *sl)
	Get a pointer to the first object in the list.
void *	cstl_slist_back (const struct cstl_slist *sl)
	Get a pointer to the last object in the list.
void	cstl_slist_reverse (struct cstl_slist *sl)
	Reverse the order of items in the list.
void	cstl_slist_sort (struct cstl_slist *sl, cstl_compare_func_t *cmp, void *priv)
	Sort the items in a list.
void	cstl_slist_concat (struct cstl_slist *list, struct cstl_slist *more)
	Append one list to the end of another.
int	cstl_slist_foreach (struct cstl_slist *sl, cstl_visit_func_t *visit, void *priv)
	Call a user-supplied function for each object in a list.
void	cstl_slist_clear (struct cstl_slist *sl, cstl_xtor_func_t *clr)
	Remove objects from and reinitialize a list.
void	cstl_slist_swap (struct cstl_slist *const a, struct cstl_slist *const b)
	Swap the list objects at the two given locations.

Detailed Description

A linked list allowing traversal in the forward direction.

Macro Definition Documentation

CSTL_SLIST_INITIALIZER

#define CSTL_SLIST_INITIALIZER	(		NAME,
			TYPE,
			MEMB
	)

Value:

    {                                                   \
        .h = {                                          \
            .n = NULL,                                  \
        },                                              \
        .t = &NAME.h,                                   \
        .count = 0,                                     \
        .off = offsetof(TYPE, MEMB),                    \
    }

Constant initialization of a slist object.

Parameters

NAME	The name of the variable being initialized
TYPE	The type of object that the list will hold
MEMB	The name of the cstl_slist_node member within TYPE.

See also

cstl_slist_node for a description of the relationship between TYPE and MEMB

Definition at line 73 of file slist.h.

DECLARE_CSTL_SLIST

#define DECLARE_CSTL_SLIST	(		NAME,
			TYPE,
			MEMB
	)		struct cstl_slist NAME = CSTL_SLIST_INITIALIZER(NAME, TYPE, MEMB)

(Statically) declare and initialize a list

Parameters

NAME	The name of the variable being declared
TYPE	The type of object that the list will hold
MEMB	The name of the cstl_slist_node member within TYPE.

See also

cstl_slist_node for a description of the relationship between TYPE and MEMB

Definition at line 92 of file slist.h.

Function Documentation

cstl_slist_back()

void * cstl_slist_back

(

const struct cstl_slist *

sl

)

Get a pointer to the last object in the list.

Parameters

[in]

sl

A pointer to a list

Returns

A pointer to the last object in the list

Return values

NULL	The list is empty

Definition at line 94 of file slist.c.

cstl_slist_clear()

void cstl_slist_clear	(	struct cstl_slist *	sl,
		cstl_xtor_func_t *	clr
	)

Remove objects from and reinitialize a list.

Parameters

[in]	sl	The list to be cleared
[in]	clr	The function to be called for each object in the list

All objects are removed from the list and the clr function is called for each object that was in the list. The order in which the objects are removed and clr is called is not specified, but the callee may take ownership of an object at the time that clr is called for that object and not before.

Upon return from this function, the list contains no objects, and it is as it was immediately after being initialized. No further operations on the list are necessary to make it ready to go out of scope or be destroyed.

Definition at line 216 of file slist.c.

cstl_slist_concat()

void cstl_slist_concat	(	struct cstl_slist *	list,
		struct cstl_slist *	more
	)

Append one list to the end of another.

Parameters

[in]	list	The list to which to append more objects
[in]	more	The list of objects to append

Upon return list will have all of the objects from more appended to its end.

Definition at line 125 of file slist.c.

cstl_slist_erase_after()

void * cstl_slist_erase_after	(	struct cstl_slist *	sl,
		void *	bef
	)

Remove an object from the list.

Parameters

[in]	sl	The list in which the object currently resides
[in]	bef	A pointer to the object in front of the object to be removed

Definition at line 65 of file slist.c.

cstl_slist_foreach()

int cstl_slist_foreach	(	struct cstl_slist *	sl,
		cstl_visit_func_t *	visit,
		void *	priv
	)

Call a user-supplied function for each object in a list.

Parameters

[in]	sl	The list containing the objects to visit
[in]	visit	A pointer to the function to call for each object
[in]	priv	A pointer to be passed to each invocation of the function

The user-supplied function must return 0 in order to continue visiting objects in the list. The visiting of objects will stop at the first occurrence of a non-zero return from the visit function.

Returns

The value returned from the user-supplied function from the last object visited or 0

Definition at line 201 of file slist.c.

cstl_slist_front()

void * cstl_slist_front

(

const struct cstl_slist *

sl

)

Get a pointer to the first object in the list.

Parameters

[in]

sl

A pointer to a list

Returns

A pointer to the first object in the list

Return values

NULL	The list is empty

Definition at line 86 of file slist.c.

cstl_slist_init()

static void cstl_slist_init ( struct cstl_slist *const  sl, const size_t  off  )

inlinestatic

Initialize a slist object.

Parameters

[in,out]	sl	A pointer to the object to be initialized
[in]	off	The offset of the cstl_slist_node object within the object(s) that will be stored in the list

Definition at line 102 of file slist.h.

cstl_slist_insert_after()

void cstl_slist_insert_after	(	struct cstl_slist *	sl,
		void *	before,
		void *	obj
	)

Insert a new object into the list.

Parameters

[in]	sl	A pointer to the list into which to insert the object
[in]	before	A pointer to an object already in the list
[in]	obj	A pointer to an object to insert into the list

The new object will be inserted after the object pointed to by before

Definition at line 58 of file slist.c.

cstl_slist_pop_front()

void * cstl_slist_pop_front

(

struct cstl_slist *

sl

)

Remove the first item in the list and return it.

Parameters

[in]

sl

A pointer to a list

Returns

A pointer to the removed object

Return values

NULL	The list was empty and no object was removed

Definition at line 81 of file slist.c.

cstl_slist_push_back()

void cstl_slist_push_back	(	struct cstl_slist *	sl,
		void *	obj
	)

Insert a new object at the back of the list.

Parameters

[in]	sl	A pointer to a list
[in]	obj	A pointer to the object to be inserted

Definition at line 76 of file slist.c.

cstl_slist_push_front()

void cstl_slist_push_front	(	struct cstl_slist *	sl,
		void *	obj
	)

Insert a new object at the front of the list.

Parameters

[in]	sl	A pointer to a list
[in]	obj	A pointer to the object to be inserted

Definition at line 71 of file slist.c.

cstl_slist_reverse()

void cstl_slist_reverse

(

struct cstl_slist *

sl

)

Reverse the order of items in the list.

Parameters

[in]

sl

A pointer to the list

Definition at line 102 of file slist.c.

cstl_slist_size()

static size_t cstl_slist_size ( const struct cstl_slist *  sl )

inlinestatic

Get the number of objects in the list.

Parameters

[in]

sl

A pointer to the list

Returns

The number of objects in the list

Definition at line 118 of file slist.h.

cstl_slist_sort()

void cstl_slist_sort	(	struct cstl_slist *	sl,
		cstl_compare_func_t *	cmp,
		void *	priv
	)

Sort the items in a list.

Parameters

[in]	sl	A pointer to the list
[in]	cmp	A pointer to a function to compare objects
[in]	priv	A pointer to be passed to each invocation of the comparison function

The items are sorted from least to greatest, according to the provided comparison function.

Definition at line 140 of file slist.c.

cstl_slist_swap()

void cstl_slist_swap	(	struct cstl_slist *const	a,
		struct cstl_slist *const	b
	)

Swap the list objects at the two given locations.

Parameters

[in,out]	a	A pointer to a list
[in,out]	b	A pointer to a(nother) list

The lists at the given locations will be swapped such that upon return, a will contain the list previously pointed to by b and vice versa.

Definition at line 231 of file slist.c.