Golem  v0.1.1
Generic Operating system Libraries for Embedded Multitasking
 All Data Structures Files Functions Variables Pages
glm_list.h File Reference

Doubly-linked list datatype. More...

#include <stdbool.h>
#include "../glm_intbase.h"
#include "../glm_heap.h"

Go to the source code of this file.

Data Structures

struct  list_item_t
 Container for storing ADT-objects as doubly-linked-list-item. More...
 
struct  list_t
 The doubly-linked-list datatype. More...
 

Functions

list_tlist_create (heap_id_t a_heap_id)
 Create an empty list for the given heap_id. More...
 
void list_destroy (list_t *a_list)
 Destroy the list including its elements (and their objects!) More...
 
void list_clear (list_t *a_list)
 Destroy all items in the list. More...
 
uint_base_t list_length (list_t *a_list)
 Get the number of items on the list. More...
 
list_item_tlist_item_create (list_t *a_list, void *a_object)
 Create a list item with the given ADT-object. More...
 
list_item_tlist_item_delete (list_t *a_list, list_item_t *a_item)
 Delete the given list item and its object. More...
 
void * list_item_remove (list_t *a_list, list_item_t *a_item)
 Remove a list item from a list without destroying the object wrapped by the item. More...
 
bool list_append (list_t *a_list, list_item_t *a_item)
 Append item to the list. More...
 
bool list_prepend (list_t *a_list, list_item_t *a_item)
 Prepend item to the list. More...
 
list_item_tlist_first_item (list_t *a_list)
 Get first item on the list. More...
 
list_item_tlist_last_item (list_t *a_list)
 Get last item on the list. More...
 
bool list_insert_after_item (list_t *a_list, list_item_t *a_item, list_item_t *a_item_new)
 Insert a new item after one that's already on the list. More...
 
bool list_insert_before_item (list_t *a_list, list_item_t *a_item, list_item_t *a_item_new)
 Insert a new item before one that's already on the list. More...
 
list_item_tlist_item_get_previous (list_item_t *a_item)
 Get the item one higher on the list than the given item. More...
 
list_item_tlist_item_get_next (list_item_t *a_item)
 Get the item one lower on the list than the given item. More...
 
void * list_item_get_object (list_item_t *a_item)
 Get object wrapped by list item. More...
 

Detailed Description

Doubly-linked list datatype.

Part of Golem's collection of Advanced Data Types (ADTs).

Author
Ruud Beukema

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

Definition in file glm_list.h.

Function Documentation

bool list_append ( list_t a_list,
list_item_t a_item 
)

Append item to the list.

Parameters
a_listPointer to the list to which the item must be added.
a_itemPointer to the item to be appended.
Returns
TRUE if item is added or FALSE if not.
Examples:
example_glm_list.c.

Definition at line 183 of file glm_list.c.

void list_clear ( list_t a_list)

Destroy all items in the list.

Parameters
a_listA pointer to the list to be cleared.

Definition at line 52 of file glm_list.c.

list_t* list_create ( heap_id_t  a_heap_id)

Create an empty list for the given heap_id.

Parameters
a_heap_idThe caller's heap-ID.
Returns
NULL if creation failed, otherwise a pointer to the newly created list.

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

Examples:
example_glm_list.c.

Definition at line 18 of file glm_list.c.

void list_destroy ( list_t a_list)

Destroy the list including its elements (and their objects!)

Parameters
a_listA pointer to the list to be destroyed. The pointer is set to NULL after successful destruction. If NULL is passed, no action is taken.

Definition at line 38 of file glm_list.c.

list_item_t* list_first_item ( list_t a_list)

Get first item on the list.

Parameters
a_listPointer to the list in question.
Returns
Pointer to the first item on the list or NULL if the list is empty.

Definition at line 251 of file glm_list.c.

bool list_insert_after_item ( list_t a_list,
list_item_t a_item,
list_item_t a_item_new 
)

Insert a new item after one that's already on the list.

Parameters
a_listPointer to the list
a_itemPointer to the list item after which the new item must be inserted.
a_item_newPointer to the new item that is to be inserted.
Returns
TRUE if successful or FALSE if not.

Definition at line 280 of file glm_list.c.

bool list_insert_before_item ( list_t a_list,
list_item_t a_item,
list_item_t a_item_new 
)

Insert a new item before one that's already on the list.

Parameters
a_listPointer to the list.
a_itemPointer to the list item before which the new item must be inserted.
a_item_newPointer to the list item to be inserted.
Returns
TRUE if successful or FALSE if not.

Definition at line 307 of file glm_list.c.

list_item_t* list_item_create ( list_t a_list,
void *  a_object 
)

Create a list item with the given ADT-object.

Parameters
a_listPointer to the list for which the item must be created.
a_objectPointer to the object for which a list item needs to be created.
Returns
NULL if creation failed, otherwise a pointer to the created list item.
Examples:
example_glm_list.c.

Definition at line 80 of file glm_list.c.

list_item_t* list_item_delete ( list_t a_list,
list_item_t a_item 
)

Delete the given list item and its object.

Parameters
a_listPointer to the list from which the item must be deleted.
a_itemPointer to the item that must be deleted.
Returns
A pointer to the next item on the list is returned.

Definition at line 107 of file glm_list.c.

list_item_t* list_item_get_next ( list_item_t a_item)

Get the item one lower on the list than the given item.

Parameters
a_itemPointer to the item of which the next item is requested.
Returns
NULL if a_item was already the last of the list. Otherwise a pointer to the next item is returned.

Definition at line 350 of file glm_list.c.

void* list_item_get_object ( list_item_t a_item)

Get object wrapped by list item.

Parameters
a_itemPointer to the item of which the ADT-object is requested.
Returns
A pointer to the object wrapped by the list item or NULL if the item has no object.
list_item_t* list_item_get_previous ( list_item_t a_item)

Get the item one higher on the list than the given item.

Parameters
a_itemPointer to the item of which the previous item is requested.
Returns
NULL if a_item was already the first on the list. Otherwise a pointer to the previous item is returned.

Definition at line 336 of file glm_list.c.

void* list_item_remove ( list_t a_list,
list_item_t a_item 
)

Remove a list item from a list without destroying the object wrapped by the item.

Parameters
a_listPointer to the list from which the item must be removed.
a_itemPointer to the item that must be removed.
Returns
A pointer to the object previously contained by the list item.

Definition at line 163 of file glm_list.c.

list_item_t* list_last_item ( list_t a_list)

Get last item on the list.

Parameters
a_listPointer to the list in question.
Returns
Pointer to the last item on the list or NULL if the list is empty.

Definition at line 267 of file glm_list.c.

uint_base_t list_length ( list_t a_list)

Get the number of items on the list.

Parameters
a_listA pointer to the list.
Returns
The number of items on the list.

Definition at line 66 of file glm_list.c.

bool list_prepend ( list_t a_list,
list_item_t a_item 
)

Prepend item to the list.

Parameters
a_listPointer to the list to which the item must be added.
a_itemPointer to the item to be prepended.
Returns
TRUE if item is added or FALSE if not.

Definition at line 217 of file glm_list.c.