Contiki-NG
Circular, singly-linked list

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

Files

file  circular-list.c
 Implementation of circular singly linked lists.
 

Macros

#define CIRCULAR_LIST(name)
 Define a circular, singly-linked list. More...
 

Typedefs

typedef void ** circular_list_t
 The circular, singly-linked list datatype.
 
typedef void *const * const_circular_list_t
 The non-modifiable circular, singly-linked list datatype.
 

Functions

void circular_list_init (circular_list_t cl)
 Initialise a circular, singly-linked list. More...
 
void * circular_list_head (const_circular_list_t cl)
 Return the tail of a circular, singly-linked list. More...
 
void * circular_list_tail (const_circular_list_t cl)
 Return the tail of a circular, singly-linked list. More...
 
void circular_list_remove (circular_list_t cl, const void *element)
 Remove an element from a circular, singly-linked list. More...
 
void circular_list_add (circular_list_t cl, void *element)
 Add an element to a circular, singly-linked list. More...
 
unsigned long circular_list_length (const_circular_list_t cl)
 Get the length of a circular, singly-linked list. More...
 
bool circular_list_is_empty (const_circular_list_t cl)
 Determine whether a circular, singly-linked list is empty. More...
 

Detailed Description

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

A circular, singly-linked list is declared using the CIRCULAR_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. This field will be used by the library to maintain the list. Application code must not modify this field 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

◆ CIRCULAR_LIST

#define CIRCULAR_LIST (   name)
Value:
static void *name##_circular_list = NULL; \
static circular_list_t name = (circular_list_t)&name##_circular_list
void ** circular_list_t
The circular, singly-linked list datatype.
Definition: circular-list.h:84

Define a circular, singly-linked list.

This macro defines a circular, singly-linked list.

The datatype for elements must be a C struct. The struct's first member must be a pointer called next. This is used internally by the library to maintain data structure integrity and must not be modified directly by application code.

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

Definition at line 77 of file circular-list.h.

Function Documentation

◆ circular_list_add()

void circular_list_add ( circular_list_t  cl,
void *  element 
)

Add an element to a circular, singly-linked list.

Parameters
clThe circular, singly-linked list.
elementA pointer to the element to be added.

The caller should make no assumptions as to the position in the list of the new element.

After this function returns, the list's head is not guaranteed to be the same as it was before the addition.

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 107 of file circular-list.c.

◆ circular_list_head()

void * circular_list_head ( const_circular_list_t  cl)

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

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

Definition at line 59 of file circular-list.c.

◆ circular_list_init()

void circular_list_init ( circular_list_t  cl)

Initialise a circular, singly-linked list.

Parameters
clThe circular, singly-linked list.

Definition at line 53 of file circular-list.c.

◆ circular_list_is_empty()

bool circular_list_is_empty ( const_circular_list_t  cl)

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

Parameters
clThe circular, singly-linked list.
Return values
trueThe list is empty
falseThe list is not empty

Definition at line 152 of file circular-list.c.

Referenced by circular_list_length().

◆ circular_list_length()

unsigned long circular_list_length ( const_circular_list_t  cl)

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

Parameters
clThe circular, singly-linked list.
Returns
The number of elements in the list

Definition at line 135 of file circular-list.c.

References circular_list_is_empty().

◆ circular_list_remove()

void circular_list_remove ( circular_list_t  cl,
const void *  element 
)

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

Parameters
clThe circular, singly-linked list.
elementA pointer to the element to be removed.

After this function returns, the list's head is not guaranteed to be the same as it was before the addition.

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 79 of file circular-list.c.

◆ circular_list_tail()

void * circular_list_tail ( const_circular_list_t  cl)

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

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

Definition at line 65 of file circular-list.c.