Linked list library

The linked list library provides a set of functions for manipulating linked lists. More...

Macros
#define	OC_LIST(name)
	Declare a linked list. More...
#define	OC_LIST_CONCAT(s1, s2)   OC_LIST_CONCAT2(s1, s2)
#define	OC_LIST_CONCAT2(s1, s2)   s1##s2
#define	OC_LIST_LOCAL(name)
	Declare a linked list with a local scope. More...
#define	OC_LIST_STRUCT(name)
	Declare a linked list inside a structure declaraction. More...
#define	OC_LIST_STRUCT_INIT(struct_ptr, name)
	Initialize a linked list that is part of a structure. More...
#define	OC_LIST_STRUCT_REINIT(struct_ptr, name)

Typedefs
typedef void **	oc_list_t
	The linked list type. More...

Functions
void	oc_list_add (oc_list_t list, void *item)
	Add an item at the end of a list. More...
void *	oc_list_chop (oc_list_t list)
	Remove the last object on the list. More...
void	oc_list_copy (oc_list_t dest, oc_list_t src)
	Duplicate a list. More...
bool	oc_list_has_item (oc_list_t list, const void *item)
	Check if a list contains a specific item. More...
void *	oc_list_head (oc_list_t list)
	Get a pointer to the first element of a list. More...
void	oc_list_init (oc_list_t list)
	Initialize a list. More...
void	oc_list_insert (oc_list_t list, void *previtem, void *newitem)
	Insert an item after a specified item on the list. More...
void *	oc_list_item_next (void *item)
	Get the next item following this item. More...
int	oc_list_length (oc_list_t list)
	Get the length of a list. More...
void *	oc_list_pop (oc_list_t list)
	Remove the first object on a list. More...
void	oc_list_push (oc_list_t list, void *item)
	Add an item to the start of the list. More...
void	oc_list_remove (oc_list_t list, const void *item)
	Remove a specific element from a list. More...
void *	oc_list_remove2 (oc_list_t list, const void *item)
	Remove a specific element from a list and return a pointer to the removed item. More...
void *	oc_list_tail (oc_list_t list)
	Get the tail of a list. More...

Detailed Description

The linked list library provides a set of functions for manipulating linked lists.

A linked list is made up of elements where the first element must be a pointer. This pointer is used by the linked list library to form lists of the elements.

Lists are declared with the LIST() macro. The declaration specifies the name of the list that later is used with all list functions.

Lists can be manipulated by inserting or removing elements from either sides of the list (list_push(), list_add(), list_pop(), list_chop()). A specified element can also be removed from inside a list with list_remove(). The head and tail of a list can be extracted using list_head() and list_tail(), respectively.

Macro Definition Documentation

OC_LIST

#define OC_LIST

(

name

)

Value:

  static void *OC_LIST_CONCAT(name, _list) = NULL;                             \
  static oc_list_t name = &OC_LIST_CONCAT(name, _list)

Declare a linked list.

This macro declares a linked list with the specified type. The type must be a structure (struct) with its first element being a pointer. This pointer is used by the linked list library to form the linked lists.

The list variable is declared as static to make it easy to use in a single C module without unnecessarily exporting the name to other modules.

Parameters

name	The name of the list.

OC_LIST_LOCAL

#define OC_LIST_LOCAL

(

name

)

Value:

  void *OC_LIST_CONCAT(name, _list) = NULL;                                    \
  oc_list_t name = &OC_LIST_CONCAT(name, _list)

Declare a linked list with a local scope.

OC_LIST_STRUCT

#define OC_LIST_STRUCT

(

name

)

Value:

  void *OC_LIST_CONCAT(name, _list);                                           \
  oc_list_t name

Declare a linked list inside a structure declaraction.

This macro declares a linked list with the specified type. The type must be a structure (struct) with its first element being a pointer. This pointer is used by the linked list library to form the linked lists.

Internally, the list is defined as two items: the list itself and a pointer to the list. The pointer has the name of the parameter to the macro and the name of the list is a concatenation of the name and the suffix "_list". The pointer must point to the list for the list to work. Thus the list must be initialized before using.

The list is initialized with the LIST_STRUCT_INIT() macro.

Parameters

name	The name of the list.

OC_LIST_STRUCT_INIT

#define OC_LIST_STRUCT_INIT	(		struct_ptr,
			name
	)

Value:

  do {                                                                         \
    (struct_ptr)->name = &((struct_ptr)->OC_LIST_CONCAT(name, _list));         \
    (struct_ptr)->OC_LIST_CONCAT(name, _list) = NULL;                          \
    oc_list_init((struct_ptr)->name);                                          \
  } while (0)

