summaryrefslogtreecommitdiff
path: root/legacy/eina
diff options
context:
space:
mode:
authorRafael Antognolli <antognolli@gmail.com>2011-06-14 17:43:53 +0000
committerRafael Antognolli <antognolli@gmail.com>2011-06-14 17:43:53 +0000
commit5ab79258a229148a52f08c0503470978e1b493e5 (patch)
treece075996e27f90bc531f43eaecb20a3132fee64b /legacy/eina
parentcb94f911a42e8198a7ca88cec3fca36216a676aa (diff)
eina: Add detailed description and some examples to Eina_Inlist.
SVN revision: 60310
Diffstat (limited to 'legacy/eina')
-rw-r--r--legacy/eina/doc/img/eina_inlist-node.pngbin0 -> 8895 bytes
-rw-r--r--legacy/eina/doc/img/eina_inlist-node_eg1-inlist.pngbin0 -> 13020 bytes
-rw-r--r--legacy/eina/doc/img/eina_inlist-node_eg1-my-struct.pngbin0 -> 7682 bytes
-rw-r--r--legacy/eina/doc/img/eina_inlist-node_eg2-list-inlist.pngbin0 -> 22126 bytes
-rw-r--r--legacy/eina/doc/img/eina_inlist-node_eg2-my-struct.pngbin0 -> 7755 bytes
-rw-r--r--legacy/eina/doc/img/eina_inlist-node_eg3-my-struct.pngbin0 -> 10177 bytes
-rw-r--r--legacy/eina/doc/img/eina_inlist-node_eg3-two-inlists.pngbin0 -> 25975 bytes
-rw-r--r--legacy/eina/src/examples/Makefile.am10
-rw-r--r--legacy/eina/src/examples/eina_inlist_01.c96
-rw-r--r--legacy/eina/src/examples/eina_inlist_02.c64
-rw-r--r--legacy/eina/src/examples/eina_inlist_03.c73
-rw-r--r--legacy/eina/src/include/eina_inlist.h377
12 files changed, 559 insertions, 61 deletions
diff --git a/legacy/eina/doc/img/eina_inlist-node.png b/legacy/eina/doc/img/eina_inlist-node.png
new file mode 100644
index 0000000000..195497bf00
--- /dev/null
+++ b/legacy/eina/doc/img/eina_inlist-node.png
Binary files differ
diff --git a/legacy/eina/doc/img/eina_inlist-node_eg1-inlist.png b/legacy/eina/doc/img/eina_inlist-node_eg1-inlist.png
new file mode 100644
index 0000000000..48c0a4799c
--- /dev/null
+++ b/legacy/eina/doc/img/eina_inlist-node_eg1-inlist.png
Binary files differ
diff --git a/legacy/eina/doc/img/eina_inlist-node_eg1-my-struct.png b/legacy/eina/doc/img/eina_inlist-node_eg1-my-struct.png
new file mode 100644
index 0000000000..4393f2c8dc
--- /dev/null
+++ b/legacy/eina/doc/img/eina_inlist-node_eg1-my-struct.png
Binary files differ
diff --git a/legacy/eina/doc/img/eina_inlist-node_eg2-list-inlist.png b/legacy/eina/doc/img/eina_inlist-node_eg2-list-inlist.png
new file mode 100644
index 0000000000..4eb3235f5a
--- /dev/null
+++ b/legacy/eina/doc/img/eina_inlist-node_eg2-list-inlist.png
Binary files differ
diff --git a/legacy/eina/doc/img/eina_inlist-node_eg2-my-struct.png b/legacy/eina/doc/img/eina_inlist-node_eg2-my-struct.png
new file mode 100644
index 0000000000..9183197213
--- /dev/null
+++ b/legacy/eina/doc/img/eina_inlist-node_eg2-my-struct.png
Binary files differ
diff --git a/legacy/eina/doc/img/eina_inlist-node_eg3-my-struct.png b/legacy/eina/doc/img/eina_inlist-node_eg3-my-struct.png
new file mode 100644
index 0000000000..f669afd4b2
--- /dev/null
+++ b/legacy/eina/doc/img/eina_inlist-node_eg3-my-struct.png
Binary files differ
diff --git a/legacy/eina/doc/img/eina_inlist-node_eg3-two-inlists.png b/legacy/eina/doc/img/eina_inlist-node_eg3-two-inlists.png
new file mode 100644
index 0000000000..c8d2c8b5f5
--- /dev/null
+++ b/legacy/eina/doc/img/eina_inlist-node_eg3-two-inlists.png
Binary files differ
diff --git a/legacy/eina/src/examples/Makefile.am b/legacy/eina/src/examples/Makefile.am
index fb0fa2fbff..e8b14b4b25 100644
--- a/legacy/eina/src/examples/Makefile.am
+++ b/legacy/eina/src/examples/Makefile.am
@@ -20,7 +20,10 @@ SRCS = \
20 eina_list_01.c \ 20 eina_list_01.c \
21 eina_list_02.c \ 21 eina_list_02.c \
22 eina_list_03.c \ 22 eina_list_03.c \
23 eina_list_04.c 23 eina_list_04.c \
24 eina_inlist_01.c \
25 eina_inlist_02.c \
26 eina_inlist_03.c
24 27
25pkglib_PROGRAMS = 28pkglib_PROGRAMS =
26 29
@@ -40,6 +43,9 @@ pkglib_PROGRAMS += \
40 eina_list_01 \ 43 eina_list_01 \
41 eina_list_02 \ 44 eina_list_02 \
42 eina_list_03 \ 45 eina_list_03 \
43 eina_list_04 46 eina_list_04 \
47 eina_inlist_01 \
48 eina_inlist_02 \
49 eina_inlist_03
44endif 50endif
45 51
diff --git a/legacy/eina/src/examples/eina_inlist_01.c b/legacy/eina/src/examples/eina_inlist_01.c
new file mode 100644
index 0000000000..fa515535e5
--- /dev/null
+++ b/legacy/eina/src/examples/eina_inlist_01.c
@@ -0,0 +1,96 @@
1// Compile with:
2// gcc -g `pkg-config --cflags --libs eina` eina_inlist_01.c -o eina_inlist_01
3#include <Eina.h>
4#include <stdio.h>
5
6struct my_struct {
7 EINA_INLIST;
8 int a, b;
9};
10
11int
12sort_cb(const void *d1, const void *d2)
13{
14 const Eina_Inlist *l1, *l2;
15 const struct my_struct *x1, *x2;
16
17 l1 = d1;
18 l2 = d2;
19
20 x1 = EINA_INLIST_CONTAINER_GET(l1, struct my_struct);
21 x2 = EINA_INLIST_CONTAINER_GET(l2, struct my_struct);
22
23 return x1->a - x2->a;
24}
25
26int
27main(void)
28{
29 struct my_struct *d, *cur;
30 Eina_Inlist *list, *itr, *tmp;
31
32 eina_init();
33
34 d = malloc(sizeof(*d));
35 d->a = 1;
36 d->b = 10;
37 list = eina_inlist_append(NULL, EINA_INLIST_GET(d));
38
39 d = malloc(sizeof(*d));
40 d->a = 2;
41 d->b = 20;
42 list = eina_inlist_append(list, EINA_INLIST_GET(d));
43
44 d = malloc(sizeof(*d));
45 d->a = 3;
46 d->b = 30;
47 list = eina_inlist_prepend(list, EINA_INLIST_GET(d));
48
49 printf("list=%p\n", list);
50 EINA_INLIST_FOREACH(list, cur)
51 printf("\ta=%d, b=%d\n", cur->a, cur->b);
52
53 list = eina_inlist_promote(list, EINA_INLIST_GET(d));
54
55 d = malloc(sizeof(*d));
56 d->a = 4;
57 d->b = 40;
58 list = eina_inlist_append_relative(list, EINA_INLIST_GET(d), list);
59
60 list = eina_inlist_demote(list, EINA_INLIST_GET(d));
61
62 list = eina_inlist_sort(list, sort_cb);
63
64 printf("list after sort=%p\n", list);
65 EINA_INLIST_FOREACH(list, cur)
66 printf("\ta=%d, b=%d\n", cur->a, cur->b);
67
68 tmp = eina_inlist_find(list, EINA_INLIST_GET(d));
69 if (tmp)
70 cur = EINA_INLIST_CONTAINER_GET(tmp, struct my_struct);
71 else
72 cur = NULL;
73
74 if (d != cur)
75 printf("wrong node! cur=%p\n", cur);
76
77 list = eina_inlist_remove(list, EINA_INLIST_GET(d));
78 free(d);
79 printf("list=%p\n", list);
80 for (itr = list; itr != NULL; itr = itr->next)
81 {
82 cur = EINA_INLIST_CONTAINER_GET(itr, struct my_struct);
83 printf("\ta=%d, b=%d\n", cur->a, cur->b);
84 }
85
86 while (list)
87 {
88 Eina_Inlist *aux = list;
89 list = eina_inlist_remove(list, list);
90 free(aux);
91 }
92
93 eina_shutdown();
94
95 return 0;
96}
diff --git a/legacy/eina/src/examples/eina_inlist_02.c b/legacy/eina/src/examples/eina_inlist_02.c
new file mode 100644
index 0000000000..7d23f137f7
--- /dev/null
+++ b/legacy/eina/src/examples/eina_inlist_02.c
@@ -0,0 +1,64 @@
1// Compile with:
2// gcc -g `pkg-config --cflags --libs eina` eina_inlist_01.c -o eina_inlist_01
3#include <Eina.h>
4#include <stdio.h>
5
6struct my_struct {
7 EINA_INLIST;
8 int a, b;
9};
10
11int
12main(void)
13{
14 struct my_struct *d, *cur;
15 int i;
16
17 Eina_Inlist *inlist = NULL;
18 Eina_List *list = NULL, *l_itr, *l_next;
19
20 eina_init();
21
22 for (i = 0; i < 100; i++)
23 {
24 d = malloc(sizeof(*d));
25 d->a = i;
26 d->b = i * 10;
27 inlist = eina_inlist_append(inlist, EINA_INLIST_GET(d));
28 if ((i % 2) == 0)
29 list = eina_list_prepend(list, d);
30 }
31
32 printf("inlist=%p\n", inlist);
33 EINA_INLIST_FOREACH(inlist, cur)
34 printf("\ta=%d, b=%d\n", cur->a, cur->b);
35
36 printf("list=%p\n", list);
37 EINA_LIST_FOREACH(list, l_itr, cur)
38 printf("\ta=%d, b=%d\n", cur->a, cur->b);
39
40 printf("inlist count=%d\n", eina_inlist_count(inlist));
41 printf("list count=%d\n\n", eina_list_count(list));
42
43 EINA_LIST_FOREACH_SAFE(list, l_itr, l_next, cur)
44 {
45 if ((cur->a % 3) == 0)
46 list = eina_list_remove_list(list, l_itr);
47 }
48
49 printf("inlist count=%d\n", eina_inlist_count(inlist));
50 printf("list count=%d\n\n", eina_list_count(list));
51
52 eina_list_free(list);
53
54 while (inlist)
55 {
56 Eina_Inlist *aux = inlist;
57 inlist = eina_inlist_remove(inlist, inlist);
58 free(aux);
59 }
60
61 eina_shutdown();
62
63 return 0;
64}
diff --git a/legacy/eina/src/examples/eina_inlist_03.c b/legacy/eina/src/examples/eina_inlist_03.c
new file mode 100644
index 0000000000..a39a78490d
--- /dev/null
+++ b/legacy/eina/src/examples/eina_inlist_03.c
@@ -0,0 +1,73 @@
1// Compile with:
2// gcc -g `pkg-config --cflags --libs eina` eina_inlist_01.c -o eina_inlist_01
3#include <Eina.h>
4#include <stdio.h>
5
6struct my_struct {
7 EINA_INLIST;
8 Eina_Inlist even;
9 int a, b;
10};
11
12#define EVEN_INLIST_GET(Inlist) (& ((Inlist)->even))
13
14#define EVEN_INLIST_CONTAINER_GET(ptr, type) \
15 ((type *)((char *)ptr - offsetof(type, even)))
16
17int
18main(void)
19{
20 struct my_struct *d, *cur;
21 int i;
22
23 Eina_Inlist *list = NULL, *list_even = NULL, *itr;
24
25 eina_init();
26
27 for (i = 0; i < 100; i++)
28 {
29 d = malloc(sizeof(*d));
30 d->a = i;
31 d->b = i * 10;
32 list = eina_inlist_append(list, EINA_INLIST_GET(d));
33 if ((i % 2) == 0)
34 list_even = eina_inlist_prepend(list_even, EVEN_INLIST_GET(d));
35 }
36
37 printf("list=%p\n", list);
38 EINA_INLIST_FOREACH(list, cur)
39 printf("\ta=%d, b=%d\n", cur->a, cur->b);
40
41 printf("list_even=%p\n", list_even);
42 for (itr = list_even; itr != NULL; itr = itr->next)
43 {
44 cur = EVEN_INLIST_CONTAINER_GET(itr, struct my_struct);
45 printf("\ta=%d, b=%d\n", cur->a, cur->b);
46 }
47
48 printf("list count=%d\n", eina_inlist_count(list));
49 printf("list_even count=%d\n\n", eina_inlist_count(list_even));
50
51 itr = list_even;
52 while (itr)
53 {
54 Eina_Inlist *next = itr->next;
55 cur = EVEN_INLIST_CONTAINER_GET(itr, struct my_struct);
56 if ((cur->a % 3) == 0)
57 list_even = eina_inlist_remove(list_even, itr);
58 itr = next;
59 }
60 printf("list count=%d\n", eina_inlist_count(list));
61 printf("list_even count=%d\n\n", eina_inlist_count(list_even));
62
63 while (list)
64 {
65 Eina_Inlist *aux = list;
66 list = eina_inlist_remove(list, list);
67 free(aux);
68 }
69
70 eina_shutdown();
71
72 return 0;
73}
diff --git a/legacy/eina/src/include/eina_inlist.h b/legacy/eina/src/include/eina_inlist.h
index eef0788428..694226e62e 100644
--- a/legacy/eina/src/include/eina_inlist.h
+++ b/legacy/eina/src/include/eina_inlist.h
@@ -25,16 +25,274 @@
25#include <stddef.h> 25#include <stddef.h>
26 26
27/** 27/**
28 * @page inlist_01_example_page Eina_Inlist basic usage
29 * @dontinclude eina_inlist_01.c
30 *
31 * To see the full source for this example, click here: @ref
32 * eina_inlist_01_c
33 *
34 * As explained before, inline lists mean its nodes pointers are part of same
35 * memory block/blob. This is done by using the macro @ref EINA_INLIST inside the
36 * data structure that will be used:
37 *
38 * @skip struct
39 * @until };
40 *
41 * The resulting node representing this struct can be exemplified by the
42 * following picture:
43 *
44 * @image html eina_inlist-node_eg1-my-struct.png
45 * @image rtf eina_inlist-node_eg1-my-struct.png
46 *
47 * Let's define a comparison function that will be used later during the
48 * sorting of the list:
49 *
50 * @skip int
51 * @until }
52 *
53 * The @ref Eina_Inlist can be used exactly the same way as @ref Eina_List when
54 * appending, prepend and removing items. But since we already have the node
55 * pointers inside the structure, they need to be retrieved with the macro @ref
56 * EINA_INLIST_GET :
57 *
58 * @skip malloc
59 * @until append
60 *
61 * Notice that @ref eina_inlist_append always receives the head of the list as
62 * first argument, and its return value should be used as the list pointer
63 * (head):
64 *
65 * @skip malloc
66 * @until append
67 *
68 * After appending 3 items, the list now should look similar to this:
69 *
70 * @image html eina_inlist-node_eg1-inlist.png
71 * @image rtf eina_inlist-node_eg1-inlist.png
72 *
73 * The macro @ref EINA_INLIST_FOREACH can be used to iterate over the list:
74 *
75 * @skip printf
76 * @until cur->a
77 *
78 * @ref eina_inlist_promote(), @ref eina_inlist_demote(), @ref
79 * eina_inlist_append_relative() and similar functions all work in the same way
80 * as the @ref Eina_List :
81 *
82 * @skip eina_inlist_promote
83 * @until eina_inlist_demote
84 *
85 * Now let's use the @c sort_cb function declared above to sort our list:
86 *
87 * @skipline eina_inlist_sort
88 *
89 * Removing an element from the inlist is also similar to @ref Eina_List :
90 *
91 * @skip inlist_remove
92 * @until free
93 *
94 * Another way of walking through the inlist.
95 *
96 * @skip for
97 * @until }
98 *
99 * Notice that in the previous piece of code, since we only have the pointers to
100 * the inlist nodes, we have to use the @ref EINA_INLIST_CONTAINER_GET macro
101 * that will return the pointer to the entire structure. Of course, in this case
102 * it is the same as the list pointer, since the @ref EINA_INLIST macro was used
103 * in the beginning of the structure.
104 *
105 * Now to finish this example, lets delete this list:
106 *
107 * @skip while
108 * @until }
109 */
110
111/**
112 * @page inlist_02_example_page Eina_Inlist advanced usage - lists and inlists
113 * @dontinclude eina_inlist_02.c
114 *
115 * This example describes the usage of @ref Eina_Inlist mixed with @ref
116 * Eina_List . We create and add elements to an inlist, and the even members
117 * are also added to a normal list. Later we remove the elements divisible by 3
118 * from this normal list.
119 *
120 * The struct that is going to be used is the same used in @ref
121 * inlist_01_example_page , since we still need the @ref EINA_INLIST macro to
122 * declare the inlist node info:
123 *
124 * @skip struct
125 * @until };
126 *
127 * The resulting node representing this struct can be exemplified by the
128 * following picture:
129 *
130 * @image html eina_inlist-node_eg2-my-struct.png
131 * @image rtf eina_inlist-node_eg2-my-struct.png
132 *
133 * Now we need some pointers and auxiliar variables that will help us iterate on
134 * the lists:
135 *
136 * @skip struct
137 * @until l_next;
138 *
139 * Allocating 100 elements and putting them into an inlist, and the even
140 * elements also go to the normal list:
141 *
142 * @skip for
143 * @until }
144 *
145 * After this point, what we have are two distinct lists that share some
146 * elements. The first list (inlist) is defined by the pointers inside the
147 * elements data structure, while the second list (normal list) has its own node
148 * data structure that is kept outside of the elements.
149 *
150 * The two lists, sharing some elements, can be represented by the following
151 * picture:
152 *
153 * <img src="eina_inlist-node_eg2-list-inlist.png" width="100%"/>
154 * @image rtf eina_inlist-node_eg2-list-inlist.png
155 *
156 * Accessing both lists is done normally, as if they didn't have any elements in
157 * common:
158 *
159 * @skip printf
160 * @until eina_list_count
161 *
162 * We can remove elements from the normal list, but we just don't free them
163 * because they are still stored in the inlist:
164 *
165 * @skip EINA_LIST_FOREACH_SAFE
166 * @until eina_list_count
167 *
168 * To finish this example, we want to free both lists, we can't just free all
169 * elements on the second list (normal list) because they are still being used
170 * in the inlist. So we first discard the normal list without freeing its
171 * elements, then we free all elements in the inlist (that contains all elements
172 * allocated until now):
173 *
174 * @skip eina_list_free
175 * @until }
176 *
177 * Here is the full source code for this example: @ref eina_inlist_02_c
178 */
179
180/**
181 * @page inlist_03_example_page Eina_Inlist advanced usage - multi-inlists
182 * @dontinclude eina_inlist_03.c
183 *
184 * This example describes the usage of multiple inlists storing the same data.
185 * It means that some data may appear in more than one inlist at the same time.
186 * We will demonstrate this by creating an inlist with 100 numbers, and adding
187 * the odd numbers to the second inlist, then remove the numbers divisible by 3
188 * from the second list.
189 *
190 * To accomplish this, it is necessary to have two inlist pointers in the struct
191 * that is going to be stored. We are using the default inlist member @ref
192 * EINA_INLIST, and adding another member @c even that is of type @ref
193 * Eina_Inlist too:
194 *
195 * @skip struct
196 * @until };
197 *
198 * The representation for this struct is:
199 *
200 * @image html eina_inlist-node_eg3-my-struct.png
201 * @image rtf eina_inlist-node_eg3-my-struct.png
202 *
203 * And we will define some convenience macros that are equivalent to @ref
204 * EINA_INLIST_GET and @ref EINA_INLIST_CONTAINER_GET :
205 *
206 * @skip define
207 * @until offsetof
208 *
209 * We need two pointers, one for each list, and a pointer that will be used as
210 * an iterator:
211 *
212 * @skipline Eina_Inlist
213 *
214 * Now we allocate and add to the first list every number from 0 to 99. These
215 * nodes data also have the @ref Eina_Inlist node info for the second list (@c
216 * even). We will use them to add just the even numbers to the second list, the
217 * @c list_even. Also notice that we are using our macro @c EVEN_INLIST_GET to
218 * get the pointer to the even list node info:
219 *
220 * @skip for
221 * @until }
222 *
223 * And the resulting lists will be as follow:
224 *
225 * <img src="eina_inlist-node_eg3-two-inlists.png" width="100%"/>
226 * @image rtf eina_inlist-node_eg3-two-inlists.png
227 *
228 * For the first list, we can use the macro @ref EINA_INLIST_FOREACH to iterate
229 * over its elements:
230 *
231 * @skip FOREACH
232 * @until printf
233 *
234 * But for the second list, we have to do it manually. Of course we could create
235 * a similar macro to @ref EINA_INLIST_FOREACH, but since this macro is more
236 * complex than the other two and we are using it only once, it's better to just
237 * do it manually:
238 *
239 * @skip for
240 * @until }
241 *
242 * Let's just check that the two lists have the expected number of elements:
243 *
244 * @skip list count
245 * @until list_even count
246 *
247 * And removing the numbers divisible by 3 only from the second list:
248 *
249 * @skip itr
250 * @until list_even count
251 *
252 * Now that we don't need the two lists anymore, we can just free all the items.
253 * Since all of the allocated data was put into the first list, and both lists
254 * are made of pointers to inside the data structures, we can free only the
255 * first list (that contains all the elements) and the second list will be gone
256 * with it:
257 *
258 * @skip while
259 * @until free
260 *
261 * To see the full source code for this example, click here: @ref
262 * eina_inlist_03_c
263 *
264 */
265
266/**
267 * @page eina_inlist_01_c eina_inlist_01.c
268 * @include eina_inlist_01.c
269 */
270
271/**
272 * @page eina_inlist_02_c eina_inlist_02.c
273 * @include eina_inlist_02.c
274 */
275
276/**
277 * @page eina_inlist_03_c eina_inlist_03.c
278 * @include eina_inlist_03.c
279 */
280
281/**
28 * @addtogroup Eina_Inline_List_Group Inline List 282 * @addtogroup Eina_Inline_List_Group Inline List
29 * 283 *
30 * @brief These functions provide inline list management. 284 * @brief These functions provide inline list management.
31 * 285 *
32 * Inline lists mean its nodes pointers are part of same memory as 286 * Inline lists mean its nodes pointers are part of same memory as
33 * data. This has the benefit of fragmenting memory less and avoiding 287 * data. This has the benefit of fragmenting memory less and avoiding
34 * @c node->data indirection, but has the drawback of elements only 288 * @c node->data indirection, but has the drawback of higher cost for some
35 * being able to be part of one single inlist at same time. But it is 289 * common operations like count and sort.
36 * possible to have inlist nodes to be part of regular lists created 290 *
37 * with eina_list_append() or eina_list_prepend(). 291 * It is possible to have inlist nodes to be part of regular lists, created with
292 * @ref eina_list_append() or @ref eina_list_prepend(). It's also possible to
293 * have a structure with two inlist pointers, thus be part of two different
294 * inlists at the same time, but the current convenience macros provided won't
295 * work for both of them. Consult @ref inlist_advanced for more info.
38 * 296 *
39 * Inline lists have their purposes, but if you don't know what those purposes are, go with 297 * Inline lists have their purposes, but if you don't know what those purposes are, go with
40 * regular lists instead. 298 * regular lists instead.
@@ -46,61 +304,62 @@
46 * This lets the compiler to do type checking and let the programmer know 304 * This lets the compiler to do type checking and let the programmer know
47 * exactly what type this list is. 305 * exactly what type this list is.
48 * 306 *
49 * @code 307 * A simple example demonstrating the basic usage of an inlist can be found
50 * #include <Eina.h> 308 * here: @ref inlist_01_example_page
51 * #include <stdio.h> 309 *
52 * 310 * @section inlist_algo Algorithm
53 * int 311 *
54 * main(void) 312 * The basic structure can be represented by the following picture:
55 * { 313 *
56 * struct my_struct { 314 * @image html eina_inlist-node.png
57 * EINA_INLIST; 315 * @image rtf eina_inlist-node.png
58 * int a, b; 316 *
59 * } *d, *cur; 317 * One data structure will also have the node information, with three pointers:
60 * Eina_Inlist *list, *itr; 318 * @a prev, @a next and @a last. The @a last pointer is just valid for the first
61 * 319 * element (the list head), otherwise each insertion in the list would have to
62 * eina_init(); 320 * be done updating every node with the correct pointer. This means that it's
63 * 321 * always very important to keep a pointer to the first element of the list,
64 * d = malloc(sizeof(*d)); 322 * since it is the only one that has the correct information to allow a proper
65 * d->a = 1; 323 * O(1) append to the list.
66 * d->b = 10; 324 *
67 * list = eina_inlist_append(NULL, EINA_INLIST_GET(d)); 325 * @section inlist_perf Performance
68 * 326 *
69 * d = malloc(sizeof(*d)); 327 * Due to the nature of the inlist, there's no accounting information, and no
70 * d->a = 2; 328 * easy access to the last element from each list node. This means that @ref
71 * d->b = 20; 329 * eina_inlist_count() is order-N, while @ref eina_list_count() is order-1 (constant
72 * list = eina_inlist_append(list, EINA_INLIST_GET(d)); 330 * time).
73 * 331 *
74 * d = malloc(sizeof(*d)); 332 * For the same reasons, @ref eina_inlist_sort() is slower than @ref
75 * d->a = 3; 333 * eina_list_sort() . If the list is intended to have faster access, be
76 * d->b = 30; 334 * sorted/merged frequently, or needs to have other complex operations, consider
77 * list = eina_inlist_prepend(list, EINA_INLIST_GET(d)); 335 * using @ref Eina_List instead.
78 * 336 *
79 * printf("list=%p\n", list); 337 * @section inlist_advanced Advanced Usage
80 * EINA_INLIST_FOREACH(list, cur) 338 *
81 * printf("\ta=%d, b=%d\n", cur->a, cur->b); 339 * The basic usage considers a struct that will have the user data, and also
82 * 340 * have an inlist node information (prev, next and last pointers) created with
83 * list = eina_inlist_remove(list, EINA_INLIST_GET(d)); 341 * @ref EINA_INLIST during the struct declaration. This allows one to use the
84 * free(d); 342 * convenience macros @ref EINA_INLIST_GET(), @ref EINA_INLIST_CONTAINER_GET(),
85 * printf("list=%p\n", list); 343 * @ref EINA_INLIST_FOREACH() and so. This happens because the @ref EINA_INLIST
86 * for (itr = list; itr != NULL; itr = itr->next) 344 * macro declares a struct member with the name @a __inlist, and all the other
87 * { 345 * macros assume that this struct member has this name.
88 * cur = EINA_INLIST_CONTAINER_GET(itr, struct my_struct); 346 *
89 * printf("\ta=%d, b=%d\n", cur->a, cur->b); 347 * It may be the case that someone needs to have some inlist nodes added to a
90 * } 348 * @ref Eina_List too. If this happens, the inlist nodes can be added to the
91 * 349 * @ref Eina_List without any problems. This example demonstrates this case:
92 * while (list) 350 * @ref inlist_02_example_page
93 * { 351 *
94 * Eina_Inlist *aux = list; 352 * It's also possible to have some data that is part of two different inlists.
95 * list = eina_inlist_remove(list, list); 353 * If this is the case, then it won't be possible to use the convenience macros
96 * free(aux); 354 * to both of the lists. It will be necessary to create a new set of macros that
97 * } 355 * will allow access to the second list node info. An example for this usage can
98 * 356 * be found here:
99 * eina_shutdown(); 357 * @ref inlist_03_example_page
100 * 358 *
101 * return 0; 359 * List of examples:
102 * } 360 * @li @ref inlist_01_example_page
103 * @endcode 361 * @li @ref inlist_02_example_page
362 * @li @ref inlist_03_example_page
104 * 363 *
105 * @{ 364 * @{
106 */ 365 */