LiLi
[Lists and Queues]

Linked List. More...

Collaboration diagram for LiLi:

Data Structures

struct  LILI_NODE
 Node object structure. More...
struct  LILI
 List object structure. More...

Defines

#define LiLiIsLifo(list)   (((list)->lst_flags & LILI_F_ORDER) == LILI_F_LIFO)
 Return true if the given list is a last in, first out queue.
#define LiLiIsFifo(list)   (((list)->lst_flags & LILI_F_ORDER) == LILI_F_FIFO)
 Return true if the given list is a first in, first out queue.
#define LiLiIsSorted(list)   (((list)->lst_flags & LILI_F_ORDER) == LILI_F_SORT)
 Return true if the given list is sorted.
#define LiLiIsEmpty(list)   ((list)->lst_head == NULL)
 Return true if the given list is empty.
#define LiLiHasUniqueItems(list)   (((list)->lst_flags & LILI_F_UNIQUE) == LILI_F_UNIQUE)
 Return true if the given list has unique items only.
#define LiLiFirstNode(list)   ((list)->lst_head)
 Return the first node object of a given list.
#define LiLiLastNode(list)   ((list)->lst_tail)
 Return the last node object of a given list.
#define LiLiNextNode(node)   ((node)->nod_nxt)
 Return the next node object of a given node.
#define LiLiPreviousNode(node)   ((node)->nod_prv)
 Return the previous node object of a given node.
#define LiLiNodeItem(node)   ((node)->nod_itm)
 Return the item reference of a given node.

Typedefs

typedef intptr_t LILI_ITEMREF
 Type of an item reference.
typedef LILI_ITEMREF(* LiLiItemCreateFunc )(LILI_ITEMREF)
typedef void(* LiLiItemDestroyFunc )(LILI_ITEMREF)
typedef int(* LiLiItemCompareFunc )(LILI_ITEMREF, LILI_ITEMREF)

Functions

void LiLiRemoveNode (LILI *list, LILI_NODE *node)
 Remove a given node from the list.
LILI_NODE * LiLiInsertItemAfterNode (LILI *list, LILI_NODE *node, LILI_ITEMREF ref)
LILI_NODE * LiLiInsertItemBeforeNode (LILI *list, LILI_NODE *node, LILI_ITEMREF ref)
LILI * LiLiCreate (uint8_t flags, LiLiItemCreateFunc icre, LiLiItemDestroyFunc ides, LiLiItemCompareFunc icmp)
 Create a linked list.
void LiLiClean (LILI *list)
 Remove all items from a list.
void LiLiDestroy (LILI *list)
 Destroy a linked list.
LILI_NODE * LiLiLocateItem (LILI *list, LILI_ITEMREF ref)
 Find the node's location by a given item.
LILI_NODE * LiLiFindItem (LILI *list, LILI_ITEMREF ref)
 Find the node of a given item.
int LiLiPushItem (LILI *list, LILI_ITEMREF ref)
 Add an item to the list.
int LiLiPopItem (LILI *list, LILI_ITEMREF *refp)
 Remove the next item from the list.
int LiLiCompareStringItems (LILI_ITEMREF ref1, LILI_ITEMREF ref2)
 Compare two string items.
LILI_ITEMREF LiLiCreateStringItemCopy (LILI_ITEMREF ref)
 Create a copy of a referenced string item.
void LiLiDestroyStringItemCopy (LILI_ITEMREF ref)
 Destroy the string item copy.
int LiLiNodes (LILI *list)
 Return the number of nodes in a given list.

List attribute flags



#define LILI_F_LIFO   0x00
 Last in, first out queue.
#define LILI_F_FIFO   0x01
 First in, first out queue.
#define LILI_F_SORT   0x02
 Sorted list.
#define LILI_F_ORDER   0x03
 List order mask.
#define LILI_F_UNIQUE   0x80
 Allow unique items only.

Detailed Description

Linked List.


Define Documentation

#define LILI_F_LIFO   0x00

Last in, first out queue.

Definition at line 58 of file lili.h.

#define LILI_F_FIFO   0x01

First in, first out queue.

Definition at line 60 of file lili.h.

#define LILI_F_SORT   0x02

Sorted list.

Definition at line 62 of file lili.h.

#define LILI_F_ORDER   0x03

List order mask.

Definition at line 64 of file lili.h.

#define LILI_F_UNIQUE   0x80

Allow unique items only.

Definition at line 66 of file lili.h.

#define LiLiIsLifo ( list   )     (((list)->lst_flags & LILI_F_ORDER) == LILI_F_LIFO)

Return true if the given list is a last in, first out queue.

Definition at line 102 of file lili.h.

#define LiLiIsFifo ( list   )     (((list)->lst_flags & LILI_F_ORDER) == LILI_F_FIFO)

Return true if the given list is a first in, first out queue.

Definition at line 107 of file lili.h.

