diff options
author | David Walter Seikel | 2012-04-22 09:19:23 +1000 |
---|---|---|
committer | David Walter Seikel | 2012-04-22 09:19:23 +1000 |
commit | c963d75dfdeec11f82e79e727062fbf89afa2c04 (patch) | |
tree | 895633dbf641110be46f117c29890c49b3ffc0bd /libraries/eina/src/include/eina_inarray.h | |
parent | Adding the new extantz viewer and grid manager. (diff) | |
download | SledjHamr-c963d75dfdeec11f82e79e727062fbf89afa2c04.zip SledjHamr-c963d75dfdeec11f82e79e727062fbf89afa2c04.tar.gz SledjHamr-c963d75dfdeec11f82e79e727062fbf89afa2c04.tar.bz2 SledjHamr-c963d75dfdeec11f82e79e727062fbf89afa2c04.tar.xz |
Update EFL to latest beta.
Diffstat (limited to '')
-rw-r--r-- | libraries/eina/src/include/eina_inarray.h | 148 |
1 files changed, 143 insertions, 5 deletions
diff --git a/libraries/eina/src/include/eina_inarray.h b/libraries/eina/src/include/eina_inarray.h index d37c76b..079f1e3 100644 --- a/libraries/eina/src/include/eina_inarray.h +++ b/libraries/eina/src/include/eina_inarray.h | |||
@@ -24,6 +24,131 @@ | |||
24 | #include "eina_accessor.h" | 24 | #include "eina_accessor.h" |
25 | 25 | ||
26 | /** | 26 | /** |
27 | * @page eina_inarray_example_01 Eina inline array usage | ||
28 | * @dontinclude eina_inarray_01.c | ||
29 | * | ||
30 | * This example will create an inline array of chars, add some elements, print | ||
31 | * it, re-purpose the array to store ints, add some elements and print that. | ||
32 | * | ||
33 | * We'll start with a function to compare ints we need this because the '>' | ||
34 | * operator is not a function and can't be used where Eina_Compare_Cb is needed. | ||
35 | * @skip int | ||
36 | * @until } | ||
37 | * | ||
38 | * And then move on to the code we actually care about, starting with variable | ||
39 | * declarations and eina initialization: | ||
40 | * @until eina_init | ||
41 | * | ||
42 | * Creating an inline array is very simple, we just need to know what type we | ||
43 | * want to store: | ||
44 | * @until inarray_new | ||
45 | * @note The second parameter(the step) is left at zero which means that eina | ||
46 | * will choose an appropriate value, this should @b only be changed if it's | ||
47 | * known, beforehand, how many elements the array will have. | ||
48 | * | ||
49 | * Once we have an array we can start adding elements to it. Because the | ||
50 | * insertion function expect a memory address we have to put the value we want | ||
51 | * to store in a variable(this should be no problem since in real world usage | ||
52 | * that's usually where the value will be anyways): | ||
53 | * @until append | ||
54 | * @note Because the inline array copies the value given to it we can later | ||
55 | * change @c ch, which we do, without affecting the contents of the array. | ||
56 | * | ||
57 | * So let's add some more elements: | ||
58 | * @until append | ||
59 | * @until append | ||
60 | * @until append | ||
61 | * | ||
62 | * We will then iterate over our array and print every position of it. The thing | ||
63 | * to note here is not so much the values which will be the expected 'a', 'b', | ||
64 | * 'c' and 'd', but rather the memory address of these values, they are | ||
65 | * sequential: | ||
66 | * @until printf | ||
67 | * @until printf | ||
68 | * | ||
69 | * We'll now use our array to store ints, so we need to first erase every member | ||
70 | * currently on the array: | ||
71 | * @until _flush | ||
72 | * | ||
73 | * And then to be able to store a different type on the same array we use the | ||
74 | * eina_array_setup() function, which is just like the eina_inarray_new() | ||
75 | * function except it receives already allocated memory. This time we're going | ||
76 | * to ask eina to use a step of size 4 because that's how many elements we'll be | ||
77 | * putting on the array: | ||
78 | * @until _setup | ||
79 | * @note Strictly speaking the reason to call eina_inarray_setup() is not | ||
80 | * because we're storing different type, but rather because our types have | ||
81 | * different sizes. Eina inline arrays don't actually know anything about types, | ||
82 | * they only deal in blocks of memory of a given size. | ||
83 | * @note Since eina_array_setup() receives already allocated memory you can(and | ||
84 | * it is in fact good practice) use inline arrays not declared as pointers: | ||
85 | * @code | ||
86 | * Eina_Inarray arr; | ||
87 | * eina_inarray_setup(&arr, sizeof(int), 4); | ||
88 | * @endcode | ||
89 | * | ||
90 | * And now to add our integer values to the array: | ||
91 | * @until append | ||
92 | * @until append | ||
93 | * @until append | ||
94 | * | ||
95 | * Just to change things up a bit we've left out the 99 value, but will still | ||
96 | * add it in such a way to keep the array ordered. There are many ways to do | ||
97 | * this, we could use eina_inarray_insert_at(), or we could change the value | ||
98 | * of the last member using eina_inarray_replace_at() and then append the values | ||
99 | * in the right order, but for no particular reason we're going to use | ||
100 | * eina_inarray_insert_sorted() instead: | ||
101 | * @until insert_sorted | ||
102 | * | ||
103 | * We then print the size of our array, and the array itself, much like last | ||
104 | * time the values are not surprising, and neither should it be that the memory | ||
105 | * addresses are contiguous: | ||
106 | * @until printf | ||
107 | * @until printf | ||
108 | * | ||
109 | * Once done we free our array and shutdown eina: | ||
110 | * @until } | ||
111 | * | ||
112 | * The source for this example: @ref eina_inarray_01_c | ||
113 | */ | ||
114 | |||
115 | /** | ||
116 | * @page eina_inarray_01_c eina_inarray_01.c | ||
117 | * @include eina_inarray_01.c | ||
118 | * @example eina_inarray_01.c | ||
119 | */ | ||
120 | |||
121 | /** | ||
122 | * @page eina_inarray_example_02 Eina inline array of strings | ||
123 | * @dontinclude eina_inarray_02.c | ||
124 | * | ||
125 | * This example will create an inline array of strings, add some elements and | ||
126 | * then print them. This example is based on @ref eina_array_01_example_page and | ||
127 | * @ref eina_inarray_example_01. | ||
128 | * | ||
129 | * We start with some variable declarations and eina initialization: | ||
130 | * @skip int | ||
131 | * @until eina_init | ||
132 | * | ||
133 | * We then create the array much like we did on @ref eina_inarray_example_01: | ||
134 | * @until inarray_new | ||
135 | * | ||
136 | * The point were this example significantly differs from the first eina inline | ||
137 | * array example. We'll not be adding the strings themselves to the array since | ||
138 | * their size varies, we'll store pointer to the strings instead. We therefore | ||
139 | * use @c char** to populate our inline array: | ||
140 | * @until } | ||
141 | * | ||
142 | * The source for this example: @ref eina_inarray_02_c | ||
143 | */ | ||
144 | |||
145 | /** | ||
146 | * @page eina_inarray_02_c eina_inarray_02.c | ||
147 | * @include eina_inarray_02.c | ||
148 | * @example eina_inarray_02.c | ||
149 | */ | ||
150 | |||
151 | /** | ||
27 | * @addtogroup Eina_Data_Types_Group Data Types | 152 | * @addtogroup Eina_Data_Types_Group Data Types |
28 | * | 153 | * |
29 | * @since 1.2 | 154 | * @since 1.2 |
@@ -40,6 +165,19 @@ | |||
40 | /** | 165 | /** |
41 | * @defgroup Eina_Inline_Array_Group Inline Array | 166 | * @defgroup Eina_Inline_Array_Group Inline Array |
42 | * | 167 | * |
168 | * Inline array is a container that stores the data itself not pointers to data, | ||
169 | * this means there is no memory fragmentation, also for small data types(such | ||
170 | * as char, short, int, etc.) it's more memory efficient. | ||
171 | * | ||
172 | * Usage of the inline array is very similar to that of other | ||
173 | * @ref Eina_Containers_Group, like all arrays adding elements to the beginning | ||
174 | * of the array is a lot more costly than appending, so those operations should | ||
175 | * be minimized. | ||
176 | * | ||
177 | * Examples: | ||
178 | * @li @ref eina_inarray_example_01 | ||
179 | * @li @ref eina_inarray_example_02 | ||
180 | * | ||
43 | * @{ | 181 | * @{ |
44 | */ | 182 | */ |
45 | 183 | ||
@@ -531,8 +669,8 @@ EAPI Eina_Accessor *eina_inarray_accessor_new(const Eina_Inarray *array) EINA_MA | |||
531 | * @since 1.2 | 669 | * @since 1.2 |
532 | */ | 670 | */ |
533 | #define EINA_INARRAY_FOREACH(array, itr) \ | 671 | #define EINA_INARRAY_FOREACH(array, itr) \ |
534 | for ((itr) = array->members; \ | 672 | for ((itr) = (array)->members; \ |
535 | (itr) < (((typeof(*itr)*)array->members) + array->len); \ | 673 | (itr) < (((typeof(*itr)*)(array)->members) + (array)->len); \ |
536 | (itr)++) | 674 | (itr)++) |
537 | 675 | ||
538 | /** | 676 | /** |
@@ -552,9 +690,9 @@ EAPI Eina_Accessor *eina_inarray_accessor_new(const Eina_Inarray *array) EINA_MA | |||
552 | * @since 1.2 | 690 | * @since 1.2 |
553 | */ | 691 | */ |
554 | #define EINA_INARRAY_REVERSE_FOREACH(array, itr) \ | 692 | #define EINA_INARRAY_REVERSE_FOREACH(array, itr) \ |
555 | for ((itr) = ((((typeof(*(itr))*)array->members) + array->len) - 1); \ | 693 | for ((itr) = ((((typeof(*(itr))*)(array)->members) + (array)->len) - 1); \ |
556 | (((itr) >= (typeof(*(itr))*)array->members) \ | 694 | (((itr) >= (typeof(*(itr))*)(array)->members) \ |
557 | && (array->members != NULL)); \ | 695 | && ((array)->members != NULL)); \ |
558 | (itr)--) | 696 | (itr)--) |
559 | 697 | ||
560 | /** | 698 | /** |