Initialize a linked list that is part of a structure.

This macro sets up the internal pointers in a list that has been defined as part of a struct. This macro must be called before using the list.

Parameters

struct_ptr	A pointer to the struct
name	The name of the list.

OC_LIST_STRUCT_REINIT

#define OC_LIST_STRUCT_REINIT	(		struct_ptr,
			name
	)

Value:

  do {                                                                         \
    (struct_ptr)->name = &((struct_ptr)->OC_LIST_CONCAT(name, _list));         \
  } while (0)

Typedef Documentation

oc_list_t

typedef void** oc_list_t

The linked list type.

Function Documentation

oc_list_add()

void oc_list_add	(	oc_list_t	list,
		void *	item
	)

Add an item at the end of a list.

This function adds an item to the end of the list.

Parameters

list	The list.
item	A pointer to the item to be added.

See also

oc_list_push()

oc_list_insert()

oc_list_chop()

void* oc_list_chop

(

oc_list_t

list

)

Remove the last object on the list.

This function removes the last object on the list and returns it.

Parameters

list

The list

Returns

The removed object

oc_list_copy()

void oc_list_copy	(	oc_list_t	dest,
		oc_list_t	src
	)

Duplicate a list.

This function duplicates a list by copying the list reference, but not the elements.

Note

This function does not copy the elements of the list, but merely duplicates the pointer to the first element of the list.

Parameters

dest	The destination list.
src	The source list.

oc_list_has_item()

bool oc_list_has_item	(	oc_list_t	list,
		const void *	item
	)

Check if a list contains a specific item.

Parameters

list	The list.
item	The item to check for.

Returns

True if the list contains the item

False if the list does not contain the item

oc_list_head()

void* oc_list_head

(

oc_list_t

list

)

Get a pointer to the first element of a list.

This function returns a pointer to the first element of the list. The element will not be removed from the list.

Parameters

list

The list.

Returns

A pointer to the first element on the list.

See also

oc_list_tail()

oc_list_init()

void oc_list_init

(

oc_list_t

list

)

Initialize a list.

This function initalizes a list. The list will be empty after this function has been called.

Parameters

list	The list to be initialized.

See also

OC_LIST()

OC_LIST_LOCAL()

OC_LIST_STRUCT()

oc_list_insert()

void oc_list_insert	(	oc_list_t	list,
		void *	previtem,
		void *	newitem
	)

Insert an item after a specified item on the list.

Parameters

list	The list
previtem	The item after which the new item should be inserted
newitem	The new item that is to be inserted

Author

Adam Dunkels

        This function inserts an item right after a specified
        item on the list. This function is useful when using
        the list module to ordered lists.

        If previtem is NULL, the new item is placed at the
        start of the list.

See also

oc_list_add()

oc_list_push()

oc_list_item_next()

void* oc_list_item_next

(

void *

item

)

Get the next item following this item.

Parameters

item	A list item

Returns

A next item on the list

        This function takes a list item and returns the next
        item on the list, or NULL if there are no more items on
        the list. This function is used when iterating through
        lists.

oc_list_length()

int oc_list_length

(

oc_list_t

list

)

Get the length of a list.

This function counts the number of elements on a specified list.

Parameters

list

The list.

Returns

The length of the list.

oc_list_pop()

void* oc_list_pop

(

oc_list_t

list

)

Remove the first object on a list.

This function removes the first object on the list and returns a pointer to it.

Parameters

list

The list.

Returns

Pointer to the removed element of list.

oc_list_push()

void oc_list_push	(	oc_list_t	list,
		void *	item
	)

Add an item to the start of the list.

Parameters

list	The list.
item	A pointer to the item to be added.

See also

oc_list_add()

oc_list_insert()

oc_list_remove()

void oc_list_remove	(	oc_list_t	list,
		const void *	item
	)

Remove a specific element from a list.

This function removes a specified element from the list.

Parameters

list	The list.
item	The item that is to be removed from the list.

oc_list_remove2()

void* oc_list_remove2	(	oc_list_t	list,
		const void *	item
	)

Remove a specific element from a list and return a pointer to the removed item.

This function removes a specified element from the list.

Parameters

list	The list.
item	The item that is to be removed from the list.

Returns

Pointer to the removed element of list.

oc_list_tail()

void* oc_list_tail

(

oc_list_t

list

)

Get the tail of a list.

This function returns a pointer to the elements following the first element of a list. No elements are removed by this function.

Parameters

list

The list

Returns

A pointer to the element after the first element on the list.

See also

oc_list_head()