Referenced by LiLiPopItem().

#define LiLiIsSorted ( list   )     (((list)->lst_flags & LILI_F_ORDER) == LILI_F_SORT)

Return true if the given list is sorted.

Definition at line 112 of file lili.h.

Referenced by LiLiFindItem(), and LiLiPushItem().

#define LiLiIsEmpty ( list   )     ((list)->lst_head == NULL)

Return true if the given list is empty.

Definition at line 117 of file lili.h.

#define LiLiHasUniqueItems ( list   )     (((list)->lst_flags & LILI_F_UNIQUE) == LILI_F_UNIQUE)

Return true if the given list has unique items only.

Definition at line 122 of file lili.h.

Referenced by LiLiPushItem().

#define LiLiFirstNode ( list   )     ((list)->lst_head)

Return the first node object of a given list.

Definition at line 127 of file lili.h.

Referenced by LiLiFindItem(), LiLiLocateItem(), LiLiNodes(), LiLiPopItem(), and LiLiPushItem().

#define LiLiLastNode ( list   )     ((list)->lst_tail)

Return the last node object of a given list.

Definition at line 132 of file lili.h.

Referenced by LiLiPopItem(), and LiLiPushItem().

#define LiLiNextNode ( node   )     ((node)->nod_nxt)

Return the next node object of a given node.

Definition at line 137 of file lili.h.

Referenced by LiLiFindItem(), LiLiLocateItem(), and LiLiNodes().

#define LiLiPreviousNode ( node   )     ((node)->nod_prv)

Return the previous node object of a given node.

Definition at line 142 of file lili.h.

#define LiLiNodeItem ( node   )     ((node)->nod_itm)

Return the item reference of a given node.

Definition at line 147 of file lili.h.

Referenced by LiLiClean(), LiLiFindItem(), LiLiLocateItem(), LiLiPopItem(), and LiLiPushItem().


Typedef Documentation

Type of an item reference.

Definition at line 70 of file lili.h.

Definition at line 72 of file lili.h.

Definition at line 73 of file lili.h.

Definition at line 74 of file lili.h.


Function Documentation

void LiLiRemoveNode ( LILI *  list,
LILI_NODE *  node 
)

Remove a given node from the list.

Special applications may use this function instead of LiLiPopItem().

The caller must make sure, that this node is a member of the specified list. After returning from this function, this pointer is no longer usable.

Note, that this call will not destroy the copy of an associated item object.

Parameters:
list Pointer to a list object, obtained from a previous call to LiLiCreate().
node Pointer to the node object to remove. Ignored if NULL.

Definition at line 107 of file lili.c.

References free, and NUTASSERT.

Referenced by LiLiPopItem().

LILI_NODE* LiLiInsertItemAfterNode ( LILI *  list,
LILI_NODE *  node,
LILI_ITEMREF  ref 
)

Definition at line 147 of file lili.c.

References malloc, and NUTASSERT.

Referenced by LiLiPushItem().

LILI_NODE* LiLiInsertItemBeforeNode ( LILI *  list,
LILI_NODE *  node,
LILI_ITEMREF  ref 
)

Definition at line 194 of file lili.c.

References malloc, and NUTASSERT.

Referenced by LiLiPushItem().

LILI* LiLiCreate ( uint8_t  flags,
LiLiItemCreateFunc  icre,
LiLiItemDestroyFunc  ides,
LiLiItemCompareFunc  icmp 
)

Create a linked list.

Parameters:
flags Attribute flags, either LILI_F_LIFO for a last-in first-out queue, LILI_F_FIFO for a first-in first-out queue, or LILI_F_SORT for a sorted list. Any of them may be or'ed with the attribute flag LILI_F_UNIQUE to avoid duplicate entries.
icre Pointer to a function, which is called to create an item for adding to the list. If NULL, the item reference itself is used in the list. See LiLiCreateStringItemCopy().
ides Pointer to a function, which is called to destroy an item. Set to NULL, if the item reference is used in the list. See LiLiDestroyStringItemCopy().
icmp Pointer to a function, which is called to compare items. If NULL, the item reference values are directly compared. See LiLiCompareStringItems().
Returns:
Pointer to a list object on success, otherwise a NULL pointer is returned.

Definition at line 247 of file lili.c.

References calloc.

void LiLiClean ( LILI *  list  ) 

Remove all items from a list.

This function will not release the list object. Use LiLiDestroy() to release the complete list.

Parameters:
list Pointer to a list object, obtained from a previous call to LiLiCreate().

Definition at line 273 of file lili.c.

References free, LiLiNodeItem, and NUTASSERT.

Referenced by LiLiDestroy().

void LiLiDestroy ( LILI *  list  ) 

Destroy a linked list.

This function will remove all nodes, destroy item object copies and finally destroy the list object.

Parameters:
list Pointer to a list object to destroy, obtained from a previous call to LiLiCreate(),

