diff options
Diffstat (limited to '')
-rw-r--r-- | libraries/eina/src/include/eina_value.h | 3114 |
1 files changed, 3114 insertions, 0 deletions
diff --git a/libraries/eina/src/include/eina_value.h b/libraries/eina/src/include/eina_value.h new file mode 100644 index 0000000..846c4ef --- /dev/null +++ b/libraries/eina/src/include/eina_value.h | |||
@@ -0,0 +1,3114 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2012 ProFUSION embedded systems | ||
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_VALUE_H_ | ||
20 | #define EINA_VALUE_H_ | ||
21 | |||
22 | #include "eina_types.h" | ||
23 | #include "eina_fp.h" /* defines int64_t and uint64_t */ | ||
24 | #include "eina_inarray.h" | ||
25 | #include "eina_list.h" | ||
26 | #include "eina_hash.h" | ||
27 | #include <stdarg.h> | ||
28 | |||
29 | /** | ||
30 | * @addtogroup Eina_Data_Types_Group Data Types | ||
31 | * | ||
32 | * @since 1.2 | ||
33 | * | ||
34 | * @{ | ||
35 | */ | ||
36 | |||
37 | /** | ||
38 | * @addtogroup Eina_Containers_Group Containers | ||
39 | * | ||
40 | * @{ | ||
41 | */ | ||
42 | |||
43 | /** | ||
44 | * @defgroup Eina_Value_Group Generic Value Storage | ||
45 | * | ||
46 | * @{ | ||
47 | */ | ||
48 | |||
49 | |||
50 | /** | ||
51 | * @typedef Eina_Value | ||
52 | * Store generic values. | ||
53 | * | ||
54 | * @since 1.2 | ||
55 | */ | ||
56 | typedef struct _Eina_Value Eina_Value; | ||
57 | |||
58 | /** | ||
59 | * @typedef Eina_Value_Type | ||
60 | * Describes the data contained by the value | ||
61 | * | ||
62 | * @since 1.2 | ||
63 | */ | ||
64 | typedef struct _Eina_Value_Type Eina_Value_Type; | ||
65 | |||
66 | /** | ||
67 | * @typedef Eina_Value_Union | ||
68 | * Union of all known value types. | ||
69 | * | ||
70 | * @since 1.2 | ||
71 | */ | ||
72 | typedef union _Eina_Value_Union Eina_Value_Union; | ||
73 | |||
74 | /** | ||
75 | * @union _Eina_Value_Union | ||
76 | * All possible value types. | ||
77 | * | ||
78 | * @since 1.2 | ||
79 | */ | ||
80 | union _Eina_Value_Union | ||
81 | { | ||
82 | unsigned char buf[8]; /**< just hold 8-bytes, more goes into ptr */ | ||
83 | void *ptr; /**< used as generic pointer */ | ||
84 | uint64_t _guarantee; /**< guarantees 8-byte alignment */ | ||
85 | }; | ||
86 | |||
87 | /** | ||
88 | * @var EINA_VALUE_TYPE_UCHAR | ||
89 | * manages unsigned char type. | ||
90 | * | ||
91 | * @since 1.2 | ||
92 | */ | ||
93 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_UCHAR; | ||
94 | |||
95 | /** | ||
96 | * @var EINA_VALUE_TYPE_USHORT | ||
97 | * manages unsigned short type. | ||
98 | * | ||
99 | * @since 1.2 | ||
100 | */ | ||
101 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_USHORT; | ||
102 | |||
103 | /** | ||
104 | * @var EINA_VALUE_TYPE_UINT | ||
105 | * manages unsigned int type. | ||
106 | * | ||
107 | * @since 1.2 | ||
108 | */ | ||
109 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_UINT; | ||
110 | |||
111 | /** | ||
112 | * @var EINA_VALUE_TYPE_ULONG | ||
113 | * manages unsigned long type. | ||
114 | * | ||
115 | * @since 1.2 | ||
116 | */ | ||
117 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_ULONG; | ||
118 | |||
119 | /** | ||
120 | * @var EINA_VALUE_TYPE_UINT64 | ||
121 | * manages unsigned integer of 64 bits type. | ||
122 | * | ||
123 | * @since 1.2 | ||
124 | */ | ||
125 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_UINT64; | ||
126 | |||
127 | /** | ||
128 | * @var EINA_VALUE_TYPE_CHAR | ||
129 | * manages char type. | ||
130 | * | ||
131 | * @since 1.2 | ||
132 | */ | ||
133 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_CHAR; | ||
134 | |||
135 | /** | ||
136 | * @var EINA_VALUE_TYPE_SHORT | ||
137 | * manages short type. | ||
138 | * | ||
139 | * @since 1.2 | ||
140 | */ | ||
141 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_SHORT; | ||
142 | |||
143 | /** | ||
144 | * @var EINA_VALUE_TYPE_INT | ||
145 | * manages int type. | ||
146 | * | ||
147 | * @since 1.2 | ||
148 | */ | ||
149 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_INT; | ||
150 | |||
151 | /** | ||
152 | * @var EINA_VALUE_TYPE_LONG | ||
153 | * manages long type. | ||
154 | * | ||
155 | * @since 1.2 | ||
156 | */ | ||
157 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_LONG; | ||
158 | |||
159 | /** | ||
160 | * @var EINA_VALUE_TYPE_INT64 | ||
161 | * manages integer of 64 bits type. | ||
162 | * | ||
163 | * @since 1.2 | ||
164 | */ | ||
165 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_INT64; | ||
166 | |||
167 | /** | ||
168 | * @var EINA_VALUE_TYPE_FLOAT | ||
169 | * manages float type. | ||
170 | * | ||
171 | * @since 1.2 | ||
172 | */ | ||
173 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_FLOAT; | ||
174 | |||
175 | /** | ||
176 | * @var EINA_VALUE_TYPE_DOUBLE | ||
177 | * manages double type. | ||
178 | * | ||
179 | * @since 1.2 | ||
180 | */ | ||
181 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_DOUBLE; | ||
182 | |||
183 | /** | ||
184 | * @var EINA_VALUE_TYPE_STRINGSHARE | ||
185 | * manages stringshared string type. | ||
186 | * | ||
187 | * @since 1.2 | ||
188 | */ | ||
189 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_STRINGSHARE; | ||
190 | |||
191 | /** | ||
192 | * @var EINA_VALUE_TYPE_STRING | ||
193 | * manages string type. | ||
194 | * | ||
195 | * @since 1.2 | ||
196 | */ | ||
197 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_STRING; | ||
198 | |||
199 | |||
200 | /** | ||
201 | * @var EINA_VALUE_TYPE_ARRAY | ||
202 | * | ||
203 | * manages array type. Use the value get/set for arrays: | ||
204 | * @li eina_value_array_get() and eina_value_array_set() | ||
205 | * @li eina_value_array_vget() and eina_value_array_vset() | ||
206 | * @li eina_value_array_pget() and eina_value_array_pset() | ||
207 | * | ||
208 | * eina_value_set() takes an #Eina_Value_Array where just @c subtype | ||
209 | * and @c step are used. If there is an @c array, it will be adopted | ||
210 | * and its contents must be properly configurable as @c subtype | ||
211 | * expects. eina_value_pset() takes a pointer to an #Eina_Value_Array. | ||
212 | * For your convenience, use eina_value_array_setup(). | ||
213 | * | ||
214 | * eina_value_get() and eina_value_pget() takes a pointer to | ||
215 | * #Eina_Value_Array, it's an exact copy of the current structure in | ||
216 | * use by value, no copies are done. | ||
217 | * | ||
218 | * @since 1.2 | ||
219 | */ | ||
220 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_ARRAY; | ||
221 | |||
222 | /** | ||
223 | * @var EINA_VALUE_TYPE_LIST | ||
224 | * | ||
225 | * manages list type. Use the value get/set for lists: | ||
226 | * @li eina_value_list_get() and eina_value_list_set() | ||
227 | * @li eina_value_list_vget() and eina_value_list_vset() | ||
228 | * @li eina_value_list_pget() and eina_value_list_pset() | ||
229 | * | ||
230 | * eina_value_set() takes an #Eina_Value_List where just @c subtype is | ||
231 | * used. If there is an @c list, it will be adopted and its contents | ||
232 | * must be properly configurable as @c subtype | ||
233 | * expects. eina_value_pset() takes a pointer to an #Eina_Value_List. | ||
234 | * For your convenience, use eina_value_list_setup(). | ||
235 | * | ||
236 | * eina_value_get() and eina_value_pget() takes a pointer to | ||
237 | * #Eina_Value_List, it's an exact copy of the current structure in | ||
238 | * use by value, no copies are done. | ||
239 | * | ||
240 | * @since 1.2 | ||
241 | */ | ||
242 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_LIST; | ||
243 | |||
244 | /** | ||
245 | * @var EINA_VALUE_TYPE_HASH | ||
246 | * | ||
247 | * manages hash type. Use the value get/set for hashes: | ||
248 | * @li eina_value_hash_get() and eina_value_hash_set() | ||
249 | * @li eina_value_hash_vget() and eina_value_hash_vset() | ||
250 | * @li eina_value_hash_pget() and eina_value_hash_pset() | ||
251 | * | ||
252 | * eina_value_set() takes an #Eina_Value_Hash where just @c subtype | ||
253 | * and @c buckets_power_size are used. If there is an @c hash, it will | ||
254 | * be adopted and its contents must be properly configurable as @c | ||
255 | * subtype expects. eina_value_pset() takes a pointer to an | ||
256 | * #Eina_Value_Hash. For your convenience, use | ||
257 | * eina_value_hash_setup(). | ||
258 | * | ||
259 | * eina_value_get() and eina_value_pget() takes a pointer to | ||
260 | * #Eina_Value_Hash, it's an exact copy of the current structure in | ||
261 | * use by value, no copies are done. | ||
262 | * | ||
263 | * @note be aware that hash data is always an allocated memory of size | ||
264 | * defined by @c subtype->value_size. If your @c subtype is an | ||
265 | * integer, add as data malloc(sizeof(int)). If your @c subtype | ||
266 | * is an string, add as data malloc(sizeof(char*)) and this data | ||
267 | * value must point to strdup(string)! | ||
268 | * | ||
269 | * @since 1.2 | ||
270 | */ | ||
271 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_HASH; | ||
272 | |||
273 | /** | ||
274 | * @var EINA_VALUE_TYPE_TIMEVAL | ||
275 | * manages 'struct timeval' type | ||
276 | * | ||
277 | * eina_value_set() takes a "struct timeval" from sys/time.h. | ||
278 | * eina_value_pset() takes a pointer to "struct timeval". | ||
279 | * | ||
280 | * eina_value_get() and eina_value_pget() takes a pointer to "struct | ||
281 | * timeval" and it's an exact copy of value. | ||
282 | * | ||
283 | * @since 1.2 | ||
284 | */ | ||
285 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_TIMEVAL; | ||
286 | |||
287 | /** | ||
288 | * @var EINA_VALUE_TYPE_BLOB | ||
289 | * manages blob of bytes type, see @ref Eina_Value_Blob | ||
290 | * | ||
291 | * eina_value_set() takes an #Eina_Value_Blob | ||
292 | * eina_value_pset() takes a pointer to #Eina_Value_Blob. | ||
293 | * | ||
294 | * eina_value_get() and eina_value_pget() takes a pointer to | ||
295 | * #Eina_Value_Blob and it's an exact copy of value, no allocations | ||
296 | * are made. | ||
297 | * | ||
298 | * Memory is untouched unless you provide @c ops (operations) pointer. | ||
299 | * | ||
300 | * @since 1.2 | ||
301 | */ | ||
302 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_BLOB; | ||
303 | |||
304 | /** | ||
305 | * @var EINA_VALUE_TYPE_STRUCT | ||
306 | * | ||
307 | * manages struct type. Use the value get/set for structs: | ||
308 | * @li eina_value_struct_get() and eina_value_struct_set() | ||
309 | * @li eina_value_struct_vget() and eina_value_struct_vset() | ||
310 | * @li eina_value_struct_pget() and eina_value_struct_pset() | ||
311 | * | ||
312 | * eina_value_set() takes an #Eina_Value_Struct where just @c desc is | ||
313 | * used. If there is an @c memory, it will be adopted and its contents | ||
314 | * must be properly configurable as @c desc expects. eina_value_pset() | ||
315 | * takes a pointer to an #Eina_Value_Struct. For your convenience, use | ||
316 | * eina_value_struct_setup(). | ||
317 | * | ||
318 | * eina_value_get() and eina_value_pget() takes a pointer to | ||
319 | * #Eina_Value_Struct, it's an exact copy of the current structure in | ||
320 | * use by value, no copies are done. | ||
321 | * | ||
322 | * @since 1.2 | ||
323 | */ | ||
324 | EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_STRUCT; | ||
325 | |||
326 | /** | ||
327 | * @var EINA_ERROR_VALUE_FAILED | ||
328 | * Error identifier corresponding to value check failure. | ||
329 | * | ||
330 | * @since 1.2 | ||
331 | */ | ||
332 | EAPI extern int EINA_ERROR_VALUE_FAILED; | ||
333 | |||
334 | /** | ||
335 | * @defgroup Eina_Value_Value_Group Generic Value management | ||
336 | * | ||
337 | * @{ | ||
338 | */ | ||
339 | |||
340 | /** | ||
341 | * @struct _Eina_Value | ||
342 | * defines the contents of a value | ||
343 | * | ||
344 | * @since 1.2 | ||
345 | */ | ||
346 | struct _Eina_Value | ||
347 | { | ||
348 | const Eina_Value_Type *type; /**< how to access values */ | ||
349 | Eina_Value_Union value; /**< to be accessed with type descriptor */ | ||
350 | }; | ||
351 | |||
352 | /** | ||
353 | * @brief Create generic value storage. | ||
354 | * @param type how to manage this value. | ||
355 | * @return The new value or @c NULL on failure. | ||
356 | * | ||
357 | * Create a new generic value storage. The members are managed using | ||
358 | * the description specified by @a type. | ||
359 | * | ||
360 | * Some types may specify more operations: | ||
361 | * eg. #EINA_VALUE_TYPE_ARRAY uses eina_value_array_set(), | ||
362 | * eina_value_array_get() and so on. | ||
363 | * | ||
364 | * On failure, @c NULL is returned and either #EINA_ERROR_OUT_OF_MEMORY or | ||
365 | * #EINA_ERROR_VALUE_FAILED is set. | ||
366 | * | ||
367 | * @note this calls creates from mempool and then uses | ||
368 | * eina_value_setup(). Consider using eina_value_flush() and | ||
369 | * eina_value_setup() instead to avoid memory allocations. | ||
370 | * | ||
371 | * @see eina_value_free() | ||
372 | * | ||
373 | * @since 1.2 | ||
374 | */ | ||
375 | EAPI Eina_Value *eina_value_new(const Eina_Value_Type *type) EINA_ARG_NONNULL(1) EINA_MALLOC EINA_WARN_UNUSED_RESULT; | ||
376 | |||
377 | /** | ||
378 | * @brief Free value and its data. | ||
379 | * @param value value object | ||
380 | * | ||
381 | * @see eina_value_flush() | ||
382 | * | ||
383 | * @since 1.2 | ||
384 | */ | ||
385 | EAPI void eina_value_free(Eina_Value *value) EINA_ARG_NONNULL(1); | ||
386 | |||
387 | |||
388 | /** | ||
389 | * @brief Initialize generic value storage. | ||
390 | * @param value value object | ||
391 | * @param type how to manage this value. | ||
392 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
393 | * | ||
394 | * Initializes existing generic value storage. The members are managed using the | ||
395 | * description specified by @a type. | ||
396 | * | ||
397 | * Some types may specify more operations, as an example | ||
398 | * #EINA_VALUE_TYPE_ARRAY uses eina_value_array_set(), | ||
399 | * eina_value_array_get() and so on. | ||
400 | * | ||
401 | * @note Existing contents are ignored! If the value was previously used, then | ||
402 | * use eina_value_flush() first. | ||
403 | * | ||
404 | * On failure, #EINA_FALSE is returned and #EINA_ERROR_OUT_OF_MEMORY | ||
405 | * or #EINA_ERROR_VALUE_FAILED is set. | ||
406 | * | ||
407 | * @see eina_value_flush() | ||
408 | * | ||
409 | * @since 1.2 | ||
410 | */ | ||
411 | static inline Eina_Bool eina_value_setup(Eina_Value *value, | ||
412 | const Eina_Value_Type *type) EINA_ARG_NONNULL(1, 2); | ||
413 | |||
414 | /** | ||
415 | * @brief Create generic value storage. | ||
416 | * @param value value object | ||
417 | * | ||
418 | * Releases all the resources associated with an #Eina_Value. The | ||
419 | * value must be already set with eina_value_setup() or | ||
420 | * eina_value_new(). | ||
421 | * | ||
422 | * After this call returns, the contents of the value are undefined, | ||
423 | * but the value can be reused by calling eina_value_setup() again. | ||
424 | * | ||
425 | * @see eina_value_setup() | ||
426 | * @see eina_value_free() | ||
427 | * | ||
428 | * @since 1.2 | ||
429 | */ | ||
430 | static inline void eina_value_flush(Eina_Value *value) EINA_ARG_NONNULL(1); | ||
431 | |||
432 | /** | ||
433 | * @brief Copy generic value storage. | ||
434 | * @param value source value object | ||
435 | * @param copy destination value object | ||
436 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
437 | * | ||
438 | * The @a copy object is considered internalized and its existing | ||
439 | * contents are overwritten (just as if eina_value_flush() was called on | ||
440 | * it). | ||
441 | * | ||
442 | * The copy happens by calling eina_value_setup() on @a copy, followed | ||
443 | * by getting the contents of @a value and setting it to @a copy. | ||
444 | * | ||
445 | * @since 1.2 | ||
446 | */ | ||
447 | EAPI Eina_Bool eina_value_copy(const Eina_Value *value, | ||
448 | Eina_Value *copy) EINA_ARG_NONNULL(1, 2); | ||
449 | |||
450 | /** | ||
451 | * @brief Compare generic value storage. | ||
452 | * @param a left side of comparison | ||
453 | * @param b right side of comparison | ||
454 | * @return less than zero if a < b, greater than zero if a > b, zero | ||
455 | * if a == b | ||
456 | * | ||
457 | * @since 1.2 | ||
458 | */ | ||
459 | static inline int eina_value_compare(const Eina_Value *a, | ||
460 | const Eina_Value *b) EINA_ARG_NONNULL(1, 2); | ||
461 | |||
462 | /** | ||
463 | * @brief Set the generic value. | ||
464 | * @param value source value object | ||
465 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
466 | * | ||
467 | * The variable argument is dependent on chosen type. The list for | ||
468 | * basic types: | ||
469 | * | ||
470 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char | ||
471 | * @li EINA_VALUE_TYPE_USHORT: unsigned short | ||
472 | * @li EINA_VALUE_TYPE_UINT: unsigned int | ||
473 | * @li EINA_VALUE_TYPE_ULONG: unsigned long | ||
474 | * @li EINA_VALUE_TYPE_UINT64: uint64_t | ||
475 | * @li EINA_VALUE_TYPE_CHAR: char | ||
476 | * @li EINA_VALUE_TYPE_SHORT: short | ||
477 | * @li EINA_VALUE_TYPE_INT: int | ||
478 | * @li EINA_VALUE_TYPE_LONG: long | ||
479 | * @li EINA_VALUE_TYPE_INT64: int64_t | ||
480 | * @li EINA_VALUE_TYPE_FLOAT: float | ||
481 | * @li EINA_VALUE_TYPE_DOUBLE: double | ||
482 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char * | ||
483 | * @li EINA_VALUE_TYPE_STRING: const char * | ||
484 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array | ||
485 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List | ||
486 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash | ||
487 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval | ||
488 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob | ||
489 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct | ||
490 | * | ||
491 | * @code | ||
492 | * Eina_Value *value = eina_value_new(EINA_VALUE_TYPE_INT); | ||
493 | * int x = 567; | ||
494 | * eina_value_set(value, 1234); | ||
495 | * eina_value_set(value, x); | ||
496 | * | ||
497 | * eina_value_flush(value); | ||
498 | * | ||
499 | * eina_value_setup(value, EINA_VALUE_TYPE_STRING); | ||
500 | * eina_value_set(value, "hello world!"); | ||
501 | * | ||
502 | * eina_value_free(value); | ||
503 | * @endcode | ||
504 | * | ||
505 | * @note for array member see eina_value_array_set() | ||
506 | * @note for list member see eina_value_list_set() | ||
507 | * @note for hash member see eina_value_hash_set() | ||
508 | * | ||
509 | * @see eina_value_get() | ||
510 | * @see eina_value_vset() | ||
511 | * @see eina_value_pset() | ||
512 | * | ||
513 | * @since 1.2 | ||
514 | */ | ||
515 | static inline Eina_Bool eina_value_set(Eina_Value *value, | ||
516 | ...) EINA_ARG_NONNULL(1); | ||
517 | |||
518 | /** | ||
519 | * @brief Get the generic value. | ||
520 | * @param value source value object | ||
521 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
522 | * | ||
523 | * The value is returned in the variable argument parameter, the | ||
524 | * actual value is type-dependent, but usually it will be what is | ||
525 | * stored inside the object. There shouldn't be any memory allocation, | ||
526 | * thus the contents should @b not be freed. | ||
527 | * | ||
528 | * The variable argument is dependent on chosen type. The list for | ||
529 | * basic types: | ||
530 | * | ||
531 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
532 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
533 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
534 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
535 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
536 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
537 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
538 | * @li EINA_VALUE_TYPE_INT: int* | ||
539 | * @li EINA_VALUE_TYPE_LONG: long* | ||
540 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
541 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
542 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
543 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
544 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
545 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array* | ||
546 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
547 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
548 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
549 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
550 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
551 | * | ||
552 | * @code | ||
553 | * Eina_Value *value = eina_value_new(EINA_VALUE_TYPE_INT); | ||
554 | * int x; | ||
555 | * const char *s; | ||
556 | * | ||
557 | * eina_value_set(value, 1234); | ||
558 | * eina_value_get(value, &x); | ||
559 | * | ||
560 | * eina_value_flush(value); | ||
561 | * | ||
562 | * eina_value_setup(value, EINA_VALUE_TYPE_STRING); | ||
563 | * eina_value_set(value, "hello world!"); | ||
564 | * eina_value_get(value, &s); | ||
565 | * | ||
566 | * eina_value_free(value); | ||
567 | * @endcode | ||
568 | * | ||
569 | * @note for array member see eina_value_array_get() | ||
570 | * @note for list member see eina_value_list_get() | ||
571 | * @note for hash member see eina_value_hash_get() | ||
572 | * | ||
573 | * @see eina_value_set() | ||
574 | * @see eina_value_vset() | ||
575 | * @see eina_value_pset() | ||
576 | * | ||
577 | * @since 1.2 | ||
578 | */ | ||
579 | static inline Eina_Bool eina_value_get(const Eina_Value *value, | ||
580 | ...) EINA_ARG_NONNULL(1); | ||
581 | |||
582 | /** | ||
583 | * @brief Set the generic value. | ||
584 | * @param value source value object | ||
585 | * @param args variable argument | ||
586 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
587 | * | ||
588 | * @note for array member see eina_value_array_vset() | ||
589 | * @note for list member see eina_value_list_vset() | ||
590 | * @note for hash member see eina_value_hash_vset() | ||
591 | * | ||
592 | * @see eina_value_vget() | ||
593 | * @see eina_value_set() | ||
594 | * @see eina_value_pset() | ||
595 | * | ||
596 | * @since 1.2 | ||
597 | */ | ||
598 | static inline Eina_Bool eina_value_vset(Eina_Value *value, | ||
599 | va_list args) EINA_ARG_NONNULL(1); | ||
600 | |||
601 | /** | ||
602 | * @brief Get the generic value. | ||
603 | * @param value source value object | ||
604 | * @param args variable argument | ||
605 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
606 | * | ||
607 | * The value is returned in the variable argument parameter, the | ||
608 | * actual value is type-dependent, but usually it will be what is | ||
609 | * stored inside the object. There shouldn't be any memory allocation, | ||
610 | * thus the contents should @b not be freed. | ||
611 | * | ||
612 | * @note for array member see eina_value_array_vget() | ||
613 | * @note for list member see eina_value_list_vget() | ||
614 | * @note for hash member see eina_value_hash_vget() | ||
615 | * | ||
616 | * @see eina_value_vset() | ||
617 | * @see eina_value_get() | ||
618 | * @see eina_value_pget() | ||
619 | * | ||
620 | * @since 1.2 | ||
621 | */ | ||
622 | static inline Eina_Bool eina_value_vget(const Eina_Value *value, | ||
623 | va_list args) EINA_ARG_NONNULL(1); | ||
624 | |||
625 | /** | ||
626 | * @brief Set the generic value from pointer. | ||
627 | * @param value source value object | ||
628 | * @param ptr pointer to specify the contents. | ||
629 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
630 | * | ||
631 | * The pointer type is dependent on chosen value type. The list for | ||
632 | * basic types: | ||
633 | * | ||
634 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
635 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
636 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
637 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
638 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
639 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
640 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
641 | * @li EINA_VALUE_TYPE_INT: int* | ||
642 | * @li EINA_VALUE_TYPE_LONG: long* | ||
643 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
644 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
645 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
646 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
647 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
648 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array* | ||
649 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
650 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
651 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
652 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
653 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
654 | * | ||
655 | * @note the pointer contents are written using the size defined by | ||
656 | * type. It can be larger than void* or uint64_t. | ||
657 | * | ||
658 | * @code | ||
659 | * Eina_Value *value = eina_value_new(EINA_VALUE_TYPE_INT); | ||
660 | * int x = 567; | ||
661 | * const char *s = "hello world!"; | ||
662 | * | ||
663 | * eina_value_pset(value, &x); | ||
664 | * | ||
665 | * eina_value_flush(value); | ||
666 | * | ||
667 | * eina_value_setup(value, EINA_VALUE_TYPE_STRING); | ||
668 | * eina_value_pset(value, &s); | ||
669 | * | ||
670 | * eina_value_free(value); | ||
671 | * @endcode | ||
672 | * | ||
673 | * @note for array member see eina_value_array_pset() | ||
674 | * @note for list member see eina_value_list_pset() | ||
675 | * @note for hash member see eina_value_hash_pset() | ||
676 | * | ||
677 | * @see eina_value_pget() | ||
678 | * @see eina_value_set() | ||
679 | * @see eina_value_vset() | ||
680 | * | ||
681 | * @since 1.2 | ||
682 | */ | ||
683 | static inline Eina_Bool eina_value_pset(Eina_Value *value, | ||
684 | const void *ptr) EINA_ARG_NONNULL(1, 2); | ||
685 | |||
686 | /** | ||
687 | * @brief Get the generic value to pointer. | ||
688 | * @param value source value object | ||
689 | * @param ptr pointer to receive the contents. | ||
690 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
691 | * | ||
692 | * The value is returned in pointer contents, the actual value is | ||
693 | * type-dependent, but usually it will be what is stored inside the | ||
694 | * object. There shouldn't be any memory allocation, thus the contents | ||
695 | * should @b not be freed. | ||
696 | * | ||
697 | * The pointer type is dependent on chosen value type. The list for | ||
698 | * basic types: | ||
699 | * | ||
700 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
701 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
702 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
703 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
704 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
705 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
706 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
707 | * @li EINA_VALUE_TYPE_INT: int* | ||
708 | * @li EINA_VALUE_TYPE_LONG: long* | ||
709 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
710 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
711 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
712 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
713 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
714 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array* | ||
715 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
716 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
717 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
718 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
719 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
720 | * | ||
721 | * @code | ||
722 | * Eina_Value *value = eina_value_new(EINA_VALUE_TYPE_INT); | ||
723 | * int x; | ||
724 | * const char *s; | ||
725 | * | ||
726 | * eina_value_set(value, 1234); | ||
727 | * eina_value_pget(value, &x); | ||
728 | * | ||
729 | * eina_value_flush(value); | ||
730 | * | ||
731 | * eina_value_setup(value, EINA_VALUE_TYPE_STRING); | ||
732 | * eina_value_set(value, "hello world!"); | ||
733 | * eina_value_pget(value, &s); | ||
734 | * | ||
735 | * eina_value_free(value); | ||
736 | * @endcode | ||
737 | * | ||
738 | * @note for array member see eina_value_array_get() | ||
739 | * @note for list member see eina_value_list_get() | ||
740 | * @note for hash member see eina_value_hash_get() | ||
741 | * | ||
742 | * @see eina_value_set() | ||
743 | * @see eina_value_vset() | ||
744 | * @see eina_value_pset() | ||
745 | * | ||
746 | * @since 1.2 | ||
747 | */ | ||
748 | static inline Eina_Bool eina_value_pget(const Eina_Value *value, | ||
749 | void *ptr) EINA_ARG_NONNULL(1, 2); | ||
750 | |||
751 | /** | ||
752 | * @brief Convert one value to another type. | ||
753 | * @param value source value object. | ||
754 | * @param convert destination value object. | ||
755 | * @return #EINA_TRUE if converted, #EINA_FALSE otherwise. | ||
756 | * | ||
757 | * Converts one value to another trying first @a value type | ||
758 | * @c convert_to() function. If unsuccessful, tries using @c convert_from() | ||
759 | * function in @a convert. | ||
760 | * | ||
761 | * Conversion functions are type defined, and the basic types can convert | ||
762 | * between themselves, but conversion is strict! That is, if | ||
763 | * converting from negative value to unsigned type, it will fail. It | ||
764 | * also fails on value overflow. | ||
765 | * | ||
766 | * It is recommended that all types implement at least convert to | ||
767 | * string, used by eina_value_to_string(). | ||
768 | * | ||
769 | * @note Both objects must have eina_value_setup() called on them beforehand! | ||
770 | * | ||
771 | * @since 1.2 | ||
772 | */ | ||
773 | EAPI Eina_Bool eina_value_convert(const Eina_Value *value, | ||
774 | Eina_Value *convert) EINA_ARG_NONNULL(1, 2); | ||
775 | |||
776 | |||
777 | /** | ||
778 | * @brief Convert value to string. | ||
779 | * @param value value object. | ||
780 | * @return newly allocated memory or @c NULL on failure. | ||
781 | * | ||
782 | * @see eina_value_convert() | ||
783 | * @since 1.2 | ||
784 | */ | ||
785 | EAPI char *eina_value_to_string(const Eina_Value *value) EINA_ARG_NONNULL(1); | ||
786 | |||
787 | /** | ||
788 | * @brief Query value type. | ||
789 | * @param value value object. | ||
790 | * @return type instance or @c NULL if type is invalid. | ||
791 | * | ||
792 | * Check if value type is valid and returns it. A type is invalid if | ||
793 | * it does not exist or if it is using a different version field. | ||
794 | * | ||
795 | * @see eina_value_type_check() | ||
796 | * | ||
797 | * @since 1.2 | ||
798 | */ | ||
799 | static inline const Eina_Value_Type *eina_value_type_get(const Eina_Value *value) EINA_PURE EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
800 | |||
801 | /** | ||
802 | * @} | ||
803 | */ | ||
804 | |||
805 | |||
806 | /** | ||
807 | * @defgroup Eina_Value_Array_Group Generic Value Array management | ||
808 | * | ||
809 | * @{ | ||
810 | */ | ||
811 | |||
812 | |||
813 | /** | ||
814 | * @typedef Eina_Value_Array | ||
815 | * Value type for #EINA_VALUE_TYPE_ARRAY | ||
816 | * | ||
817 | * @since 1.2 | ||
818 | */ | ||
819 | typedef struct _Eina_Value_Array Eina_Value_Array; | ||
820 | |||
821 | /** | ||
822 | * @struct _Eina_Value_Array | ||
823 | * Used to store the array and its subtype. | ||
824 | */ | ||
825 | struct _Eina_Value_Array | ||
826 | { | ||
827 | const Eina_Value_Type *subtype; /**< how to allocate and access items */ | ||
828 | unsigned int step; /**< how to grow the members array */ | ||
829 | Eina_Inarray *array; /**< the array that holds data, members are of subtype->value_size bytes. */ | ||
830 | }; | ||
831 | |||
832 | /** | ||
833 | * @brief Create generic value storage of type array. | ||
834 | * @param subtype how to manage this array members. | ||
835 | * @param step how to grow the members array. | ||
836 | * @return The new value or @c NULL on failure. | ||
837 | * | ||
838 | * Create a new generic value storage of type array. The members are | ||
839 | * managed using the description specified by @a subtype. | ||
840 | * | ||
841 | * On failure, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY or | ||
842 | * #EINA_ERROR_VALUE_FAILED is set. | ||
843 | * | ||
844 | * @note this creates from mempool and then uses | ||
845 | * eina_value_array_setup(). @see eina_value_free() @see | ||
846 | * eina_value_array_setup() | ||
847 | * | ||
848 | * @since 1.2 | ||
849 | */ | ||
850 | EAPI Eina_Value *eina_value_array_new(const Eina_Value_Type *subtype, | ||
851 | unsigned int step) EINA_ARG_NONNULL(1); | ||
852 | |||
853 | /** | ||
854 | * @brief Initialize generic value storage of type array. | ||
855 | * @param value value object | ||
856 | * @param subtype how to manage array members. | ||
857 | * @param step how to grow the members array. | ||
858 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
859 | * | ||
860 | * Initializes new generic value storage of type array with the given | ||
861 | * @a subtype. | ||
862 | * | ||
863 | * This is the same as calling eina_value_set() with | ||
864 | * #EINA_VALUE_TYPE_ARRAY followed by eina_value_pset() with the | ||
865 | * #Eina_Value_Array description configured. | ||
866 | * | ||
867 | * @note Existing contents are ignored! If the value was previously used, then | ||
868 | * use eina_value_flush() first. | ||
869 | * | ||
870 | * On failure, #EINA_FALSE is returned and #EINA_ERROR_OUT_OF_MEMORY | ||
871 | * or #EINA_ERROR_VALUE_FAILED is set. | ||
872 | * | ||
873 | * @see eina_value_flush() | ||
874 | * | ||
875 | * @since 1.2 | ||
876 | */ | ||
877 | static inline Eina_Bool eina_value_array_setup(Eina_Value *value, | ||
878 | const Eina_Value_Type *subtype, | ||
879 | unsigned int step) EINA_ARG_NONNULL(1, 2); | ||
880 | |||
881 | /** | ||
882 | * @brief Query number of elements in value of array type. | ||
883 | * @param value value object. | ||
884 | * @return number of child elements. | ||
885 | * @since 1.2 | ||
886 | */ | ||
887 | static inline unsigned int eina_value_array_count(const Eina_Value *value); | ||
888 | |||
889 | /** | ||
890 | * @brief Remove element at given position in value of array type. | ||
891 | * @param value value object. | ||
892 | * @param position index of the member | ||
893 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
894 | * @since 1.2 | ||
895 | */ | ||
896 | static inline Eina_Bool eina_value_array_remove(Eina_Value *value, | ||
897 | unsigned int position) EINA_ARG_NONNULL(1); | ||
898 | |||
899 | /** | ||
900 | * @brief Set the generic value in an array member. | ||
901 | * @param value source value object | ||
902 | * @param position index of the member | ||
903 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
904 | * | ||
905 | * The variable argument is dependent on chosen subtype. The list for | ||
906 | * basic types: | ||
907 | * | ||
908 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char | ||
909 | * @li EINA_VALUE_TYPE_USHORT: unsigned short | ||
910 | * @li EINA_VALUE_TYPE_UINT: unsigned int | ||
911 | * @li EINA_VALUE_TYPE_ULONG: unsigned long | ||
912 | * @li EINA_VALUE_TYPE_UINT64: uint64_t | ||
913 | * @li EINA_VALUE_TYPE_CHAR: char | ||
914 | * @li EINA_VALUE_TYPE_SHORT: short | ||
915 | * @li EINA_VALUE_TYPE_INT: int | ||
916 | * @li EINA_VALUE_TYPE_LONG: long | ||
917 | * @li EINA_VALUE_TYPE_INT64: int64_t | ||
918 | * @li EINA_VALUE_TYPE_FLOAT: float | ||
919 | * @li EINA_VALUE_TYPE_DOUBLE: double | ||
920 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char * | ||
921 | * @li EINA_VALUE_TYPE_STRING: const char * | ||
922 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array | ||
923 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List | ||
924 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash | ||
925 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval | ||
926 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob | ||
927 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct | ||
928 | * | ||
929 | * @code | ||
930 | * Eina_Value *value = eina_value_array_new(EINA_VALUE_TYPE_INT, 0); | ||
931 | * int x; | ||
932 | * | ||
933 | * eina_value_array_append(value, 1234); | ||
934 | * eina_value_array_set(value, 0, 5678); | ||
935 | * eina_value_array_get(value, 0, &x); | ||
936 | * eina_value_free(value); | ||
937 | * @endcode | ||
938 | * | ||
939 | * @see eina_value_array_get() | ||
940 | * @see eina_value_array_vset() | ||
941 | * @see eina_value_array_pset() | ||
942 | * @see eina_value_array_insert() | ||
943 | * @see eina_value_array_vinsert() | ||
944 | * @see eina_value_array_pinsert() | ||
945 | * @see eina_value_array_append() | ||
946 | * @see eina_value_array_vappend() | ||
947 | * @see eina_value_array_pappend() | ||
948 | * | ||
949 | * @since 1.2 | ||
950 | */ | ||
951 | static inline Eina_Bool eina_value_array_set(Eina_Value *value, | ||
952 | unsigned int position, | ||
953 | ...) EINA_ARG_NONNULL(1); | ||
954 | |||
955 | /** | ||
956 | * @brief Get the generic value from an array member. | ||
957 | * @param value source value object | ||
958 | * @param position index of the member | ||
959 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
960 | * | ||
961 | * The value is returned in the variable argument parameter, and the | ||
962 | * actual value is type-dependent, but usually it will be what is | ||
963 | * stored inside the object. There shouldn't be any memory allocation; | ||
964 | * thus the contents should @b not be freed. | ||
965 | * | ||
966 | * The variable argument is dependent on chosen subtype. The list for | ||
967 | * basic types: | ||
968 | * | ||
969 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
970 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
971 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
972 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
973 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
974 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
975 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
976 | * @li EINA_VALUE_TYPE_INT: int* | ||
977 | * @li EINA_VALUE_TYPE_LONG: long* | ||
978 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
979 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
980 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
981 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
982 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
983 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array* | ||
984 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
985 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
986 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
987 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
988 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
989 | * | ||
990 | * @code | ||
991 | * Eina_Value *value = eina_value_array_new(EINA_VALUE_TYPE_INT, 0); | ||
992 | * int x; | ||
993 | * | ||
994 | * eina_value_array_append(value, 1234); | ||
995 | * eina_value_array_get(value, 0, &x); | ||
996 | * eina_value_free(value); | ||
997 | * @endcode | ||
998 | * | ||
999 | * @see eina_value_array_set() | ||
1000 | * @see eina_value_array_vset() | ||
1001 | * @see eina_value_array_pset() | ||
1002 | * | ||
1003 | * @since 1.2 | ||
1004 | */ | ||
1005 | static inline Eina_Bool eina_value_array_get(const Eina_Value *value, | ||
1006 | unsigned int position, | ||
1007 | ...) EINA_ARG_NONNULL(1); | ||
1008 | |||
1009 | /** | ||
1010 | * @brief Insert a generic value in an array member position. | ||
1011 | * @param value source value object | ||
1012 | * @param position index of the member | ||
1013 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1014 | * | ||
1015 | * The variable argument is dependent on chosen subtype. The list for | ||
1016 | * basic types: | ||
1017 | * | ||
1018 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char | ||
1019 | * @li EINA_VALUE_TYPE_USHORT: unsigned short | ||
1020 | * @li EINA_VALUE_TYPE_UINT: unsigned int | ||
1021 | * @li EINA_VALUE_TYPE_ULONG: unsigned long | ||
1022 | * @li EINA_VALUE_TYPE_UINT64: uint64_t | ||
1023 | * @li EINA_VALUE_TYPE_CHAR: char | ||
1024 | * @li EINA_VALUE_TYPE_SHORT: short | ||
1025 | * @li EINA_VALUE_TYPE_INT: int | ||
1026 | * @li EINA_VALUE_TYPE_LONG: long | ||
1027 | * @li EINA_VALUE_TYPE_INT64: int64_t | ||
1028 | * @li EINA_VALUE_TYPE_FLOAT: float | ||
1029 | * @li EINA_VALUE_TYPE_DOUBLE: double | ||
1030 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char * | ||
1031 | * @li EINA_VALUE_TYPE_STRING: const char * | ||
1032 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array | ||
1033 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List | ||
1034 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash | ||
1035 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval | ||
1036 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob | ||
1037 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct | ||
1038 | * | ||
1039 | * @code | ||
1040 | * Eina_Value *value = eina_value_array_new(EINA_VALUE_TYPE_INT, 0); | ||
1041 | * int x; | ||
1042 | * | ||
1043 | * eina_value_array_insert(value, 0, 1234); | ||
1044 | * eina_value_array_get(value, 0, &x); | ||
1045 | * eina_value_free(value); | ||
1046 | * @endcode | ||
1047 | * | ||
1048 | * @see eina_value_array_set() | ||
1049 | * @see eina_value_array_get() | ||
1050 | * @see eina_value_array_vset() | ||
1051 | * @see eina_value_array_pset() | ||
1052 | * @see eina_value_array_vinsert() | ||
1053 | * @see eina_value_array_pinsert() | ||
1054 | * @see eina_value_array_append() | ||
1055 | * @see eina_value_array_vappend() | ||
1056 | * @see eina_value_array_pappend() | ||
1057 | * | ||
1058 | * @since 1.2 | ||
1059 | */ | ||
1060 | static inline Eina_Bool eina_value_array_insert(Eina_Value *value, | ||
1061 | unsigned int position, | ||
1062 | ...) EINA_ARG_NONNULL(1); | ||
1063 | |||
1064 | |||
1065 | /** | ||
1066 | * @brief Append a generic value in an array. | ||
1067 | * @param value source value object | ||
1068 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1069 | * | ||
1070 | * The variable argument is dependent on chosen subtype. The list for | ||
1071 | * basic types: | ||
1072 | * | ||
1073 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char | ||
1074 | * @li EINA_VALUE_TYPE_USHORT: unsigned short | ||
1075 | * @li EINA_VALUE_TYPE_UINT: unsigned int | ||
1076 | * @li EINA_VALUE_TYPE_ULONG: unsigned long | ||
1077 | * @li EINA_VALUE_TYPE_UINT64: uint64_t | ||
1078 | * @li EINA_VALUE_TYPE_CHAR: char | ||
1079 | * @li EINA_VALUE_TYPE_SHORT: short | ||
1080 | * @li EINA_VALUE_TYPE_INT: int | ||
1081 | * @li EINA_VALUE_TYPE_LONG: long | ||
1082 | * @li EINA_VALUE_TYPE_INT64: int64_t | ||
1083 | * @li EINA_VALUE_TYPE_FLOAT: float | ||
1084 | * @li EINA_VALUE_TYPE_DOUBLE: double | ||
1085 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char * | ||
1086 | * @li EINA_VALUE_TYPE_STRING: const char * | ||
1087 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array | ||
1088 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List | ||
1089 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash | ||
1090 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval | ||
1091 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob | ||
1092 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct | ||
1093 | * | ||
1094 | * @code | ||
1095 | * Eina_Value *value = eina_value_array_new(EINA_VALUE_TYPE_INT, 0); | ||
1096 | * int x; | ||
1097 | * | ||
1098 | * eina_value_array_append(value, 1234); | ||
1099 | * eina_value_array_get(value, 0, &x); | ||
1100 | * eina_value_free(value); | ||
1101 | * @endcode | ||
1102 | * | ||
1103 | * @see eina_value_array_set() | ||
1104 | * @see eina_value_array_get() | ||
1105 | * @see eina_value_array_vset() | ||
1106 | * @see eina_value_array_pset() | ||
1107 | * @see eina_value_array_vinsert() | ||
1108 | * @see eina_value_array_pinsert() | ||
1109 | * @see eina_value_array_append() | ||
1110 | * @see eina_value_array_vappend() | ||
1111 | * @see eina_value_array_pappend() | ||
1112 | * | ||
1113 | * @since 1.2 | ||
1114 | */ | ||
1115 | static inline Eina_Bool eina_value_array_append(Eina_Value *value, | ||
1116 | ...) EINA_ARG_NONNULL(1); | ||
1117 | |||
1118 | /** | ||
1119 | * @brief Set a generic value to an array member. | ||
1120 | * @param value source value object | ||
1121 | * @param position index of the member | ||
1122 | * @param args variable argument | ||
1123 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1124 | * @see eina_value_array_set() | ||
1125 | * @see eina_value_array_get() | ||
1126 | * @see eina_value_array_pset() | ||
1127 | * @see eina_value_array_insert() | ||
1128 | * @see eina_value_array_vinsert() | ||
1129 | * @see eina_value_array_pinsert() | ||
1130 | * @see eina_value_array_append() | ||
1131 | * @see eina_value_array_vappend() | ||
1132 | * @see eina_value_array_pappend() | ||
1133 | * | ||
1134 | * @since 1.2 | ||
1135 | */ | ||
1136 | static inline Eina_Bool eina_value_array_vset(Eina_Value *value, | ||
1137 | unsigned int position, | ||
1138 | va_list args) EINA_ARG_NONNULL(1); | ||
1139 | |||
1140 | /** | ||
1141 | * @brief Get the generic value from an array member. | ||
1142 | * @param value source value object | ||
1143 | * @param position index of the member | ||
1144 | * @param args variable argument | ||
1145 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1146 | * | ||
1147 | * The value is returned in the variable argument parameter, the | ||
1148 | * actual value is type-dependent, but usually it will be what is | ||
1149 | * stored inside the object. There shouldn't be any memory allocation, | ||
1150 | * thus the contents should @b not be freed. | ||
1151 | * | ||
1152 | * @see eina_value_array_vset() | ||
1153 | * @see eina_value_array_get() | ||
1154 | * @see eina_value_array_pget() | ||
1155 | * | ||
1156 | * @since 1.2 | ||
1157 | */ | ||
1158 | static inline Eina_Bool eina_value_array_vget(const Eina_Value *value, | ||
1159 | unsigned int position, | ||
1160 | va_list args) EINA_ARG_NONNULL(1); | ||
1161 | /** | ||
1162 | * @brief Insert a generic value to an array member position. | ||
1163 | * @param value source value object | ||
1164 | * @param position index of the member | ||
1165 | * @param args variable argument | ||
1166 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1167 | * @see eina_value_array_set() | ||
1168 | * @see eina_value_array_get() | ||
1169 | * @see eina_value_array_vset() | ||
1170 | * @see eina_value_array_pset() | ||
1171 | * @see eina_value_array_insert() | ||
1172 | * @see eina_value_array_pinsert() | ||
1173 | * @see eina_value_array_append() | ||
1174 | * @see eina_value_array_vappend() | ||
1175 | * @see eina_value_array_pappend() | ||
1176 | * | ||
1177 | * @since 1.2 | ||
1178 | */ | ||
1179 | static inline Eina_Bool eina_value_array_vinsert(Eina_Value *value, | ||
1180 | unsigned int position, | ||
1181 | va_list args) EINA_ARG_NONNULL(1); | ||
1182 | |||
1183 | /** | ||
1184 | * @brief Append a generic value to an array. | ||
1185 | * @param value source value object | ||
1186 | * @param args variable argument | ||
1187 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1188 | * @see eina_value_array_set() | ||
1189 | * @see eina_value_array_get() | ||
1190 | * @see eina_value_array_vget() | ||
1191 | * @see eina_value_array_pset() | ||
1192 | * @see eina_value_array_insert() | ||
1193 | * @see eina_value_array_vinsert() | ||
1194 | * @see eina_value_array_pinsert() | ||
1195 | * @see eina_value_array_append() | ||
1196 | * @see eina_value_array_pappend() | ||
1197 | * | ||
1198 | * @since 1.2 | ||
1199 | */ | ||
1200 | static inline Eina_Bool eina_value_array_vappend(Eina_Value *value, | ||
1201 | va_list args) EINA_ARG_NONNULL(1); | ||
1202 | |||
1203 | |||
1204 | /** | ||
1205 | * @brief Set a generic value to an array member from a pointer. | ||
1206 | * @param value source value object | ||
1207 | * @param position index of the member | ||
1208 | * @param ptr pointer to specify the contents. | ||
1209 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1210 | * | ||
1211 | * The pointer type is dependent on chosen value type. The list for | ||
1212 | * basic types: | ||
1213 | * | ||
1214 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
1215 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
1216 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
1217 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
1218 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
1219 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
1220 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
1221 | * @li EINA_VALUE_TYPE_INT: int* | ||
1222 | * @li EINA_VALUE_TYPE_LONG: long* | ||
1223 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
1224 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
1225 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
1226 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
1227 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
1228 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array* | ||
1229 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
1230 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
1231 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
1232 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
1233 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
1234 | * | ||
1235 | * @note the pointer contents are written using the size defined by | ||
1236 | * type. It can be larger than void* or uint64_t. | ||
1237 | * | ||
1238 | * @code | ||
1239 | * Eina_Value *value = eina_value_array_new(EINA_VALUE_TYPE_INT, 0); | ||
1240 | * int x = 1234; | ||
1241 | * | ||
1242 | * eina_value_array_append(value, 1234); | ||
1243 | * eina_value_array_pset(value, 0, &x); | ||
1244 | * eina_value_array_pget(value, 0, &x); | ||
1245 | * eina_value_free(value); | ||
1246 | * @endcode | ||
1247 | * | ||
1248 | * @see eina_value_array_set() | ||
1249 | * @see eina_value_array_get() | ||
1250 | * @see eina_value_array_vset() | ||
1251 | * @see eina_value_array_insert() | ||
1252 | * @see eina_value_array_vinsert() | ||
1253 | * @see eina_value_array_pinsert() | ||
1254 | * @see eina_value_array_append() | ||
1255 | * @see eina_value_array_vappend() | ||
1256 | * @see eina_value_array_pappend() | ||
1257 | * | ||
1258 | * @since 1.2 | ||
1259 | */ | ||
1260 | static inline Eina_Bool eina_value_array_pset(Eina_Value *value, | ||
1261 | unsigned int position, | ||
1262 | const void *ptr) EINA_ARG_NONNULL(1, 3); | ||
1263 | |||
1264 | /** | ||
1265 | * @brief Retrieve a generic value into a pointer from an array member. | ||
1266 | * @param value source value object | ||
1267 | * @param position index of the member | ||
1268 | * @param ptr pointer to receive the contents. | ||
1269 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1270 | * | ||
1271 | * The value is returned in pointer contents, the actual value is | ||
1272 | * type-dependent, but usually it will be what is stored inside the | ||
1273 | * object. There shouldn't be any memory allocation, thus the contents | ||
1274 | * should @b not be freed. | ||
1275 | * | ||
1276 | * The pointer type is dependent on chosen value type. The list for | ||
1277 | * basic types: | ||
1278 | * | ||
1279 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
1280 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
1281 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
1282 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
1283 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
1284 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
1285 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
1286 | * @li EINA_VALUE_TYPE_INT: int* | ||
1287 | * @li EINA_VALUE_TYPE_LONG: long* | ||
1288 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
1289 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
1290 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
1291 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
1292 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
1293 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array* | ||
1294 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
1295 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
1296 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
1297 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
1298 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
1299 | * | ||
1300 | * @code | ||
1301 | * Eina_Value *value = eina_value_array_new(EINA_VALUE_TYPE_INT, 0); | ||
1302 | * int x; | ||
1303 | * | ||
1304 | * eina_value_array_append(value, 1234); | ||
1305 | * eina_value_array_pget(value, 0, &x); | ||
1306 | * eina_value_free(value); | ||
1307 | * @endcode | ||
1308 | * | ||
1309 | * @see eina_value_array_set() | ||
1310 | * @see eina_value_array_vset() | ||
1311 | * @see eina_value_array_pset() | ||
1312 | * | ||
1313 | * @since 1.2 | ||
1314 | */ | ||
1315 | static inline Eina_Bool eina_value_array_pget(const Eina_Value *value, | ||
1316 | unsigned int position, | ||
1317 | void *ptr) EINA_ARG_NONNULL(1, 3); | ||
1318 | |||
1319 | /** | ||
1320 | * @brief Insert a generic value to an array member position from a pointer. | ||
1321 | * @param value source value object | ||
1322 | * @param position index of the member | ||
1323 | * @param ptr pointer to specify the contents. | ||
1324 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1325 | * | ||
1326 | * The pointer type is dependent on chosen value type. The list for | ||
1327 | * basic types: | ||
1328 | * | ||
1329 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
1330 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
1331 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
1332 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
1333 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
1334 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
1335 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
1336 | * @li EINA_VALUE_TYPE_INT: int* | ||
1337 | * @li EINA_VALUE_TYPE_LONG: long* | ||
1338 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
1339 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
1340 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
1341 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
1342 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
1343 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array* | ||
1344 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
1345 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
1346 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
1347 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
1348 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
1349 | * | ||
1350 | * @note the pointer contents are written using the size defined by | ||
1351 | * type. It can be larger than void* or uint64_t. | ||
1352 | * | ||
1353 | * @code | ||
1354 | * Eina_Value *value = eina_value_array_new(EINA_VALUE_TYPE_INT, 0); | ||
1355 | * int x = 1234; | ||
1356 | * | ||
1357 | * eina_value_array_pinsert(value, 0, &x); | ||
1358 | * eina_value_array_pget(value, 0, &x); | ||
1359 | * eina_value_free(value); | ||
1360 | * @endcode | ||
1361 | * | ||
1362 | * @see eina_value_array_set() | ||
1363 | * @see eina_value_array_get() | ||
1364 | * @see eina_value_array_vset() | ||
1365 | * @see eina_value_array_insert() | ||
1366 | * @see eina_value_array_vinsert() | ||
1367 | * @see eina_value_array_pinsert() | ||
1368 | * @see eina_value_array_append() | ||
1369 | * @see eina_value_array_vappend() | ||
1370 | * @see eina_value_array_pappend() | ||
1371 | * | ||
1372 | * @since 1.2 | ||
1373 | */ | ||
1374 | static inline Eina_Bool eina_value_array_pinsert(Eina_Value *value, | ||
1375 | unsigned int position, | ||
1376 | const void *ptr) EINA_ARG_NONNULL(1); | ||
1377 | |||
1378 | /** | ||
1379 | * @brief Append a generic value to an array from a pointer. | ||
1380 | * @param value source value object | ||
1381 | * @param ptr pointer to specify the contents. | ||
1382 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1383 | * | ||
1384 | * The pointer type is dependent on chosen value type. The list for | ||
1385 | * basic types: | ||
1386 | * | ||
1387 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
1388 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
1389 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
1390 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
1391 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
1392 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
1393 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
1394 | * @li EINA_VALUE_TYPE_INT: int* | ||
1395 | * @li EINA_VALUE_TYPE_LONG: long* | ||
1396 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
1397 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
1398 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
1399 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
1400 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
1401 | * @li EINA_VALUE_TYPE_ARRAY: Eina_Value_Array* | ||
1402 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
1403 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
1404 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
1405 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
1406 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
1407 | * | ||
1408 | * @note the pointer contents are written using the size defined by | ||
1409 | * type. It can be larger than void* or uint64_t. | ||
1410 | * | ||
1411 | * @code | ||
1412 | * Eina_Value *value = eina_value_array_new(EINA_VALUE_TYPE_INT, 0); | ||
1413 | * int x = 1234; | ||
1414 | * | ||
1415 | * eina_value_array_pappend(value, &x); | ||
1416 | * eina_value_array_pget(value, 0, &x); | ||
1417 | * eina_value_free(value); | ||
1418 | * @endcode | ||
1419 | * | ||
1420 | * @see eina_value_array_set() | ||
1421 | * @see eina_value_array_get() | ||
1422 | * @see eina_value_array_vset() | ||
1423 | * @see eina_value_array_insert() | ||
1424 | * @see eina_value_array_vinsert() | ||
1425 | * @see eina_value_array_pinsert() | ||
1426 | * @see eina_value_array_append() | ||
1427 | * @see eina_value_array_vappend() | ||
1428 | * @see eina_value_array_pappend() | ||
1429 | * | ||
1430 | * @since 1.2 | ||
1431 | */ | ||
1432 | static inline Eina_Bool eina_value_array_pappend(Eina_Value *value, | ||
1433 | const void *ptr) EINA_ARG_NONNULL(1); | ||
1434 | |||
1435 | /** | ||
1436 | * @} | ||
1437 | */ | ||
1438 | |||
1439 | |||
1440 | /** | ||
1441 | * @defgroup Eina_Value_List_Group Generic Value List management | ||
1442 | * | ||
1443 | * @{ | ||
1444 | */ | ||
1445 | |||
1446 | |||
1447 | /** | ||
1448 | * @typedef Eina_Value_List | ||
1449 | * Value type for #EINA_VALUE_TYPE_LIST | ||
1450 | * | ||
1451 | * @since 1.2 | ||
1452 | */ | ||
1453 | typedef struct _Eina_Value_List Eina_Value_List; | ||
1454 | |||
1455 | /** | ||
1456 | * @struct _Eina_Value_List | ||
1457 | * Used to store the list and its subtype. | ||
1458 | */ | ||
1459 | struct _Eina_Value_List | ||
1460 | { | ||
1461 | const Eina_Value_Type *subtype; /**< how to allocate and access items */ | ||
1462 | Eina_List *list; /**< the list that holds data, members are of subtype->value_size bytes. */ | ||
1463 | }; | ||
1464 | |||
1465 | /** | ||
1466 | * @brief Create generic value storage of type list. | ||
1467 | * @param subtype how to manage this list members. | ||
1468 | * @return The new value or @c NULL on failure. | ||
1469 | * | ||
1470 | * Create a new generic value storage of type list. The members are | ||
1471 | * managed using the description specified by @a subtype. | ||
1472 | * | ||
1473 | * On failure, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY or | ||
1474 | * #EINA_ERROR_VALUE_FAILED is set. | ||
1475 | * | ||
1476 | * @note this creates from mempool and then uses | ||
1477 | * eina_value_list_setup(). | ||
1478 | * | ||
1479 | * @see eina_value_free() | ||
1480 | * @see eina_value_list_setup() | ||
1481 | * | ||
1482 | * @since 1.2 | ||
1483 | */ | ||
1484 | EAPI Eina_Value *eina_value_list_new(const Eina_Value_Type *subtype) EINA_ARG_NONNULL(1); | ||
1485 | |||
1486 | /** | ||
1487 | * @brief Initialize generic value storage of type list. | ||
1488 | * @param value value object | ||
1489 | * @param subtype how to manage this list members. | ||
1490 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1491 | * | ||
1492 | * Initializes new generic value storage of type list with the given | ||
1493 | * @a subtype. | ||
1494 | * | ||
1495 | * This is the same as calling eina_value_set() with | ||
1496 | * #EINA_VALUE_TYPE_LIST followed by eina_value_pset() with the | ||
1497 | * #Eina_Value_List description configured. | ||
1498 | * | ||
1499 | * @note Existing contents are ignored! If the value was previously used, then | ||
1500 | * use eina_value_flush() first. | ||
1501 | * | ||
1502 | * On failure, #EINA_FALSE is returned and #EINA_ERROR_OUT_OF_MEMORY | ||
1503 | * or #EINA_ERROR_VALUE_FAILED is set. | ||
1504 | * | ||
1505 | * @see eina_value_flush() | ||
1506 | * | ||
1507 | * @since 1.2 | ||
1508 | */ | ||
1509 | static inline Eina_Bool eina_value_list_setup(Eina_Value *value, | ||
1510 | const Eina_Value_Type *subtype) EINA_ARG_NONNULL(1, 2); | ||
1511 | |||
1512 | /** | ||
1513 | * @brief Query number of elements in value of list type. | ||
1514 | * @param value value object. | ||
1515 | * @return number of child elements. | ||
1516 | * @since 1.2 | ||
1517 | */ | ||
1518 | static inline unsigned int eina_value_list_count(const Eina_Value *value); | ||
1519 | |||
1520 | /** | ||
1521 | * @brief Remove element at given position in value of list type. | ||
1522 | * @param value value object. | ||
1523 | * @param position index of the member | ||
1524 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1525 | * @since 1.2 | ||
1526 | */ | ||
1527 | static inline Eina_Bool eina_value_list_remove(Eina_Value *value, | ||
1528 | unsigned int position) EINA_ARG_NONNULL(1); | ||
1529 | |||
1530 | /** | ||
1531 | * @brief Set the generic value in an list member. | ||
1532 | * @param value source value object | ||
1533 | * @param position index of the member | ||
1534 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1535 | * | ||
1536 | * The variable argument is dependent on chosen subtype. The list for | ||
1537 | * basic types: | ||
1538 | * | ||
1539 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char | ||
1540 | * @li EINA_VALUE_TYPE_USHORT: unsigned short | ||
1541 | * @li EINA_VALUE_TYPE_UINT: unsigned int | ||
1542 | * @li EINA_VALUE_TYPE_ULONG: unsigned long | ||
1543 | * @li EINA_VALUE_TYPE_UINT64: uint64_t | ||
1544 | * @li EINA_VALUE_TYPE_CHAR: char | ||
1545 | * @li EINA_VALUE_TYPE_SHORT: short | ||
1546 | * @li EINA_VALUE_TYPE_INT: int | ||
1547 | * @li EINA_VALUE_TYPE_LONG: long | ||
1548 | * @li EINA_VALUE_TYPE_INT64: int64_t | ||
1549 | * @li EINA_VALUE_TYPE_FLOAT: float | ||
1550 | * @li EINA_VALUE_TYPE_DOUBLE: double | ||
1551 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char * | ||
1552 | * @li EINA_VALUE_TYPE_STRING: const char * | ||
1553 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List | ||
1554 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash | ||
1555 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval | ||
1556 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob | ||
1557 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct | ||
1558 | * | ||
1559 | * @code | ||
1560 | * Eina_Value *value = eina_value_list_new(EINA_VALUE_TYPE_INT); | ||
1561 | * int x; | ||
1562 | * | ||
1563 | * eina_value_list_append(value, 1234); | ||
1564 | * eina_value_list_set(value, 0, 5678); | ||
1565 | * eina_value_list_get(value, 0, &x); | ||
1566 | * eina_value_free(value); | ||
1567 | * @endcode | ||
1568 | * | ||
1569 | * @see eina_value_list_get() | ||
1570 | * @see eina_value_list_vset() | ||
1571 | * @see eina_value_list_pset() | ||
1572 | * @see eina_value_list_insert() | ||
1573 | * @see eina_value_list_vinsert() | ||
1574 | * @see eina_value_list_pinsert() | ||
1575 | * @see eina_value_list_append() | ||
1576 | * @see eina_value_list_vappend() | ||
1577 | * @see eina_value_list_pappend() | ||
1578 | * | ||
1579 | * @since 1.2 | ||
1580 | */ | ||
1581 | static inline Eina_Bool eina_value_list_set(Eina_Value *value, | ||
1582 | unsigned int position, | ||
1583 | ...) EINA_ARG_NONNULL(1); | ||
1584 | |||
1585 | /** | ||
1586 | * @brief Get the generic value from an list member. | ||
1587 | * @param value source value object | ||
1588 | * @param position index of the member | ||
1589 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1590 | * | ||
1591 | * The value is returned in the variable argument parameter, the | ||
1592 | * actual value is type-dependent, but usually it will be what is | ||
1593 | * stored inside the object. There shouldn't be any memory allocation, | ||
1594 | * thus the contents should @b not be freed. | ||
1595 | * | ||
1596 | * The variable argument is dependent on chosen subtype. The list for | ||
1597 | * basic types: | ||
1598 | * | ||
1599 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
1600 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
1601 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
1602 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
1603 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
1604 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
1605 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
1606 | * @li EINA_VALUE_TYPE_INT: int* | ||
1607 | * @li EINA_VALUE_TYPE_LONG: long* | ||
1608 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
1609 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
1610 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
1611 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
1612 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
1613 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
1614 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
1615 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
1616 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
1617 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
1618 | * | ||
1619 | * @code | ||
1620 | * Eina_Value *value = eina_value_list_new(EINA_VALUE_TYPE_INT); | ||
1621 | * int x; | ||
1622 | * | ||
1623 | * eina_value_list_append(value, 1234); | ||
1624 | * eina_value_list_get(value, 0, &x); | ||
1625 | * eina_value_free(value); | ||
1626 | * @endcode | ||
1627 | * | ||
1628 | * @see eina_value_list_set() | ||
1629 | * @see eina_value_list_vset() | ||
1630 | * @see eina_value_list_pset() | ||
1631 | * | ||
1632 | * @since 1.2 | ||
1633 | */ | ||
1634 | static inline Eina_Bool eina_value_list_get(const Eina_Value *value, | ||
1635 | unsigned int position, | ||
1636 | ...) EINA_ARG_NONNULL(1); | ||
1637 | |||
1638 | /** | ||
1639 | * @brief Insert the generic value in an list member position. | ||
1640 | * @param value source value object | ||
1641 | * @param position index of the member | ||
1642 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1643 | * | ||
1644 | * The variable argument is dependent on chosen subtype. The list for | ||
1645 | * basic types: | ||
1646 | * | ||
1647 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char | ||
1648 | * @li EINA_VALUE_TYPE_USHORT: unsigned short | ||
1649 | * @li EINA_VALUE_TYPE_UINT: unsigned int | ||
1650 | * @li EINA_VALUE_TYPE_ULONG: unsigned long | ||
1651 | * @li EINA_VALUE_TYPE_UINT64: uint64_t | ||
1652 | * @li EINA_VALUE_TYPE_CHAR: char | ||
1653 | * @li EINA_VALUE_TYPE_SHORT: short | ||
1654 | * @li EINA_VALUE_TYPE_INT: int | ||
1655 | * @li EINA_VALUE_TYPE_LONG: long | ||
1656 | * @li EINA_VALUE_TYPE_INT64: int64_t | ||
1657 | * @li EINA_VALUE_TYPE_FLOAT: float | ||
1658 | * @li EINA_VALUE_TYPE_DOUBLE: double | ||
1659 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char * | ||
1660 | * @li EINA_VALUE_TYPE_STRING: const char * | ||
1661 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List | ||
1662 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash | ||
1663 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval | ||
1664 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob | ||
1665 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct | ||
1666 | * | ||
1667 | * @code | ||
1668 | * Eina_Value *value = eina_value_list_new(EINA_VALUE_TYPE_INT); | ||
1669 | * int x; | ||
1670 | * | ||
1671 | * eina_value_list_insert(value, 0, 1234); | ||
1672 | * eina_value_list_get(value, 0, &x); | ||
1673 | * eina_value_free(value); | ||
1674 | * @endcode | ||
1675 | * | ||
1676 | * @see eina_value_list_set() | ||
1677 | * @see eina_value_list_get() | ||
1678 | * @see eina_value_list_vset() | ||
1679 | * @see eina_value_list_pset() | ||
1680 | * @see eina_value_list_vinsert() | ||
1681 | * @see eina_value_list_pinsert() | ||
1682 | * @see eina_value_list_append() | ||
1683 | * @see eina_value_list_vappend() | ||
1684 | * @see eina_value_list_pappend() | ||
1685 | * | ||
1686 | * @since 1.2 | ||
1687 | */ | ||
1688 | static inline Eina_Bool eina_value_list_insert(Eina_Value *value, | ||
1689 | unsigned int position, | ||
1690 | ...) EINA_ARG_NONNULL(1); | ||
1691 | |||
1692 | |||
1693 | /** | ||
1694 | * @brief Append the generic value in an list. | ||
1695 | * @param value source value object | ||
1696 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1697 | * | ||
1698 | * The variable argument is dependent on chosen subtype. The list for | ||
1699 | * basic types: | ||
1700 | * | ||
1701 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char | ||
1702 | * @li EINA_VALUE_TYPE_USHORT: unsigned short | ||
1703 | * @li EINA_VALUE_TYPE_UINT: unsigned int | ||
1704 | * @li EINA_VALUE_TYPE_ULONG: unsigned long | ||
1705 | * @li EINA_VALUE_TYPE_UINT64: uint64_t | ||
1706 | * @li EINA_VALUE_TYPE_CHAR: char | ||
1707 | * @li EINA_VALUE_TYPE_SHORT: short | ||
1708 | * @li EINA_VALUE_TYPE_INT: int | ||
1709 | * @li EINA_VALUE_TYPE_LONG: long | ||
1710 | * @li EINA_VALUE_TYPE_INT64: int64_t | ||
1711 | * @li EINA_VALUE_TYPE_FLOAT: float | ||
1712 | * @li EINA_VALUE_TYPE_DOUBLE: double | ||
1713 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char * | ||
1714 | * @li EINA_VALUE_TYPE_STRING: const char * | ||
1715 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List | ||
1716 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash | ||
1717 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval | ||
1718 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob | ||
1719 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct | ||
1720 | * | ||
1721 | * @code | ||
1722 | * Eina_Value *value = eina_value_list_new(EINA_VALUE_TYPE_INT); | ||
1723 | * int x; | ||
1724 | * | ||
1725 | * eina_value_list_append(value, 1234); | ||
1726 | * eina_value_list_get(value, 0, &x); | ||
1727 | * eina_value_free(value); | ||
1728 | * @endcode | ||
1729 | * | ||
1730 | * @see eina_value_list_set() | ||
1731 | * @see eina_value_list_get() | ||
1732 | * @see eina_value_list_vset() | ||
1733 | * @see eina_value_list_pset() | ||
1734 | * @see eina_value_list_vinsert() | ||
1735 | * @see eina_value_list_pinsert() | ||
1736 | * @see eina_value_list_append() | ||
1737 | * @see eina_value_list_vappend() | ||
1738 | * @see eina_value_list_pappend() | ||
1739 | * | ||
1740 | * @since 1.2 | ||
1741 | */ | ||
1742 | static inline Eina_Bool eina_value_list_append(Eina_Value *value, | ||
1743 | ...) EINA_ARG_NONNULL(1); | ||
1744 | |||
1745 | /** | ||
1746 | * @brief Set the generic value in an list member. | ||
1747 | * @param value source value object | ||
1748 | * @param position index of the member | ||
1749 | * @param args variable argument | ||
1750 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1751 | * @see eina_value_list_set() | ||
1752 | * @see eina_value_list_get() | ||
1753 | * @see eina_value_list_pset() | ||
1754 | * @see eina_value_list_insert() | ||
1755 | * @see eina_value_list_vinsert() | ||
1756 | * @see eina_value_list_pinsert() | ||
1757 | * @see eina_value_list_append() | ||
1758 | * @see eina_value_list_vappend() | ||
1759 | * @see eina_value_list_pappend() | ||
1760 | * | ||
1761 | * @since 1.2 | ||
1762 | */ | ||
1763 | static inline Eina_Bool eina_value_list_vset(Eina_Value *value, | ||
1764 | unsigned int position, | ||
1765 | va_list args) EINA_ARG_NONNULL(1); | ||
1766 | |||
1767 | /** | ||
1768 | * @brief Get the generic value from an list member. | ||
1769 | * @param value source value object | ||
1770 | * @param position index of the member | ||
1771 | * @param args variable argument | ||
1772 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1773 | * | ||
1774 | * The value is returned in the variable argument parameter, the | ||
1775 | * actual value is type-dependent, but usually it will be what is | ||
1776 | * stored inside the object. There shouldn't be any memory allocation, | ||
1777 | * thus the contents should @b not be freed. | ||
1778 | * | ||
1779 | * @see eina_value_list_vset() | ||
1780 | * @see eina_value_list_get() | ||
1781 | * @see eina_value_list_pget() | ||
1782 | * | ||
1783 | * @since 1.2 | ||
1784 | */ | ||
1785 | static inline Eina_Bool eina_value_list_vget(const Eina_Value *value, | ||
1786 | unsigned int position, | ||
1787 | va_list args) EINA_ARG_NONNULL(1); | ||
1788 | /** | ||
1789 | * @brief Insert the generic value in an list member position. | ||
1790 | * @param value source value object | ||
1791 | * @param position index of the member | ||
1792 | * @param args variable argument | ||
1793 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1794 | * @see eina_value_list_set() | ||
1795 | * @see eina_value_list_get() | ||
1796 | * @see eina_value_list_vset() | ||
1797 | * @see eina_value_list_pset() | ||
1798 | * @see eina_value_list_insert() | ||
1799 | * @see eina_value_list_pinsert() | ||
1800 | * @see eina_value_list_append() | ||
1801 | * @see eina_value_list_vappend() | ||
1802 | * @see eina_value_list_pappend() | ||
1803 | * | ||
1804 | * @since 1.2 | ||
1805 | */ | ||
1806 | static inline Eina_Bool eina_value_list_vinsert(Eina_Value *value, | ||
1807 | unsigned int position, | ||
1808 | va_list args) EINA_ARG_NONNULL(1); | ||
1809 | |||
1810 | /** | ||
1811 | * @brief Append the generic value in an list. | ||
1812 | * @param value source value object | ||
1813 | * @param args variable argument | ||
1814 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1815 | * @see eina_value_list_set() | ||
1816 | * @see eina_value_list_get() | ||
1817 | * @see eina_value_list_vget() | ||
1818 | * @see eina_value_list_pset() | ||
1819 | * @see eina_value_list_insert() | ||
1820 | * @see eina_value_list_vinsert() | ||
1821 | * @see eina_value_list_pinsert() | ||
1822 | * @see eina_value_list_append() | ||
1823 | * @see eina_value_list_pappend() | ||
1824 | * | ||
1825 | * @since 1.2 | ||
1826 | */ | ||
1827 | static inline Eina_Bool eina_value_list_vappend(Eina_Value *value, | ||
1828 | va_list args) EINA_ARG_NONNULL(1); | ||
1829 | |||
1830 | |||
1831 | /** | ||
1832 | * @brief Set the generic value in an list member from pointer. | ||
1833 | * @param value source value object | ||
1834 | * @param position index of the member | ||
1835 | * @param ptr pointer to specify the contents. | ||
1836 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1837 | * | ||
1838 | * The pointer type is dependent on chosen value type. The list for | ||
1839 | * basic types: | ||
1840 | * | ||
1841 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
1842 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
1843 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
1844 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
1845 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
1846 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
1847 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
1848 | * @li EINA_VALUE_TYPE_INT: int* | ||
1849 | * @li EINA_VALUE_TYPE_LONG: long* | ||
1850 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
1851 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
1852 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
1853 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
1854 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
1855 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
1856 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
1857 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
1858 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
1859 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
1860 | * | ||
1861 | * @note the pointer contents are written using the size defined by | ||
1862 | * type. It can be larger than void* or uint64_t. | ||
1863 | * | ||
1864 | * @code | ||
1865 | * Eina_Value *value = eina_value_list_new(EINA_VALUE_TYPE_INT); | ||
1866 | * int x = 1234; | ||
1867 | * | ||
1868 | * eina_value_list_append(value, 1234); | ||
1869 | * eina_value_list_pset(value, 0, &x); | ||
1870 | * eina_value_list_pget(value, 0, &x); | ||
1871 | * eina_value_free(value); | ||
1872 | * @endcode | ||
1873 | * | ||
1874 | * @see eina_value_list_set() | ||
1875 | * @see eina_value_list_get() | ||
1876 | * @see eina_value_list_vset() | ||
1877 | * @see eina_value_list_insert() | ||
1878 | * @see eina_value_list_vinsert() | ||
1879 | * @see eina_value_list_pinsert() | ||
1880 | * @see eina_value_list_append() | ||
1881 | * @see eina_value_list_vappend() | ||
1882 | * @see eina_value_list_pappend() | ||
1883 | * | ||
1884 | * @since 1.2 | ||
1885 | */ | ||
1886 | static inline Eina_Bool eina_value_list_pset(Eina_Value *value, | ||
1887 | unsigned int position, | ||
1888 | const void *ptr) EINA_ARG_NONNULL(1, 3); | ||
1889 | |||
1890 | /** | ||
1891 | * @brief Get the generic value to pointer from an list member. | ||
1892 | * @param value source value object | ||
1893 | * @param position index of the member | ||
1894 | * @param ptr pointer to receive the contents. | ||
1895 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1896 | * | ||
1897 | * The value is returned in pointer contents, the actual value is | ||
1898 | * type-dependent, but usually it will be what is stored inside the | ||
1899 | * object. There shouldn't be any memory allocation, thus the contents | ||
1900 | * should @b not be freed. | ||
1901 | * | ||
1902 | * The pointer type is dependent on chosen value type. The list for | ||
1903 | * basic types: | ||
1904 | * | ||
1905 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
1906 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
1907 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
1908 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
1909 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
1910 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
1911 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
1912 | * @li EINA_VALUE_TYPE_INT: int* | ||
1913 | * @li EINA_VALUE_TYPE_LONG: long* | ||
1914 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
1915 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
1916 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
1917 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
1918 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
1919 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
1920 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
1921 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
1922 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
1923 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
1924 | * | ||
1925 | * @code | ||
1926 | * Eina_Value *value = eina_value_list_new(EINA_VALUE_TYPE_INT); | ||
1927 | * int x; | ||
1928 | * | ||
1929 | * eina_value_list_append(value, 1234); | ||
1930 | * eina_value_list_pget(value, 0, &x); | ||
1931 | * eina_value_free(value); | ||
1932 | * @endcode | ||
1933 | * | ||
1934 | * @see eina_value_list_set() | ||
1935 | * @see eina_value_list_vset() | ||
1936 | * @see eina_value_list_pset() | ||
1937 | * | ||
1938 | * @since 1.2 | ||
1939 | */ | ||
1940 | static inline Eina_Bool eina_value_list_pget(const Eina_Value *value, | ||
1941 | unsigned int position, | ||
1942 | void *ptr) EINA_ARG_NONNULL(1, 3); | ||
1943 | |||
1944 | /** | ||
1945 | * @brief Insert the generic value in an list member position from pointer. | ||
1946 | * @param value source value object | ||
1947 | * @param position index of the member | ||
1948 | * @param ptr pointer to specify the contents. | ||
1949 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
1950 | * | ||
1951 | * The pointer type is dependent on chosen value type. The list for | ||
1952 | * basic types: | ||
1953 | * | ||
1954 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
1955 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
1956 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
1957 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
1958 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
1959 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
1960 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
1961 | * @li EINA_VALUE_TYPE_INT: int* | ||
1962 | * @li EINA_VALUE_TYPE_LONG: long* | ||
1963 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
1964 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
1965 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
1966 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
1967 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
1968 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
1969 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
1970 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
1971 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
1972 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
1973 | * | ||
1974 | * @note the pointer contents are written using the size defined by | ||
1975 | * type. It can be larger than void* or uint64_t. | ||
1976 | * | ||
1977 | * @code | ||
1978 | * Eina_Value *value = eina_value_list_new(EINA_VALUE_TYPE_INT); | ||
1979 | * int x = 1234; | ||
1980 | * | ||
1981 | * eina_value_list_pinsert(value, 0, &x); | ||
1982 | * eina_value_list_pget(value, 0, &x); | ||
1983 | * eina_value_free(value); | ||
1984 | * @endcode | ||
1985 | * | ||
1986 | * @see eina_value_list_set() | ||
1987 | * @see eina_value_list_get() | ||
1988 | * @see eina_value_list_vset() | ||
1989 | * @see eina_value_list_insert() | ||
1990 | * @see eina_value_list_vinsert() | ||
1991 | * @see eina_value_list_pinsert() | ||
1992 | * @see eina_value_list_append() | ||
1993 | * @see eina_value_list_vappend() | ||
1994 | * @see eina_value_list_pappend() | ||
1995 | * | ||
1996 | * @since 1.2 | ||
1997 | */ | ||
1998 | static inline Eina_Bool eina_value_list_pinsert(Eina_Value *value, | ||
1999 | unsigned int position, | ||
2000 | const void *ptr) EINA_ARG_NONNULL(1); | ||
2001 | |||
2002 | /** | ||
2003 | * @brief Append the generic value in an list from pointer. | ||
2004 | * @param value source value object | ||
2005 | * @param ptr pointer to specify the contents. | ||
2006 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2007 | * | ||
2008 | * The pointer type is dependent on chosen value type. The list for | ||
2009 | * basic types: | ||
2010 | * | ||
2011 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
2012 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
2013 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
2014 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
2015 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
2016 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
2017 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
2018 | * @li EINA_VALUE_TYPE_INT: int* | ||
2019 | * @li EINA_VALUE_TYPE_LONG: long* | ||
2020 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
2021 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
2022 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
2023 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
2024 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
2025 | * @li EINA_VALUE_TYPE_LIST: Eina_Value_List* | ||
2026 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
2027 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
2028 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
2029 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
2030 | * | ||
2031 | * @note the pointer contents are written using the size defined by | ||
2032 | * type. It can be larger than void* or uint64_t. | ||
2033 | * | ||
2034 | * @code | ||
2035 | * Eina_Value *value = eina_value_list_new(EINA_VALUE_TYPE_INT); | ||
2036 | * int x = 1234; | ||
2037 | * | ||
2038 | * eina_value_list_pappend(value, &x); | ||
2039 | * eina_value_list_pget(value, 0, &x); | ||
2040 | * eina_value_free(value); | ||
2041 | * @endcode | ||
2042 | * | ||
2043 | * @see eina_value_list_set() | ||
2044 | * @see eina_value_list_get() | ||
2045 | * @see eina_value_list_vset() | ||
2046 | * @see eina_value_list_insert() | ||
2047 | * @see eina_value_list_vinsert() | ||
2048 | * @see eina_value_list_pinsert() | ||
2049 | * @see eina_value_list_append() | ||
2050 | * @see eina_value_list_vappend() | ||
2051 | * @see eina_value_list_pappend() | ||
2052 | * | ||
2053 | * @since 1.2 | ||
2054 | */ | ||
2055 | static inline Eina_Bool eina_value_list_pappend(Eina_Value *value, | ||
2056 | const void *ptr) EINA_ARG_NONNULL(1); | ||
2057 | |||
2058 | /** | ||
2059 | * @} | ||
2060 | */ | ||
2061 | |||
2062 | /** | ||
2063 | * @defgroup Eina_Value_Hash_Group Generic Value Hash management | ||
2064 | * | ||
2065 | * @{ | ||
2066 | */ | ||
2067 | |||
2068 | /** | ||
2069 | * @typedef Eina_Value_Hash | ||
2070 | * Value type for #EINA_VALUE_TYPE_HASH | ||
2071 | * | ||
2072 | * @since 1.2 | ||
2073 | */ | ||
2074 | typedef struct _Eina_Value_Hash Eina_Value_Hash; | ||
2075 | |||
2076 | /** | ||
2077 | * @struct _Eina_Value_Hash | ||
2078 | * Used to store the hash and its subtype. | ||
2079 | */ | ||
2080 | struct _Eina_Value_Hash | ||
2081 | { | ||
2082 | const Eina_Value_Type *subtype; /**< how to allocate and access items */ | ||
2083 | unsigned int buckets_power_size; /**< how to allocate hash buckets, if zero a sane default is chosen. */ | ||
2084 | Eina_Hash *hash; /**< the hash that holds data, members are of subtype->value_size bytes. */ | ||
2085 | }; | ||
2086 | |||
2087 | /** | ||
2088 | * @brief Create generic value storage of type hash. | ||
2089 | * @param subtype how to manage this hash members. | ||
2090 | * @param buckets_power_size how to allocate hash buckets (2 ^ | ||
2091 | * buckets_power_size), if zero then a sane value is chosen. | ||
2092 | * @return The new value or @c NULL on failure. | ||
2093 | * | ||
2094 | * Create a new generic value storage of type hash. The members are | ||
2095 | * managed using the description specified by @a subtype. | ||
2096 | * | ||
2097 | * On failure, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY or | ||
2098 | * #EINA_ERROR_VALUE_FAILED is set. | ||
2099 | * | ||
2100 | * @note this creates from mempool and then uses | ||
2101 | * eina_value_hash_setup(). | ||
2102 | * | ||
2103 | * @see eina_value_free() | ||
2104 | * @see eina_value_hash_setup() | ||
2105 | * | ||
2106 | * @since 1.2 | ||
2107 | */ | ||
2108 | EAPI Eina_Value *eina_value_hash_new(const Eina_Value_Type *subtype, unsigned int buckets_power_size) EINA_ARG_NONNULL(1); | ||
2109 | |||
2110 | /** | ||
2111 | * @brief Initialize generic value storage of type hash. | ||
2112 | * @param value value object | ||
2113 | * @param subtype how to manage this hash members. | ||
2114 | * @param buckets_power_size how to allocate hash buckets (2 ^ | ||
2115 | * buckets_power_size), if zero then a sane value is chosen. | ||
2116 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2117 | * | ||
2118 | * Initializes new generic value storage of type hash with the given | ||
2119 | * @a subtype. | ||
2120 | * | ||
2121 | * This is the same as calling eina_value_set() with | ||
2122 | * #EINA_VALUE_TYPE_HASH followed by eina_value_pset() with the | ||
2123 | * #Eina_Value_Hash description configured. | ||
2124 | * | ||
2125 | * @note Existing contents are ignored! If the value was previously used, then | ||
2126 | * use eina_value_flush() first. | ||
2127 | * | ||
2128 | * On failure, #EINA_FALSE is returned and #EINA_ERROR_OUT_OF_MEMORY | ||
2129 | * or #EINA_ERROR_VALUE_FAILED is set. | ||
2130 | * | ||
2131 | * @see eina_value_flush() | ||
2132 | * | ||
2133 | * @since 1.2 | ||
2134 | */ | ||
2135 | static inline Eina_Bool eina_value_hash_setup(Eina_Value *value, | ||
2136 | const Eina_Value_Type *subtype, | ||
2137 | unsigned int buckets_power_size) EINA_ARG_NONNULL(1, 2); | ||
2138 | |||
2139 | /** | ||
2140 | * @brief Query number of elements in value of hash type. | ||
2141 | * @param value value object. | ||
2142 | * @return number of child elements. | ||
2143 | * @since 1.2 | ||
2144 | */ | ||
2145 | static inline unsigned int eina_value_hash_population(const Eina_Value *value); | ||
2146 | |||
2147 | /** | ||
2148 | * @brief Remove element at given position in value of hash type. | ||
2149 | * @param value value object. | ||
2150 | * @param key key to find the member | ||
2151 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2152 | * @since 1.2 | ||
2153 | */ | ||
2154 | static inline Eina_Bool eina_value_hash_del(Eina_Value *value, | ||
2155 | const char *key) EINA_ARG_NONNULL(1); | ||
2156 | |||
2157 | /** | ||
2158 | * @brief Set the generic value in an hash member. | ||
2159 | * @param value source value object | ||
2160 | * @param key key to find the member | ||
2161 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2162 | * | ||
2163 | * The variable argument is dependent on chosen subtype. The list for | ||
2164 | * basic types: | ||
2165 | * | ||
2166 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char | ||
2167 | * @li EINA_VALUE_TYPE_USHORT: unsigned short | ||
2168 | * @li EINA_VALUE_TYPE_UINT: unsigned int | ||
2169 | * @li EINA_VALUE_TYPE_ULONG: unsigned long | ||
2170 | * @li EINA_VALUE_TYPE_UINT64: uint64_t | ||
2171 | * @li EINA_VALUE_TYPE_CHAR: char | ||
2172 | * @li EINA_VALUE_TYPE_SHORT: short | ||
2173 | * @li EINA_VALUE_TYPE_INT: int | ||
2174 | * @li EINA_VALUE_TYPE_LONG: long | ||
2175 | * @li EINA_VALUE_TYPE_INT64: int64_t | ||
2176 | * @li EINA_VALUE_TYPE_FLOAT: float | ||
2177 | * @li EINA_VALUE_TYPE_DOUBLE: double | ||
2178 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char * | ||
2179 | * @li EINA_VALUE_TYPE_STRING: const char * | ||
2180 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash | ||
2181 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
2182 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
2183 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
2184 | * | ||
2185 | * @code | ||
2186 | * Eina_Value *value = eina_value_hash_new(EINA_VALUE_TYPE_INT, 0); | ||
2187 | * int x; | ||
2188 | * | ||
2189 | * eina_value_hash_set(value, "abc", 5678); | ||
2190 | * eina_value_hash_get(value, "abc", &x); | ||
2191 | * eina_value_free(value); | ||
2192 | * @endcode | ||
2193 | * | ||
2194 | * @see eina_value_hash_get() | ||
2195 | * @see eina_value_hash_vset() | ||
2196 | * @see eina_value_hash_pset() | ||
2197 | * @see eina_value_hash_del() | ||
2198 | * | ||
2199 | * @since 1.2 | ||
2200 | */ | ||
2201 | static inline Eina_Bool eina_value_hash_set(Eina_Value *value, | ||
2202 | const char *key, | ||
2203 | ...) EINA_ARG_NONNULL(1); | ||
2204 | |||
2205 | /** | ||
2206 | * @brief Get the generic value from an hash member. | ||
2207 | * @param value source value object | ||
2208 | * @param key key to find the member | ||
2209 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2210 | * | ||
2211 | * The value is returned in the variable argument parameter, the | ||
2212 | * actual value is type-dependent, but usually it will be what is | ||
2213 | * stored inside the object. There shouldn't be any memory allocation, | ||
2214 | * thus the contents should @b not be freed. | ||
2215 | * | ||
2216 | * The variable argument is dependent on chosen subtype. The list for | ||
2217 | * basic types: | ||
2218 | * | ||
2219 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
2220 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
2221 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
2222 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
2223 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
2224 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
2225 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
2226 | * @li EINA_VALUE_TYPE_INT: int* | ||
2227 | * @li EINA_VALUE_TYPE_LONG: long* | ||
2228 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
2229 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
2230 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
2231 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
2232 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
2233 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
2234 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
2235 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
2236 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
2237 | * | ||
2238 | * @code | ||
2239 | * Eina_Value *value = eina_value_hash_new(EINA_VALUE_TYPE_INT, 0); | ||
2240 | * int x; | ||
2241 | * | ||
2242 | * eina_value_hash_set(value, "abc", 1234); | ||
2243 | * eina_value_hash_get(value, "abc", &x); | ||
2244 | * eina_value_free(value); | ||
2245 | * @endcode | ||
2246 | * | ||
2247 | * @see eina_value_hash_set() | ||
2248 | * @see eina_value_hash_vset() | ||
2249 | * @see eina_value_hash_pset() | ||
2250 | * | ||
2251 | * @since 1.2 | ||
2252 | */ | ||
2253 | static inline Eina_Bool eina_value_hash_get(const Eina_Value *value, | ||
2254 | const char *key, | ||
2255 | ...) EINA_ARG_NONNULL(1); | ||
2256 | |||
2257 | /** | ||
2258 | * @brief Set the generic value in an hash member. | ||
2259 | * @param value source value object | ||
2260 | * @param key key to find the member | ||
2261 | * @param args variable argument | ||
2262 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2263 | * @see eina_value_hash_set() | ||
2264 | * @see eina_value_hash_get() | ||
2265 | * @see eina_value_hash_pset() | ||
2266 | * | ||
2267 | * @since 1.2 | ||
2268 | */ | ||
2269 | static inline Eina_Bool eina_value_hash_vset(Eina_Value *value, | ||
2270 | const char *key, | ||
2271 | va_list args) EINA_ARG_NONNULL(1); | ||
2272 | |||
2273 | /** | ||
2274 | * @brief Get the generic value from an hash member. | ||
2275 | * @param value source value object | ||
2276 | * @param key key to find the member | ||
2277 | * @param args variable argument | ||
2278 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2279 | * | ||
2280 | * The value is returned in the variable argument parameter, the | ||
2281 | * actual value is type-dependent, but usually it will be what is | ||
2282 | * stored inside the object. There shouldn't be any memory allocation, | ||
2283 | * thus the contents should @b not be freed. | ||
2284 | * | ||
2285 | * @see eina_value_hash_vset() | ||
2286 | * @see eina_value_hash_get() | ||
2287 | * @see eina_value_hash_pget() | ||
2288 | * | ||
2289 | * @since 1.2 | ||
2290 | */ | ||
2291 | static inline Eina_Bool eina_value_hash_vget(const Eina_Value *value, | ||
2292 | const char *key, | ||
2293 | va_list args) EINA_ARG_NONNULL(1); | ||
2294 | |||
2295 | /** | ||
2296 | * @brief Set the generic value in an hash member from pointer. | ||
2297 | * @param value source value object | ||
2298 | * @param key key to find the member | ||
2299 | * @param ptr pointer to specify the contents. | ||
2300 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2301 | * | ||
2302 | * The pointer type is dependent on chosen value type. The list for | ||
2303 | * basic types: | ||
2304 | * | ||
2305 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
2306 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
2307 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
2308 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
2309 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
2310 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
2311 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
2312 | * @li EINA_VALUE_TYPE_INT: int* | ||
2313 | * @li EINA_VALUE_TYPE_LONG: long* | ||
2314 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
2315 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
2316 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
2317 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
2318 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
2319 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
2320 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
2321 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
2322 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
2323 | * | ||
2324 | * @note the pointer contents are written using the size defined by | ||
2325 | * type. It can be larger than void* or uint64_t. | ||
2326 | * | ||
2327 | * @code | ||
2328 | * Eina_Value *value = eina_value_hash_new(EINA_VALUE_TYPE_INT, 0); | ||
2329 | * int x = 1234; | ||
2330 | * | ||
2331 | * eina_value_hash_pset(value, "abc", &x); | ||
2332 | * eina_value_hash_pget(value, "abc", &x); | ||
2333 | * eina_value_free(value); | ||
2334 | * @endcode | ||
2335 | * | ||
2336 | * @see eina_value_hash_set() | ||
2337 | * @see eina_value_hash_get() | ||
2338 | * @see eina_value_hash_vset() | ||
2339 | * | ||
2340 | * @since 1.2 | ||
2341 | */ | ||
2342 | static inline Eina_Bool eina_value_hash_pset(Eina_Value *value, | ||
2343 | const char *key, | ||
2344 | const void *ptr) EINA_ARG_NONNULL(1, 3); | ||
2345 | |||
2346 | /** | ||
2347 | * @brief Get the generic value to pointer from an hash member. | ||
2348 | * @param value source value object | ||
2349 | * @param key key to find the member | ||
2350 | * @param ptr pointer to receive the contents. | ||
2351 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2352 | * | ||
2353 | * The value is returned in pointer contents, the actual value is | ||
2354 | * type-dependent, but usually it will be what is stored inside the | ||
2355 | * object. There shouldn't be any memory allocation, thus the contents | ||
2356 | * should @b not be freed. | ||
2357 | * | ||
2358 | * The pointer type is dependent on chosen value type. The list for | ||
2359 | * basic types: | ||
2360 | * | ||
2361 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
2362 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
2363 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
2364 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
2365 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
2366 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
2367 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
2368 | * @li EINA_VALUE_TYPE_INT: int* | ||
2369 | * @li EINA_VALUE_TYPE_LONG: long* | ||
2370 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
2371 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
2372 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
2373 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
2374 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
2375 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
2376 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
2377 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
2378 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
2379 | * | ||
2380 | * @code | ||
2381 | * Eina_Value *value = eina_value_hash_new(EINA_VALUE_TYPE_INT, 0); | ||
2382 | * int x; | ||
2383 | * | ||
2384 | * eina_value_hash_set(value, "abc", 1234); | ||
2385 | * eina_value_hash_pget(value, "abc", &x); | ||
2386 | * eina_value_free(value); | ||
2387 | * @endcode | ||
2388 | * | ||
2389 | * @see eina_value_hash_set() | ||
2390 | * @see eina_value_hash_vset() | ||
2391 | * @see eina_value_hash_pset() | ||
2392 | * | ||
2393 | * @since 1.2 | ||
2394 | */ | ||
2395 | static inline Eina_Bool eina_value_hash_pget(const Eina_Value *value, | ||
2396 | const char *key, | ||
2397 | void *ptr) EINA_ARG_NONNULL(1, 3); | ||
2398 | |||
2399 | /** | ||
2400 | * @} | ||
2401 | */ | ||
2402 | |||
2403 | /** | ||
2404 | * @defgroup Eina_Value_Blob_Group Generic Value Blob management | ||
2405 | * | ||
2406 | * @{ | ||
2407 | */ | ||
2408 | |||
2409 | /** | ||
2410 | * @typedef Eina_Value_Blob_Operations | ||
2411 | * How to manage blob. Any @c NULL callback is ignored. | ||
2412 | * @since 1.2 | ||
2413 | */ | ||
2414 | typedef struct _Eina_Value_Blob_Operations Eina_Value_Blob_Operations; | ||
2415 | |||
2416 | /** | ||
2417 | * @struct _Eina_Value_Blob_Operations | ||
2418 | * How to manage blob. Any @c NULL callback is ignored. | ||
2419 | * @since 1.2 | ||
2420 | */ | ||
2421 | struct _Eina_Value_Blob_Operations | ||
2422 | { | ||
2423 | #define EINA_VALUE_BLOB_OPERATIONS_VERSION (1) | ||
2424 | unsigned int version; /**< must be EINA_VALUE_BLOB_OPERATIONS_VERSION */ | ||
2425 | void (*free)(const Eina_Value_Blob_Operations *ops, void *memory, size_t size); | ||
2426 | void *(*copy)(const Eina_Value_Blob_Operations *ops, const void *memory, size_t size); | ||
2427 | int (*compare)(const Eina_Value_Blob_Operations *ops, const void *data1, size_t size_data1, const void *data2, size_t size_data2); | ||
2428 | char *(*to_string)(const Eina_Value_Blob_Operations *ops, const void *memory, size_t size); | ||
2429 | }; | ||
2430 | |||
2431 | /** | ||
2432 | * @var EINA_VALUE_BLOB_OPERATIONS_MALLOC | ||
2433 | * | ||
2434 | * Assumes @c memory was create with malloc() and applies free() to it | ||
2435 | * during flush (Eina_Value_Blob_Operations::free). Copy is done with | ||
2436 | * malloc() as well. | ||
2437 | * | ||
2438 | * No compare or to_string are provided, defaults will be used. | ||
2439 | */ | ||
2440 | EAPI extern const Eina_Value_Blob_Operations *EINA_VALUE_BLOB_OPERATIONS_MALLOC; | ||
2441 | |||
2442 | /** | ||
2443 | * @typedef Eina_Value_Blob | ||
2444 | * @since 1.2 | ||
2445 | */ | ||
2446 | typedef struct _Eina_Value_Blob Eina_Value_Blob; | ||
2447 | |||
2448 | /** | ||
2449 | * @struct _Eina_Value_Blob | ||
2450 | * @since 1.2 | ||
2451 | */ | ||
2452 | struct _Eina_Value_Blob | ||
2453 | { | ||
2454 | const Eina_Value_Blob_Operations *ops; /**< if @c NULL, nothing is freed, copy will just copy the memory pointer, not its value. */ | ||
2455 | const void *memory; | ||
2456 | unsigned int size; | ||
2457 | }; | ||
2458 | |||
2459 | /** | ||
2460 | * @} | ||
2461 | */ | ||
2462 | |||
2463 | /** | ||
2464 | * @defgroup Eina_Value_Struct_Group Generic Value Struct management | ||
2465 | * | ||
2466 | * @{ | ||
2467 | */ | ||
2468 | |||
2469 | /** | ||
2470 | * @typedef Eina_Value_Struct_Operations | ||
2471 | * How to manage struct. Any @c NULL callback is ignored. | ||
2472 | * @since 1.2 | ||
2473 | */ | ||
2474 | typedef struct _Eina_Value_Struct_Operations Eina_Value_Struct_Operations; | ||
2475 | |||
2476 | /** | ||
2477 | * @typedef Eina_Value_Struct_Member | ||
2478 | * Describes a single member of struct. | ||
2479 | * @since 1.2 | ||
2480 | */ | ||
2481 | typedef struct _Eina_Value_Struct_Member Eina_Value_Struct_Member; | ||
2482 | |||
2483 | /** | ||
2484 | * @typedef Eina_Value_Struct_Desc | ||
2485 | * Describes the struct by listing its size, members and operations. | ||
2486 | * @since 1.2 | ||
2487 | */ | ||
2488 | typedef struct _Eina_Value_Struct_Desc Eina_Value_Struct_Desc; | ||
2489 | |||
2490 | /** | ||
2491 | * @typedef Eina_Value_Struct | ||
2492 | * @since 1.2 | ||
2493 | */ | ||
2494 | typedef struct _Eina_Value_Struct Eina_Value_Struct; | ||
2495 | |||
2496 | /** | ||
2497 | * @struct _Eina_Value_Struct_Operations | ||
2498 | * How to manage struct. Any @c NULL callback is ignored. | ||
2499 | * @since 1.2 | ||
2500 | */ | ||
2501 | struct _Eina_Value_Struct_Operations | ||
2502 | { | ||
2503 | #define EINA_VALUE_STRUCT_OPERATIONS_VERSION (1) | ||
2504 | unsigned int version; /**< must be EINA_VALUE_STRUCT_OPERATIONS_VERSION */ | ||
2505 | void *(*alloc)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc); | ||
2506 | void (*free)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, void *memory); | ||
2507 | void *(*copy)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const void *memory); | ||
2508 | int (*compare)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const void *data1, const void *data2); | ||
2509 | const Eina_Value_Struct_Member *(*find_member)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const char *name); /**< replace the function to find description for member. For huge structures consider using binary search, stringshared, hash or gperf. The default function does linear search using strcmp(). */ | ||
2510 | }; | ||
2511 | |||
2512 | /** | ||
2513 | * @var EINA_VALUE_STRUCT_OPERATIONS_BINSEARCH | ||
2514 | * | ||
2515 | * Assumes @c members is sorted by name and applies binary search for | ||
2516 | * names. | ||
2517 | * | ||
2518 | * Ideally the @c member_count field is set to speed it up. | ||
2519 | * | ||
2520 | * No other methods are set (alloc, free, copy, compare), then it uses | ||
2521 | * the default operations. | ||
2522 | */ | ||
2523 | EAPI extern const Eina_Value_Struct_Operations *EINA_VALUE_STRUCT_OPERATIONS_BINSEARCH; | ||
2524 | |||
2525 | /** | ||
2526 | * @var EINA_VALUE_STRUCT_OPERATIONS_STRINGSHARE | ||
2527 | * | ||
2528 | * Assumes @c members name are stringshared and can be compared for | ||
2529 | * equality without using its contents (simple pointer comparison). | ||
2530 | * | ||
2531 | * Ideally the search @c name will be stringshared as well, but it | ||
2532 | * will do a second loop with a forced stringshare if it did not find | ||
2533 | * the member. | ||
2534 | * | ||
2535 | * No other methods are set (alloc, free, copy, compare), then it uses | ||
2536 | * the default operations. | ||
2537 | */ | ||
2538 | EAPI extern const Eina_Value_Struct_Operations *EINA_VALUE_STRUCT_OPERATIONS_STRINGSHARE; | ||
2539 | |||
2540 | /** | ||
2541 | * @struct _Eina_Value_Struct_Member | ||
2542 | * @since 1.2 | ||
2543 | */ | ||
2544 | struct _Eina_Value_Struct_Member | ||
2545 | { | ||
2546 | const char *name; | ||
2547 | const Eina_Value_Type *type; | ||
2548 | unsigned int offset; | ||
2549 | }; | ||
2550 | |||
2551 | /** | ||
2552 | * @struct _Eina_Value_Struct_Desc | ||
2553 | * @since 1.2 | ||
2554 | */ | ||
2555 | struct _Eina_Value_Struct_Desc | ||
2556 | { | ||
2557 | #define EINA_VALUE_STRUCT_DESC_VERSION (1) | ||
2558 | unsigned int version; /**< must be EINA_VALUE_STRUCT_DESC_VERSION */ | ||
2559 | const Eina_Value_Struct_Operations *ops; /**< operations, if @c NULL defaults will be used. You may use operations to optimize member lookup using binary search or gperf hash. */ | ||
2560 | const Eina_Value_Struct_Member *members; /**< array of member descriptions, if @c member_count is zero, then it must be @c NULL terminated. */ | ||
2561 | unsigned int member_count; /**< if > 0, specifies number of members. If zero then @c members must be NULL terminated. */ | ||
2562 | unsigned int size; /**< byte size to allocate, may be bigger than sum of members */ | ||
2563 | }; | ||
2564 | |||
2565 | /** | ||
2566 | * @def EINA_VALUE_STRUCT_MEMBER | ||
2567 | * | ||
2568 | * Helper to define Eina_Value_Struct_Member fields, uses offsetof() | ||
2569 | * with type and member. | ||
2570 | * | ||
2571 | * @since 1.2 | ||
2572 | */ | ||
2573 | #define EINA_VALUE_STRUCT_MEMBER(eina_value_type, type, member) \ | ||
2574 | {#member, eina_value_type, offsetof(type, member)} | ||
2575 | |||
2576 | /** | ||
2577 | * @def EINA_VALUE_STRUCT_MEMBER_SENTINEL | ||
2578 | * | ||
2579 | * Helper to define Eina_Value_Struct_Member fields for sentinel (last | ||
2580 | * item), useful if you did not define @c member_count. | ||
2581 | * | ||
2582 | * @since 1.2 | ||
2583 | */ | ||
2584 | #define EINA_VALUE_STRUCT_MEMBER_SENTINEL {NULL, NULL, 0} | ||
2585 | |||
2586 | |||
2587 | /** | ||
2588 | * @struct _Eina_Value_Struct | ||
2589 | * @since 1.2 | ||
2590 | */ | ||
2591 | struct _Eina_Value_Struct | ||
2592 | { | ||
2593 | const Eina_Value_Struct_Desc *desc; | ||
2594 | void *memory; | ||
2595 | }; | ||
2596 | |||
2597 | /** | ||
2598 | * @brief Create generic value storage of type struct. | ||
2599 | * @param desc how to manage this struct members. | ||
2600 | * @return The new value or @c NULL on failure. | ||
2601 | * | ||
2602 | * Create a new generic value storage of type struct. The members are | ||
2603 | * managed using the description specified by @a desc. | ||
2604 | * | ||
2605 | * On failure, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY or | ||
2606 | * #EINA_ERROR_VALUE_FAILED is set. | ||
2607 | * | ||
2608 | * @note this creates from mempool and then uses | ||
2609 | * eina_value_struct_setup(). | ||
2610 | * | ||
2611 | * @see eina_value_free() | ||
2612 | * @see eina_value_struct_setup() | ||
2613 | * | ||
2614 | * @since 1.2 | ||
2615 | */ | ||
2616 | EAPI Eina_Value *eina_value_struct_new(const Eina_Value_Struct_Desc *desc) EINA_ARG_NONNULL(1); | ||
2617 | |||
2618 | /** | ||
2619 | * @brief Initialize generic value storage of type struct. | ||
2620 | * @param value value object | ||
2621 | * @param desc how to manage this struct members. | ||
2622 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2623 | * | ||
2624 | * Initializes new generic value storage of type struct with the given | ||
2625 | * @a desc. | ||
2626 | * | ||
2627 | * This is the same as calling eina_value_set() with | ||
2628 | * #EINA_VALUE_TYPE_STRUCT followed by eina_value_pset() with the | ||
2629 | * #Eina_Value_Struct description configured. | ||
2630 | * | ||
2631 | * @note Existing contents are ignored! If the value was previously used, then | ||
2632 | * use eina_value_flush() first. | ||
2633 | * | ||
2634 | * On failure, #EINA_FALSE is returned and #EINA_ERROR_OUT_OF_MEMORY | ||
2635 | * or #EINA_ERROR_VALUE_FAILED is set. | ||
2636 | * | ||
2637 | * @see eina_value_flush() | ||
2638 | * | ||
2639 | * @since 1.2 | ||
2640 | */ | ||
2641 | static inline Eina_Bool eina_value_struct_setup(Eina_Value *value, | ||
2642 | const Eina_Value_Struct_Desc *desc) EINA_ARG_NONNULL(1, 2); | ||
2643 | |||
2644 | /** | ||
2645 | * @brief Set the generic value in an struct member. | ||
2646 | * @param value source value object | ||
2647 | * @param name name to find the member | ||
2648 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2649 | * | ||
2650 | * The variable argument is dependent on chosen member type. The list | ||
2651 | * for basic types: | ||
2652 | * | ||
2653 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char | ||
2654 | * @li EINA_VALUE_TYPE_USHORT: unsigned short | ||
2655 | * @li EINA_VALUE_TYPE_UINT: unsigned int | ||
2656 | * @li EINA_VALUE_TYPE_ULONG: unsigned long | ||
2657 | * @li EINA_VALUE_TYPE_UINT64: uint64_t | ||
2658 | * @li EINA_VALUE_TYPE_CHAR: char | ||
2659 | * @li EINA_VALUE_TYPE_SHORT: short | ||
2660 | * @li EINA_VALUE_TYPE_INT: int | ||
2661 | * @li EINA_VALUE_TYPE_LONG: long | ||
2662 | * @li EINA_VALUE_TYPE_INT64: int64_t | ||
2663 | * @li EINA_VALUE_TYPE_FLOAT: float | ||
2664 | * @li EINA_VALUE_TYPE_DOUBLE: double | ||
2665 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char * | ||
2666 | * @li EINA_VALUE_TYPE_STRING: const char * | ||
2667 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash | ||
2668 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
2669 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
2670 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
2671 | * | ||
2672 | * @code | ||
2673 | * struct myst { | ||
2674 | * int i; | ||
2675 | * char c; | ||
2676 | * }; | ||
2677 | * const Eina_Value_Struct_Member myst_members[] = { | ||
2678 | * {"i", EINA_VALUE_TYPE_INT, 0}, | ||
2679 | * {"c", EINA_VALUE_TYPE_CHAR, 4}, | ||
2680 | * {NULL, NULL, 0} | ||
2681 | * }; | ||
2682 | * const Eina_Value_Struct_Desc myst_desc = { | ||
2683 | * EINA_VALUE_STRUCT_DESC_VERSION, | ||
2684 | * NULL, myst_members, 2, sizeof(struct myst) | ||
2685 | * }; | ||
2686 | * Eina_Value *value = eina_value_struct_new(&my_desc); | ||
2687 | * int x; | ||
2688 | * char y; | ||
2689 | * | ||
2690 | * eina_value_struct_set(value, "i", 5678); | ||
2691 | * eina_value_struct_get(value, "i", &x); | ||
2692 | * eina_value_struct_set(value, "c", 0xf); | ||
2693 | * eina_value_struct_get(value, "c", &y); | ||
2694 | * eina_value_free(value); | ||
2695 | * @endcode | ||
2696 | * | ||
2697 | * @see eina_value_struct_get() | ||
2698 | * @see eina_value_struct_vset() | ||
2699 | * @see eina_value_struct_pset() | ||
2700 | * | ||
2701 | * @since 1.2 | ||
2702 | */ | ||
2703 | static inline Eina_Bool eina_value_struct_set(Eina_Value *value, | ||
2704 | const char *name, | ||
2705 | ...) EINA_ARG_NONNULL(1); | ||
2706 | |||
2707 | /** | ||
2708 | * @brief Get the generic value from an struct member. | ||
2709 | * @param value source value object | ||
2710 | * @param name name to find the member | ||
2711 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2712 | * | ||
2713 | * The value is returned in the variable argument parameter, the | ||
2714 | * actual value is type-dependent, but usually it will be what is | ||
2715 | * stored inside the object. There shouldn't be any memory allocation, | ||
2716 | * thus the contents should @b not be freed. | ||
2717 | * | ||
2718 | * The variable argument is dependent on chosen member type. The list | ||
2719 | * for basic types: | ||
2720 | * | ||
2721 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
2722 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
2723 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
2724 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
2725 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
2726 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
2727 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
2728 | * @li EINA_VALUE_TYPE_INT: int* | ||
2729 | * @li EINA_VALUE_TYPE_LONG: long* | ||
2730 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
2731 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
2732 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
2733 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
2734 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
2735 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
2736 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
2737 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
2738 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
2739 | * | ||
2740 | * @code | ||
2741 | * struct myst { | ||
2742 | * int i; | ||
2743 | * char c; | ||
2744 | * }; | ||
2745 | * const Eina_Value_Struct_Member myst_members[] = { | ||
2746 | * {"i", EINA_VALUE_TYPE_INT, 0}, | ||
2747 | * {"c", EINA_VALUE_TYPE_CHAR, 4}, | ||
2748 | * {NULL, NULL, 0} | ||
2749 | * }; | ||
2750 | * const Eina_Value_Struct_Desc myst_desc = { | ||
2751 | * EINA_VALUE_STRUCT_DESC_VERSION, | ||
2752 | * NULL, myst_members, 2, sizeof(struct myst) | ||
2753 | * }; | ||
2754 | * Eina_Value *value = eina_value_struct_new(&my_desc); | ||
2755 | * int x; | ||
2756 | * char y; | ||
2757 | * | ||
2758 | * eina_value_struct_set(value, "i", 5678); | ||
2759 | * eina_value_struct_get(value, "i", &x); | ||
2760 | * eina_value_struct_set(value, "c", 0xf); | ||
2761 | * eina_value_struct_get(value, "c", &y); | ||
2762 | * eina_value_free(value); | ||
2763 | * @endcode | ||
2764 | * | ||
2765 | * @see eina_value_struct_set() | ||
2766 | * @see eina_value_struct_vset() | ||
2767 | * @see eina_value_struct_pset() | ||
2768 | * | ||
2769 | * @since 1.2 | ||
2770 | */ | ||
2771 | static inline Eina_Bool eina_value_struct_get(const Eina_Value *value, | ||
2772 | const char *name, | ||
2773 | ...) EINA_ARG_NONNULL(1); | ||
2774 | |||
2775 | /** | ||
2776 | * @brief Set the generic value in an struct member. | ||
2777 | * @param value source value object | ||
2778 | * @param name name to find the member | ||
2779 | * @param args variable argument | ||
2780 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2781 | * @see eina_value_struct_set() | ||
2782 | * @see eina_value_struct_get() | ||
2783 | * @see eina_value_struct_pset() | ||
2784 | * | ||
2785 | * @since 1.2 | ||
2786 | */ | ||
2787 | static inline Eina_Bool eina_value_struct_vset(Eina_Value *value, | ||
2788 | const char *name, | ||
2789 | va_list args) EINA_ARG_NONNULL(1); | ||
2790 | |||
2791 | /** | ||
2792 | * @brief Get the generic value from an struct member. | ||
2793 | * @param value source value object | ||
2794 | * @param name name to find the member | ||
2795 | * @param args variable argument | ||
2796 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2797 | * | ||
2798 | * The value is returned in the variable argument parameter, the | ||
2799 | * actual value is type-dependent, but usually it will be what is | ||
2800 | * stored inside the object. There shouldn't be any memory allocation, | ||
2801 | * thus the contents should @b not be freed. | ||
2802 | * | ||
2803 | * @see eina_value_struct_vset() | ||
2804 | * @see eina_value_struct_get() | ||
2805 | * @see eina_value_struct_pget() | ||
2806 | * | ||
2807 | * @since 1.2 | ||
2808 | */ | ||
2809 | static inline Eina_Bool eina_value_struct_vget(const Eina_Value *value, | ||
2810 | const char *name, | ||
2811 | va_list args) EINA_ARG_NONNULL(1); | ||
2812 | |||
2813 | /** | ||
2814 | * @brief Set the generic value in an struct member from pointer. | ||
2815 | * @param value source value object | ||
2816 | * @param name name to find the member | ||
2817 | * @param ptr pointer to specify the contents. | ||
2818 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2819 | * | ||
2820 | * The pointer type is dependent on chosen value type. The list for | ||
2821 | * basic types: | ||
2822 | * | ||
2823 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
2824 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
2825 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
2826 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
2827 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
2828 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
2829 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
2830 | * @li EINA_VALUE_TYPE_INT: int* | ||
2831 | * @li EINA_VALUE_TYPE_LONG: long* | ||
2832 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
2833 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
2834 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
2835 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
2836 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
2837 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
2838 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
2839 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
2840 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
2841 | * | ||
2842 | * @note the pointer contents are written using the size defined by | ||
2843 | * type. It can be larger than void* or uint64_t. | ||
2844 | * | ||
2845 | * @code | ||
2846 | * struct myst { | ||
2847 | * int i; | ||
2848 | * char c; | ||
2849 | * }; | ||
2850 | * const Eina_Value_Struct_Member myst_members[] = { | ||
2851 | * {"i", EINA_VALUE_TYPE_INT, 0}, | ||
2852 | * {"c", EINA_VALUE_TYPE_CHAR, 4}, | ||
2853 | * {NULL, NULL, 0} | ||
2854 | * }; | ||
2855 | * const Eina_Value_Struct_Desc myst_desc = { | ||
2856 | * EINA_VALUE_STRUCT_DESC_VERSION, | ||
2857 | * NULL, myst_members, 2, sizeof(struct myst) | ||
2858 | * }; | ||
2859 | * Eina_Value *value = eina_value_struct_new(&my_desc); | ||
2860 | * int x = 5678; | ||
2861 | * char y = 0xf; | ||
2862 | * | ||
2863 | * eina_value_struct_pset(value, "i", &); | ||
2864 | * eina_value_struct_pget(value, "i", &x); | ||
2865 | * eina_value_struct_pset(value, "c", &y); | ||
2866 | * eina_value_struct_pget(value, "c", &y); | ||
2867 | * eina_value_free(value); | ||
2868 | * @endcode | ||
2869 | * | ||
2870 | * @see eina_value_struct_set() | ||
2871 | * @see eina_value_struct_get() | ||
2872 | * @see eina_value_struct_vset() | ||
2873 | * | ||
2874 | * @since 1.2 | ||
2875 | */ | ||
2876 | static inline Eina_Bool eina_value_struct_pset(Eina_Value *value, | ||
2877 | const char *name, | ||
2878 | const void *ptr) EINA_ARG_NONNULL(1, 3); | ||
2879 | |||
2880 | /** | ||
2881 | * @brief Get the generic value to pointer from an struct member. | ||
2882 | * @param value source value object | ||
2883 | * @param name name to find the member | ||
2884 | * @param ptr pointer to receive the contents. | ||
2885 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
2886 | * | ||
2887 | * The value is returned in pointer contents, the actual value is | ||
2888 | * type-dependent, but usually it will be what is stored inside the | ||
2889 | * object. There shouldn't be any memory allocation, thus the contents | ||
2890 | * should @b not be freed. | ||
2891 | * | ||
2892 | * The pointer type is dependent on chosen value type. The list for | ||
2893 | * basic types: | ||
2894 | * | ||
2895 | * @li EINA_VALUE_TYPE_UCHAR: unsigned char* | ||
2896 | * @li EINA_VALUE_TYPE_USHORT: unsigned short* | ||
2897 | * @li EINA_VALUE_TYPE_UINT: unsigned int* | ||
2898 | * @li EINA_VALUE_TYPE_ULONG: unsigned long* | ||
2899 | * @li EINA_VALUE_TYPE_UINT64: uint64_t* | ||
2900 | * @li EINA_VALUE_TYPE_CHAR: char* | ||
2901 | * @li EINA_VALUE_TYPE_SHORT: short* | ||
2902 | * @li EINA_VALUE_TYPE_INT: int* | ||
2903 | * @li EINA_VALUE_TYPE_LONG: long* | ||
2904 | * @li EINA_VALUE_TYPE_INT64: int64_t* | ||
2905 | * @li EINA_VALUE_TYPE_FLOAT: float* | ||
2906 | * @li EINA_VALUE_TYPE_DOUBLE: double* | ||
2907 | * @li EINA_VALUE_TYPE_STRINGSHARE: const char ** | ||
2908 | * @li EINA_VALUE_TYPE_STRING: const char ** | ||
2909 | * @li EINA_VALUE_TYPE_HASH: Eina_Value_Hash* | ||
2910 | * @li EINA_VALUE_TYPE_TIMEVAL: struct timeval* | ||
2911 | * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* | ||
2912 | * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* | ||
2913 | * | ||
2914 | * @code | ||
2915 | * struct myst { | ||
2916 | * int i; | ||
2917 | * char c; | ||
2918 | * }; | ||
2919 | * const Eina_Value_Struct_Member myst_members[] = { | ||
2920 | * {"i", EINA_VALUE_TYPE_INT, 0}, | ||
2921 | * {"c", EINA_VALUE_TYPE_CHAR, 4}, | ||
2922 | * {NULL, NULL, 0} | ||
2923 | * }; | ||
2924 | * const Eina_Value_Struct_Desc myst_desc = { | ||
2925 | * EINA_VALUE_STRUCT_DESC_VERSION, | ||
2926 | * NULL, myst_members, 2, sizeof(struct myst) | ||
2927 | * }; | ||
2928 | * Eina_Value *value = eina_value_struct_new(&my_desc); | ||
2929 | * int x = 5678; | ||
2930 | * char y = 0xf; | ||
2931 | * | ||
2932 | * eina_value_struct_pset(value, "i", &); | ||
2933 | * eina_value_struct_pget(value, "i", &x); | ||
2934 | * eina_value_struct_pset(value, "c", &y); | ||
2935 | * eina_value_struct_pget(value, "c", &y); | ||
2936 | * eina_value_free(value); | ||
2937 | * @endcode | ||
2938 | * | ||
2939 | * @see eina_value_struct_set() | ||
2940 | * @see eina_value_struct_vset() | ||
2941 | * @see eina_value_struct_pset() | ||
2942 | * | ||
2943 | * @since 1.2 | ||
2944 | */ | ||
2945 | static inline Eina_Bool eina_value_struct_pget(const Eina_Value *value, | ||
2946 | const char *name, | ||
2947 | void *ptr) EINA_ARG_NONNULL(1, 3); | ||
2948 | |||
2949 | /** | ||
2950 | * @} | ||
2951 | */ | ||
2952 | |||
2953 | |||
2954 | /** | ||
2955 | * @defgroup Eina_Value_Type_Group Generic Value Type management | ||
2956 | * | ||
2957 | * @{ | ||
2958 | */ | ||
2959 | |||
2960 | /** | ||
2961 | * @struct _Eina_Value_Type | ||
2962 | * API to access values. | ||
2963 | * | ||
2964 | * @since 1.2 | ||
2965 | */ | ||
2966 | struct _Eina_Value_Type | ||
2967 | { | ||
2968 | /** | ||
2969 | * @def EINA_VALUE_TYPE_VERSION | ||
2970 | * Current API version, used to validate type. | ||
2971 | */ | ||
2972 | #define EINA_VALUE_TYPE_VERSION (1) | ||
2973 | unsigned int version; /**< must be #EINA_VALUE_TYPE_VERSION */ | ||
2974 | unsigned int value_size; /**< byte size of value */ | ||
2975 | const char *name; /**< name for debug and introspection */ | ||
2976 | Eina_Bool (*setup)(const Eina_Value_Type *type, void *mem); /**< mem will be malloc(value_size) and should be configured */ | ||
2977 | Eina_Bool (*flush)(const Eina_Value_Type *type, void *mem); /**< clear any values from mem */ | ||
2978 | Eina_Bool (*copy)(const Eina_Value_Type *type, const void *src, void *dst); /**< how to copy values, both memory are @c value_size */ | ||
2979 | int (*compare)(const Eina_Value_Type *type, const void *a, const void *b); /**< how to compare values, both memory are @c value_size */ | ||
2980 | Eina_Bool (*convert_to)(const Eina_Value_Type *type, const Eina_Value_Type *convert, const void *type_mem, void *convert_mem); /**< how to convert values, both memory are @c value_size */ | ||
2981 | Eina_Bool (*convert_from)(const Eina_Value_Type *type, const Eina_Value_Type *convert, void *type_mem, const void *convert_mem); /**< how to convert values, both memory are @c value_size */ | ||
2982 | Eina_Bool (*vset)(const Eina_Value_Type *type, void *mem, va_list args); /**< how to set memory from variable argument */ | ||
2983 | Eina_Bool (*pset)(const Eina_Value_Type *type, void *mem, const void *ptr); /**< how to set memory from pointer */ | ||
2984 | Eina_Bool (*pget)(const Eina_Value_Type *type, const void *mem, void *ptr); /**< how to read memory */ | ||
2985 | }; | ||
2986 | |||
2987 | /** | ||
2988 | * @brief Query type name. | ||
2989 | * @param type type reference. | ||
2990 | * @return string or @c NULL if type is invalid. | ||
2991 | * @since 1.2 | ||
2992 | */ | ||
2993 | EAPI const char *eina_value_type_name_get(const Eina_Value_Type *type) EINA_PURE EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
2994 | |||
2995 | /** | ||
2996 | * @brief Check if type is valid. | ||
2997 | * @param type type reference. | ||
2998 | * @return #EINA_TRUE if valid, #EINA_FALSE otherwise. | ||
2999 | * | ||
3000 | * A type is invalid if it's NULL or if version field is not the same | ||
3001 | * as runtime #EINA_VALUE_TYPE_VERSION. | ||
3002 | * | ||
3003 | * @since 1.2 | ||
3004 | */ | ||
3005 | EAPI Eina_Bool eina_value_type_check(const Eina_Value_Type *type) EINA_PURE EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
3006 | |||
3007 | /** | ||
3008 | * @brief Initialize memory using type descriptor. | ||
3009 | * @param type type reference. | ||
3010 | * @param mem memory to operate, must be of size @c type->value_size. | ||
3011 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3012 | * @since 1.2 | ||
3013 | */ | ||
3014 | static inline Eina_Bool eina_value_type_setup(const Eina_Value_Type *type, void *mem); | ||
3015 | |||
3016 | /** | ||
3017 | * @brief Flush (clear) memory using type descriptor. | ||
3018 | * @param type type reference. | ||
3019 | * @param mem memory to operate, must be of size @c type->value_size. | ||
3020 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3021 | * @since 1.2 | ||
3022 | */ | ||
3023 | static inline Eina_Bool eina_value_type_flush(const Eina_Value_Type *type, void *mem); | ||
3024 | |||
3025 | /** | ||
3026 | * @brief Copy memory using type descriptor. | ||
3027 | * @param type type reference. | ||
3028 | * @param src memory to operate, must be of size @c type->value_size. | ||
3029 | * @param dst memory to operate, must be of size @c type->value_size. | ||
3030 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3031 | * @since 1.2 | ||
3032 | */ | ||
3033 | static inline Eina_Bool eina_value_type_copy(const Eina_Value_Type *type, const void *src, void *dst); | ||
3034 | |||
3035 | /** | ||
3036 | * @brief Compare memory using type descriptor. | ||
3037 | * @param type type reference. | ||
3038 | * @param a memory to operate, must be of size @c type->value_size. | ||
3039 | * @param b memory to operate, must be of size @c type->value_size. | ||
3040 | * @return less than zero if a < b, greater than zero if a > b, zero if equal. | ||
3041 | * @since 1.2 | ||
3042 | */ | ||
3043 | static inline int eina_value_type_compare(const Eina_Value_Type *type, const void *a, const void *b); | ||
3044 | |||
3045 | /** | ||
3046 | * @brief Convert memory using type descriptor. | ||
3047 | * @param type type reference of the source. | ||
3048 | * @param convert type reference of the destination. | ||
3049 | * @param type_mem memory to operate, must be of size @c type->value_size. | ||
3050 | * @param convert_mem memory to operate, must be of size @c convert->value_size. | ||
3051 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3052 | * @since 1.2 | ||
3053 | */ | ||
3054 | static inline Eina_Bool eina_value_type_convert_to(const Eina_Value_Type *type, const Eina_Value_Type *convert, const void *type_mem, void *convert_mem); | ||
3055 | |||
3056 | /** | ||
3057 | * @brief Convert memory using type descriptor. | ||
3058 | * @param type type reference of the destination. | ||
3059 | * @param convert type reference of the source. | ||
3060 | * @param type_mem memory to operate, must be of size @c type->value_size. | ||
3061 | * @param convert_mem memory to operate, must be of size @c convert->value_size. | ||
3062 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3063 | * @since 1.2 | ||
3064 | */ | ||
3065 | static inline Eina_Bool eina_value_type_convert_from(const Eina_Value_Type *type, const Eina_Value_Type *convert, void *type_mem, const void *convert_mem); | ||
3066 | |||
3067 | /** | ||
3068 | * @brief Set memory using type descriptor and variable argument. | ||
3069 | * @param type type reference of the source. | ||
3070 | * @param mem memory to operate, must be of size @c type->value_size. | ||
3071 | * @param args input value. | ||
3072 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3073 | * @since 1.2 | ||
3074 | */ | ||
3075 | static inline Eina_Bool eina_value_type_vset(const Eina_Value_Type *type, void *mem, va_list args); | ||
3076 | |||
3077 | /** | ||
3078 | * @brief Set memory using type descriptor and pointer. | ||
3079 | * @param type type reference of the source. | ||
3080 | * @param mem memory to operate, must be of size @c type->value_size. | ||
3081 | * @param ptr pointer to input value. | ||
3082 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3083 | * @since 1.2 | ||
3084 | */ | ||
3085 | static inline Eina_Bool eina_value_type_pset(const Eina_Value_Type *type, void *mem, const void *ptr); | ||
3086 | |||
3087 | /** | ||
3088 | * @brief Get memory using type descriptor. | ||
3089 | * @param type type reference of the source. | ||
3090 | * @param mem memory to operate, must be of size @c type->value_size. | ||
3091 | * @param ptr pointer to output. | ||
3092 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
3093 | * @since 1.2 | ||
3094 | */ | ||
3095 | static inline Eina_Bool eina_value_type_pget(const Eina_Value_Type *type, const void *mem, void *ptr); | ||
3096 | |||
3097 | /** | ||
3098 | * @} | ||
3099 | */ | ||
3100 | |||
3101 | #include "eina_inline_value.x" | ||
3102 | |||
3103 | /** | ||
3104 | * @} | ||
3105 | */ | ||
3106 | |||
3107 | /** | ||
3108 | * @} | ||
3109 | */ | ||
3110 | |||
3111 | /** | ||
3112 | * @} | ||
3113 | */ | ||
3114 | #endif | ||