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