diff options
author | Vincent Torri <vincent.torri@gmail.com> | 2012-09-16 10:57:48 +0000 |
---|---|---|
committer | Vincent Torri <vincent.torri@gmail.com> | 2012-09-16 10:57:48 +0000 |
commit | 785f2a6b3a70454ecfe94addc6480ebf20c44c13 (patch) | |
tree | 17a195d2c1f022cd480fd0e0b95be5035ad915e2 /src | |
parent | dfc0331373c3f98df7cb996abc588c7dcf44af0a (diff) |
merge : add eina
currently, examples, tests and benchmark are not set. That's the next things i'll do
SVN revision: 76710
Diffstat (limited to 'src')
216 files changed, 138223 insertions, 1 deletions
diff --git a/src/Makefile.am b/src/Makefile.am index a8590b2f0d..d53263a5cb 100644 --- a/src/Makefile.am +++ b/src/Makefile.am | |||
@@ -1,3 +1,3 @@ | |||
1 | MAINTAINERCLEANFILES = Makefile.in | 1 | MAINTAINERCLEANFILES = Makefile.in |
2 | 2 | ||
3 | SUBDIRS = lib bin | 3 | SUBDIRS = lib include modules bin scripts |
diff --git a/src/include/Makefile.am b/src/include/Makefile.am new file mode 100644 index 0000000000..b8f642fb72 --- /dev/null +++ b/src/include/Makefile.am | |||
@@ -0,0 +1,3 @@ | |||
1 | MAINTAINERCLEANFILES = Makefile.in | ||
2 | |||
3 | SUBDIRS = eina | ||
diff --git a/src/include/eina/Eina.h b/src/include/eina/Eina.h new file mode 100644 index 0000000000..584bccd9de --- /dev/null +++ b/src/include/eina/Eina.h | |||
@@ -0,0 +1,248 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2008-2012 Enlightenment Developers: | ||
3 | * Albin "Lutin" Tonnerre <albin.tonnerre@gmail.com> | ||
4 | * Alexandre "diaxen" Becoulet <diaxen@free.fr> | ||
5 | * Andre Dieb <andre.dieb@gmail.com> | ||
6 | * Arnaud de Turckheim "quarium" <quarium@gmail.com> | ||
7 | * Carsten Haitzler <raster@rasterman.com> | ||
8 | * Cedric Bail <cedric.bail@free.fr> | ||
9 | * Corey "atmos" Donohoe <atmos@atmos.org> | ||
10 | * Fabiano Fidêncio <fidencio@profusion.mobi> | ||
11 | * Gustavo Chaves <glima@profusion.mobi> | ||
12 | * Gustavo Sverzut Barbieri <barbieri@gmail.com> | ||
13 | * Jorge Luis "turran" Zapata <jorgeluis.zapata@gmail.com> | ||
14 | * Peter "pfritz" Wehrfritz <peter.wehrfritz@web.de> | ||
15 | * Raphael Kubo da Costa <kubo@profusion.mobi> | ||
16 | * Tilman Sauerbeck <tilman@code-monkey.de> | ||
17 | * Vincent "caro" Torri <vtorri at univ-evry dot fr> | ||
18 | * Tom Hacohen <tom@stosb.com> | ||
19 | * Jonas M. Gastal <jgastal@profusion.mobi> | ||
20 | * | ||
21 | * This library is free software; you can redistribute it and/or | ||
22 | * modify it under the terms of the GNU Lesser General Public | ||
23 | * License as published by the Free Software Foundation; either | ||
24 | * version 2.1 of the License, or (at your option) any later version. | ||
25 | * | ||
26 | * This library is distributed in the hope that it will be useful, | ||
27 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
28 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
29 | * Lesser General Public License for more details. | ||
30 | * | ||
31 | * You should have received a copy of the GNU Lesser General Public | ||
32 | * License along with this library; | ||
33 | * if not, see <http://www.gnu.org/licenses/>. | ||
34 | */ | ||
35 | |||
36 | #ifndef EINA_H_ | ||
37 | #define EINA_H_ | ||
38 | |||
39 | /** | ||
40 | * @file | ||
41 | * @brief Eina Utility library | ||
42 | * | ||
43 | * These routines are used for Eina. | ||
44 | */ | ||
45 | |||
46 | /** | ||
47 | * @mainpage Eina | ||
48 | * | ||
49 | * @version 1.7 | ||
50 | * @date 2008-2012 | ||
51 | * | ||
52 | * @section eina_intro_sec Introduction | ||
53 | * | ||
54 | * The Eina library is a library that implements an API for data types | ||
55 | * in an efficient way. It also provides some useful tools like | ||
56 | * opening shared libraries, errors management, type conversion, | ||
57 | * time accounting and memory pool. | ||
58 | * | ||
59 | * This library is cross-platform and can be compiled and used on | ||
60 | * Linux, BSD, Opensolaris and Windows (XP and CE). | ||
61 | * | ||
62 | * The data types that are available are (see @ref Eina_Data_Types_Group): | ||
63 | * @li @ref Eina_Inline_Array_Group standard array of inlined members. | ||
64 | * @li @ref Eina_Array_Group standard array of @c void* data. | ||
65 | * @li @ref Eina_Hash_Group standard hash of @c void* data. | ||
66 | * @li @ref Eina_Inline_List_Group list with nodes inlined into user type. | ||
67 | * @li @ref Eina_CList_Group Compact List. | ||
68 | * @li @ref Eina_List_Group standard list of @c void* data. | ||
69 | * @li @ref Eina_Iterator_Group Iterator functions. | ||
70 | * @li @ref Eina_Matrixsparse_Group sparse matrix of @c void* data. | ||
71 | * @li @ref Eina_Rbtree_Group red-black tree with nodes inlined into user type. | ||
72 | * @li @ref Eina_String_Buffer_Group mutable string to prepend, insert or append strings to a buffer. | ||
73 | * @li @ref Eina_Stringshare_Group saves memory by sharing read-only string references. | ||
74 | * @li @ref Eina_Tiler_Group split, merge and navigates into 2D tiled regions. | ||
75 | * @li @ref Eina_Trash_Group container of unused but allocated data. | ||
76 | * @li @ref Eina_Value_Group container for generic value storage and access. | ||
77 | * @li @ref Eina_Model_Group container for data with user defined hierarchy/structure. | ||
78 | * | ||
79 | * The tools that are available are (see @ref Eina_Tools_Group): | ||
80 | * @li @ref Eina_Benchmark_Group helper to write benchmarks. | ||
81 | * @li @ref Eina_Convert_Group faster conversion from strings to integers, double, etc. | ||
82 | * @li @ref Eina_Counter_Group measures number of calls and their time. | ||
83 | * @li @ref Eina_Error_Group error identifiers. | ||
84 | * @li @ref Eina_File_Group simple file list and path split. | ||
85 | * @li @ref Eina_Lalloc_Group simple lazy allocator. | ||
86 | * @li @ref Eina_Log_Group full-featured logging system. | ||
87 | * @li @ref Eina_Magic_Group provides runtime type checking. | ||
88 | * @li @ref Eina_Memory_Pool_Group abstraction for various memory allocators. | ||
89 | * @li @ref Eina_Module_Group lists, loads and share modules using Eina_Module standard. | ||
90 | * @li @ref Eina_Rectangle_Group rectangle structure and standard manipulation methods. | ||
91 | * @li @ref Eina_Safety_Checks_Group extra checks that will report unexpected conditions and can be disabled at compile time. | ||
92 | * @li @ref Eina_String_Group a set of functions that manages C strings. | ||
93 | * | ||
94 | * Please see the @ref authors page for contact details. | ||
95 | * | ||
96 | * @defgroup Eina_Data_Types_Group Data Types | ||
97 | * | ||
98 | * Eina provide easy to use and optimized data types and structures. | ||
99 | * | ||
100 | * | ||
101 | * @defgroup Eina_Containers_Group Containers | ||
102 | * | ||
103 | * @section Intro Introduction | ||
104 | * Containers are data types that hold data and allow iteration over | ||
105 | * their elements with an @ref Eina_Iterator_Group, or eventually an | ||
106 | * @ref Eina_Accessor_Group. | ||
107 | * | ||
108 | * The containers in eina are designed with performance in mind, one consequence | ||
109 | * of this is that they @b don't check the validity of data structures given to | ||
110 | * them(@ref Eina_Magic_Group). | ||
111 | * | ||
112 | * @section Choice Choosing container type | ||
113 | * | ||
114 | * The choice of which container to use in each situation is very important in | ||
115 | * achieving good performance and readable code. The most common container types | ||
116 | * to be used are: | ||
117 | * @li List | ||
118 | * @li Inline list | ||
119 | * @li Array | ||
120 | * @li Inline array | ||
121 | * @li Hash | ||
122 | * | ||
123 | * All types have virtues and vices. The following considerations are good | ||
124 | * starting point in deciding which container to use: | ||
125 | * @li Hashes are appropriate for datasets which will be searched often; | ||
126 | * @li arrays are good when accessing members by position; | ||
127 | * @li lists provide good versatility for adding elements in any position with | ||
128 | * minimal overhead; | ||
129 | * @li inline arrays use very little memory and don't cause fragmentation and | ||
130 | * therefore are a good option in memory constrained systems; | ||
131 | * @li inline lists are the appropriate type to use when the flexibility of a | ||
132 | * list is required but the overhead of pointer indirection is not acceptable. | ||
133 | * @warning These are general considerations, every situation is different, | ||
134 | * don't follow these recommendations blindly. | ||
135 | * | ||
136 | * @section Creation Creating custom container types | ||
137 | * | ||
138 | * @note Before creating a custom container check if one of the existing ones | ||
139 | * doesn't suit your needs. For example, while there is no stack type @ref | ||
140 | * Eina_Array_Group is a very good substitute, similarly there is no queue type | ||
141 | * however an @ref Eina_List_Group works very well as a queue. | ||
142 | * | ||
143 | * If creating a custom container type consider allowing access to the data in | ||
144 | * your container through @ref Eina_Iterator_Group "Iterators" and @ref | ||
145 | * Eina_Accessor_Group "Accessors". To do so your container should have an | ||
146 | * iterator creation function and an accessor creation function, these functions | ||
147 | * should return properly populated @ref _Eina_Iterator and @ref _Eina_Accessor. | ||
148 | * | ||
149 | * @defgroup Eina_Tools_Group Tools | ||
150 | * | ||
151 | * Eina tools aims to help application development, providing ways to | ||
152 | * make it safer, log errors, manage memory more efficiently and more. | ||
153 | * | ||
154 | */ | ||
155 | |||
156 | /** | ||
157 | * | ||
158 | * @page authors Authors | ||
159 | * | ||
160 | * @author Albin "Lutin" Tonnerre <albin.tonnerre@@gmail.com> | ||
161 | * @author Alexandre "diaxen" Becoulet <diaxen@@free.fr> | ||
162 | * @author Andre Dieb <andre.dieb@@gmail.com> | ||
163 | * @author Arnaud de Turckheim "quarium" <quarium@@gmail.com> | ||
164 | * @author Carsten Haitzler <raster@@rasterman.com> | ||
165 | * @author Cedric Bail <cedric.bail@@free.fr> | ||
166 | * @author Corey "atmos" Donohoe <atmos@@atmos.org> | ||
167 | * @author Vincent "caro" Torri <vtorri at univ-evry dot fr> | ||
168 | * @author Fabiano Fidêncio <fidencio@@profusion.mobi> | ||
169 | * @author Gustavo Chaves <glima@@profusion.mobi> | ||
170 | * @author Gustavo Sverzut Barbieri <barbieri@@profusion.mobi> | ||
171 | * @author Jorge Luis "turran" Zapata <jorgeluis.zapata@@gmail.com> | ||
172 | * @author Tilman Sauerbeck <tilman@@code-monkey.de> | ||
173 | * @author Peter "pfritz" Wehrfritz <peter.wehrfritz@@web.de> | ||
174 | * @author Raphael Kubo da Costa <kubo@@profusion.mobi> | ||
175 | * @author Tom Hacohen <tom@@stosb.com> | ||
176 | * @author Brett Nash <nash@@nash.id.au> | ||
177 | * @author Sebastian Dransfeld <sd@@tango.flipp.net> | ||
178 | * @author Myungjae Lee <mjae.lee@@samsung.com> | ||
179 | * @author Youness Alaoui <kakaroto@@kakaroto.homelinux.net> | ||
180 | * @author Boris "billiob" Faure <billiob@@gmail.com> | ||
181 | * @author Sung W. Park <sungwoo@@gmail.com> | ||
182 | * @author Guillaume Friloux <guillaume.friloux@@asp64.com> | ||
183 | * | ||
184 | * Please contact <enlightenment-devel@lists.sourceforge.net> to get in | ||
185 | * contact with the developers and maintainers. | ||
186 | * | ||
187 | */ | ||
188 | |||
189 | #ifdef _WIN32 | ||
190 | # include <Evil.h> | ||
191 | #endif | ||
192 | |||
193 | #ifdef __cplusplus | ||
194 | extern "C" { | ||
195 | #endif | ||
196 | |||
197 | #include "eina_config.h" | ||
198 | #include "eina_types.h" | ||
199 | #include "eina_main.h" | ||
200 | #include "eina_fp.h" | ||
201 | #include "eina_rectangle.h" | ||
202 | #include "eina_clist.h" | ||
203 | #include "eina_inlist.h" | ||
204 | #include "eina_file.h" | ||
205 | #include "eina_list.h" | ||
206 | #include "eina_hash.h" | ||
207 | #include "eina_trash.h" | ||
208 | #include "eina_lalloc.h" | ||
209 | #include "eina_module.h" | ||
210 | #include "eina_mempool.h" | ||
211 | #include "eina_error.h" | ||
212 | #include "eina_log.h" | ||
213 | #include "eina_inarray.h" | ||
214 | #include "eina_array.h" | ||
215 | #include "eina_binshare.h" | ||
216 | #include "eina_stringshare.h" | ||
217 | #include "eina_ustringshare.h" | ||
218 | #include "eina_magic.h" | ||
219 | #include "eina_counter.h" | ||
220 | #include "eina_rbtree.h" | ||
221 | #include "eina_accessor.h" | ||
222 | #include "eina_iterator.h" | ||
223 | #include "eina_benchmark.h" | ||
224 | #include "eina_convert.h" | ||
225 | #include "eina_cpu.h" | ||
226 | #include "eina_sched.h" | ||
227 | #include "eina_tiler.h" | ||
228 | #include "eina_hamster.h" | ||
229 | #include "eina_matrixsparse.h" | ||
230 | #include "eina_str.h" | ||
231 | #include "eina_strbuf.h" | ||
232 | #include "eina_binbuf.h" | ||
233 | #include "eina_ustrbuf.h" | ||
234 | #include "eina_unicode.h" | ||
235 | #include "eina_quadtree.h" | ||
236 | #include "eina_simple_xml_parser.h" | ||
237 | #include "eina_lock.h" | ||
238 | #include "eina_prefix.h" | ||
239 | #include "eina_refcount.h" | ||
240 | #include "eina_mmap.h" | ||
241 | #include "eina_xattr.h" | ||
242 | #include "eina_value.h" | ||
243 | |||
244 | #ifdef __cplusplus | ||
245 | } | ||
246 | #endif | ||
247 | |||
248 | #endif /* EINA_H */ | ||
diff --git a/src/include/eina/Makefile.am b/src/include/eina/Makefile.am new file mode 100644 index 0000000000..ef87ce05a6 --- /dev/null +++ b/src/include/eina/Makefile.am | |||
@@ -0,0 +1,93 @@ | |||
1 | MAINTAINERCLEANFILES = Makefile.in | ||
2 | |||
3 | EINAHEADERS = \ | ||
4 | eina_safety_checks.h \ | ||
5 | eina_error.h \ | ||
6 | eina_log.h \ | ||
7 | eina_inline_log.x \ | ||
8 | eina_fp.h \ | ||
9 | eina_inline_f32p32.x \ | ||
10 | eina_inline_f16p16.x \ | ||
11 | eina_inline_f8p24.x \ | ||
12 | eina_inline_fp.x \ | ||
13 | eina_hash.h \ | ||
14 | eina_inline_hash.x \ | ||
15 | eina_lalloc.h \ | ||
16 | eina_clist.h \ | ||
17 | eina_inline_clist.x \ | ||
18 | eina_inarray.h \ | ||
19 | eina_inlist.h \ | ||
20 | eina_list.h \ | ||
21 | eina_file.h \ | ||
22 | eina_mempool.h \ | ||
23 | eina_module.h \ | ||
24 | eina_rectangle.h \ | ||
25 | eina_types.h \ | ||
26 | eina_array.h \ | ||
27 | eina_counter.h \ | ||
28 | eina_inline_array.x \ | ||
29 | eina_magic.h \ | ||
30 | eina_stringshare.h \ | ||
31 | eina_binshare.h \ | ||
32 | eina_binbuf.h \ | ||
33 | eina_ustringshare.h \ | ||
34 | eina_inline_stringshare.x \ | ||
35 | eina_inline_ustringshare.x \ | ||
36 | eina_inline_list.x \ | ||
37 | eina_accessor.h \ | ||
38 | eina_convert.h \ | ||
39 | eina_rbtree.h \ | ||
40 | eina_benchmark.h \ | ||
41 | eina_inline_rbtree.x \ | ||
42 | eina_inline_mempool.x \ | ||
43 | eina_inline_rectangle.x \ | ||
44 | eina_inline_trash.x \ | ||
45 | eina_trash.h \ | ||
46 | eina_iterator.h \ | ||
47 | eina_main.h \ | ||
48 | eina_cpu.h \ | ||
49 | eina_sched.h \ | ||
50 | eina_tiler.h \ | ||
51 | eina_hamster.h \ | ||
52 | eina_matrixsparse.h \ | ||
53 | eina_inline_tiler.x \ | ||
54 | eina_str.h \ | ||
55 | eina_inline_str.x \ | ||
56 | eina_strbuf.h \ | ||
57 | eina_ustrbuf.h \ | ||
58 | eina_unicode.h \ | ||
59 | eina_quadtree.h \ | ||
60 | eina_simple_xml_parser.h \ | ||
61 | eina_lock.h \ | ||
62 | eina_prefix.h \ | ||
63 | eina_refcount.h \ | ||
64 | eina_mmap.h \ | ||
65 | eina_xattr.h \ | ||
66 | eina_value.h \ | ||
67 | eina_inline_value.x | ||
68 | |||
69 | # Will be back for developper after 1.2. | ||
70 | # eina_model.h | ||
71 | # eina_object.h | ||
72 | |||
73 | if EINA_HAVE_THREADS | ||
74 | if HAVE_WINCE | ||
75 | EINAHEADERS += eina_inline_lock_wince.x | ||
76 | else | ||
77 | if HAVE_WIN32 | ||
78 | EINAHEADERS += eina_inline_lock_win32.x | ||
79 | else | ||
80 | EINAHEADERS += eina_inline_lock_posix.x | ||
81 | endif | ||
82 | endif | ||
83 | else | ||
84 | EINAHEADERS += eina_inline_lock_void.x | ||
85 | endif | ||
86 | |||
87 | installed_mainheaderdir = $(includedir)/eina-@VMAJ@ | ||
88 | dist_installed_mainheader_DATA = Eina.h eina_config.h | ||
89 | |||
90 | installed_headersdir = $(includedir)/eina-@VMAJ@/eina | ||
91 | dist_installed_headers_DATA = $(EINAHEADERS) | ||
92 | |||
93 | EXTRA_DIST = eina_config.h.in | ||
diff --git a/src/include/eina/eina_accessor.h b/src/include/eina/eina_accessor.h new file mode 100644 index 0000000000..c51c86da6e --- /dev/null +++ b/src/include/eina/eina_accessor.h | |||
@@ -0,0 +1,348 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2008 Cedric Bail | ||
3 | * | ||
4 | * This library is free software; you can redistribute it and/or | ||
5 | * modify it under the terms of the GNU Lesser General Public | ||
6 | * License as published by the Free Software Foundation; either | ||
7 | * version 2.1 of the License, or (at your option) any later version. | ||
8 | * | ||
9 | * This library is distributed in the hope that it will be useful, | ||
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
12 | * Lesser General Public License for more details. | ||
13 | * | ||
14 | * You should have received a copy of the GNU Lesser General Public | ||
15 | * License along with this library; | ||
16 | * if not, see <http://www.gnu.org/licenses/>. | ||
17 | */ | ||
18 | |||
19 | #ifndef EINA_ACCESSOR_H__ | ||
20 | #define EINA_ACCESSOR_H__ | ||
21 | |||
22 | #include "eina_config.h" | ||
23 | |||
24 | #include "eina_types.h" | ||
25 | #include "eina_magic.h" | ||
26 | |||
27 | /** | ||
28 | * @page eina_accessor_example_01_page Eina_Accessor usage | ||
29 | * @dontinclude eina_accessor_01.c | ||
30 | * | ||
31 | * We start by including necessary headers, declaring variables and | ||
32 | * initializing eina: | ||
33 | * @skip #include | ||
34 | * @until eina_init | ||
35 | * | ||
36 | * Next we populate our array and list: | ||
37 | * @until } | ||
38 | * | ||
39 | * Now that we have two containers populated we can actually start the example | ||
40 | * and create an accessor: | ||
41 | * @until accessor_new | ||
42 | * | ||
43 | * Once having the accessor we can use it to access certain elements in the | ||
44 | * container: | ||
45 | * @until } | ||
46 | * @note Unlike iterators accessors allow us non-linear access, which allows us | ||
47 | * to print only the odd elements in the container. | ||
48 | * | ||
49 | * As with every other resource we allocate we need to free the accessor(and the | ||
50 | * array): | ||
51 | * @until array_free | ||
52 | * | ||
53 | * Now we create another accessor, this time for the list: | ||
54 | * @until accessor_new | ||
55 | * | ||
56 | * And now the interesting bit, we use the same code we used above to print | ||
57 | * parts of the array to print parts of the list: | ||
58 | * @until } | ||
59 | * | ||
60 | * And to free the list we use a gimmick, instead of freeing @a list, we ask the | ||
61 | * accessor for it's container and free that: | ||
62 | * @until list_free | ||
63 | * | ||
64 | * Finally we shut eina down and leave: | ||
65 | * @until } | ||
66 | * | ||
67 | * The full source code can be found on the examples folder | ||
68 | * on the @ref eina_accessor_01_c "eina_accessor_01.c" file. | ||
69 | */ | ||
70 | |||
71 | /** | ||
72 | * @page eina_accessor_01_c Eina_Accessor usage example | ||
73 | * | ||
74 | * @include eina_accessor_01.c | ||
75 | * @example eina_accessor_01.c | ||
76 | */ | ||
77 | |||
78 | /** | ||
79 | * @addtogroup Eina_Accessor_Group Accessor Functions | ||
80 | * | ||
81 | * @brief These functions manage accessor on containers. | ||
82 | * | ||
83 | * These functions allow to access elements of a container in a | ||
84 | * generic way, without knowing which container is used (a bit like | ||
85 | * iterators in the C++ STL). Accessors allows random access (that is, any | ||
86 | * element in the container). For sequential access, see | ||
87 | * @ref Eina_Iterator_Group. | ||
88 | * | ||
89 | * Getting an accessor to access elements of a given container is done through | ||
90 | * the functions of that particular container. There is no function to create | ||
91 | * a generic accessor as accessors absolutely depend on the container. This | ||
92 | * means you won't find accessor creation function here, those can be found on | ||
93 | * the documentation of the container type you're using. Though created with | ||
94 | * container specific functions accessors are always deleted with the same | ||
95 | * function: eina_accessor_free(). | ||
96 | * | ||
97 | * To get the data of an element at a given | ||
98 | * position, use eina_accessor_data_get(). To call a function on | ||
99 | * chosen elements of a container, use eina_accessor_over(). | ||
100 | * | ||
101 | * See an example @ref eina_accessor_example_01_page "here". | ||
102 | */ | ||
103 | |||
104 | /** | ||
105 | * @addtogroup Eina_Content_Access_Group Content Access | ||
106 | * | ||
107 | * @{ | ||
108 | */ | ||
109 | |||
110 | /** | ||
111 | * @defgroup Eina_Accessor_Group Accessor Functions | ||
112 | * | ||
113 | * @{ | ||
114 | */ | ||
115 | |||
116 | /** | ||
117 | * @typedef Eina_Accessor | ||
118 | * Abstract type for accessors. | ||
119 | */ | ||
120 | typedef struct _Eina_Accessor Eina_Accessor; | ||
121 | |||
122 | /** | ||
123 | * @typedef Eina_Accessor_Get_At_Callback | ||
124 | * Type for a callback that returns the data of a container as the given index. | ||
125 | */ | ||
126 | typedef Eina_Bool (*Eina_Accessor_Get_At_Callback)(Eina_Accessor *it, | ||
127 | unsigned int idx, | ||
128 | void **data); | ||
129 | |||
130 | /** | ||
131 | * @typedef Eina_Accessor_Get_Container_Callback | ||
132 | * Type for a callback that returns the container. | ||
133 | */ | ||
134 | typedef void *(*Eina_Accessor_Get_Container_Callback)(Eina_Accessor *it); | ||
135 | |||
136 | /** | ||
137 | * @typedef Eina_Accessor_Free_Callback | ||
138 | * Type for a callback that frees the container. | ||
139 | */ | ||
140 | typedef void (*Eina_Accessor_Free_Callback)(Eina_Accessor *it); | ||
141 | |||
142 | /** | ||
143 | * @typedef Eina_Accessor_Lock_Callback | ||
144 | * Type for a callback that lock the container. | ||
145 | */ | ||
146 | typedef Eina_Bool (*Eina_Accessor_Lock_Callback)(Eina_Accessor *it); | ||
147 | |||
148 | /** | ||
149 | * @struct _Eina_Accessor | ||
150 | * Type to provide random access to data structures. | ||
151 | * | ||
152 | * If creating an accessor remember to set the type using @ref EINA_MAGIC_SET. | ||
153 | */ | ||
154 | struct _Eina_Accessor | ||
155 | { | ||
156 | #define EINA_ACCESSOR_VERSION 1 | ||
157 | int version; /**< Version of the Accessor API. */ | ||
158 | |||
159 | Eina_Accessor_Get_At_Callback get_at EINA_ARG_NONNULL(1, 3) EINA_WARN_UNUSED_RESULT; /**< Callback called when a data element is requested. */ | ||
160 | Eina_Accessor_Get_Container_Callback get_container EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is requested. */ | ||
161 | Eina_Accessor_Free_Callback free EINA_ARG_NONNULL(1); /**< Callback called when the container is freed. */ | ||
162 | |||
163 | Eina_Accessor_Lock_Callback lock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is locked. */ | ||
164 | Eina_Accessor_Lock_Callback unlock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is unlocked. */ | ||
165 | |||
166 | #define EINA_MAGIC_ACCESSOR 0x98761232 | ||
167 | EINA_MAGIC | ||
168 | }; | ||
169 | |||
170 | /** | ||
171 | * @def FUNC_ACCESSOR_GET_AT(Function) | ||
172 | * Helper macro to cast @p Function to a Eina_Accessor_Get_At_Callback. | ||
173 | */ | ||
174 | #define FUNC_ACCESSOR_GET_AT(Function) ((Eina_Accessor_Get_At_Callback)Function) | ||
175 | |||
176 | /** | ||
177 | * @def FUNC_ACCESSOR_GET_CONTAINER(Function) | ||
178 | * Helper macro to cast @p Function to a Eina_Accessor_Get_Container_Callback. | ||
179 | */ | ||
180 | #define FUNC_ACCESSOR_GET_CONTAINER(Function) ((Eina_Accessor_Get_Container_Callback)Function) | ||
181 | |||
182 | /** | ||
183 | * @def FUNC_ACCESSOR_FREE(Function) | ||
184 | * Helper macro to cast @p Function to a Eina_Accessor_Free_Callback. | ||
185 | */ | ||
186 | #define FUNC_ACCESSOR_FREE(Function) ((Eina_Accessor_Free_Callback)Function) | ||
187 | |||
188 | /** | ||
189 | * @def FUNC_ACCESSOR_LOCK(Function) | ||
190 | * Helper macro to cast @p Function to a Eina_Iterator_Lock_Callback. | ||
191 | */ | ||
192 | #define FUNC_ACCESSOR_LOCK(Function) ((Eina_Accessor_Lock_Callback)Function) | ||
193 | |||
194 | |||
195 | /** | ||
196 | * @brief Free an accessor. | ||
197 | * | ||
198 | * @param accessor The accessor to free. | ||
199 | * | ||
200 | * This function frees @p accessor if it is not @c NULL; | ||
201 | */ | ||
202 | EAPI void eina_accessor_free(Eina_Accessor *accessor); | ||
203 | |||
204 | /** | ||
205 | * @brief Retrieve the data of an accessor at a given position. | ||
206 | * | ||
207 | * @param accessor The accessor. | ||
208 | * @param position The position of the element. | ||
209 | * @param data The pointer that stores the data to retrieve. | ||
210 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
211 | * | ||
212 | * This function retrieves the data of the element pointed by | ||
213 | * @p accessor at the porition @p position, and stores it in | ||
214 | * @p data. If @p accessor is @c NULL or if an error occurred, #EINA_FALSE | ||
215 | * is returned, otherwise #EINA_TRUE is returned. | ||
216 | */ | ||
217 | EAPI Eina_Bool eina_accessor_data_get(Eina_Accessor *accessor, | ||
218 | unsigned int position, | ||
219 | void **data) EINA_ARG_NONNULL(1); | ||
220 | |||
221 | /** | ||
222 | * @brief Return the container of an accessor. | ||
223 | * | ||
224 | * @param accessor The accessor. | ||
225 | * @return The container which created the accessor. | ||
226 | * | ||
227 | * This function returns the container which created @p accessor. If | ||
228 | * @p accessor is @c NULL, this function returns @c NULL. | ||
229 | */ | ||
230 | EAPI void *eina_accessor_container_get(Eina_Accessor *accessor) EINA_ARG_NONNULL(1) EINA_PURE; | ||
231 | |||
232 | /** | ||
233 | * @brief Iterate over the container and execute a callback on chosen elements. | ||
234 | * | ||
235 | * @param accessor The accessor. | ||
236 | * @param cb The callback called on the chosen elements. | ||
237 | * @param start The position of the first element. | ||
238 | * @param end The position of the last element. | ||
239 | * @param fdata The data passed to the callback. | ||
240 | * | ||
241 | * This function iterates over the elements pointed by @p accessor, | ||
242 | * starting from the element at position @p start and ending to the | ||
243 | * element at position @p end. For Each element, the callback | ||
244 | * @p cb is called with the data @p fdata. If @p accessor is @c NULL | ||
245 | * or if @p start is greter or equal than @p end, the function returns | ||
246 | * immediately. | ||
247 | */ | ||
248 | EAPI void eina_accessor_over(Eina_Accessor *accessor, | ||
249 | Eina_Each_Cb cb, | ||
250 | unsigned int start, | ||
251 | unsigned int end, | ||
252 | const void *fdata) EINA_ARG_NONNULL(2); | ||
253 | |||
254 | /** | ||
255 | * @brief Lock the container of the accessor. | ||
256 | * | ||
257 | * @param accessor The accessor. | ||
258 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
259 | * | ||
260 | * If the container of the @p accessor permits it, it will be locked. When a | ||
261 | * container is locked calling eina_accessor_over() on it will return | ||
262 | * immediately. If @p accessor is @c NULL or if a problem occurred, #EINA_FALSE | ||
263 | * is returned, otherwise #EINA_TRUE is returned. If the container isn't | ||
264 | * lockable, it will return #EINA_TRUE. | ||
265 | * | ||
266 | * @warning None of the existing eina data structures are lockable. | ||
267 | */ | ||
268 | EAPI Eina_Bool eina_accessor_lock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1); | ||
269 | |||
270 | /** | ||
271 | * @brief Unlock the container of the accessor. | ||
272 | * | ||
273 | * @param accessor The accessor. | ||
274 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
275 | * | ||
276 | * If the container of the @p accessor permits it and was previously | ||
277 | * locked, it will be unlocked. If @p accessor is @c NULL or if a | ||
278 | * problem occurred, #EINA_FALSE is returned, otherwise #EINA_TRUE | ||
279 | * is returned. If the container is not lockable, it will | ||
280 | * return #EINA_TRUE. | ||
281 | * | ||
282 | * @warning None of the existing eina data structures are lockable. | ||
283 | */ | ||
284 | EAPI Eina_Bool eina_accessor_unlock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1); | ||
285 | |||
286 | /** | ||
287 | * @def EINA_ACCESSOR_FOREACH | ||
288 | * @brief Macro to iterate over all elements easily. | ||
289 | * | ||
290 | * @param accessor The accessor to use. | ||
291 | * @param counter A counter used by eina_accessor_data_get() when | ||
292 | * iterating over the container. | ||
293 | * @param data Where to store * data, must be a pointer support getting | ||
294 | * its address since * eina_accessor_data_get() requires a pointer to | ||
295 | * pointer! | ||
296 | * | ||
297 | * This macro allows a convenient way to loop over all elements in an | ||
298 | * accessor, very similar to EINA_LIST_FOREACH(). | ||
299 | * | ||
300 | * This macro can be used for freeing the data of a list, like in the | ||
301 | * following example. It has the same goal as the one documented in | ||
302 | * EINA_LIST_FOREACH(), but using accessors: | ||
303 | * | ||
304 | * @code | ||
305 | * Eina_List *list; | ||
306 | * Eina_Accessor *accessor; | ||
307 | * unsigned int i; | ||
308 | * char *data; | ||
309 | * | ||
310 | * // list is already filled, | ||
311 | * // its elements are just duplicated strings | ||
312 | * | ||
313 | * accessor = eina_list_accessor_new(list); | ||
314 | * EINA_ACCESSOR_FOREACH(accessor, i, data) | ||
315 | * free(data); | ||
316 | * eina_accessor_free(accessor); | ||
317 | * eina_list_free(list); | ||
318 | * @endcode | ||
319 | * | ||
320 | * @note if the datatype provides both iterators and accessors prefer | ||
321 | * to use iterators to iterate over, as they're likely to be more | ||
322 | * optimized for such task. | ||
323 | * | ||
324 | * @note this example is not optimal algorithm to release a list since | ||
325 | * it will walk the list twice, but it serves as an example. For | ||
326 | * optimized version use EINA_LIST_FREE() | ||
327 | * | ||
328 | * @warning unless explicitly stated in functions returning accessors, | ||
329 | * do not modify the accessed object while you walk it, in this | ||
330 | * example using lists, do not remove list nodes or you might | ||
331 | * crash! This is not a limitation of accessors themselves, | ||
332 | * rather in the accessors implementations to keep them as simple | ||
333 | * and fast as possible. | ||
334 | */ | ||
335 | #define EINA_ACCESSOR_FOREACH(accessor, counter, data) \ | ||
336 | for ((counter) = 0; \ | ||
337 | eina_accessor_data_get((accessor), (counter), (void **)(void *)&(data)); \ | ||
338 | (counter)++) | ||
339 | |||
340 | /** | ||
341 | * @} | ||
342 | */ | ||
343 | |||
344 | /** | ||
345 | * @} | ||
346 | */ | ||
347 | |||
348 | #endif | ||
diff --git a/src/include/eina/eina_array.h b/src/include/eina/eina_array.h new file mode 100644 index 0000000000..a9f5c7a557 --- /dev/null +++ b/src/include/eina/eina_array.h | |||
@@ -0,0 +1,450 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2008 Cedric Bail | ||
3 | * | ||
4 | * This library is free software; you can redistribute it and/or | ||
5 | * modify it under the terms of the GNU Lesser General Public | ||
6 | * License as published by the Free Software Foundation; either | ||
7 | * version 2.1 of the License, or (at your option) any later version. | ||
8 | * | ||
9 | * This library is distributed in the hope that it will be useful, | ||
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
12 | * Lesser General Public License for more details. | ||
13 | * | ||
14 | * You should have received a copy of the GNU Lesser General Public | ||
15 | * License along with this library; | ||
16 | * if not, see <http://www.gnu.org/licenses/>. | ||
17 | */ | ||
18 | |||
19 | #ifndef EINA_ARRAY_H_ | ||
20 | #define EINA_ARRAY_H_ | ||
21 | |||
22 | #include <stdlib.h> | ||
23 | |||
24 | #include "eina_config.h" | ||
25 | |||
26 | #include "eina_types.h" | ||
27 | #include "eina_error.h" | ||
28 | #include "eina_iterator.h" | ||
29 | #include "eina_accessor.h" | ||
30 | #include "eina_magic.h" | ||
31 | |||
32 | |||
33 | /** | ||
34 | * @page eina_array_01_example_page Basic array usage | ||
35 | * @dontinclude eina_array_01.c | ||
36 | * | ||
37 | * For this example we add stdlib.h, stdio.h and string.h for some | ||
38 | * convenience functions. The first thing to do to be able to use an | ||
39 | * @ref Eina_Array is to include Eina.h: | ||
40 | * @skip #include | ||
41 | * @until Eina.h | ||
42 | * | ||
43 | * Here we have a callback that prints the element given to it: | ||
44 | * @until } | ||
45 | * | ||
46 | * Now we create our entry point and declare some variables, nothing especial: | ||
47 | * @until unsigned | ||
48 | * | ||
49 | * Before we can start using any array function we need to initialize eina: | ||
50 | * @until eina_init | ||
51 | * | ||
52 | * So now to actually creating our array. The only interesting thing here is the | ||
53 | * argument given to the eina_array_new() function, this argument sets how fast | ||
54 | * the array grows. | ||
55 | * @until array_new | ||
56 | * | ||
57 | * If you know before hand how big the array will need to be you should set the | ||
58 | * step to that. In our case we can set it to the number of string we have and | ||
59 | * since we didn't do that in the eina_array_new() we can do it now: | ||
60 | * @until array_step_set | ||
61 | * | ||
62 | * Now let us populate our array with some strings: | ||
63 | * @until push | ||
64 | * @note Notice we use strdup, so we will have to free that memory later on. | ||
65 | * | ||
66 | * Now lets check the size of the array: | ||
67 | * @until printf | ||
68 | * | ||
69 | * And now we call a function on every member of our array to print it: | ||
70 | * @until foreach | ||
71 | * | ||
72 | * One of the strengths of @ref Eina_Array over @ref Eina_List is that it has | ||
73 | * very fast random access to elements, so this is very efficient: | ||
74 | * @until printf | ||
75 | * | ||
76 | * And now we free up the memory allocated with the strdup()s: | ||
77 | * @until free | ||
78 | * | ||
79 | * And the array memory itself: | ||
80 | * @until array_free | ||
81 | * | ||
82 | * And finally shutdown eina and exit: | ||
83 | * @until } | ||
84 | * | ||
85 | * The full source code can be found on the examples folder | ||
86 | * on the @ref eina_array_01_c "eina_array_01.c" file. | ||
87 | */ | ||
88 | |||
89 | /** | ||
90 | * @page eina_array_01_c Basic array usage example | ||
91 | * | ||
92 | * @include eina_array_01.c | ||
93 | * @example eina_array_01.c | ||
94 | */ | ||
95 | |||
96 | /** | ||
97 | * @page eina_array_02_example_page Removing array elements | ||
98 | * @dontinclude eina_array_02.c | ||
99 | * | ||
100 | * Just the usual includes: | ||
101 | * @skip #include | ||
102 | * @until Eina.h | ||
103 | * | ||
104 | * This the callback we are going to use to decide which strings stay on the | ||
105 | * array and which will be removed, we use something simple, but this can be as | ||
106 | * complex as you like: | ||
107 | * @until } | ||
108 | * | ||
109 | * This is the same code we used before to populate the list with the slight | ||
110 | * difference of not using strdup: | ||
111 | * @until array_push | ||
112 | * | ||
113 | * So we have added all our elements to the array, but it turns out that is not | ||
114 | * the elements we wanted, so let's empty the array and add the correct strings: | ||
115 | * @until array_push | ||
116 | * | ||
117 | * It seems we made a little mistake in one of our strings so we need to replace | ||
118 | * it, here is how: | ||
119 | * @until data_set | ||
120 | * | ||
121 | * Now that there is a populated array we can remove elements from it easily: | ||
122 | * @until array_remove | ||
123 | * | ||
124 | * And check that the elements were actually removed: | ||
125 | * @until printf | ||
126 | * | ||
127 | * Since this time we didn't use strdup we don't need to free each string: | ||
128 | * @until } | ||
129 | * | ||
130 | * The full source code can be found on the examples folder | ||
131 | * on the @ref eina_array_02_c "eina_array_02.c" file. | ||
132 | */ | ||
133 | |||
134 | /** | ||
135 | * @page eina_array_02_c Basic array usage example | ||
136 | * | ||
137 | * @include eina_array_02.c | ||
138 | * @example eina_array_02.c | ||
139 | */ | ||
140 | |||
141 | /** | ||
142 | * @addtogroup Eina_Array_Group Array | ||
143 | * | ||
144 | * @brief These functions provide array management. | ||
145 | * | ||
146 | * The Array data type in Eina is designed to have very fast access to | ||
147 | * its data (compared to the Eina @ref Eina_List_Group). On the other hand, | ||
148 | * data can be added or removed only at the end of the array. To insert | ||
149 | * data at any place, the Eina @ref Eina_List_Group is the correct container | ||
150 | * to use. | ||
151 | * | ||
152 | * To use the array data type, eina_init() must be called before any | ||
153 | * other array functions. When no more eina array functions are used, | ||
154 | * eina_shutdown() must be called to free all the resources. | ||
155 | * | ||
156 | * An array must be created with eina_array_new(). It allocates all | ||
157 | * the necessary data for an array. When not needed anymore, an array | ||
158 | * is freed with eina_array_free(). This function does not free any | ||
159 | * allocated memory used to store the data of each element. For that, | ||
160 | * just iterate over the array to free them. A convenient way to do | ||
161 | * that is by using #EINA_ARRAY_ITER_NEXT. An example of code is given | ||
162 | * in the description of this macro. | ||
163 | * | ||
164 | * @warning Functions do not check if the used array is valid or not. It's up to | ||
165 | * the user to be sure of that. It is designed like that for performance | ||
166 | * reasons. | ||
167 | * | ||
168 | * The usual features of an array are classic ones: to append an | ||
169 | * element, use eina_array_push() and to remove the last element, use | ||
170 | * eina_array_pop(). To retrieve the element at a given position, use | ||
171 | * eina_array_data_get(). The number of elements can be retrieved with | ||
172 | * eina_array_count(). | ||
173 | * | ||
174 | * Eina_Array is different from a conventional C array in a number of ways, most | ||
175 | * importantly they grow and shrink dynamically, this means that if you add an | ||
176 | * element to a full array it grows and that when you remove an element from an | ||
177 | * array it @b may shrink. | ||
178 | * | ||
179 | * When the array needs to grow it allocates memory not just for the element | ||
180 | * currently being added since that would mean allocating memory(which is | ||
181 | * computationally expensive) often, instead it grows to be able to hold @p step | ||
182 | * more elements. Similarly if you remove elements in such a way that that the | ||
183 | * array is left holding its capacity - @p step elements it will shrink. | ||
184 | * | ||
185 | * The following image illustrates how an Eina_Array grows: | ||
186 | * | ||
187 | * @image html eina_array-growth.png | ||
188 | * @image latex eina_array-growth.eps width=\textwidth | ||
189 | * | ||
190 | * Eina_Array only stores pointers but it can store data of any type in the form | ||
191 | * of void pointers. | ||
192 | * | ||
193 | * See here some examples: | ||
194 | * @li @ref eina_array_01_example_page | ||
195 | * @li @ref eina_array_02_example_page | ||
196 | */ | ||
197 | |||
198 | /** | ||
199 | * @addtogroup Eina_Data_Types_Group Data Types | ||
200 | * | ||
201 | * @{ | ||
202 | */ | ||
203 | |||
204 | /** | ||
205 | * @addtogroup Eina_Containers_Group Containers | ||
206 | * | ||
207 | * @{ | ||
208 | */ | ||
209 | |||
210 | /** | ||
211 | * @defgroup Eina_Array_Group Array | ||
212 | * | ||
213 | * @{ | ||
214 | */ | ||
215 | |||
216 | /** | ||
217 | * @typedef Eina_Array | ||
218 | * Type for a generic vector. | ||
219 | */ | ||
220 | typedef struct _Eina_Array Eina_Array; | ||
221 | |||
222 | /** | ||
223 | * @typedef Eina_Array_Iterator | ||
224 | * Type for an iterator on arrays, used with #EINA_ARRAY_ITER_NEXT. | ||
225 | */ | ||
226 | typedef void **Eina_Array_Iterator; | ||
227 | |||
228 | /** | ||
229 | * @struct _Eina_Array | ||
230 | * Type for an array of data. | ||
231 | */ | ||
232 | struct _Eina_Array | ||
233 | { | ||
234 | #define EINA_ARRAY_VERSION 1 | ||
235 | int version; /**< Should match EINA_ARRAY_VERSION used when compiled your apps, provided for ABI compatibility */ | ||
236 | |||
237 | void **data; /**< Pointer to a vector of pointer to payload */ | ||
238 | unsigned int total; /**< Total number of slots in the vector */ | ||
239 | unsigned int count; /**< Number of active slots in the vector */ | ||
240 | unsigned int step; /**< How much must we grow the vector when it is full */ | ||
241 | EINA_MAGIC | ||
242 | }; | ||
243 | |||
244 | |||
245 | /** | ||
246 | * @brief Create a new array. | ||
247 | * | ||
248 | * @param step The count of pointers to add when increasing the array size. | ||
249 | * @return @c NULL on failure, non @c NULL otherwise. | ||
250 | * | ||
251 | * This function creates a new array. When adding an element, the array | ||
252 | * allocates @p step elements. When that buffer is full, then adding | ||
253 | * another element will increase the buffer by @p step elements again. | ||
254 | * | ||
255 | * This function return a valid array on success, or @c NULL if memory | ||
256 | * allocation fails. In that case, the error is set | ||
257 | * to #EINA_ERROR_OUT_OF_MEMORY. | ||
258 | */ | ||
259 | EAPI Eina_Array *eina_array_new(unsigned int step) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_WARN_UNUSED_RESULT; | ||
260 | |||
261 | /** | ||
262 | * @brief Free an array. | ||
263 | * | ||
264 | * @param array The array to free. | ||
265 | * | ||
266 | * This function frees @p array. It calls first eina_array_flush() then | ||
267 | * free the memory of the pointer. It does not free the memory | ||
268 | * allocated for the elements of @p array. To free them, | ||
269 | * use #EINA_ARRAY_ITER_NEXT. For performance reasons, there is no check | ||
270 | * of @p array. | ||
271 | */ | ||
272 | EAPI void eina_array_free(Eina_Array *array) EINA_ARG_NONNULL(1); | ||
273 | |||
274 | /** | ||
275 | * @brief Set the step of an array. | ||
276 | * | ||
277 | * @param array The array. | ||
278 | * @param sizeof_eina_array Should be the value returned by sizeof(Eina_Array). | ||
279 | * @param step The count of pointers to add when increasing the array size. | ||
280 | * | ||
281 | * This function sets the step of @p array to @p step. For performance | ||
282 | * reasons, there is no check of @p array. If it is @c NULL or | ||
283 | * invalid, the program may crash. | ||
284 | * | ||
285 | * @warning This function can @b only be called on uninitialized arrays. | ||
286 | */ | ||
287 | EAPI void eina_array_step_set(Eina_Array *array, | ||
288 | unsigned int sizeof_eina_array, | ||
289 | unsigned int step) EINA_ARG_NONNULL(1); | ||
290 | /** | ||
291 | * @brief Clean an array. | ||
292 | * | ||
293 | * @param array The array to clean. | ||
294 | * | ||
295 | * This function sets the count member of @p array to 0, however it doesn't free | ||
296 | * any space. This is particularly useful if you need to empty the array and | ||
297 | * add lots of elements quickly. For performance reasons, there is no check of | ||
298 | * @p array. If it is @c NULL or invalid, the program may crash. | ||
299 | */ | ||
300 | static inline void eina_array_clean(Eina_Array *array) EINA_ARG_NONNULL(1); | ||
301 | |||
302 | /** | ||
303 | * @brief Flush an array. | ||
304 | * | ||
305 | * @param array The array to flush. | ||
306 | * | ||
307 | * This function sets the count and total members of @p array to 0, | ||
308 | * frees and set to NULL its data member. For performance reasons, | ||
309 | * there is no check of @p array. If it is @c NULL or invalid, the | ||
310 | * program may crash. | ||
311 | */ | ||
312 | EAPI void eina_array_flush(Eina_Array *array) EINA_ARG_NONNULL(1); | ||
313 | |||
314 | /** | ||
315 | * @brief Rebuild an array by specifying the data to keep. | ||
316 | * | ||
317 | * @param array The array. | ||
318 | * @param keep The functions which selects the data to keep. | ||
319 | * @param gdata The data to pass to the function keep. | ||
320 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
321 | * | ||
322 | * This function rebuilds @p array be specifying the elements to keep with the | ||
323 | * function @p keep. No empty/invalid fields are left in the array. @p gdata is | ||
324 | * an additional data to pass to @p keep. For performance reasons, there is no | ||
325 | * check of @p array. If it is @c NULL or invalid, the program may crash. | ||
326 | * | ||
327 | * If it wasn't able to remove items due to an allocation failure, it will | ||
328 | * return #EINA_FALSE and the error is set to #EINA_ERROR_OUT_OF_MEMORY. | ||
329 | */ | ||
330 | EAPI Eina_Bool eina_array_remove(Eina_Array * array, | ||
331 | Eina_Bool (*keep)(void *data, void *gdata), | ||
332 | void *gdata) EINA_ARG_NONNULL(1, 2); | ||
333 | static inline Eina_Bool eina_array_push(Eina_Array *array, | ||
334 | const void *data) EINA_ARG_NONNULL(1, 2); | ||
335 | static inline void *eina_array_pop(Eina_Array *array) EINA_ARG_NONNULL(1); | ||
336 | static inline void *eina_array_data_get(const Eina_Array *array, | ||
337 | unsigned int idx) EINA_ARG_NONNULL(1); | ||
338 | /** | ||
339 | * @brief Set the data at a given position in an array. | ||
340 | * | ||
341 | * @param array The array. | ||
342 | * @param idx The position of the data to set. | ||
343 | * @param data The data to set. | ||
344 | * | ||
345 | * This function sets the data at the position @p idx in @p | ||
346 | * array to @p data, this effectively replaces the previously held data, you | ||
347 | * must therefore get a pointer to it first if you need to free it. For | ||
348 | * performance reasons, there is no check of @p array or @p idx. If it is @c | ||
349 | * NULL or invalid, the program may crash. | ||
350 | */ | ||
351 | static inline void eina_array_data_set(const Eina_Array *array, | ||
352 | unsigned int idx, | ||
353 | const void *data) EINA_ARG_NONNULL(1); | ||
354 | static inline unsigned int eina_array_count_get(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
355 | static inline unsigned int eina_array_count(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
356 | |||
357 | /** | ||
358 | * @brief Returned a new iterator associated to an array. | ||
359 | * | ||
360 | * @param array The array. | ||
361 | * @return A new iterator. | ||
362 | * | ||
363 | * This function returns a newly allocated iterator associated to | ||
364 | * @p array. If @p array is @c NULL or the count member of @p array is | ||
365 | * less or equal than 0, this function returns @c NULL. If the memory can | ||
366 | * not be allocated, NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is | ||
367 | * set. Otherwise, a valid iterator is returned. | ||
368 | */ | ||
369 | EAPI Eina_Iterator *eina_array_iterator_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
370 | |||
371 | /** | ||
372 | * @brief Returned a new accessor associated to an array. | ||
373 | * | ||
374 | * @param array The array. | ||
375 | * @return A new accessor. | ||
376 | * | ||
377 | * This function returns a newly allocated accessor associated to | ||
378 | * @p array. If @p array is @c NULL or the count member of @p array is | ||
379 | * less or equal than 0, this function returns @c NULL. If the memory can | ||
380 | * not be allocated, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is | ||
381 | * set. Otherwise, a valid accessor is returned. | ||
382 | */ | ||
383 | EAPI Eina_Accessor *eina_array_accessor_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
384 | /** | ||
385 | * @brief Provide a safe way to iterate over an array | ||
386 | * | ||
387 | * @param array The array to iterate over. | ||
388 | * @param cb The callback to call for each item. | ||
389 | * @param fdata The user data to pass to the callback. | ||
390 | * @return #EINA_TRUE if it successfully iterate all items of the array. | ||
391 | * | ||
392 | * This function provide a safe way to iterate over an array. @p cb should | ||
393 | * return #EINA_TRUE as long as you want the function to continue iterating, | ||
394 | * by returning #EINA_FALSE it will stop and return #EINA_FALSE as a result. | ||
395 | */ | ||
396 | static inline Eina_Bool eina_array_foreach(Eina_Array *array, | ||
397 | Eina_Each_Cb cb, | ||
398 | void *fdata); | ||
399 | /** | ||
400 | * @def EINA_ARRAY_ITER_NEXT | ||
401 | * @brief Macro to iterate over an array easily. | ||
402 | * | ||
403 | * @param array The array to iterate over. | ||
404 | * @param index The integer number that is increased while iterating. | ||
405 | * @param item The data | ||
406 | * @param iterator The iterator | ||
407 | * | ||
408 | * This macro allows the iteration over @p array in an easy way. It | ||
409 | * iterates from the first element to the last one. @p index is an | ||
410 | * integer that increases from 0 to the number of elements. @p item is | ||
411 | * the data of each element of @p array, so it is a pointer to a type | ||
412 | * chosen by the user. @p iterator is of type #Eina_Array_Iterator. | ||
413 | * | ||
414 | * This macro can be used for freeing the data of an array, like in | ||
415 | * the following example: | ||
416 | * | ||
417 | * @code | ||
418 | * Eina_Array *array; | ||
419 | * char *item; | ||
420 | * Eina_Array_Iterator iterator; | ||
421 | * unsigned int i; | ||
422 | * | ||
423 | * // array is already filled, | ||
424 | * // its elements are just duplicated strings, | ||
425 | * // EINA_ARRAY_ITER_NEXT will be used to free those strings | ||
426 | * | ||
427 | * EINA_ARRAY_ITER_NEXT(array, i, item, iterator) | ||
428 | * free(item); | ||
429 | * @endcode | ||
430 | */ | ||
431 | #define EINA_ARRAY_ITER_NEXT(array, index, item, iterator) \ | ||
432 | for (index = 0, iterator = (array)->data; \ | ||
433 | (index < eina_array_count(array)) && ((item = *((iterator)++))); \ | ||
434 | ++(index)) | ||
435 | |||
436 | #include "eina_inline_array.x" | ||
437 | |||
438 | /** | ||
439 | * @} | ||
440 | */ | ||
441 | |||
442 | /** | ||
443 | * @} | ||
444 | */ | ||
445 | |||
446 | /** | ||
447 | * @} | ||
448 | */ | ||
449 | |||
450 | #endif | ||
diff --git a/src/include/eina/eina_benchmark.h b/src/include/eina/eina_benchmark.h new file mode 100644 index 0000000000..a95aadf14e --- /dev/null +++ b/src/include/eina/eina_benchmark.h | |||
@@ -0,0 +1,453 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2008 Cedric Bail | ||
3 | * | ||
4 | * This library is free software; you can redistribute it and/or | ||
5 | * modify it under the terms of the GNU Lesser General Public | ||
6 | * License as published by the Free Software Foundation; either | ||
7 | * version 2.1 of the License, or (at your option) any later version. | ||
8 | * | ||
9 | * This library is distributed in the hope that it will be useful, | ||
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
12 | * Lesser General Public License for more details. | ||
13 | * | ||
14 | * You should have received a copy of the GNU Lesser General Public | ||
15 | * License along with this library; | ||
16 | * if not, see <http://www.gnu.org/licenses/>. | ||
17 | */ | ||
18 | |||
19 | #ifndef EINA_BENCHMARK_H_ | ||
20 | #define EINA_BENCHMARK_H_ | ||
21 | |||
22 | #include "eina_array.h" | ||
23 | |||
24 | |||
25 | |||
26 | /** | ||
27 | * @page tutorial_benchmark_page Benchmark Tutorial | ||
28 | * | ||
29 | * The Benchmark module allows you to write easily benchmarks | ||
30 | * framework in a project for timing critical part and detect slow | ||
31 | * parts of code. In addition it automatically creates data files of | ||
32 | * these benchmark, as well as a gnuplot file which can display the | ||
33 | * comparison curves of the benchmarks. | ||
34 | * | ||
35 | * @section tutorial_benchmark_basic_usage Basic Usage | ||
36 | * | ||
37 | * To create a basic benchmark, you have to follow these steps: | ||
38 | * | ||
39 | * @li Create a new benchmark | ||
40 | * @li Write the functions that wraps the functions you want to | ||
41 | * benchmark. | ||
42 | * @li Register these wrappers functions. | ||
43 | * @li Run the benchmark. | ||
44 | * @li Free the memory. | ||
45 | * | ||
46 | * Here is a basic example of benchmark which creates two functions | ||
47 | * that will be run. These functions just print a message. | ||
48 | * | ||
49 | * @code | ||
50 | * #include <stdlib.h> | ||
51 | * #include <stdio.h> | ||
52 | * | ||
53 | * #include <Eina.h> | ||
54 | * | ||
55 | * static | ||
56 | * void work1(int request) | ||
57 | * { | ||
58 | * printf ("work1 in progress... Request: %d\n", request); | ||
59 | * } | ||
60 | * | ||
61 | * static | ||
62 | * void work2(int request) | ||
63 | * { | ||
64 | * printf ("work2 in progress... Request: %d\n", request); | ||
65 | * } | ||
66 | * | ||
67 | * int main() | ||
68 | * { | ||
69 | * Eina_Benchmark *test; | ||
70 | * Eina_Array *ea; | ||
71 | * | ||
72 | * if (!eina_init()) | ||
73 | * return EXIT_FAILURE; | ||
74 | * | ||
75 | * test = eina_benchmark_new("test", "run"); | ||
76 | * if (!test) | ||
77 | * goto shutdown_eina; | ||
78 | * | ||
79 | * eina_benchmark_register(test, "work-1", EINA_BENCHMARK(work1), 200, 300, 10); | ||
80 | * eina_benchmark_register(test, "work-2", EINA_BENCHMARK(work2), 100, 150, 5); | ||
81 | * | ||
82 | * ea = eina_benchmark_run(test); | ||
83 | * | ||
84 | * eina_benchmark_free(test); | ||
85 | * eina_shutdown(); | ||
86 | * | ||
87 | * return EXIT_SUCCESS; | ||
88 | * | ||
89 | * shutdown_eina: | ||
90 | * eina_shutdown(); | ||
91 | * | ||
92 | * return EXIT_FAILURE; | ||
93 | * } | ||
94 | * @endcode | ||
95 | * | ||
96 | * As "test", "run" are passed to eina_benchmark_new() and as the tests | ||
97 | * "work-1" and "work-2" are registered, the data files | ||
98 | * bench_test_run.work-1.data and bench_test_run.work-2.data will be | ||
99 | * created after the eina_benchmark_run() call. They contain four | ||
100 | * columns. The file bench_test_run.work-1.data contains for example: | ||
101 | * | ||
102 | * @code | ||
103 | * # specimen experiment time starting time ending time | ||
104 | * 200 23632 2852446 2876078 | ||
105 | * 210 6924 2883046 2889970 | ||
106 | * 220 6467 2895962 2902429 | ||
107 | * 230 6508 2908271 2914779 | ||
108 | * 240 6278 2920610 2926888 | ||
109 | * 250 6342 2932830 2939172 | ||
110 | * 260 6252 2944954 2951206 | ||
111 | * 270 6463 2956978 2963441 | ||
112 | * 280 6347 2969548 2975895 | ||
113 | * 290 6457 2981702 2988159 | ||
114 | * @endcode | ||
115 | * | ||
116 | * The first column (specimen) is the integer passed to the work1() | ||
117 | * function when the test is run. The second column (experiment time) | ||
118 | * is the time, in nanosecond, that work1() takes. The third and | ||
119 | * fourth columnd are self-explicit. | ||
120 | * | ||
121 | * You can see that the integer passed work1() starts from 200 and | ||
122 | * finishes at 290, with a step of 10. These values are computed withe | ||
123 | * last 3 values passed to eina_benchmark_register(). See the document | ||
124 | * of that function for the detailed behavior. | ||
125 | * | ||
126 | * The gnuplot file will be named bench_test_run.gnuplot. Just run: | ||
127 | * | ||
128 | * @code | ||
129 | * gnuplot bench_test_run.gnuplot | ||
130 | * @endcode | ||
131 | * | ||
132 | * to create the graphic of the comparison curves. The image file is | ||
133 | * named output_test_run.png. | ||
134 | * | ||
135 | * @section tutorial_benchmark_advanced_usage More Advanced Usage | ||
136 | * | ||
137 | * In this section, several test will be created and run. The idea is | ||
138 | * exactly the same than in the previous section, but with some basic | ||
139 | * automatic way to run all the benchmarks. The following code | ||
140 | * benchmarks some Eina converts functions, and some Eina containers | ||
141 | * types: | ||
142 | * | ||
143 | * @code | ||
144 | * #include <stdlib.h> | ||
145 | * #include <stdio.h> | ||
146 | * #include <time.h> | ||
147 | * | ||
148 | * #include <Eina.h> | ||
149 | * | ||
150 | * static void bench_convert(Eina_Benchmark *bench); | ||
151 | * static void bench_container(Eina_Benchmark *bench); | ||
152 | * | ||
153 | * typedef struct _Benchmark_Case Benchmark_Case; | ||
154 | * | ||
155 | * struct _Benchmark_Case | ||
156 | * { | ||
157 | * const char *bench_case; | ||
158 | * void (*build)(Eina_Benchmark *bench); | ||
159 | * }; | ||
160 | * | ||
161 | * static const Benchmark_Case benchmarks[] = { | ||
162 | * { "Bench 1", bench_convert }, | ||
163 | * { "Bench 2", bench_container }, | ||
164 | * { NULL, NULL } | ||
165 | * }; | ||
166 | * | ||
167 | * static | ||
168 | * void convert1(int request) | ||
169 | * { | ||
170 | * char tmp[128]; | ||
171 | * int i; | ||
172 | * | ||
173 | * srand(time(NULL)); | ||
174 | * | ||
175 | * for (i = 0; i < request; ++i) | ||
176 | * eina_convert_itoa(rand(), tmp); | ||
177 | * } | ||
178 | * | ||
179 | * static | ||
180 | * void convert2(int request) | ||
181 | * { | ||
182 | * char tmp[128]; | ||
183 | * int i; | ||
184 | * | ||
185 | * srand(time(NULL)); | ||
186 | * | ||
187 | * for (i = 0; i < request; ++i) | ||
188 | * eina_convert_xtoa(rand(), tmp); | ||
189 | * } | ||
190 | * | ||
191 | * static void | ||
192 | * bench_convert(Eina_Benchmark *bench) | ||
193 | * { | ||
194 | * eina_benchmark_register(bench, "convert-1", EINA_BENCHMARK(convert1), 200, 400, 10); | ||
195 | * eina_benchmark_register(bench, "convert-2", EINA_BENCHMARK(convert2), 200, 400, 10); | ||
196 | * } | ||
197 | * | ||
198 | * static | ||
199 | * void array(int request) | ||
200 | * { | ||
201 | * Eina_Array *array; | ||
202 | * Eina_Array_Iterator it; | ||
203 | * int *data; | ||
204 | * int i; | ||
205 | * | ||
206 | * srand(time(NULL)); | ||
207 | * | ||
208 | * array = eina_array_new(64); | ||
209 | * | ||
210 | * for (i = 0; i < request; ++i) | ||
211 | * { | ||
212 | * data = (int *)malloc(sizeof(int)); | ||
213 | * if (!data) continue; | ||
214 | * *data = rand(); | ||
215 | * eina_array_push(array, data); | ||
216 | * } | ||
217 | * | ||
218 | * EINA_ARRAY_ITER_NEXT(array, i, data, it) | ||
219 | * free(data); | ||
220 | * | ||
221 | * eina_array_free(array); | ||
222 | * } | ||
223 | * | ||
224 | * static | ||
225 | * void list(int request) | ||
226 | * { | ||
227 | * Eina_List *l = NULL; | ||
228 | * int *data; | ||
229 | * int i; | ||
230 | * | ||
231 | * srand(time(NULL)); | ||
232 | * | ||
233 | * for (i = 0; i < request; ++i) | ||
234 | * { | ||
235 | * data = (int *)malloc(sizeof(int)); | ||
236 | * if (!data) continue; | ||
237 | * *data = rand(); | ||
238 | * l = eina_list_prepend(l, data); | ||
239 | * } | ||
240 | * | ||
241 | * while (l) | ||
242 | * { | ||
243 | * free(eina_list_data_get(l)); | ||
244 | * l = eina_list_remove_list(l, l); | ||
245 | * } | ||
246 | * } | ||
247 | * | ||
248 | * static void | ||
249 | * bench_container(Eina_Benchmark *bench) | ||
250 | * { | ||
251 | * eina_benchmark_register(bench, "array", EINA_BENCHMARK(array), 200, 300, 10); | ||
252 | * eina_benchmark_register(bench, "list", EINA_BENCHMARK(list), 200, 300, 10); | ||
253 | * } | ||
254 | * | ||
255 | * int main() | ||
256 | * { | ||
257 | * Eina_Benchmark *test; | ||
258 | * Eina_Array *ea; | ||
259 | * unsigned int i; | ||
260 | * | ||
261 | * if (!eina_init()) | ||
262 | * return EXIT_FAILURE; | ||
263 | * | ||
264 | * for (i = 0; benchmarks[i].bench_case != NULL; ++i) | ||
265 | * { | ||
266 | * test = eina_benchmark_new(benchmarks[i].bench_case, "Benchmark example"); | ||
267 | * if (!test) | ||
268 | * continue; | ||
269 | * | ||
270 | * benchmarks[i].build(test); | ||
271 | * | ||
272 | * ea = eina_benchmark_run(test); | ||
273 | * | ||
274 | * eina_benchmark_free(test); | ||
275 | * } | ||
276 | * | ||
277 | * eina_shutdown(); | ||
278 | * | ||
279 | * return EXIT_SUCCESS; | ||
280 | * } | ||
281 | * @endcode | ||
282 | * | ||
283 | * gnuplot can be used to see how are performed the convert functions | ||
284 | * together, as well as how are performed the containers. So it is now | ||
285 | * easy to see that the hexadecimal convert function is faster than | ||
286 | * the decimal one, and that arrays are faster than lists. | ||
287 | * | ||
288 | * You can improve all that by executing automatically gnuplot in your | ||
289 | * program, or integrate the Eina benchmark framework in an autotooled | ||
290 | * project. See that | ||
291 | * <a href="http://trac.enlightenment.org/e/wiki/AutotoolsIntegration#Benchmark">page</a> | ||
292 | * for more informations. | ||
293 | * | ||
294 | */ | ||
295 | |||
296 | |||
297 | /** | ||
298 | * @addtogroup Eina_Benchmark_Group Benchmark | ||
299 | * | ||
300 | * These functions allow you to add benchmark framework in a project | ||
301 | * for timing critical part and detect slow parts of code. It is used | ||
302 | * in Eina to compare the time used by eina, glib, evas and ecore data | ||
303 | * types. | ||
304 | * | ||
305 | * To use the benchmark module, Eina must be initialized with | ||
306 | * eina_init() and later shut down with eina_shutdown(). A benchmark | ||
307 | * is created with eina_benchmark_new() and freed with | ||
308 | * eina_benchmark_free(). | ||
309 | * | ||
310 | * eina_benchmark_register() adds a test to a benchmark. That test can | ||
311 | * be run a certain amount of times. Adding more than one test to be | ||
312 | * executed allows the comparison between several parts of a program, | ||
313 | * or different implementations. | ||
314 | * | ||
315 | * eina_benchmark_run() runs all the tests registered with | ||
316 | * eina_benchmark_register(). The amount of time of each test is | ||
317 | * written in a gnuplot file. | ||
318 | * | ||
319 | * For more information, you can look at the @ref tutorial_benchmark_page. | ||
320 | */ | ||
321 | |||
322 | /** | ||
323 | * @addtogroup Eina_Tools_Group Tools | ||
324 | * | ||
325 | * @{ | ||
326 | */ | ||
327 | |||
328 | /** | ||
329 | * @defgroup Eina_Benchmark_Group Benchmark | ||
330 | * | ||
331 | * @{ | ||
332 | */ | ||
333 | |||
334 | /** | ||
335 | * @typedef Eina_Benchmark | ||
336 | * Type for a benchmark. | ||
337 | */ | ||
338 | typedef struct _Eina_Benchmark Eina_Benchmark; | ||
339 | |||
340 | /** | ||
341 | * @typedef Eina_Benchmark_Specimens | ||
342 | * Type for a test function to be called when running a benchmark. | ||
343 | */ | ||
344 | typedef void (*Eina_Benchmark_Specimens)(int request); | ||
345 | |||
346 | /** | ||
347 | * @def EINA_BENCHMARK | ||
348 | * @brief cast to an #Eina_Benchmark_Specimens. | ||
349 | * | ||
350 | * @param function The function to cast. | ||
351 | * | ||
352 | * This macro casts @p function to Eina_Benchmark_Specimens. | ||
353 | */ | ||
354 | #define EINA_BENCHMARK(function) ((Eina_Benchmark_Specimens)function) | ||
355 | |||
356 | |||
357 | /** | ||
358 | * @brief Create a new array. | ||
359 | * | ||
360 | * @param name The name of the benchmark. | ||
361 | * @param run The name of the run. | ||
362 | * @return @c NULL on failure, non @c NULL otherwise. | ||
363 | * | ||
364 | * This function creates a new benchmark. @p name and @p run are used | ||
365 | * to name the gnuplot file that eina_benchmark_run() will create. | ||
366 | * | ||
367 | * This function return a valid benchmark on success, or @c NULL if | ||
368 | * memory allocation fails. In that case, the error is set | ||
369 | * to #EINA_ERROR_OUT_OF_MEMORY. | ||
370 | * | ||
371 | * When the new module is not needed anymore, use | ||
372 | * eina_benchmark_free() to free the allocated memory. | ||
373 | */ | ||
374 | EAPI Eina_Benchmark *eina_benchmark_new(const char *name, | ||
375 | const char *run); | ||
376 | |||
377 | /** | ||
378 | * @brief Free a benchmark object. | ||
379 | * | ||
380 | * @param bench The benchmark to free. | ||
381 | * | ||
382 | * This function removes all the benchmark tests that have been | ||
383 | * registered and frees @p bench. If @p bench is @c NULL, this | ||
384 | * function returns immediately. | ||
385 | */ | ||
386 | EAPI void eina_benchmark_free(Eina_Benchmark *bench); | ||
387 | |||
388 | /** | ||
389 | * @brief Add a test to a benchmark. | ||
390 | * | ||
391 | * @param bench The benchmark. | ||
392 | * @param name The name of the test. | ||
393 | * @param bench_cb The test function to be called. | ||
394 | * @param count_start The start data to be passed to @p bench_cb. | ||
395 | * @param count_end The end data to be passed to @p bench_cb. | ||
396 | * @param count_step The step data to be passed to @p bench_cb. | ||
397 | * @return #EINA_FALSE on failure, #EINA_TRUE otherwise. | ||
398 | * | ||
399 | * This function adds the test named @p name to @p benchmark. @p | ||
400 | * bench_cb is the function called when the test is executed. That | ||
401 | * test can be executed a certain amount of time. @p count_start, @p count_end and | ||
402 | * @p count_step define a loop with a step increment. The integer that is | ||
403 | * increasing by @p count_step from @p count_start to @p count_end is passed to @p | ||
404 | * bench_cb when eina_benchmark_run() is called. | ||
405 | * | ||
406 | * If @p bench is @c NULL, this function returns immediately. If the | ||
407 | * allocation of the memory of the test to add fails, the error is set | ||
408 | * to #EINA_ERROR_OUT_OF_MEMORY. This function returns #EINA_FALSE | ||
409 | * on failure, #EINA_TRUE otherwise. | ||
410 | */ | ||
411 | EAPI Eina_Bool eina_benchmark_register(Eina_Benchmark *bench, | ||
412 | const char *name, | ||
413 | Eina_Benchmark_Specimens bench_cb, | ||
414 | int count_start, | ||
415 | int count_end, | ||
416 | int count_step); | ||
417 | |||
418 | /** | ||
419 | * @brief Run the benchmark tests that have been registered. | ||
420 | * | ||
421 | * @param bench The benchmark. | ||
422 | * @return The list of names of the test files. | ||
423 | * | ||
424 | * This function runs all the tests that as been registered with | ||
425 | * eina_benchmark_register() and save the result in a gnuplot | ||
426 | * file. The name of the file has the following format: | ||
427 | * | ||
428 | * @code | ||
429 | * bench_[name]_[run]%s.gnuplot | ||
430 | * @endcode | ||
431 | * | ||
432 | * where [name] and [run] are the values passed to | ||
433 | * eina_benchmark_new(). | ||
434 | * | ||
435 | * Each registered test is executed and timed. The time is written to | ||
436 | * the gnuplot file. The number of times each test is executed is | ||
437 | * controlled by the parameters passed to eina_benchmark_register(). | ||
438 | * | ||
439 | * If @p bench is @c NULL, this functions returns @c NULL | ||
440 | * immediately. Otherwise, it returns the list of the names of each | ||
441 | * test. | ||
442 | */ | ||
443 | EAPI Eina_Array *eina_benchmark_run(Eina_Benchmark *bench); | ||
444 | |||
445 | /** | ||
446 | * @} | ||
447 | */ | ||
448 | |||
449 | /** | ||
450 | * @} | ||
451 | */ | ||
452 | |||
453 | #endif /* EINA_BENCHMARK_H_ */ | ||
diff --git a/src/include/eina/eina_binbuf.h b/src/include/eina/eina_binbuf.h new file mode 100644 index 0000000000..c28df05af4 --- /dev/null +++ b/src/include/eina/eina_binbuf.h | |||
@@ -0,0 +1,235 @@ | |||
1 | #ifndef EINA_BINBUF_H | ||
2 | #define EINA_BINBUF_H | ||
3 | |||
4 | #include <stddef.h> | ||
5 | #include <stdarg.h> | ||
6 | |||
7 | #include "eina_types.h" | ||
8 | |||
9 | /** | ||
10 | * @addtogroup Eina_Binary_Buffer_Group Binary Buffer | ||
11 | * | ||
12 | * @brief These functions provide string buffers management. | ||
13 | * | ||
14 | * The Binary Buffer data type is designed to be a mutable string, | ||
15 | * allowing to append, prepend or insert a string to a buffer. | ||
16 | */ | ||
17 | |||
18 | /** | ||
19 | * @addtogroup Eina_Data_Types_Group Data Types | ||
20 | * | ||
21 | * @{ | ||
22 | */ | ||
23 | |||
24 | /** | ||
25 | * @defgroup Eina_Binary_Buffer_Group Binary Buffer | ||
26 | * | ||
27 | * @{ | ||
28 | */ | ||
29 | |||
30 | /** | ||
31 | * @typedef Eina_Binbuf | ||
32 | * Type for a string buffer. | ||
33 | */ | ||
34 | typedef struct _Eina_Strbuf Eina_Binbuf; | ||
35 | |||
36 | /** | ||
37 | * @brief Create a new string buffer. | ||
38 | * | ||
39 | * @return Newly allocated string buffer instance. | ||
40 | * | ||
41 | * This function creates a new string buffer. On error, @c NULL is | ||
42 | * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To | ||
43 | * free the resources, use eina_binbuf_free(). | ||
44 | * | ||
45 | * @see eina_binbuf_free() | ||
46 | * @see eina_binbuf_append() | ||
47 | * @see eina_binbuf_string_get() | ||
48 | */ | ||
49 | EAPI Eina_Binbuf *eina_binbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT; | ||
50 | |||
51 | /** | ||
52 | * @brief Create a new string buffer using the passed string. The passed | ||
53 | * string is used directly as the buffer, it's somehow the opposite function of | ||
54 | * @ref eina_binbuf_string_steal . The passed string must be malloced. | ||
55 | * | ||
56 | * @param str the string to manage | ||
57 | * @param length the length of the string. | ||
58 | * @return Newly allocated string buffer instance. | ||
59 | * | ||
60 | * This function creates a new string buffer. On error, @c NULL is | ||
61 | * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To | ||
62 | * free the resources, use eina_binbuf_free(). | ||
63 | * | ||
64 | * @see eina_binbuf_manage_new() | ||
65 | * @since 1.2.0 | ||
66 | */ | ||
67 | EAPI Eina_Binbuf *eina_binbuf_manage_new_length(unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT; | ||
68 | |||
69 | /** | ||
70 | * @brief Free a string buffer. | ||
71 | * | ||
72 | * @param buf The string buffer to free. | ||
73 | * | ||
74 | * This function frees the memory of @p buf. @p buf must have been | ||
75 | * created by eina_binbuf_new(). | ||
76 | */ | ||
77 | EAPI void eina_binbuf_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1); | ||
78 | |||
79 | /** | ||
80 | * @brief Reset a string buffer. | ||
81 | * | ||
82 | * @param buf The string buffer to reset. | ||
83 | * | ||
84 | * This function reset @p buf: the buffer len is set to 0, and the | ||
85 | * string is set to '\\0'. No memory is free'd. | ||
86 | */ | ||
87 | EAPI void eina_binbuf_reset(Eina_Binbuf *buf) EINA_ARG_NONNULL(1); | ||
88 | |||
89 | /** | ||
90 | * @brief Append a string of exact length to a buffer, reallocating as necessary. | ||
91 | * | ||
92 | * @param buf The string buffer to append to. | ||
93 | * @param str The string to append. | ||
94 | * @param length The exact length to use. | ||
95 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
96 | * | ||
97 | * This function appends @p str to @p buf. @p str must be of size at | ||
98 | * most @p length. It is slightly faster than eina_binbuf_append() as | ||
99 | * it does not compute the size of @p str. It is useful when dealing | ||
100 | * with strings of known size, such as eina_strngshare. If @p buf | ||
101 | * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is | ||
102 | * returned. | ||
103 | * | ||
104 | * @see eina_stringshare_length() | ||
105 | * @see eina_binbuf_append() | ||
106 | * @see eina_binbuf_append_n() | ||
107 | */ | ||
108 | EAPI Eina_Bool eina_binbuf_append_length(Eina_Binbuf *buf, const unsigned char *str, size_t length) EINA_ARG_NONNULL(1, 2); | ||
109 | |||
110 | /** | ||
111 | * @brief Append a character to a string buffer, reallocating as | ||
112 | * necessary. | ||
113 | * | ||
114 | * @param buf The string buffer to append to. | ||
115 | * @param c The char to append. | ||
116 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
117 | * | ||
118 | * This function inserts @p c to @p buf. If it can not insert it, #EINA_FALSE | ||
119 | * is returned, otherwise #EINA_TRUE is returned. | ||
120 | */ | ||
121 | EAPI Eina_Bool eina_binbuf_append_char(Eina_Binbuf *buf, unsigned char c) EINA_ARG_NONNULL(1); | ||
122 | |||
123 | /** | ||
124 | * @brief Insert a string of exact length to a buffer, reallocating as necessary. | ||
125 | * | ||
126 | * @param buf The string buffer to insert to. | ||
127 | * @param str The string to insert. | ||
128 | * @param length The exact length to use. | ||
129 | * @param pos The position to insert the string. | ||
130 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
131 | * | ||
132 | * This function inserts @p str to @p buf. @p str must be of size at | ||
133 | * most @p length. It is slightly faster than eina_binbuf_insert() as | ||
134 | * it does not compute the size of @p str. It is useful when dealing | ||
135 | * with strings of known size, such as eina_strngshare. If @p buf | ||
136 | * can't insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is | ||
137 | * returned. | ||
138 | * | ||
139 | * @see eina_stringshare_length() | ||
140 | * @see eina_binbuf_insert() | ||
141 | * @see eina_binbuf_insert_n() | ||
142 | */ | ||
143 | EAPI Eina_Bool eina_binbuf_insert_length(Eina_Binbuf *buf, const unsigned char *str, size_t length, size_t pos) EINA_ARG_NONNULL(1, 2); | ||
144 | |||
145 | /** | ||
146 | * @brief Insert a character to a string buffer, reallocating as | ||
147 | * necessary. | ||
148 | * | ||
149 | * @param buf The string buffer to insert to. | ||
150 | * @param c The char to insert. | ||
151 | * @param pos The position to insert the char. | ||
152 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
153 | * | ||
154 | * This function inserts @p c to @p buf at position @p pos. If @p buf | ||
155 | * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is | ||
156 | * returned. | ||
157 | */ | ||
158 | EAPI Eina_Bool eina_binbuf_insert_char(Eina_Binbuf *buf, unsigned char c, size_t pos) EINA_ARG_NONNULL(1); | ||
159 | |||
160 | /** | ||
161 | * @brief Remove a slice of the given string buffer. | ||
162 | * | ||
163 | * @param buf The string buffer to remove a slice. | ||
164 | * @param start The initial (inclusive) slice position to start | ||
165 | * removing, in bytes. | ||
166 | * @param end The final (non-inclusive) slice position to finish | ||
167 | * removing, in bytes. | ||
168 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
169 | * | ||
170 | * This function removes a slice of @p buf, starting at @p start | ||
171 | * (inclusive) and ending at @p end (non-inclusive). Both values are | ||
172 | * in bytes. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise. | ||
173 | */ | ||
174 | |||
175 | EAPI Eina_Bool eina_binbuf_remove(Eina_Binbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1); | ||
176 | |||
177 | /** | ||
178 | * @brief Retrieve a pointer to the contents of a string buffer | ||
179 | * | ||
180 | * @param buf The string buffer. | ||
181 | * @return The current string in the string buffer. | ||
182 | * | ||
183 | * This function returns the string contained in @p buf. The returned | ||
184 | * value must not be modified and will no longer be valid if @p buf is | ||
185 | * modified. In other words, any eina_binbuf_append() or similar will | ||
186 | * make that pointer invalid. | ||
187 | * | ||
188 | * @see eina_binbuf_string_steal() | ||
189 | */ | ||
190 | EAPI const unsigned char *eina_binbuf_string_get(const Eina_Binbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
191 | |||
192 | /** | ||
193 | * @brief Steal the contents of a string buffer. | ||
194 | * | ||
195 | * @param buf The string buffer to steal. | ||
196 | * @return The current string in the string buffer. | ||
197 | * | ||
198 | * This function returns the string contained in @p buf. @p buf is | ||
199 | * then initialized and does not own the returned string anymore. The | ||
200 | * caller must release the memory of the returned string by calling | ||
201 | * free(). | ||
202 | * | ||
203 | * @see eina_binbuf_string_get() | ||
204 | */ | ||
205 | EAPI unsigned char *eina_binbuf_string_steal(Eina_Binbuf *buf) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); | ||
206 | |||
207 | /** | ||
208 | * @brief Free the contents of a string buffer but not the buffer. | ||
209 | * | ||
210 | * @param buf The string buffer to free the string of. | ||
211 | * | ||
212 | * This function frees the string contained in @p buf without freeing | ||
213 | * @p buf. | ||
214 | */ | ||
215 | EAPI void eina_binbuf_string_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1); | ||
216 | |||
217 | /** | ||
218 | * @brief Retrieve the length of the string buffer content. | ||
219 | * | ||
220 | * @param buf The string buffer. | ||
221 | * @return The current length of the string, in bytes. | ||
222 | * | ||
223 | * This function returns the length of @p buf. | ||
224 | */ | ||
225 | EAPI size_t eina_binbuf_length_get(const Eina_Binbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
226 | |||
227 | /** | ||
228 | * @} | ||
229 | */ | ||
230 | |||
231 | /** | ||
232 | * @} | ||
233 | */ | ||
234 | |||
235 | #endif /* EINA_STRBUF_H */ | ||
diff --git a/src/include/eina/eina_binshare.h b/src/include/eina/eina_binshare.h new file mode 100644 index 0000000000..5a4488d940 --- /dev/null +++ b/src/include/eina/eina_binshare.h | |||
@@ -0,0 +1,193 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2002-2008 Carsten Haitzler, Jorge Luis Zapata Muga, Cedric Bail | ||
3 | * | ||
4 | * This library is free software; you can redistribute it and/or | ||
5 | * modify it under the terms of the GNU Lesser General Public | ||
6 | * License as published by the Free Software Foundation; either | ||
7 | * version 2.1 of the License, or (at your option) any later version. | ||
8 | * | ||
9 | * This library is distributed in the hope that it will be useful, | ||
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
12 | * Lesser General Public License for more details. | ||
13 | * | ||
14 | * You should have received a copy of the GNU Lesser General Public | ||
15 | * License along with this library; | ||
16 | * if not, see <http://www.gnu.org/licenses/>. | ||
17 | * | ||
18 | * This file incorporates work covered by the following copyright and | ||
19 | * permission notice: | ||
20 | * | ||
21 | * Copyright (C) 2008 Peter Wehrfritz | ||
22 | * | ||
23 | * Permission is hereby granted, free of charge, to any person obtaining a copy | ||
24 | * of this software and associated documentation files (the "Software"), to | ||
25 | * deal in the Software without restriction, including without limitation the | ||
26 | * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or | ||
27 | * sell copies of the Software, and to permit persons to whom the Software is | ||
28 | * furnished to do so, subject to the following conditions: | ||
29 | * | ||
30 | * The above copyright notice and this permission notice shall be included in | ||
31 | * all copies of the Software and its Copyright notices. In addition publicly | ||
32 | * documented acknowledgment must be given that this software has been used if no | ||
33 | * source code of this software is made available publicly. This includes | ||
34 | * acknowledgments in either Copyright notices, Manuals, Publicity and Marketing | ||
35 | * documents or any documentation provided with any product containing this | ||
36 | * software. This License does not apply to any software that links to the | ||
37 | * libraries provided by this software (statically or dynamically), but only to | ||
38 | * the software provided. | ||
39 | * | ||
40 | * Please see the OLD-COPYING.PLAIN for a plain-english explanation of this notice | ||
41 | * and it's intent. | ||
42 | * | ||
43 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | ||
44 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | ||
45 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL | ||
46 | * THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER | ||
47 | * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN | ||
48 | * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. | ||
49 | */ | ||
50 | |||
51 | #ifndef EINA_BINSHARE_H_ | ||
52 | #define EINA_BINSHARE_H_ | ||
53 | |||
54 | #include "eina_types.h" | ||
55 | |||
56 | /** | ||
57 | * @page tutorial_binshare_page Binary Share Tutorial | ||
58 | * | ||
59 | * Should call eina_binshare_init() before usage and eina_binshare_shutdown() after. | ||
60 | * to be written... | ||
61 | * | ||
62 | */ | ||
63 | |||
64 | /** | ||
65 | * @addtogroup Eina_Binshare_Group Binary Share | ||
66 | * | ||
67 | * These functions allow you to store one copy of an object, and use it | ||
68 | * throughout your program. | ||
69 | * | ||
70 | * This is a method to reduce the number of duplicated objects kept in | ||
71 | * memory. | ||
72 | * | ||
73 | * For more information, you can look at the @ref tutorial_binshare_page. | ||
74 | */ | ||
75 | |||
76 | /** | ||
77 | * @addtogroup Eina_Data_Types_Group Data Types | ||
78 | * | ||
79 | * @{ | ||
80 | */ | ||
81 | |||
82 | /** | ||
83 | * @defgroup Eina_Binshare_Group Binary Share | ||
84 | * | ||
85 | * @{ | ||
86 | */ | ||
87 | |||
88 | |||
89 | /** | ||
90 | * @brief Retrieve an instance of an object for use in a program. | ||
91 | * | ||
92 | * @param obj The binary object to retrieve an instance of. | ||
93 | * @param olen The byte size | ||
94 | * @return A pointer to an instance of the object on success. | ||
95 | * @c NULL on failure. | ||
96 | * | ||
97 | * This function retrieves an instance of @p obj. If @p obj is | ||
98 | * @c NULL, then @c NULL is returned. If @p obj is already stored, it | ||
99 | * is just returned and its reference counter is increased. Otherwise | ||
100 | * it is added to the objects to be searched and a duplicated object | ||
101 | * of @p obj is returned. | ||
102 | * | ||
103 | * This function does not check object size, but uses the | ||
104 | * exact given size. This can be used to share part of a larger | ||
105 | * object or subobject. | ||
106 | * | ||
107 | * @see eina_binshare_add() | ||
108 | */ | ||
109 | EAPI const void *eina_binshare_add_length(const void *obj, | ||
110 | unsigned int olen) EINA_PURE EINA_WARN_UNUSED_RESULT; | ||
111 | |||
112 | /** | ||
113 | * Increment references of the given shared object. | ||
114 | * | ||
115 | * @param obj The shared object. | ||
116 | * @return A pointer to an instance of the object on success. | ||
117 | * @c NULL on failure. | ||
118 | * | ||
119 | * This is similar to eina_share_common_add(), but it's faster since it will | ||
120 | * avoid lookups if possible, but on the down side it requires the parameter | ||
121 | * to be shared before, in other words, it must be the return of a previous | ||
122 | * eina_binshare_add(). | ||
123 | * | ||
124 | * There is no unref since this is the work of eina_binshare_del(). | ||
125 | */ | ||
126 | EAPI const void *eina_binshare_ref(const void *obj); | ||
127 | |||
128 | /** | ||
129 | * @brief Note that the given object has lost an instance. | ||
130 | * | ||
131 | * @param obj object The given object. | ||
132 | * | ||
133 | * This function decreases the reference counter associated to @p obj | ||
134 | * if it exists. If that counter reaches 0, the memory associated to | ||
135 | * @p obj is freed. If @p obj is @c NULL, the function returns | ||
136 | * immediately. | ||
137 | * | ||
138 | * @note If the given pointer is not shared, bad things will happen, likely a | ||
139 | * segmentation fault. | ||
140 | */ | ||
141 | EAPI void eina_binshare_del(const void *obj); | ||
142 | |||
143 | /** | ||
144 | * @brief Note that the given object @b must be shared. | ||
145 | * | ||
146 | * @param obj the shared object to know the length. It is safe to | ||
147 | * give @c NULL, in that case @c -1 is returned. | ||
148 | * @return The length of the shared object. | ||
149 | * | ||
150 | * This function is a cheap way to known the length of a shared | ||
151 | * object. | ||
152 | * @note If the given pointer is not shared, bad things will happen, likely a | ||
153 | * segmentation fault. If in doubt, try strlen(). | ||
154 | */ | ||
155 | EAPI int eina_binshare_length(const void *obj) EINA_WARN_UNUSED_RESULT; | ||
156 | |||
157 | /** | ||
158 | * @brief Dump the contents of the share_common. | ||
159 | * | ||
160 | * This function dumps all objects in the share_common to stdout with a | ||
161 | * DDD: prefix per line and a memory usage summary. | ||
162 | */ | ||
163 | EAPI void eina_binshare_dump(void); | ||
164 | |||
165 | /** | ||
166 | * @brief Retrieve an instance of a blob for use in a program. | ||
167 | * | ||
168 | * @param ptr The binary blob to retrieve an instance of. | ||
169 | * @return A pointer to an instance of the string on success. | ||
170 | * @c NULL on failure. | ||
171 | * | ||
172 | * This macro retrieves an instance of @p obj. If @p obj is | ||
173 | * @c NULL, then @c NULL is returned. If @p obj is already stored, it | ||
174 | * is just returned and its reference counter is increased. Otherwise | ||
175 | * it is added to the blobs to be searched and a duplicated blob | ||
176 | * of @p obj is returned. | ||
177 | * | ||
178 | * This macro essentially calls eina_binshare_add_length with ptr and sizeof(*ptr) | ||
179 | * as the parameters. It's useful for pointers to structures. | ||
180 | * | ||
181 | * @see eina_stringshare_add_length() | ||
182 | */ | ||
183 | #define eina_binshare_add(ptr) eina_binshare_add_length(ptr, sizeof(*ptr)) | ||
184 | |||
185 | /** | ||
186 | * @} | ||
187 | */ | ||
188 | |||
189 | /** | ||
190 | * @} | ||
191 | */ | ||
192 | |||
193 | #endif /* EINA_STRINGSHARE_H_ */ | ||
diff --git a/src/include/eina/eina_clist.h b/src/include/eina/eina_clist.h new file mode 100644 index 0000000000..4e7f63a614 --- /dev/null +++ b/src/include/eina/eina_clist.h | |||
@@ -0,0 +1,439 @@ | |||
1 | /* | ||
2 | * Linked lists support | ||
3 | * | ||
4 | * Copyright (C) 2002 Alexandre Julliard | ||
5 | * Copyright (C) 2011 Mike McCormack (adapted for Eina) | ||
6 | * | ||
7 | * This library is free software; you can redistribute it and/or | ||
8 | * modify it under the terms of the GNU Lesser General Public | ||
9 | * License as published by the Free Software Foundation; either | ||
10 | * version 2.1 of the License, or (at your option) any later version. | ||
11 | * | ||
12 | * This library is distributed in the hope that it will be useful, | ||
13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
15 | * Lesser General Public License for more details. | ||
16 | * | ||
17 | * You should have received a copy of the GNU Lesser General Public | ||
18 | * License along with this library; if not, write to the Free Software | ||
19 | * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA | ||
20 | */ | ||
21 | |||
22 | #ifndef __EINA_CLIST_H__ | ||
23 | #define __EINA_CLIST_H__ | ||
24 | |||
25 | /** | ||
26 | * @addtogroup Eina_Data_Types_Group Data Types | ||
27 | * | ||
28 | * @{ | ||
29 | */ | ||
30 | |||
31 | /** | ||
32 | * @addtogroup Eina_Containers_Group Containers | ||
33 | * | ||
34 | * @{ | ||
35 | */ | ||
36 | |||
37 | /** | ||
38 | * @defgroup Eina_CList_Group Compact List | ||
39 | * | ||
40 | * @{ | ||
41 | * | ||
42 | * @brief Eina_Clist is a compact (inline) list implementation | ||
43 | * | ||
44 | * Elements of this list are members of the structs stored in the list | ||
45 | * | ||
46 | * Advantages over @ref Eina_List and @ref Eina_Inlist : | ||
47 | * - uses less memory (two machine words per item) | ||
48 | * - allows removing items without knowing which list they're in using O(1) time | ||
49 | * - no need to keep updating the head pointer as the list is changed | ||
50 | * | ||
51 | * Disadvantages: | ||
52 | * - O(N) time to calculate list length | ||
53 | * - requires one list entry in a struct per list (i.e. it's an inlist) | ||
54 | * - requires a head/tail pointer | ||
55 | * - need to know the list head when moving to next or previous pointer | ||
56 | * | ||
57 | * @note There's no NULL at the end of the list, the last item points to the head. | ||
58 | * | ||
59 | * @note List heads must be initialized with EINA_CLIST_INIT or by calling eina_clist_element_init | ||
60 | * | ||
61 | * Define a list like so: | ||
62 | * | ||
63 | * @code | ||
64 | * struct gadget | ||
65 | * { | ||
66 | * struct Eina_Clist entry; <-- doesn't have to be the first item in the struct | ||
67 | * int a, b; | ||
68 | * }; | ||
69 | * | ||
70 | * static Eina_Clist global_gadgets = EINA_CLIST_INIT( global_gadgets ); | ||
71 | * @endcode | ||
72 | * | ||
73 | * or | ||
74 | * | ||
75 | * @code | ||
76 | * struct some_global_thing | ||
77 | * { | ||
78 | * Eina_Clist gadgets; | ||
79 | * }; | ||
80 | * | ||
81 | * eina_clist_init( &some_global_thing->gadgets ); | ||
82 | * @endcode | ||
83 | * | ||
84 | * Manipulate it like this: | ||
85 | * | ||
86 | * @code | ||
87 | * eina_clist_add_head( &global_gadgets, &new_gadget->entry ); | ||
88 | * eina_clist_remove( &new_gadget->entry ); | ||
89 | * eina_clist_add_after( &some_random_gadget->entry, &new_gadget->entry ); | ||
90 | * @endcode | ||
91 | * | ||
92 | * And to iterate over it: | ||
93 | * | ||
94 | * @code | ||
95 | * struct gadget *gadget; | ||
96 | * EINA_CLIST_FOR_EACH_ENTRY( gadget, &global_gadgets, struct gadget, entry ) | ||
97 | * { | ||
98 | * ... | ||
99 | * } | ||
100 | * @endcode | ||
101 | * | ||
102 | */ | ||
103 | |||
104 | /** | ||
105 | * @typedef Eina_Clist | ||
106 | * This is the list head and the list entry. | ||
107 | * @since 1.1.0 | ||
108 | */ | ||
109 | typedef struct _Eina_Clist Eina_Clist; | ||
110 | |||
111 | /** | ||
112 | * @struct _Eina_Clist | ||
113 | * Compact list type | ||
114 | * @note This structure is used as both the list head and the list entry. | ||
115 | * @since 1.1.0 | ||
116 | */ | ||
117 | struct _Eina_Clist | ||
118 | { | ||
119 | Eina_Clist *next; | ||
120 | Eina_Clist *prev; | ||
121 | }; | ||
122 | |||
123 | /** | ||
124 | * Add an element after the specified one. | ||
125 | * | ||
126 | * @param elem An element in the list | ||
127 | * @param to_add The element to add to the list | ||
128 | * @pre The list head must be initialized once before adding anything. | ||
129 | * @pre The element is not in any list. | ||
130 | * | ||
131 | * @note There's no need to initialize an element before adding it to the list. | ||
132 | * @since 1.1.0 | ||
133 | */ | ||
134 | static inline void eina_clist_add_after(Eina_Clist *elem, Eina_Clist *to_add); | ||
135 | |||
136 | /** | ||
137 | * Add an element before the specified one. | ||
138 | * | ||
139 | * @param elem An element in the list | ||
140 | * @param to_add The element to add to the list | ||
141 | * @pre The list head must be initialized once before adding anything. | ||
142 | * @pre The element is not in any list. | ||
143 | * | ||
144 | * @note There's no need to initialize an element before adding it to the list. | ||
145 | * @since 1.1.0 | ||
146 | */ | ||
147 | static inline void eina_clist_add_before(Eina_Clist *elem, Eina_Clist *to_add); | ||
148 | |||
149 | /** | ||
150 | * Add element at the head of the list. | ||
151 | * | ||
152 | * @param list The list | ||
153 | * @param elem An element | ||
154 | * @pre The list head must be initialized once before adding anything. | ||
155 | * @pre The element is not in any list. | ||
156 | * | ||
157 | * @note There's no need to initialize an element before adding it to the list. | ||
158 | * @since 1.1.0 | ||
159 | */ | ||
160 | static inline void eina_clist_add_head(Eina_Clist *list, Eina_Clist *elem); | ||
161 | |||
162 | /** | ||
163 | * Add element at the tail of the list. | ||
164 | * | ||
165 | * @param list The list | ||
166 | * @param elem An element | ||
167 | * @pre The list head must be initialized once before adding anything. | ||
168 | * @pre The element is not in any list. | ||
169 | * | ||
170 | * @note There's no need to initialize an element before adding it to the list. | ||
171 | * @since 1.1.0 | ||
172 | */ | ||
173 | static inline void eina_clist_add_tail(Eina_Clist *list, Eina_Clist *elem); | ||
174 | |||
175 | /** | ||
176 | * Init an (unlinked) element. | ||
177 | * | ||
178 | * Call this function on elements that have not been added to the list | ||
179 | * if you want eina_clist_element_init() to work correctly | ||
180 | * | ||
181 | * @param elem An element | ||
182 | * @pre The element is not in any list. | ||
183 | * @post The element is marked as not being in any list | ||
184 | * | ||
185 | * @note It is not necessary to call this before adding an element to this list. | ||
186 | * @since 1.1.0 | ||
187 | */ | ||
188 | static inline void eina_clist_element_init(Eina_Clist *elem); | ||
189 | |||
190 | /** | ||
191 | * Check if an element is in a list or not. | ||
192 | * | ||
193 | * @param elem An element | ||
194 | * | ||
195 | * @pre Either eina_clist_element_init() has been called on @a elem, | ||
196 | * it has been added to a list or remove from a list. | ||
197 | * @since 1.1.0 | ||
198 | */ | ||
199 | static inline int eina_clist_element_is_linked(Eina_Clist *elem); | ||
200 | |||
201 | /** | ||
202 | * Remove an element from its list. | ||
203 | * | ||
204 | * @param elem An element | ||
205 | * @pre The element is in a list already | ||
206 | * @post The element is marked as not being in any list | ||
207 | * @since 1.1.0 | ||
208 | */ | ||
209 | static inline void eina_clist_remove(Eina_Clist *elem); | ||
210 | |||
211 | /** | ||
212 | * Get the next element. | ||
213 | * | ||
214 | * @param list The list | ||
215 | * @param elem An element | ||
216 | * @pre @a elem is in @a list | ||
217 | * @return The element after @a elem in @a list or @c NULL if @a elem is last in @a list. | ||
218 | * @since 1.1.0 | ||
219 | */ | ||
220 | static inline Eina_Clist *eina_clist_next(const Eina_Clist *list, const Eina_Clist *elem); | ||
221 | |||
222 | /** | ||
223 | * Get the previous element. | ||
224 | * | ||
225 | * @param list The list | ||
226 | * @param elem An element | ||
227 | * | ||
228 | * @return The element before @a elem or @c NULL if @a elem is the first in the list. | ||
229 | * @since 1.1.0 | ||
230 | */ | ||
231 | static inline Eina_Clist *eina_clist_prev(const Eina_Clist *list, const Eina_Clist *elem); | ||
232 | |||
233 | /** | ||
234 | * Get the first element. | ||
235 | * | ||
236 | * @param list The list | ||
237 | * @returns The first element in @a list or @c NULL if @a list is empty. | ||
238 | * @since 1.1.0 | ||
239 | */ | ||
240 | static inline Eina_Clist *eina_clist_head(const Eina_Clist *list); | ||
241 | |||
242 | /** | ||
243 | * Get the last element. | ||
244 | * | ||
245 | * @param list The list | ||
246 | * @returns The last element in @a list or @c NULL if @a list is empty. | ||
247 | * @since 1.1.0 | ||
248 | */ | ||
249 | static inline Eina_Clist *eina_clist_tail(const Eina_Clist *list); | ||
250 | |||
251 | /** | ||
252 | * Check if a list is empty. | ||
253 | * | ||
254 | * @param list The list | ||
255 | * @returns non-zero if @a list is empty, zero if it is not | ||
256 | * @since 1.1.0 | ||
257 | */ | ||
258 | static inline int eina_clist_empty(const Eina_Clist *list); | ||
259 | |||
260 | /** | ||
261 | * Initialize a list | ||
262 | * | ||
263 | * @param list The list | ||
264 | * @pre The list is uninitialized | ||
265 | * @post The list contains no items | ||
266 | * | ||
267 | * @note Don't call this function on a list with items | ||
268 | * @note This function must be called. Don't try do | ||
269 | * initialize the list by zero'ing out the list head. | ||
270 | * @since 1.1.0 | ||
271 | */ | ||
272 | static inline void eina_clist_init(Eina_Clist *list); | ||
273 | |||
274 | /** | ||
275 | * Count the elements of a list | ||
276 | * | ||
277 | * @param list The list | ||
278 | * @returns The number of items in the list | ||
279 | * @since 1.1.0 | ||
280 | */ | ||
281 | static inline unsigned int eina_clist_count(const Eina_Clist *list); | ||
282 | |||
283 | /** | ||
284 | * Move all elements from src to the tail of dst | ||
285 | * | ||
286 | * @param dst List to be appended to | ||
287 | * @param src List to append | ||
288 | * | ||
289 | * @post @a src is initialized but empty after this operation | ||
290 | * @since 1.1.0 | ||
291 | */ | ||
292 | static inline void eina_clist_move_tail(Eina_Clist *dst, Eina_Clist *src); | ||
293 | |||
294 | /** | ||
295 | * move all elements from src to the head of dst | ||
296 | * | ||
297 | * @param dst List to be prepended to | ||
298 | * @param src List to prepend | ||
299 | * | ||
300 | * @post @a src is initialized but empty after this operation | ||
301 | * @since 1.1.0 | ||
302 | */ | ||
303 | static inline void eina_clist_move_head(Eina_Clist *dst, Eina_Clist *src); | ||
304 | |||
305 | /** | ||
306 | * @def EINA_CLIST_FOR_EACH | ||
307 | * @brief Iterate through the list. | ||
308 | * @param cursor The pointer to be used during the interation. | ||
309 | * @param list The list to be interated. | ||
310 | */ | ||
311 | #define EINA_CLIST_FOR_EACH(cursor,list) \ | ||
312 | for ((cursor) = (list)->next; (cursor) != (list); (cursor) = (cursor)->next) | ||
313 | |||
314 | /** | ||
315 | * @def EINA_CLIST_FOR_EACH_SAFE | ||
316 | * @brief Iterate through the list, with safety against removal. | ||
317 | * @param cursor The pointer to be used during the interation. | ||
318 | * @param cursor2 The auxiliar pointer to be used during the interation. | ||
319 | * @param list The list to be interated. | ||
320 | */ | ||
321 | #define EINA_CLIST_FOR_EACH_SAFE(cursor, cursor2, list) \ | ||
322 | for ((cursor) = (list)->next, (cursor2) = (cursor)->next; \ | ||
323 | (cursor) != (list); \ | ||
324 | (cursor) = (cursor2), (cursor2) = (cursor)->next) | ||
325 | |||
326 | /** | ||
327 | * @def EINA_CLIST_FOR_EACH_ENTRY | ||
328 | * @brief Iterate through the list using a list entry. | ||
329 | * @param elem The element to be used. | ||
330 | * @param list The list to be iterated. | ||
331 | * @param type The type of the list. | ||
332 | * @param field The field of the element. | ||
333 | */ | ||
334 | #define EINA_CLIST_FOR_EACH_ENTRY(elem, list, type, field) \ | ||
335 | for ((elem) = EINA_CLIST_ENTRY((list)->next, type, field); \ | ||
336 | &(elem)->field != (list); \ | ||
337 | (elem) = EINA_CLIST_ENTRY((elem)->field.next, type, field)) | ||
338 | |||
339 | /** | ||
340 | * @def EINA_CLIST_FOR_EACH_ENTRY_SAFE | ||
341 | * @brief Iterate through the list using a list entry, with safety against removal. | ||
342 | * @param cursor The pointer to be used during the interation. | ||
343 | * @param cursor2 The auxiliar pointer to be used during the interation. | ||
344 | * @param list The list to be interated. | ||
345 | * @param type The type of the list. | ||
346 | * @param field The field of the element. | ||
347 | */ | ||
348 | #define EINA_CLIST_FOR_EACH_ENTRY_SAFE(cursor, cursor2, list, type, field) \ | ||
349 | for ((cursor) = EINA_CLIST_ENTRY((list)->next, type, field), \ | ||
350 | (cursor2) = EINA_CLIST_ENTRY((cursor)->field.next, type, field); \ | ||
351 | &(cursor)->field != (list); \ | ||
352 | (cursor) = (cursor2), \ | ||
353 | (cursor2) = EINA_CLIST_ENTRY((cursor)->field.next, type, field)) | ||
354 | |||
355 | /** | ||
356 | * @def EINA_CLIST_FOR_EACH_REV | ||
357 | * @brief Iterate through the list in reverse order. | ||
358 | * @param cursor The pointer to be used during the interation. | ||
359 | * @param list The list to be interated. | ||
360 | */ | ||
361 | #define EINA_CLIST_FOR_EACH_REV(cursor,list) \ | ||
362 | for ((cursor) = (list)->prev; (cursor) != (list); (cursor) = (cursor)->prev) | ||
363 | |||
364 | /** | ||
365 | * @def EINA_CLIST_FOR_EACH_SAFE_REV | ||
366 | * @brief Iterate through the list in reverse order, with safety against removal. | ||
367 | * @param cursor The pointer to be used during the interation. | ||
368 | * @param cursor2 The auxiliar pointer to be used during the interation. | ||
369 | * @param list The list to be interated. | ||
370 | */ | ||
371 | #define EINA_CLIST_FOR_EACH_SAFE_REV(cursor, cursor2, list) \ | ||
372 | for ((cursor) = (list)->prev, (cursor2) = (cursor)->prev; \ | ||
373 | (cursor) != (list); \ | ||
374 | (cursor) = (cursor2), (cursor2) = (cursor)->prev) | ||
375 | |||
376 | /** | ||
377 | * @def EINA_CLIST_FOR_EACH_ENTRY_REV | ||
378 | * @brief Iterate through the list in reverse order using a list entry. | ||
379 | * @param elem The element to be used. | ||
380 | * @param list The list to be iterated. | ||
381 | * @param type The type of the list. | ||
382 | * @param field The field of the element. | ||
383 | */ | ||
384 | #define EINA_CLIST_FOR_EACH_ENTRY_REV(elem, list, type, field) \ | ||
385 | for ((elem) = EINA_CLIST_ENTRY((list)->prev, type, field); \ | ||
386 | &(elem)->field != (list); \ | ||
387 | (elem) = EINA_CLIST_ENTRY((elem)->field.prev, type, field)) | ||
388 | |||
389 | /** | ||
390 | * @def EINA_CLIST_FOR_EACH_ENTRY_SAFE_REV | ||
391 | * @brief Iterate through the list in reverse order using a list entry, with safety against | ||
392 | * removal. | ||
393 | * @param cursor The pointer to be used during the interation. | ||
394 | * @param cursor2 The auxiliar pointer to be used during the interation. | ||
395 | * @param list The list to be interated. | ||
396 | * @param type The type of the list. | ||
397 | * @param field The field of the element. | ||
398 | */ | ||
399 | #define EINA_CLIST_FOR_EACH_ENTRY_SAFE_REV(cursor, cursor2, list, type, field) \ | ||
400 | for ((cursor) = EINA_CLIST_ENTRY((list)->prev, type, field), \ | ||
401 | (cursor2) = EINA_CLIST_ENTRY((cursor)->field.prev, type, field); \ | ||
402 | &(cursor)->field != (list); \ | ||
403 | (cursor) = (cursor2), \ | ||
404 | (cursor2) = EINA_CLIST_ENTRY((cursor)->field.prev, type, field)) | ||
405 | |||
406 | /** | ||
407 | * @def EINA_CLIST_INIT | ||
408 | * @brief Macros for statically initialized lists. | ||
409 | * @param list The list to be used. | ||
410 | */ | ||
411 | #undef EINA_CLIST_INIT | ||
412 | #define EINA_CLIST_INIT(list) { &(list), &(list) } | ||
413 | |||
414 | /** | ||
415 | * @def EINA_CLIST_ENTRY | ||
416 | * @brief Get pointer to object containing list element. | ||
417 | * @param elem The element to be used. | ||
418 | * @param type The type of the element. | ||
419 | * @param field The field of the element. | ||
420 | */ | ||
421 | #undef EINA_CLIST_ENTRY | ||
422 | #define EINA_CLIST_ENTRY(elem, type, field) \ | ||
423 | ((type *)((char *)(elem) - (unsigned long)(&((type *)0)->field))) | ||
424 | |||
425 | #include "eina_inline_clist.x" | ||
426 | |||
427 | /** | ||
428 | * @} | ||
429 | */ | ||
430 | |||
431 | /** | ||
432 | * @} | ||
433 | */ | ||
434 | |||
435 | /** | ||
436 | * @} | ||
437 | */ | ||
438 | |||
439 | #endif /* __EINA_CLIST_H__ */ | ||
diff --git a/src/include/eina/eina_config.h.in b/src/include/eina/eina_config.h.in new file mode 100644 index 0000000000..937d208208 --- /dev/null +++ b/src/include/eina/eina_config.h.in | |||
@@ -0,0 +1,86 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2008 Cedric Bail | ||
3 | * | ||
4 | * This library is free software; you can redistribute it and/or | ||
5 | * modify it under the terms of the GNU Lesser General Public | ||
6 | * License as published by the Free Software Foundation; either | ||
7 | * version 2.1 of the License, or (at your option) any later version. | ||
8 | * | ||
9 | * This library is distributed in the hope that it will be useful, | ||
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
12 | * Lesser General Public License for more details. | ||
13 | * | ||
14 | * You should have received a copy of the GNU Lesser General Public | ||
15 | * License along with this library; | ||
16 | * if not, see <http://www.gnu.org/licenses/>. | ||
17 | */ | ||
18 | |||
19 | #ifndef EINA_CONFIG_H_ | ||
20 | #define EINA_CONFIG_H_ | ||
21 | |||
22 | #ifdef EINA_HAVE_EXOTIC_H | ||
23 | # undef EINA_HAVE_EXOTIC_H | ||
24 | #endif | ||
25 | @EINA_CONFIGURE_HAVE_EXOTIC@ | ||
26 | |||
27 | #ifdef EINA_HAVE_EXOTIC | ||
28 | # include <Exotic.h> | ||
29 | #endif | ||
30 | |||
31 | #ifdef EINA_MAGIC_DEBUG | ||
32 | # undef EINA_MAGIC_DEBUG | ||
33 | #endif | ||
34 | @EINA_CONFIGURE_MAGIC_DEBUG@ | ||
35 | |||
36 | #ifdef EINA_DEFAULT_MEMPOOL | ||
37 | # undef EINA_DEFAULT_MEMPOOL | ||
38 | #endif | ||
39 | @EINA_CONFIGURE_DEFAULT_MEMPOOL@ | ||
40 | |||
41 | #ifdef EINA_SAFETY_CHECKS | ||
42 | # undef EINA_SAFETY_CHECKS | ||
43 | #endif | ||
44 | @EINA_CONFIGURE_SAFETY_CHECKS@ | ||
45 | |||
46 | #ifdef EINA_HAVE_INTTYPES_H | ||
47 | # undef EINA_HAVE_INTTYPES_H | ||
48 | #endif | ||
49 | @EINA_CONFIGURE_HAVE_INTTYPES_H@ | ||
50 | |||
51 | #ifdef EINA_HAVE_STDINT_H | ||
52 | # undef EINA_HAVE_STDINT_H | ||
53 | #endif | ||
54 | @EINA_CONFIGURE_HAVE_STDINT_H@ | ||
55 | |||
56 | #ifdef EINA_HAVE_THREADS | ||
57 | # undef EINA_HAVE_THREADS | ||
58 | #endif | ||
59 | @EINA_CONFIGURE_HAVE_THREADS@ | ||
60 | |||
61 | #ifdef EINA_HAVE_DEBUG_THREADS | ||
62 | # undef EINA_HAVE_DEBUG_THREADS | ||
63 | #endif | ||
64 | @EINA_CONFIGURE_HAVE_DEBUG_THREADS@ | ||
65 | |||
66 | #ifdef EINA_SIZEOF_WCHAR_T | ||
67 | # undef EINA_SIZEOF_WCHAR_T | ||
68 | #endif | ||
69 | #define EINA_SIZEOF_WCHAR_T @EINA_SIZEOF_WCHAR_T@ | ||
70 | |||
71 | #ifdef EINA_HAVE_ON_OFF_THREADS | ||
72 | # undef EINA_HAVE_ON_OFF_THREADS | ||
73 | #endif | ||
74 | @EINA_CONFIGURE_HAVE_ON_OFF_THREADS@ | ||
75 | |||
76 | #ifdef EINA_CONFIGURE_HAVE_DIRENT_H | ||
77 | # undef EINA_CONFIGURE_HAVE_DIRENT_H | ||
78 | #endif | ||
79 | @EINA_CONFIGURE_HAVE_DIRENT_H@ | ||
80 | |||
81 | #ifdef EINA_CONFIGURE_ENABLE_LOG | ||
82 | # undef EINA_CONFIGURE_ENABLE_LOG | ||
83 | #endif | ||
84 | @EINA_CONFIGURE_ENABLE_LOG@ | ||
85 | |||
86 | #endif /* EINA_CONFIG_H_ */ | ||
diff --git a/src/include/eina/eina_convert.h b/src/include/eina/eina_convert.h new file mode 100644 index 0000000000..6493964a2f --- /dev/null +++ b/src/include/eina/eina_convert.h | |||
@@ -0,0 +1,374 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2008 Cedric BAIL, Vincent Torri | ||
3 | * | ||
4 | * This library is free software; you can redistribute it and/or | ||
5 | * modify it under the terms of the GNU Lesser General Public | ||
6 | * License as published by the Free Software Foundation; either | ||
7 | * version 2.1 of the License, or (at your option) any later version. | ||
8 | * | ||
9 | * This library is distributed in the hope that it will be useful, | ||
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
12 | * Lesser General Public License for more details. | ||
13 | * | ||
14 | * You should have received a copy of the GNU Lesser General Public | ||
15 | * License along with this library; | ||
16 | * if not, see <http://www.gnu.org/licenses/>. | ||
17 | */ | ||
18 | |||
19 | #ifndef EINA_CONVERT_H_ | ||
20 | #define EINA_CONVERT_H_ | ||
21 | |||
22 | #include "eina_types.h" | ||
23 | #include "eina_error.h" | ||
24 | |||
25 | #include "eina_fp.h" | ||
26 | |||
27 | |||
28 | /** | ||
29 | * @addtogroup Eina_Convert_Group Convert | ||
30 | * | ||
31 | * These functions allow you to convert integer or real numbers to | ||
32 | * string or conversely. | ||
33 | * | ||
34 | * To use these functions, you have to call eina_init() | ||
35 | * first, and eina_shutdown() when eina is not used anymore. | ||
36 | * | ||
37 | * @section Eina_Convert_From_Integer_To_Sring Conversion from integer to string | ||
38 | * | ||
39 | * To convert an integer to a string in the decimal base, | ||
40 | * eina_convert_itoa() should be used. If the hexadecimal base is | ||
41 | * wanted, eina_convert_xtoa() should be used. They all need a buffer | ||
42 | * sufficiently large to store all the cyphers. | ||
43 | * | ||
44 | * Here is an example of use: | ||
45 | * | ||
46 | * @code | ||
47 | * #include <stdlib.h> | ||
48 | * #include <stdio.h> | ||
49 | * | ||
50 | * #include <Eina.h> | ||
51 | * | ||
52 | * int main(void) | ||
53 | * { | ||
54 | * char tmp[128]; | ||
55 | * | ||
56 | * if (!eina_init()) | ||
57 | * { | ||
58 | * printf ("Error during the initialization of eina.\n"); | ||
59 | * return EXIT_FAILURE; | ||
60 | * } | ||
61 | * | ||
62 | * eina_convert_itoa(45, tmp); | ||
63 | * printf("value: %s\n", tmp); | ||
64 | * eina_convert_xtoa(0xA1, tmp); | ||
65 | * printf("value: %s\n", tmp); | ||
66 | * | ||
67 | * eina_shutdown(); | ||
68 | * | ||
69 | * return EXIT_SUCCESS; | ||
70 | * } | ||
71 | * @endcode | ||
72 | * | ||
73 | * Compile this code with the following command: | ||
74 | * | ||
75 | * @code | ||
76 | * gcc -Wall -o test_eina_convert test_eina.c `pkg-config --cflags --libs eina` | ||
77 | * @endcode | ||
78 | * | ||
79 | * @note | ||
80 | * The alphabetical cyphers are in lower case. | ||
81 | * | ||
82 | * @section Eina_Convert_Double Conversion double / string | ||
83 | * | ||
84 | * To convert a double to a string, eina_convert_dtoa() should be | ||
85 | * used. Like with the integer functions, a buffer must be used. The | ||
86 | * resulting string has the following format (which is the result | ||
87 | * obtained with snprintf() and the @%a modifier): | ||
88 | * | ||
89 | * @code | ||
90 | * [-]0xh.hhhhhp[+-]e | ||
91 | * @endcode | ||
92 | * | ||
93 | * To convert a string to a double, eina_convert_atod() should be | ||
94 | * used. The format of the string must be as above. Then, the double | ||
95 | * has the following mantiss and exponent: | ||
96 | * | ||
97 | * @code | ||
98 | * mantiss : [-]hhhhhh | ||
99 | * exponent : 2^([+-]e - 4 * n) | ||
100 | * @endcode | ||
101 | * | ||
102 | * with n being number of cypers after the point in the string | ||
103 | * format. To obtain the double number from the mantiss and exponent, | ||
104 | * use ldexp(). | ||
105 | * | ||
106 | * Here is an example of use: | ||
107 | * | ||
108 | * @code | ||
109 | * #include <stdlib.h> | ||
110 | * #include <stdio.h> | ||
111 | * #include <math.h> | ||
112 | * | ||
113 | * #include <Eina.h> | ||
114 | * | ||
115 | * int main(void) | ||
116 | * { | ||
117 | * char tmp[128]; | ||
118 | * long long int m = 0; | ||
119 | * long int e = 0; | ||
120 | * double r; | ||
121 | * | ||
122 | * if (!eina_init()) | ||
123 | * { | ||
124 | * printf ("Error during the initialization of eina.\n"); | ||
125 | * return EXIT_FAILURE; | ||
126 | * } | ||
127 | * | ||
128 | * printf("initial value : 40.56\n"); | ||
129 | * eina_convert_dtoa(40.56, tmp); | ||
130 | * printf("result dtoa : %s\n", tmp); | ||
131 | |||
132 | * eina_convert_atod(tmp, 128, &m, &e); | ||
133 | * r = ldexp((double)m, e); | ||
134 | * printf("result atod : %f\n", r); | ||
135 | * | ||
136 | * eina_shutdown(); | ||
137 | * | ||
138 | * return EXIT_SUCCESS; | ||
139 | * } | ||
140 | * @endcode | ||
141 | * | ||
142 | * Compile this code with the following command: | ||
143 | * | ||
144 | * @code | ||
145 | * gcc -Wall -o test_eina_convert test_eina.c `pkg-config --cflags --libs eina` -lm | ||
146 | * @endcode | ||
147 | */ | ||
148 | |||
149 | /** | ||
150 | * @addtogroup Eina_Tools_Group Tools | ||
151 | * | ||
152 | * @{ | ||
153 | */ | ||
154 | |||
155 | /** | ||
156 | * @defgroup Eina_Convert_Group Convert | ||
157 | * | ||
158 | * @{ | ||
159 | */ | ||
160 | |||
161 | /** | ||
162 | * @var EINA_ERROR_CONVERT_P_NOT_FOUND | ||
163 | * Error identifier corresponding to string not containing 'p'. | ||
164 | */ | ||
165 | |||
166 | EAPI extern Eina_Error EINA_ERROR_CONVERT_P_NOT_FOUND; | ||
167 | |||
168 | /** | ||
169 | * @var EINA_ERROR_CONVERT_0X_NOT_FOUND | ||
170 | * Error identifier corresponding to string not containing '0x'. | ||
171 | */ | ||
172 | EAPI extern Eina_Error EINA_ERROR_CONVERT_0X_NOT_FOUND; | ||
173 | |||
174 | /** | ||
175 | * @var EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH | ||
176 | * Error identifier corresponding to length of the string being too small. | ||
177 | */ | ||
178 | EAPI extern Eina_Error EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH; | ||
179 | |||
180 | /** | ||
181 | * @brief Convert an integer number to a string in decimal base. | ||
182 | * | ||
183 | * @param n The integer to convert. | ||
184 | * @param s The buffer to store the converted integer. | ||
185 | * @return The length of the string, including the nul terminated | ||
186 | * character. | ||
187 | * | ||
188 | * This function converts @p n to a nul terminated string. The | ||
189 | * converted string is in decimal base. As no check is done, @p s must | ||
190 | * be a buffer that is sufficiently large to store the integer. | ||
191 | * | ||
192 | * The returned value is the length of the string, including the nul | ||
193 | * terminated character. | ||
194 | */ | ||
195 | EAPI int eina_convert_itoa(int n, char *s) EINA_ARG_NONNULL(2); | ||
196 | |||
197 | /** | ||
198 | * @brief Convert an integer number to a string in hexadecimal base. | ||
199 | * | ||
200 | * @param n The integer to convert. | ||
201 | * @param s The buffer to store the converted integer. | ||
202 | * @return The length of the string, including the nul terminated | ||
203 | * character. | ||
204 | * | ||
205 | * This function converts @p n to a nul terminated string. The | ||
206 | * converted string is in hexadecimal base and the alphabetical | ||
207 | * cyphers are in lower case. As no check is done, @p s must be a | ||
208 | * buffer that is sufficiently large to store the integer. | ||
209 | * | ||
210 | * The returned value is the length of the string, including the nul | ||
211 | * terminated character. | ||
212 | */ | ||
213 | EAPI int eina_convert_xtoa(unsigned int n, char *s) EINA_ARG_NONNULL(2); | ||
214 | |||
215 | |||
216 | /** | ||
217 | * @brief Convert a double to a string. | ||
218 | * | ||
219 | * @param d The double to convert. | ||
220 | * @param des The destination buffer to store the converted double. | ||
221 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
222 | * | ||
223 | * This function converts the double @p d to a string. The string is | ||
224 | * stored in the buffer pointed by @p des and must be sufficiently | ||
225 | * large to contain the converted double. The returned string is nul | ||
226 | * terminated and has the following format: | ||
227 | * | ||
228 | * @code | ||
229 | * [-]0xh.hhhhhp[+-]e | ||
230 | * @endcode | ||
231 | * | ||
232 | * where the h are the hexadecimal cyphers of the mantiss and e the | ||
233 | * exponent (a decimal number). | ||
234 | * | ||
235 | * The returned value is the length of the string, including the nul | ||
236 | * character. | ||
237 | */ | ||
238 | EAPI int eina_convert_dtoa(double d, char *des) EINA_ARG_NONNULL(2); | ||
239 | |||
240 | /** | ||
241 | * @brief Convert a string to a double. | ||
242 | * | ||
243 | * @param src The string to convert. | ||
244 | * @param length The length of the string. | ||
245 | * @param m The mantisse. | ||
246 | * @param e The exponent. | ||
247 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
248 | * | ||
249 | * This function converts the string @p s of length @p length that | ||
250 | * represent a double in hexadecimal base to a double. It is used to | ||
251 | * replace the use of snprintf() with the \%a modifier, which is | ||
252 | * missing on some platform (like Windows (tm) or OpenBSD). | ||
253 | * | ||
254 | * The string must have the following format: | ||
255 | * | ||
256 | * @code | ||
257 | * [-]0xh.hhhhhp[+-]e | ||
258 | * @endcode | ||
259 | * | ||
260 | * where the h are the hexadecimal cyphers of the mantiss and e the | ||
261 | * exponent (a decimal number). If n is the number of cypers after the | ||
262 | * point, the returned mantiss and exponents are: | ||
263 | * | ||
264 | * @code | ||
265 | * mantiss : [-]hhhhhh | ||
266 | * exponent : 2^([+-]e - 4 * n) | ||
267 | * @endcode | ||
268 | * | ||
269 | * The mantiss and exponent are stored in the buffers pointed | ||
270 | * respectively by @p m and @p e. | ||
271 | * | ||
272 | * If the string is invalid, the error is set to: | ||
273 | * | ||
274 | * @li #EINA_ERROR_CONVERT_0X_NOT_FOUND if no 0x is found, | ||
275 | * @li #EINA_ERROR_CONVERT_P_NOT_FOUND if no p is found, | ||
276 | * @li #EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH if @p length is not | ||
277 | * correct. | ||
278 | * | ||
279 | * In those cases, #EINA_FALSE is returned, otherwise #EINA_TRUE is | ||
280 | * returned. | ||
281 | */ | ||
282 | EAPI Eina_Bool eina_convert_atod(const char *src, | ||
283 | int length, | ||
284 | long long *m, | ||
285 | long *e) EINA_ARG_NONNULL(1, 3, 4); | ||
286 | |||
287 | |||
288 | /** | ||
289 | * @brief Convert a 32.32 fixed point number to a string. | ||
290 | * | ||
291 | * @param fp The fixed point number to convert. | ||
292 | * @param des The destination buffer to store the converted fixed point number. | ||
293 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
294 | * | ||
295 | * This function converts the 32.32 fixed point number @p fp to a | ||
296 | * string. The string is stored in the buffer pointed by @p des and | ||
297 | * must be sufficiently large to contain the converted fixed point | ||
298 | * number. The returned string is terminated and has the following | ||
299 | * format: | ||
300 | * | ||
301 | * @code | ||
302 | * [-]0xh.hhhhhp[+-]e | ||
303 | * @endcode | ||
304 | * | ||
305 | * where the h are the hexadecimal cyphers of the mantiss and e the | ||
306 | * exponent (a decimal number). | ||
307 | * | ||
308 | * The returned value is the length of the string, including the nul | ||
309 | * character. | ||
310 | * | ||
311 | * @note The code is the same than eina_convert_dtoa() except that it | ||
312 | * implements the frexp() function for fixed point numbers and does | ||
313 | * some optimisations. | ||
314 | */ | ||
315 | EAPI int eina_convert_fptoa(Eina_F32p32 fp, | ||
316 | char *des) EINA_ARG_NONNULL(2); | ||
317 | |||
318 | /** | ||
319 | * @brief Convert a string to a 32.32 fixed point number. | ||
320 | * | ||
321 | * @param src The string to convert. | ||
322 | * @param length The length of the string. | ||
323 | * @param fp The fixed point number. | ||
324 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
325 | * | ||
326 | * This function converts the string @p src of length @p length that | ||
327 | * represent a double in hexadecimal base to a 32.32 fixed point | ||
328 | * number stored in @p fp. The function always tries to convert the | ||
329 | * string with eina_convert_atod(). | ||
330 | * | ||
331 | * The string must have the following format: | ||
332 | * | ||
333 | * @code | ||
334 | * [-]0xh.hhhhhp[+-]e | ||
335 | * @endcode | ||
336 | * | ||
337 | * where the h are the hexadecimal cyphers of the mantiss and e the | ||
338 | * exponent (a decimal number). If n is the number of cypers after the | ||
339 | * point, the returned mantiss and exponents are: | ||
340 | * | ||
341 | * @code | ||
342 | * mantiss : [-]hhhhhh | ||
343 | * exponent : 2^([+-]e - 4 * n) | ||
344 | * @endcode | ||
345 | * | ||
346 | * The mantiss and exponent are stored in the buffers pointed | ||
347 | * respectively by @p m and @p e. | ||
348 | * | ||
349 | * If the string is invalid, the error is set to: | ||
350 | * | ||
351 | * @li #EINA_ERROR_CONVERT_0X_NOT_FOUND if no 0x is found, | ||
352 | * @li #EINA_ERROR_CONVERT_P_NOT_FOUND if no p is found, | ||
353 | * @li #EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH if @p length is not | ||
354 | * correct. | ||
355 | * | ||
356 | * In those cases, or if @p fp is @c NULL, #EINA_FALSE is returned, | ||
357 | * otherwise @p fp is computed and #EINA_TRUE is returned. | ||
358 | * | ||
359 | * @note The code uses eina_convert_atod() and do the correct bit | ||
360 | * shift to compute the fixed point number. | ||
361 | */ | ||
362 | EAPI Eina_Bool eina_convert_atofp(const char *src, | ||
363 | int length, | ||
364 | Eina_F32p32 *fp) EINA_ARG_NONNULL(1, 3); | ||
365 | |||
366 | /** | ||
367 | * @} | ||
368 | */ | ||
369 | |||
370 | /** | ||
371 | * @} | ||
372 | */ | ||
373 | |||
374 | #endif /* EINA_CONVERT_H_ */ | ||
diff --git a/src/include/eina/eina_counter.h b/src/include/eina/eina_counter.h new file mode 100644 index 0000000000..677d97e86b --- /dev/null +++ b/src/include/eina/eina_counter.h | |||
@@ -0,0 +1,213 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2008 Cedric Bail | ||
3 | * | ||
4 | * This library is free software; you can redistribute it and/or | ||
5 | * modify it under the terms of the GNU Lesser General Public | ||
6 | * License as published by the Free Software Foundation; either | ||
7 | * version 2.1 of the License, or (at your option) any later version. | ||
8 | * | ||
9 | * This library is distributed in the hope that it will be useful, | ||
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
12 | * Lesser General Public License for more details. | ||
13 | * | ||
14 | * You should have received a copy of the GNU Lesser General Public | ||
15 | * License along with this library; | ||
16 | * if not, see <http://www.gnu.org/licenses/>. | ||
17 | */ | ||
18 | |||
19 | #ifndef EINA_COUNTER_H_ | ||
20 | #define EINA_COUNTER_H_ | ||
21 | |||
22 | #include "eina_types.h" | ||
23 | |||
24 | /** | ||
25 | * @addtogroup Eina_Counter_Group Counter | ||
26 | * | ||
27 | * @brief These functions allow you to get the time spent in a part of a code. | ||
28 | * | ||
29 | * Before using the counter system, Eina must be initialized with | ||
30 | * eina_init() and later shut down with eina_shutdown(). The create a | ||
31 | * counter, use eina_counter_new(). To free it, use | ||
32 | * eina_counter_free(). | ||
33 | * | ||
34 | * To time a part of a code, call eina_counter_start() just before it, | ||
35 | * and eina_counter_stop() just after it. Each time you start to time | ||
36 | * a code, a clock is added to a list. You can give a number of that | ||
37 | * clock with the second argument of eina_counter_stop(). To send all | ||
38 | * the registered clocks to a stream (like stdout, ofr a file), use | ||
39 | * eina_counter_dump(). | ||
40 | * | ||
41 | * Here is a straightforward example: | ||
42 | * | ||
43 | * @code | ||
44 | * #include <stdlib.h> | ||
45 | * #include <stdio.h> | ||
46 | * | ||
47 | * #include <eina_counter.h> | ||
48 | * | ||
49 | * void test_malloc(void) | ||
50 | * { | ||
51 | * int i; | ||
52 | * | ||
53 | * for (i = 0; i < 100000; ++i) | ||
54 | * { | ||
55 | * void *buf; | ||
56 | * | ||
57 | * buf = malloc(100); | ||
58 | * free(buf); | ||
59 | * } | ||
60 | * } | ||
61 | * | ||
62 | * int main(void) | ||
63 | * { | ||
64 | * Eina_Counter *counter; | ||
65 | * | ||
66 | * if (!eina_init()) | ||
67 | * { | ||
68 | * printf("Error during the initialization of eina\n"); | ||
69 | * return EXIT_FAILURE; | ||
70 | * } | ||
71 | * | ||
72 | * counter = eina_counter_new("malloc"); | ||
73 | * | ||
74 | * eina_counter_start(counter); | ||
75 | * test_malloc(); | ||
76 | * eina_counter_stop(counter, 1); | ||
77 | * | ||
78 | * char* result = eina_counter_dump(counter); | ||
79 | * printf("%s", result); | ||
80 | * free(result); | ||
81 | * | ||
82 | * eina_counter_free(counter); | ||
83 | * eina_shutdown(); | ||
84 | * | ||
85 | * return EXIT_SUCCESS; | ||
86 | * } | ||
87 | * @endcode | ||
88 | * | ||
89 | * Compile this code with the following commant: | ||
90 | * | ||
91 | * @verbatim | ||
92 | * gcc -Wall -o test_eina_counter test_eina.c `pkg-config --cflags --libs eina` | ||
93 | * @endverbatim | ||
94 | * | ||
95 | * The result should be something like that: | ||
96 | * | ||
97 | * @verbatim | ||
98 | * \# specimen experiment time starting time ending time | ||
99 | * 1 9794125 783816 10577941 | ||
100 | * @endverbatim | ||
101 | * | ||
102 | * @note The displayed time is in nanosecond. | ||
103 | */ | ||
104 | |||
105 | /** | ||
106 | * @addtogroup Eina_Tools_Group Tools | ||
107 | * | ||
108 | * @{ | ||
109 | */ | ||
110 | |||
111 | /** | ||
112 | * @defgroup Eina_Counter_Group Counter | ||
113 | * | ||
114 | * @{ | ||
115 | */ | ||
116 | |||
117 | /** | ||
118 | * @typedef Eina_Counter | ||
119 | * Counter type. | ||
120 | */ | ||
121 | typedef struct _Eina_Counter Eina_Counter; | ||
122 | |||
123 | |||
124 | /** | ||
125 | * @brief Return a counter. | ||
126 | * | ||
127 | * @param name The name of the counter. | ||
128 | * @return A newly allocated counter. | ||
129 | * | ||
130 | * This function returns a new counter. It is characterized by @p | ||
131 | * name. If @p name is @c NULL, the function returns @c NULL | ||
132 | * immediately. If memory allocation fails, @c NULL is returned and the | ||
133 | * error is set to #EINA_ERROR_OUT_OF_MEMORY. | ||
134 | * | ||
135 | * Whe the new counter is not needed anymore, use eina_counter_free() to | ||
136 | * free the allocated memory. | ||
137 | */ | ||
138 | EAPI Eina_Counter *eina_counter_new(const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); | ||
139 | |||
140 | /** | ||
141 | * @brief Delete a counter. | ||
142 | * | ||
143 | * @param counter The counter to delete. | ||
144 | * | ||
145 | * This function remove the clock of @p counter from the used clocks | ||
146 | * (see eina_counter_start()) and frees the memory allocated for | ||
147 | * @p counter. If @p counter is @c NULL, the function returns | ||
148 | * immediately. | ||
149 | */ | ||
150 | EAPI void eina_counter_free(Eina_Counter *counter) EINA_ARG_NONNULL(1); | ||
151 | |||
152 | /** | ||
153 | * @brief Start the time count. | ||
154 | * | ||
155 | * @param counter The counter. | ||
156 | * | ||
157 | * This function specifies that the part of the code beginning just | ||
158 | * after its call is being to be timed, using @p counter. If | ||
159 | * @p counter is @c NULL, this function returns immediately. | ||
160 | * | ||
161 | * This function adds the clock associated to @p counter in a list. If | ||
162 | * the memory needed by that clock can not be allocated, the function | ||
163 | * returns and the error is set to #EINA_ERROR_OUT_OF_MEMORY. | ||
164 | * | ||
165 | * To stop the timing, eina_counter_stop() must be called with the | ||
166 | * same counter. | ||
167 | */ | ||
168 | EAPI void eina_counter_start(Eina_Counter *counter) EINA_ARG_NONNULL(1); | ||
169 | |||
170 | /** | ||
171 | * @brief Stop the time count. | ||
172 | * | ||
173 | * @param counter The counter. | ||
174 | * @param specimen The number of the test. | ||
175 | * | ||
176 | * This function stop the timing that has been started with | ||
177 | * eina_counter_start(). @p counter must be the same than the one used | ||
178 | * with eina_counter_start(). @p specimen is the number of the | ||
179 | * test. If @p counter or its associated clock are @c NULL, or if the | ||
180 | * time can't be retrieved the function exits. | ||
181 | */ | ||
182 | EAPI void eina_counter_stop(Eina_Counter *counter, | ||
183 | int specimen) EINA_ARG_NONNULL(1); | ||
184 | |||
185 | /** | ||
186 | * @brief Dump the result of all clocks of a counter to a stream. | ||
187 | * | ||
188 | * @return A string with a summary of the test. | ||
189 | * @param counter The counter. | ||
190 | * | ||
191 | * This function returns an malloc'd string containing the dump of | ||
192 | * all the valid clocks of @p counter. | ||
193 | * If @p counter @c NULL, the functions exits | ||
194 | * immediately. Otherwise, the output is formattted like that: | ||
195 | * | ||
196 | * @verbatim | ||
197 | * \# specimen experiment time starting time ending time | ||
198 | * 1 208 120000 120208 | ||
199 | * @endverbatim | ||
200 | * | ||
201 | * The unit of time is the nanosecond. | ||
202 | */ | ||
203 | EAPI char *eina_counter_dump(Eina_Counter *counter) EINA_ARG_NONNULL(1); | ||
204 | |||
205 | /** | ||
206 | * @} | ||
207 | */ | ||
208 | |||
209 | /** | ||
210 | * @} | ||
211 | */ | ||
212 | |||
213 | #endif /* EINA_COUNTER_H_ */ | ||
diff --git a/src/include/eina/eina_cpu.h b/src/include/eina/eina_cpu.h new file mode 100644 index 0000000000..ac32e1db9b --- /dev/null +++ b/src/include/eina/eina_cpu.h | |||
@@ -0,0 +1,39 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2007-2008 Jorge Luis Zapata Muga | ||
3 | * | ||
4 | * This library is free software; you can redistribute it and/or | ||
5 | * modify it under the terms of the GNU Lesser General Public | ||
6 | * License as published by the Free Software Foundation; either | ||
7 | * version 2.1 of the License, or (at your option) any later version. | ||
8 | * | ||
9 | * This library is distributed in the hope that it will be useful, | ||
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
12 | * Lesser General Public License for more details. | ||
13 | * | ||
14 | * You should have received a copy of the GNU Lesser General Public | ||
15 | * License along with this library; | ||
16 | * if not, see <http://www.gnu.org/licenses/>. | ||
17 | */ | ||
18 | |||
19 | #ifndef EINA_CPU_H_ | ||
20 | #define EINA_CPU_H_ | ||
21 | |||
22 | #include "eina_types.h" | ||
23 | |||
24 | typedef enum _Eina_Cpu_Features | ||
25 | { | ||
26 | EINA_CPU_MMX = 0x00000001, | ||
27 | EINA_CPU_SSE = 0x00000002, | ||
28 | EINA_CPU_SSE2 = 0x00000004, | ||
29 | EINA_CPU_SSE3 = 0x00000008, | ||
30 | /* TODO 3DNow! */ | ||
31 | EINA_CPU_ALTIVEC = 0x00000010, | ||
32 | EINA_CPU_VIS = 0x00000020, | ||
33 | EINA_CPU_NEON = 0x00000040, | ||
34 | } Eina_Cpu_Features; | ||
35 | |||
36 | EAPI Eina_Cpu_Features eina_cpu_features_get(void); | ||
37 | EAPI int eina_cpu_count(void); | ||
38 | |||
39 | #endif /* EINA_CPU_H_ */ | ||
diff --git a/src/include/eina/eina_error.h b/src/include/eina/eina_error.h new file mode 100644 index 0000000000..e4205e4e45 --- /dev/null +++ b/src/include/eina/eina_error.h | |||
@@ -0,0 +1,198 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2007-2008 Jorge Luis Zapata Muga, Cedric Bail | ||
3 | * | ||
4 | * This library is free software; you can redistribute it and/or | ||
5 | * modify it under the terms of the GNU Lesser General Public | ||
6 | * License as published by the Free Software Foundation; either | ||
7 | * version 2.1 of the License, or (at your option) any later version. | ||
8 | * | ||
9 | * This library is distributed in the hope that it will be useful, | ||
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
12 | * Lesser General Public License for more details. | ||
13 | * | ||
14 | * You should have received a copy of the GNU Lesser General Public | ||
15 | * License along with this library; | ||
16 | * if not, see <http://www.gnu.org/licenses/>. | ||
17 | */ | ||
18 | |||
19 | #ifndef EINA_ERROR_H_ | ||
20 | #define EINA_ERROR_H_ | ||
21 | |||
22 | #include <stdarg.h> | ||
23 | |||
24 | #include "eina_types.h" | ||
25 | |||
26 | |||
27 | /** | ||
28 | * @page tutorial_error_page Error Tutorial | ||
29 | * | ||
30 | * @section tutorial_error_registering_msg Registering messages | ||
31 | * | ||
32 | * The error module can provide a system that mimics the errno system | ||
33 | * of the C standard library. It consists in 2 parts: | ||
34 | * | ||
35 | * @li a way of registering new messages with | ||
36 | * eina_error_msg_register() and eina_error_msg_get(), | ||
37 | * @li a way of setting / getting last error message with | ||
38 | * eina_error_set() / eina_error_get(). | ||
39 | * | ||
40 | * So one has to fisrt register all the error messages that a program | ||
41 | * or a lib should manage. Then, when an error can occur, use | ||
42 | * eina_error_set(), and when errors are managed, use | ||
43 | * eina_error_get(). If eina_error_set() is used to set an error, do | ||
44 | * not forget to call before eina_error_set(), to remove previous set | ||
45 | * errors. | ||
46 | * | ||
47 | * Here is an example of use: | ||
48 | * | ||
49 | * @include eina_error_01.c | ||
50 | * | ||
51 | * Of course, instead of printf(), eina_log_print() can be used to | ||
52 | * have beautiful error messages. | ||
53 | */ | ||
54 | |||
55 | /** | ||
56 | * @addtogroup Eina_Error_Group Error | ||
57 | * | ||
58 | * @brief These functions provide error management for projects. | ||
59 | * | ||
60 | * The Eina error module provides a way to manage errors in a simple but | ||
61 | * powerful way in libraries and modules. It is also used in Eina itself. | ||
62 | * Similar to libC's @c errno and strerror() facilities, this is extensible and | ||
63 | * recommended for other libraries and applications. | ||
64 | * | ||
65 | * A simple example of how to use this can be seen @ref tutorial_error_page | ||
66 | * "here". | ||
67 | */ | ||
68 | |||
69 | /** | ||
70 | * @addtogroup Eina_Tools_Group Tools | ||
71 | * | ||
72 | * @{ | ||
73 | */ | ||
74 | |||
75 | /** | ||
76 | * @defgroup Eina_Error_Group Error | ||
77 | * | ||
78 | * @{ | ||
79 | */ | ||
80 | |||
81 | /** | ||
82 | * @typedef Eina_Error | ||
83 | * Error type. | ||
84 | */ | ||
85 | typedef int Eina_Error; | ||
86 | |||
87 | /** | ||
88 | * @var EINA_ERROR_OUT_OF_MEMORY | ||
89 | * Error identifier corresponding to a lack of memory. | ||
90 | */ | ||
91 | |||
92 | EAPI extern Eina_Error EINA_ERROR_OUT_OF_MEMORY; | ||
93 | |||
94 | /** | ||
95 | * @brief Register a new error type. | ||
96 | * | ||
97 | * @param msg The description of the error. It will be duplicated using | ||
98 | * eina_stringshare_add(). | ||
99 | * @return The unique number identifier for this error. | ||
100 | * | ||
101 | * This function stores in a list the error message described by | ||
102 | * @p msg. The returned value is a unique identifier greater or equal | ||
103 | * than 1. The description can be retrieve later by passing to | ||
104 | * eina_error_msg_get() the returned value. | ||
105 | * | ||
106 | * @see eina_error_msg_static_register() | ||
107 | */ | ||
108 | EAPI Eina_Error eina_error_msg_register(const char *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
109 | |||
110 | /** | ||
111 | * @brief Register a new error type, statically allocated message. | ||
112 | * | ||
113 | * @param msg The description of the error. This string will not be | ||
114 | * duplicated and thus the given pointer should live during | ||
115 | * usage of eina_error. | ||
116 | * @return The unique number identifier for this error. | ||
117 | * | ||
118 | * This function stores in a list the error message described by | ||
119 | * @p msg. The returned value is a unique identifier greater or equal | ||
120 | * than 1. The description can be retrieve later by passing to | ||
121 | * eina_error_msg_get() the returned value. | ||
122 | * | ||
123 | * @see eina_error_msg_register() | ||
124 | */ | ||
125 | EAPI Eina_Error eina_error_msg_static_register(const char *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
126 | |||
127 | /** | ||
128 | * @brief Change the message of an already registered message | ||
129 | * | ||
130 | * @param error The Eina_Error to change the message of | ||
131 | * @param msg The description of the error. This string will be | ||
132 | * duplicated only if the error was registered with @ref eina_error_msg_register | ||
133 | * otherwise it must remain intact for the duration. | ||
134 | * @return #EINA_TRUE if successful, #EINA_FALSE on error. | ||
135 | * | ||
136 | * This function modifies the message associated with @p error and changes | ||
137 | * it to @p msg. If the error was previously registered by @ref eina_error_msg_static_register | ||
138 | * then the string will not be duplicated, otherwise the previous message | ||
139 | * will be unrefed and @p msg copied. | ||
140 | * | ||
141 | * @see eina_error_msg_register() | ||
142 | */ | ||
143 | EAPI Eina_Bool eina_error_msg_modify(Eina_Error error, | ||
144 | const char *msg) EINA_ARG_NONNULL(2); | ||
145 | |||
146 | /** | ||
147 | * @brief Return the last set error. | ||
148 | * | ||
149 | * @return The last error. | ||
150 | * | ||
151 | * This function returns the last error set by eina_error_set(). The | ||
152 | * description of the message is returned by eina_error_msg_get(). | ||
153 | */ | ||
154 | EAPI Eina_Error eina_error_get(void); | ||
155 | |||
156 | /** | ||
157 | * @brief Set the last error. | ||
158 | * | ||
159 | * @param err The error identifier. | ||
160 | * | ||
161 | * This function sets the last error identifier. The last error can be | ||
162 | * retrieved with eina_error_get(). | ||
163 | * | ||
164 | * @note This is also used to clear previous errors, in that case @p err should | ||
165 | * be @c 0. | ||
166 | */ | ||
167 | EAPI void eina_error_set(Eina_Error err); | ||
168 | |||
169 | /** | ||
170 | * @brief Return the description of the given an error number. | ||
171 | * | ||
172 | * @param error The error number. | ||
173 | * @return The description of the error. | ||
174 | * | ||
175 | * This function returns the description of an error that has been | ||
176 | * registered with eina_error_msg_register(). If an incorrect error is | ||
177 | * given, then @c NULL is returned. | ||
178 | */ | ||
179 | EAPI const char *eina_error_msg_get(Eina_Error error) EINA_PURE; | ||
180 | |||
181 | /** | ||
182 | * @brief Find the #Eina_Error corresponding to a message string | ||
183 | * @param msg The error message string to match (NOT @c NULL) | ||
184 | * @return The #Eina_Error matching @p msg, or 0 on failure | ||
185 | * This function attempts to match @p msg with its corresponding #Eina_Error value. | ||
186 | * If no such value is found, 0 is returned. | ||
187 | */ | ||
188 | EAPI Eina_Error eina_error_find(const char *msg) EINA_ARG_NONNULL(1) EINA_PURE; | ||
189 | |||
190 | /** | ||
191 | * @} | ||
192 | */ | ||
193 | |||
194 | /** | ||
195 | * @} | ||
196 | */ | ||
197 | |||
198 | #endif /* EINA_ERROR_H_ */ | ||
diff --git a/src/include/eina/eina_file.h b/src/include/eina/eina_file.h new file mode 100644 index 0000000000..31c4eb5b62 --- /dev/null +++ b/src/include/eina/eina_file.h | |||
@@ -0,0 +1,524 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2007-2008 Jorge Luis Zapata Muga | ||
3 | * 2011 Cedric Bail | ||
4 | * | ||
5 | * This library is free software; you can redistribute it and/or | ||
6 | * modify it under the terms of the GNU Lesser General Public | ||
7 | * License as published by the Free Software Foundation; either | ||
8 | * version 2.1 of the License, or (at your option) any later version. | ||
9 | * | ||
10 | * This library is distributed in the hope that it will be useful, | ||
11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
13 | * Lesser General Public License for more details. | ||
14 | * | ||
15 | * You should have received a copy of the GNU Lesser General Public | ||
16 | * License along with this library; | ||
17 | * if not, see <http://www.gnu.org/licenses/>. | ||
18 | */ | ||
19 | |||
20 | #ifndef EINA_FILE_H_ | ||
21 | #define EINA_FILE_H_ | ||
22 | |||
23 | #include <limits.h> | ||
24 | #include <time.h> | ||
25 | #include <sys/stat.h> | ||
26 | |||
27 | #include "eina_types.h" | ||
28 | #include "eina_array.h" | ||
29 | #include "eina_iterator.h" | ||
30 | |||
31 | |||
32 | /** | ||
33 | * @page eina_file_example_01_page | ||
34 | * @dontinclude eina_file_01.c | ||
35 | * | ||
36 | * For brevity includes, variable declarations and initialization was omitted | ||
37 | * from this page, however the full source code can be seen @ref | ||
38 | * eina_file_example_01 "here". | ||
39 | * | ||
40 | * Here we have a simple callback to print the name of a file and the path that | ||
41 | * contains it: | ||
42 | * @skip static | ||
43 | * @until } | ||
44 | * | ||
45 | * We can use this callback in the following call: | ||
46 | * @skipline eina_file_dir_list | ||
47 | * | ||
48 | * The above was a way to print the files in a directory, but it is not the only | ||
49 | * one: | ||
50 | * @until iterator_free | ||
51 | * | ||
52 | * And now two ways to get more information than just file names: | ||
53 | * @until iterator_free | ||
54 | * @until iterator_free | ||
55 | * | ||
56 | * The above ways of getting files on a list may produce the same output, but | ||
57 | * they have an important difference, eina_file_direct_ls() will @b not call | ||
58 | * stat, this means that on some systems it might not have file type | ||
59 | * information. On the other hand it might be faster than eina_file_stat_ls(). | ||
60 | */ | ||
61 | /** | ||
62 | * @page eina_file_example_01 | ||
63 | * @include eina_file_01.c | ||
64 | * @example eina_file_01.c | ||
65 | */ | ||
66 | /** | ||
67 | * @addtogroup Eina_Tools_Group Tools | ||
68 | * | ||
69 | * @{ | ||
70 | */ | ||
71 | /** | ||
72 | * @addtogroup Eina_File_Group File | ||
73 | * | ||
74 | * @brief Functions to handle files and directories. | ||
75 | * | ||
76 | * This functions make it easier to do a number o file and directory operations | ||
77 | * such as getting the list of files in a directory, spliting paths and finding | ||
78 | * out file size and type. | ||
79 | * | ||
80 | * @warning All functions in this group are @b blocking which means they make | ||
81 | * take a long time to return, use them carefully. | ||
82 | * | ||