27a8e93aec83ac82f33ea25165e3f4da4366a7df
[asterisk/asterisk.git] / doc / linkedlists.README
1
2 2nd version, implemented as macros.
3
4         include <asterisk/linkedlists.h>
5
6 AST_LIST_ENTRY declares pointers inside the object structure : 
7
8         struct ast_var_t {
9                 char *name;
10                 char *value;
11                 AST_LIST_ENTRY(ast_var_t) listpointers;
12         };
13
14 AST_LIST_HEAD declares a head structure, which is initialized
15 to AST_LIST_HEAD_NULL : 
16
17         AST_LIST_HEAD(head, ast_var_t) head 
18
19 Next, we declare a pointer to this structure : 
20
21         struct headtype *headp = head;
22
23 AST_LIST_INIT initializes the head pointer to a null value
24
25         AST_LIST_INIT(headp);
26
27 AST_LIST_INSERT_HEAD inserts an element to the head of the list : 
28
29         struct ast_var_t *node; 
30
31         node=malloc(sizeof(struct ast_var_t));
32         (...we fill data in struct....)
33         data->name=malloc(100);
34         strcpy(data->name,"lalalalaa");
35         etc etc
36
37         (then we insert the node in the head of the list :)
38
39         AST_LIST_INSERT_HEAD(headp,node,listpointers);
40
41 AST_LIST_INSERT_HEAD_AFTER inserts an element after another : 
42
43         struct ast_var_t *node1;
44         ...
45         AST_LIST_INSERT_AFTER(node,node1,listpointers);
46
47 AST_LIST_REMOVE removes an arbitrary element from the head:
48
49         AST_LIST_REMOVE(headp,node1,ast_var_t,listpointers);
50
51 AST_LIST_REMOVE_HEAD removes the entry at the head of the list and
52 returns a pointer to the removed entry: 
53
54         AST_LIST_REMOVE_HEAD(headp,node,listpointers);
55
56 AST_LIST_FIRST returns a pointer to the first element of the list;
57
58         struct ast_var_t *firstnode;
59         firstnode=AST_LIST_FIRST(headp);
60
61 AST_LIST_NEXT returns a pointer to the next element : 
62
63         struct ast_var_t *nextnode;
64         nextnode=AST_LIST_NEXT(firstnode,listpointers);
65
66 AST_LIST_TRAVERSE traverses all elements of the list : 
67
68         struct ast_var_t *node;
69
70         AST_LIST_TRAVERSE(headp,node,listpointers) {
71                 printf("%s\n",node->name);
72         }
73
74 AST_LIST_EMPTY evaluates to a true condition if there are no elements on 
75 the list. 
76
77 To completely delete a list : 
78
79         struct ast_var_t *vardata;
80
81         while (!AST_LIST_EMPTY(headp)) {           /* List Deletion. */
82                     vardata = AST_LIST_REMOVE_HEAD(head, ast_var_t, listpointers);
83                     free(vardata->name);
84                     free(vardata->value);
85         }
86
87 AST_LIST_LOCK returns true if it can lock the list, AST_LIST_UNLOCK unlocks
88 the list : 
89
90 if (AST_LIST_LOCK(headp)) {
91         ...do all list operations here...
92         AST_LIST_UNLOCK(headp);
93 } else {
94         ast_log(LOG_WARNING,"List locked bla bla bla\n");
95 }