Contiki-NG

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

Files

file  dbl-list.c
 Implementation of doubly-linked lists.
 

Macros

#define DBL_LIST(name)
 Define a doubly-linked list. More...
 

Typedefs

typedef void ** dbl_list_t
 The doubly-linked list datatype.
 
typedef void *const * const_dbl_list_t
 The non-modifiable doubly-linked list type.
 

Functions

void dbl_list_init (dbl_list_t dll)
 Initialise a doubly-linked list. More...
 
void * dbl_list_head (const_dbl_list_t dll)
 Return the tail of a doubly-linked list. More...
 
void * dbl_list_tail (const_dbl_list_t dll)
 Return the tail of a doubly-linked list. More...
 
void dbl_list_remove (dbl_list_t dll, const void *element)
 Remove an element from a doubly-linked list. More...
 
void dbl_list_add_head (dbl_list_t dll, void *element)
 Add an element to the head of a doubly-linked list. More...
 
void dbl_list_add_tail (dbl_list_t dll, void *element)
 Add an element to the tail of a doubly-linked list. More...
 
void dbl_list_add_after (dbl_list_t dll, void *existing, void *element)
 Add an element to a doubly linked list after an existing element. More...
 
void dbl_list_add_before (dbl_list_t dll, void *existing, void *element)
 Add an element to a doubly linked list before an existing element. More...
 
unsigned long dbl_list_length (const_dbl_list_t dll)
 Get the length of a doubly-linked list. More...
 
bool dbl_list_is_empty (const_dbl_list_t dll)
 Determine whether a doubly-linked list is empty. More...
 

Detailed Description

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

A doubly-linked list is declared using the DBL_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_LIST

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

Define a doubly-linked list.

This macro defines a 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 doubly-linked list.

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

Function Documentation

◆ dbl_list_add_after()

void dbl_list_add_after ( dbl_list_t  dll,
void *  existing,
void *  element 
)

Add an element to a doubly linked list after an existing element.

Parameters
dllThe 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 161 of file dbl-list.c.

◆ dbl_list_add_before()

void dbl_list_add_before ( dbl_list_t  dll,
void *  existing,
void *  element 
)

Add an element to a doubly linked list before an existing element.

Parameters
dllThe 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 180 of file dbl-list.c.

◆ dbl_list_add_head()

void dbl_list_add_head ( dbl_list_t  dll,
void *  element 
)

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

Parameters
dllThe 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-list.c.

◆ dbl_list_add_tail()

void dbl_list_add_tail ( dbl_list_t  dll,
void *  element 
)

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

Parameters
dllThe 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 136 of file dbl-list.c.

◆ dbl_list_head()

void * dbl_list_head ( const_dbl_list_t  dll)

Return the tail of a doubly-linked list.

Parameters
dllThe 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-list.c.

◆ dbl_list_init()

void dbl_list_init ( dbl_list_t  dll)

Initialise a doubly-linked list.

Parameters
dllThe doubly-linked list.

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

◆ dbl_list_is_empty()

bool dbl_list_is_empty ( const_dbl_list_t  dll)

Determine whether a doubly-linked list is empty.

Parameters
dllThe doubly-linked list.
Return values
trueThe list is empty
falseThe list is not empty

Definition at line 221 of file dbl-list.c.

◆ dbl_list_length()

unsigned long dbl_list_length ( const_dbl_list_t  dll)

Get the length of a doubly-linked list.

Parameters
dllThe doubly-linked list.
Returns
The number of elements in the list

Definition at line 204 of file dbl-list.c.

◆ dbl_list_remove()

void dbl_list_remove ( dbl_list_t  dll,
const void *  element 
)

Remove an element from a doubly-linked list.

Parameters
dllThe 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-list.c.

◆ dbl_list_tail()

void * dbl_list_tail ( const_dbl_list_t  dll)

Return the tail of a doubly-linked list.

Parameters
dllThe 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-list.c.