SolarCapture C Bindings User Guide  SF-115721-CD
Issue 3
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
dlist.h File Reference

sc_dlist: A doubly-linked list. More...

Data Structures

struct  sc_dlist
 Doubly linked list pointers. More...
 

Macros

#define SC_CONTAINER(c_type, mbr_name, p_mbr)   ( (c_type*) ((char*)(p_mbr) - SC_MEMBER_OFFSET(c_type, mbr_name)) )
 Get pointer to container from pointer to member. More...
 
#define SC_DLIST_FOR_EACH_OBJ(list, iter, mbr)
 Create a for statement that loops over each container item in the list. It is not safe to modify the list using this macro, if list modifications are required see SC_DLIST_FOR_EACH_OBJ_SAFE. More...
 
#define SC_DLIST_FOR_EACH_OBJ_SAFE(list, iter, next_entry, mbr)
 Create a for statement that loops over each container item in the list which can be safely be modified during traversal. More...
 

Functions

static void sc_dlist_init (struct sc_dlist *list)
 Initialise a pre-allocated sc_dlist to be an empty doubly linked list. More...
 
static int sc_dlist_is_empty (const struct sc_dlist *list)
 Check if a doubly linked list is empty, returns 1 if true 0 otherwise.
 
static void sc_dlist_push_head (struct sc_dlist *list, struct sc_dlist *l)
 Prepend an item to the head of a doubly-linked list. More...
 
static void sc_dlist_push_tail (struct sc_dlist *list, struct sc_dlist *l)
 Append an item to the tail of a doubly-linked list. More...
 
static void sc_dlist_remove (struct sc_dlist *l)
 Remove an item from the list. More...
 
static struct sc_dlistsc_dlist_pop_head (struct sc_dlist *list)
 Pop off the head of a list. More...
 
static struct sc_dlistsc_dlist_pop_tail (struct sc_dlist *list)
 Pop the tail of a list. More...
 
static void sc_dlist_rehome (struct sc_dlist *to_list, struct sc_dlist *from_list)
 Replace an item in a list with another item. More...
 

Detailed Description

sc_dlist: A doubly-linked list.

A doubly-linked list always has one item with no data at the head. This can be used by embedding dlist in a parent struct.

For example:

#include <stdio.h>
#include <stdlib.h>
#include <solar_capture.h>

int main()
{
    struct my_struct {
      int my_int;
      double my_double;
      struct sc_dlist list_ptr;
    };

    struct sc_dlist my_list;
    sc_dlist_init(&my_list);
    int i;
    struct my_struct* element;
    // Add some elements to the list
    for( i=0; i < 10; ++i )
    {
      element = malloc(sizeof(struct my_struct));
      element->my_int = i;
      element->my_double = i;
      sc_dlist_push_tail(&my_list, &element->list_ptr);
    }
    // cycle over the list
    SC_DLIST_FOR_EACH_OBJ(&my_list, element, list_ptr)
      printf("element->my_int=%d, element->my_double=%f\n", element->my_int, element->my_double);

    // remove each item from the list
    struct sc_dlist* list_ptr;
    while( !sc_dlist_is_empty(&my_list) ) {
      list_ptr = sc_dlist_pop_tail(&my_list);
      element = SC_CONTAINER(struct my_struct, list_ptr, list_ptr);
      printf("Just popped element with element->my_int=%d", element->my_int);
      free(element);
    }

Macro Definition Documentation

#define SC_CONTAINER (   c_type,
  mbr_name,
  p_mbr 
)    ( (c_type*) ((char*)(p_mbr) - SC_MEMBER_OFFSET(c_type, mbr_name)) )

Get pointer to container from pointer to member.

Parameters
c_typeThe container type.
mbr_nameThe name of the member in c_type.
p_mbrPointer to the member.
#define SC_DLIST_FOR_EACH_OBJ (   list,
  iter,
  mbr 
)
Value:
for( (iter) = SC_CONTAINER(typeof(*(iter)), mbr, (list)->next); \
&(iter)->mbr != (list); \
(iter) = SC_CONTAINER(typeof(*(iter)), mbr, (iter)->mbr.next) )
#define SC_CONTAINER(c_type, mbr_name, p_mbr)
Get pointer to container from pointer to member.
Definition: dlist.h:117

Create a for statement that loops over each container item in the list. It is not safe to modify the list using this macro, if list modifications are required see SC_DLIST_FOR_EACH_OBJ_SAFE.

Parameters
listA pointer to the head of the sc_dlist.
iterA pointer of the same type as the container.
mbrThe name of the field in the container containing the sc_dlist struct.
#define SC_DLIST_FOR_EACH_OBJ_SAFE (   list,
  iter,
  next_entry,
  mbr 
)
Value:
for( (iter) = SC_CONTAINER(typeof(*(iter)), mbr, (list)->next), \
(next_entry) = SC_CONTAINER(typeof(*(iter)), mbr, (iter)->mbr.next); \
&(iter)->mbr != (list); \
(iter) = (next_entry), \
(next_entry) = SC_CONTAINER(typeof(*(iter)), mbr, (iter)->mbr.next) )
#define SC_CONTAINER(c_type, mbr_name, p_mbr)
Get pointer to container from pointer to member.
Definition: dlist.h:117

Create a for statement that loops over each container item in the list which can be safely be modified during traversal.

Parameters
listA pointer to the head of the sc_dlist.
iterA pointer of the same type as the container.
next_entryA pointer of the same type as the container.
mbrThe name of the field in the container containing the sc_dlist struct.

Function Documentation

static void sc_dlist_init ( struct sc_dlist list)
inlinestatic

Initialise a pre-allocated sc_dlist to be an empty doubly linked list.

Parameters
listA pointer to the pre-allocated sc_dlist to be initialised.
static struct sc_dlist* sc_dlist_pop_head ( struct sc_dlist list)
static

Pop off the head of a list.

Parameters
listThe point to pop the head from.
Returns
The item popped from list.
static struct sc_dlist* sc_dlist_pop_tail ( struct sc_dlist list)
static

Pop the tail of a list.

Parameters
listThe point to pop the tail from.
Returns
The item popped from list.
static void sc_dlist_push_head ( struct sc_dlist list,
struct sc_dlist l 
)
inlinestatic

Prepend an item to the head of a doubly-linked list.

Parameters
listThe list to prepend to.
lThe item to prepend to list.
static void sc_dlist_push_tail ( struct sc_dlist list,
struct sc_dlist l 
)
inlinestatic

Append an item to the tail of a doubly-linked list.

Parameters
listThe list to append to.
lThe item to append to list.
static void sc_dlist_rehome ( struct sc_dlist to_list,
struct sc_dlist from_list 
)
inlinestatic

Replace an item in a list with another item.

Parameters
to_listThe item to add to the list, replacing from_list.
from_listThe item to remove from the list.
static void sc_dlist_remove ( struct sc_dlist l)
inlinestatic

Remove an item from the list.

Parameters
lThe item to remove.