Contiki-NG
Loading...
Searching...
No Matches
Circular, doubly-linked list

Files

file  dbl-circ-list.c
 Implementation of circular, doubly-linked lists.
 

Macros

#define DBL_CIRC_LIST(name)
 Define a circular, doubly-linked list.
 

Typedefs

typedef void ** dbl_circ_list_t
 The doubly-linked circular list datatype.
 
typedef void *const * const_dbl_circ_list_t
 The non-modifiable doubly-linked circular list type.
 

Functions

void dbl_circ_list_init (dbl_circ_list_t dblcl)
 Initialise a circular, doubly-linked list.
 
void * dbl_circ_list_head (const_dbl_circ_list_t dblcl)
 Return the tail of a circular, doubly-linked list.
 
void * dbl_circ_list_tail (const_dbl_circ_list_t dblcl)
 Return the tail of a circular, doubly-linked list.
 
void dbl_circ_list_remove (dbl_circ_list_t dblcl, const void *element)
 Remove an element from a circular, doubly-linked list.
 
void dbl_circ_list_add_head (dbl_circ_list_t dblcl, void *element)
 Add an element to the head of a circular, doubly-linked list.
 
void dbl_circ_list_add_tail (dbl_circ_list_t dblcl, void *element)
 Add an element to the tail of a circular, doubly-linked list.
 
void dbl_circ_list_add_after (dbl_circ_list_t dblcl, void *existing, void *element)
 Add element to a circular, doubly-linked list after existing element.
 
void dbl_circ_list_add_before (dbl_circ_list_t dblcl, void *existing, void *element)
 Add element to a circular, doubly-linked list before existing element.
 
unsigned long dbl_circ_list_length (const_dbl_circ_list_t dblcl)
 Get the length of a circular, doubly-linked list.
 
bool dbl_circ_list_is_empty (const_dbl_circ_list_t dblcl)
 Determine whether a circular, doubly-linked list is empty.
 

Detailed Description

This library provides functions for the creation and manipulation of circular, doubly-linked lists.

A circular, doubly-linked list is declared using the DBL_CIRC_LIST macro. Elements must be allocated by the calling code and must be of a C struct datatype. In this struct, the first field must be a pointer called next. The second field must be a pointer called previous. These fields will be used by the library to maintain the list. Application code must not modify these fields directly.

Functions that modify the list (add / remove) will, in the general case, update the list's head and item order. If you call one of these functions as part of a list traversal, it is advised to stop / restart traversing after the respective function returns.

This library is not safe to be used within an interrupt context.

Macro Definition Documentation

◆ DBL_CIRC_LIST

#define DBL_CIRC_LIST ( name)
Value:
static void *name##_dbl_circ_list = NULL; \
static dbl_list_t name = (dbl_circ_list_t)&name##_dbl_circ_list
void ** dbl_circ_list_t
The doubly-linked circular list datatype.
void ** dbl_list_t
The doubly-linked list datatype.
Definition dbl-list.h:86

Define a circular, doubly-linked list.

This macro defines a circular, doubly-linked list.

The datatype for elements must be a C struct. The struct's first member must be a pointer called next. The second field must be a pointer called previous. These fields will be used by the library to maintain the list. Application code must not modify these fields directly.

Parameters
nameThe name of the circular, doubly-linked list.

Definition at line 79 of file dbl-circ-list.h.

Function Documentation

◆ dbl_circ_list_add_after()

void dbl_circ_list_add_after ( dbl_circ_list_t dblcl,
void * existing,
void * element )

Add element to a circular, doubly-linked list after existing element.

Parameters
dblclThe circular, doubly-linked list.
existingA pointer to the existing element.
elementA pointer to the element to be added.

This function will add element after existing

The function will not verify that existing is already part of the list.

Calling this function will update the list's head and item order. If you call this function as part of a list traversal, it is advised to stop traversing after this function returns.

Definition at line 168 of file dbl-circ-list.c.

References dbl_circ_list_remove().