Definition at line 301 of file lili.c.

References free, and LiLiClean().

LILI_NODE* LiLiLocateItem ( LILI *  list,
LILI_ITEMREF  ref 
)

Find the node's location by a given item.

Like LiLiFindItem(), but returns the first node of which the item is larger than the given item. This function is useful for sorted lists only.

Parameters:
list Pointer to a list object, obtained from a previous call to LiLiCreate().
ref Reference of the item to search for.
Returns:
Pointer to the node, or NULL if no node was found.

Definition at line 66 of file lpushpop.c.

References LiLiFirstNode, LiLiNextNode, LiLiNodeItem, and NUTASSERT.

Referenced by LiLiPushItem().

LILI_NODE* LiLiFindItem ( LILI *  list,
LILI_ITEMREF  ref 
)

Find the node of a given item.

Like LiLiLocateItem(), but searches for an exact match. If the list is unsorted, all nodes will be scanned.

Parameters:
list Pointer to a list object, obtained from a previous call to LiLiCreate().
ref Reference of the item to search for.
Returns:
Pointer to the node, or NULL if no node was found.

Definition at line 93 of file lpushpop.c.

References LiLiFirstNode, LiLiIsSorted, LiLiNextNode, LiLiNodeItem, and NUTASSERT.

Referenced by LiLiPushItem().

int LiLiPushItem ( LILI *  list,
LILI_ITEMREF  ref 
)

Add an item to the list.

In most cases this function will be used by applications to add new items to a list.

If the attribute LILI_F_SORT has been set when creating the list, then a node will be inserted before the first node, of which the item is larger or equal than the given one.

If the attribute LILI_F_UNIQUE has been set and if a node with the same item is already a member of the list, then no new node will be added. This adds significant overhead to LIFO and FIFO queues.

Parameters:
list Pointer to a list object, obtained from a previous call to LiLiCreate().
ref The item's reference. If a function for creating an item has been specified, if will be called before inserting a new node.
Returns:
0 if a new node had been successfully added or of the given item already exists in a unique list. On errors, -1 is returned.

Definition at line 137 of file lpushpop.c.

References LiLiFindItem(), LiLiFirstNode, LiLiHasUniqueItems, LiLiInsertItemAfterNode(), LiLiInsertItemBeforeNode(), LiLiIsSorted, LiLiLastNode, LiLiLocateItem(), LiLiNodeItem, and NUTASSERT.

int LiLiPopItem ( LILI *  list,
LILI_ITEMREF refp 
)

Remove the next item from the list.

Parameters:
list Pointer to a list object, obtained from a previous call to LiLiCreate().
refp Pointer that receives the item's reference of the removed node. If a copy of the item object has been created during list insertion, then the caller is responsible for destroying it.
Returns:
-1 if the list is empty, otherwise 0 is returned.

Definition at line 191 of file lpushpop.c.

References LiLiFirstNode, LiLiIsFifo, LiLiLastNode, LiLiNodeItem, LiLiRemoveNode(), and NUTASSERT.

int LiLiCompareStringItems ( LILI_ITEMREF  ref1,
LILI_ITEMREF  ref2 
)

Compare two string items.

A pointer to this function can be passed to LiLiCreate(), if the items of a sorted list are simple strings.

Parameters:
ref1 Reference of the first string.
ref2 Reference of the second string.
Returns:
An integer less than, equal to, or greater than zero, if the first string is less than, equal, or greater than the second string, resp.

Definition at line 65 of file lstrcmp.c.

References strcmp().

LILI_ITEMREF LiLiCreateStringItemCopy ( LILI_ITEMREF  ref  ) 

Create a copy of a referenced string item.

A pointer to this function can be passed to LiLiCreate(), if the list items are simple strings.

Note, that the result is not checked during list insertion. If not enough memory is available to create a copy, then a reference value of zero is stored in the node object.

Parameters:
ref Reference of the original string. Actually this is a pointer to the string. If 0, no copy is created.
Returns:
Reference of a successfully created copy, otherwise 0.

Definition at line 70 of file lstrcopy.c.

References strdup().

void LiLiDestroyStringItemCopy ( LILI_ITEMREF  ref  ) 

Destroy the string item copy.

A pointer to this function can be passed to LiLiCreate(), if the list items are simple strings.

Parameters:
ref Reference of the string copy to destroy. Ignored if 0.

Definition at line 86 of file lstrcopy.c.

References free.

int LiLiNodes ( LILI *  list  ) 

Return the number of nodes in a given list.

Use LiLiIsEmpty(), if you need a simple check for an empty list.

Parameters:
list Pointer to a list object, obtained from a previous call to LiLiCreate().
Returns:
The number of nodes.

Definition at line 63 of file lutil.c.

References LiLiFirstNode, LiLiNextNode, and NUTASSERT.


© 2000-2010 by contributors - visit http://www.ethernut.de/