◆ dbl_circ_list_add_before()

void dbl_circ_list_add_before ( dbl_circ_list_t dblcl,
void * existing,
void * element )

Add element to a circular, doubly-linked list before existing element.

Parameters
dblclThe circular, doubly-linked list.
existingA pointer to the existing element.
elementA pointer to the element to be added.

This function will add element before existing

The function will not verify that existing is already part of the list.

Calling this function will update the list's head and item order. If you call this function as part of a list traversal, it is advised to stop traversing after this function returns.

Definition at line 184 of file dbl-circ-list.c.

References dbl_circ_list_remove().

◆ dbl_circ_list_add_head()

void dbl_circ_list_add_head ( dbl_circ_list_t dblcl,
void * element )

Add an element to the head of a circular, doubly-linked list.

Parameters
dblclThe circular, doubly-linked list.
elementA pointer to the element to be added.

Calling this function will update the list's head and item order. If you call this function as part of a list traversal, it is advised to stop traversing after this function returns.

Definition at line 111 of file dbl-circ-list.c.

References dbl_circ_list_head(), and dbl_circ_list_remove().

◆ dbl_circ_list_add_tail()

void dbl_circ_list_add_tail ( dbl_circ_list_t dblcl,
void * element )

Add an element to the tail of a circular, doubly-linked list.

Parameters
dblclThe circular, doubly-linked list.
elementA pointer to the element to be added.

Calling this function will update the list's head and item order. If you call this function as part of a list traversal, it is advised to stop traversing after this function returns.

Definition at line 140 of file dbl-circ-list.c.

References dbl_circ_list_remove(), and dbl_circ_list_tail().

◆ dbl_circ_list_head()

void * dbl_circ_list_head ( const_dbl_circ_list_t dblcl)

Return the tail of a circular, doubly-linked list.

Parameters
dblclThe circular, doubly-linked list.
Returns
A pointer to the list's head, or NULL if the list is empty

Definition at line 60 of file dbl-circ-list.c.

Referenced by dbl_circ_list_add_head().

◆ dbl_circ_list_init()

void dbl_circ_list_init ( dbl_circ_list_t dblcl)

Initialise a circular, doubly-linked list.

Parameters
dblclThe circular, doubly-linked list.

Definition at line 54 of file dbl-circ-list.c.

◆ dbl_circ_list_is_empty()

bool dbl_circ_list_is_empty ( const_dbl_circ_list_t dblcl)

Determine whether a circular, doubly-linked list is empty.

Parameters
dblclThe circular, doubly-linked list.
Return values
trueThe list is empty
falseThe list is not empty

Definition at line 222 of file dbl-circ-list.c.

◆ dbl_circ_list_length()

unsigned long dbl_circ_list_length ( const_dbl_circ_list_t dblcl)

Get the length of a circular, doubly-linked list.

Parameters
dblclThe circular, doubly-linked list.
Returns
The number of elements in the list

Definition at line 205 of file dbl-circ-list.c.

◆ dbl_circ_list_remove()

void dbl_circ_list_remove ( dbl_circ_list_t dblcl,
const void * element )

Remove an element from a circular, doubly-linked list.

Parameters
dblclThe circular, doubly-linked list.
elementA pointer to the element to be removed.

Calling this function will update the list's head and item order. If you call this function as part of a list traversal, it is advised to stop traversing after this function returns.

Definition at line 80 of file dbl-circ-list.c.

Referenced by dbl_circ_list_add_after(), dbl_circ_list_add_before(), dbl_circ_list_add_head(), and dbl_circ_list_add_tail().

◆ dbl_circ_list_tail()

void * dbl_circ_list_tail ( const_dbl_circ_list_t dblcl)

Return the tail of a circular, doubly-linked list.

Parameters
dblclThe circular, doubly-linked list.
Returns
A pointer to the list's tail, or NULL if the list is empty

Definition at line 66 of file dbl-circ-list.c.

Referenced by dbl_circ_list_add_tail().