From c963d75dfdeec11f82e79e727062fbf89afa2c04 Mon Sep 17 00:00:00 2001 From: David Walter Seikel Date: Sun, 22 Apr 2012 09:19:23 +1000 Subject: Update EFL to latest beta. --- libraries/eina/src/include/eina_value.h | 511 +++++++++++++++++++++++++++++--- 1 file changed, 465 insertions(+), 46 deletions(-) (limited to 'libraries/eina/src/include/eina_value.h') diff --git a/libraries/eina/src/include/eina_value.h b/libraries/eina/src/include/eina_value.h index 846c4ef..341781f 100644 --- a/libraries/eina/src/include/eina_value.h +++ b/libraries/eina/src/include/eina_value.h @@ -19,12 +19,244 @@ #ifndef EINA_VALUE_H_ #define EINA_VALUE_H_ +#include + #include "eina_types.h" #include "eina_fp.h" /* defines int64_t and uint64_t */ #include "eina_inarray.h" #include "eina_list.h" #include "eina_hash.h" -#include + +/** + * @page eina_value_example_01_page Eina_Value usage + * @dontinclude eina_value_01.c + * + * This very simple example shows how to use some of the basic features of eina + * value: setting and getting values, converting between types and printing a + * value as a string. + * + * Our main function starts out with the basic, declaring some variables and + * initializing eina: + * @until eina_init + * + * Now we can jump into using eina value. We set a value, get this value and + * then print it: + * @until printf + * + * In the above snippet of code we printed an @c int value, we can however print + * the value as a string: + * @until free + * + * And once done with a value it's good practice to destroy it: + * @until eina_value_flush + * + * We now reuse @c v to store a string, get its value and print it: + * @until printf + * @note Since @c s is the value and not returned by @c eina_value_to_string() + * we don't need to free it. + * + * Just because we stored a string doesn't mean we can't use the @c + * eina_value_to_string() function, we can and it's important to note that it + * will return not the stored string but rather a copy of it(one we have to + * free): + * @until eina_value_flush + * + * And now to explore conversions between two type we'll create another value: + * @until eina_value_setup + * + * And make sure @c v and @c otherv have different types: + * @until eina_value_setup + * + * We then set a value to @c v and have it converted, to do this we don't need + * to tell to which type we want to convert, we just say were we want to store + * the converted value and eina value will figure out what to convert to, and + * how: + * @until eina_value_convert + * + * And now let's check the conversion worked: + * @until printf + * + * But converting to strings is not particularly exciting, @c + * eina_value_to_string() already did that, so now let's make the conversion the + * other way around, from string to @c int: + * @until printf + * + * And once done, destroy the values: + * @until } + * + * Full source code: @ref eina_value_01_c + */ + +/** + * @page eina_value_01_c eina_value_01.c + * @include eina_value_01.c + * @example eina_value_01.c + */ + +/** + * @page eina_value_example_02_page Eina_Value struct usage + * @dontinclude eina_value_02.c + * + * This example will examine a hypothetical situation in which we had a + * structure(which represented parameters) with two fields, and then need to add + * a third field to our structure. If using structs directly we'd need to + * rewrite every piece of code that touches the struct, by using eina value, and + * thus having the compiler not even know the struct, we can reduce the amount + * of changes needed and retain interoperability between the old and new format. + * + * Our example will start with a function that creates descriptions of both of + * our structs for eina value usage. The first step is to create a struct and + * describe its members: + * @until v1_members[1] + * @note We can't pass the types of the members to EINA_VALUE_STRUCT_MEMBER + * macro because they are not constant initializers. + * + * So far it should be pretty easy to understand, we said @c My_Struct_V1 has + * two members, one of type @c int and another of type @c char. We now create + * the description of the actual struct, again nothing overly complex, we signal + * which version of EINA_VALUE_STRUCT we're using, we declare no special + * operations, our members and our size: + * @until V1_DESC + * + * We now repeat the process for the second version of our struct, the only + * difference is the addition of a third parameter of type @c int : + * @until V2_DESC + * @until } + * + * We'll now look at a function that sets the values of our structs. For + * simplicity's sake we initialize it we random values, a real world case would + * read these values from a file, a database or even from the network. The + * fundamental detail here is that this function works for both V1 and V2 + * structs, this is because setting a parameter that a struct that doesn't have + * does nothing without throwing any errors: + * @until } + * @note While using eina_value_struct_set() with an in-existing parameter + * causes no error, it does return #EINA_FALSE, to notify it was not possible + * to set the value. This could be used to determine that we're handling a V1 + * struct and take some action based on that. + * + * The next thing is to do is see what a function that uses the values of the + * struct looks like. We'll again be very simplistic in our usage, we'll just + * print the values, but a real world case, might send these values to another + * process use them to open a network/database connection or anything else. + * Since all versions of the struct have @c param1 and @c param2 we'll + * unconditionally use them: + * @until printf + * + * The next step is to conditionally use @c param3, which can fortunately be + * done in the same step in which we get it's value: + * @until } + * + * There we've now got functions that can both populate and use values from both + * our structs, so now let's actually use them in our main function by creating + * a struct of each type, initializing them and them using them: + * @until } + * + * This concludes our example. For the full source code see @ref + * eina_value_02_c. + */ + +/** + * @page eina_value_02_c eina_value_02.c + * @include eina_value_02.c + * @example eina_value_02.c + */ + +/** + * @page eina_value_example_03_page Eina value custom type example + * @dontinclude eina_value_03.c + * + * For this example we'll be creating our own custom type of eina value. Eina + * value can already store struct timeval(man gettimeofday for more information) + * but it has no type to store struct timezone, so that's what this example will + * do. + * @note struct timezone is actually obsolete, so using it in real world + * programs is probably not a good idea, but this is an example so, bear with + * us. + * + * To create our own custom eina value type we need to define functions to + * do the following operations on it: + * @li Setup + * @li Flush + * @li Copy + * @li Compare + * @li Set + * @li Get + * @li Conversion + * + * Most of this functions are very simple, so let's look at them, starting with + * setup which only clear the memory so that we can be certain we won't be using + * stale data: + * @until } + * + * Now the flush function, which is even simpler, it does nothing, that's + * because there is nothing we need to do, all the necessary steps are taken by + * eina value itself: + * @until } + * + * Our next function, copy, is a bit more interesting, but not much, it just + * casts our void pointers to struct timezone pointers and does the copy: + * @until } + * @note By now you might be wondering why our functions receive void pointers + * instead of pointers to struct timezone, and this is a good point. The reason + * for this is that eina value doesn't know anything about our type so it must + * use a generic void pointer, casting that pointer into a proper value is the + * job of the implementor of the new type. + * + * Next we have the comparison function, which compares the @c tz_minuteswest + * field of struct timezone, we don't compare @c tz_dsttime because that field + * is not used in linux: + * @until } + * + * Next we have setting, this however requires not one but rather two functions, + * the reason for this is because to be able to receive arguments of any type + * eina value uses @ref https://wikipedia.org/wiki/Variadic_functions "variadic + * functions", so we need a function to get the argument from a va_list and + * another to actually to the setting. + * + * Lets first look at the pset function which sets the received value to a + * pointer: + * @until } + * + * Next we have the vset function which get the argument from the va_list and + * passes it to the pset function: + * @until } + * + * And now the function to get the value, a very simple copying of the value to + * the given pointer: + * @until } + * + * And finally our conversion function, this is our longest and most interesting + * one. For numeric type we simply assign the value of @c tz_minuteswest to the + * new type and call a set function using it: + * @until EINA_VALUE_TYPE_DOUBLE + * @until return + * @note It would be a good idea to add checks for over and underflow for these + * types and return #EINA_FALSE in thoses cases, we omit this here for brevity. + * + * For string types we use @c snprintf() to format our @c tz_minuteswest field + * and put it in a string(again @c tz_dsttime is ignored because it's not used): + * @until } + * + * Finally we handle any other types by returning an error in that case: + * @until } + * + * Now that we have all the functions, we can populate an @c Eina_Value_Type to + * later use it with @c eina_value_setup(): + * @until } + * + * We can now finally use our new TZ_TYPE with eina value, so lets conclude our + * example by practicing that by setting its value and printing it: + * @until } + * + * For the full source code see @ref eina_value_03_c. + */ + +/** + * @page eina_value_03_c eina_value_03.c + * @include eina_value_03.c + * @example eina_value_03.c + */ /** * @addtogroup Eina_Data_Types_Group Data Types @@ -43,6 +275,24 @@ /** * @defgroup Eina_Value_Group Generic Value Storage * + * Abstracts generic data storage and access to it in an extensible + * and efficient way. + * + * It comes with pre-defined types for numbers, array, list, hash, + * blob and structs. It is able to convert between data types, + * including to string. + * + * It is meant for simple data types, providing uniform access and + * release functions, useful to exchange data preserving their + * types. For more complex hierarchical data, with properties and + * children, reference counting, inheritance and interfaces, see @ref + * Eina_Model_Group. + * + * Examples of usage of the Eina_Value API: + * @li @ref eina_value_example_01_page + * @li @ref eina_value_example_02_page + * @li @ref eina_value_example_03_page + * * @{ */ @@ -67,6 +317,9 @@ typedef struct _Eina_Value_Type Eina_Value_Type; * @typedef Eina_Value_Union * Union of all known value types. * + * This is only used to specify the minimum payload memory for #Eina_Value. + * + * @internal * @since 1.2 */ typedef union _Eina_Value_Union Eina_Value_Union; @@ -75,6 +328,9 @@ typedef union _Eina_Value_Union Eina_Value_Union; * @union _Eina_Value_Union * All possible value types. * + * This is only used to specify the minimum payload memory for #Eina_Value. + * + * @internal * @since 1.2 */ union _Eina_Value_Union @@ -117,6 +373,15 @@ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_UINT; EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_ULONG; /** + * @var EINA_VALUE_TYPE_TIMESTAMP + * manages unsigned long type used for timestamps. + * @note this is identical in function to EINA_VALUE_TYPE_ULONG + * + * @since 1.2 + */ +EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_TIMESTAMP; + +/** * @var EINA_VALUE_TYPE_UINT64 * manages unsigned integer of 64 bits type. * @@ -206,10 +471,11 @@ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_STRING; * @li eina_value_array_pget() and eina_value_array_pset() * * eina_value_set() takes an #Eina_Value_Array where just @c subtype - * and @c step are used. If there is an @c array, it will be adopted - * and its contents must be properly configurable as @c subtype - * expects. eina_value_pset() takes a pointer to an #Eina_Value_Array. - * For your convenience, use eina_value_array_setup(). + * and @c step are used. If there is an @c array, it will be copied + * (including each item) and its contents must be properly + * configurable as @c subtype expects. eina_value_pset() takes a + * pointer to an #Eina_Value_Array. For your convenience, use + * eina_value_array_setup(). * * eina_value_get() and eina_value_pget() takes a pointer to * #Eina_Value_Array, it's an exact copy of the current structure in @@ -228,10 +494,11 @@ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_ARRAY; * @li eina_value_list_pget() and eina_value_list_pset() * * eina_value_set() takes an #Eina_Value_List where just @c subtype is - * used. If there is an @c list, it will be adopted and its contents - * must be properly configurable as @c subtype - * expects. eina_value_pset() takes a pointer to an #Eina_Value_List. - * For your convenience, use eina_value_list_setup(). + * used. If there is an @c list, it will be copied (including each + * item) and its contents must be properly configurable as @c + * subtype expects. eina_value_pset() takes a pointer to an + * #Eina_Value_List. For your convenience, use + * eina_value_list_setup(). * * eina_value_get() and eina_value_pget() takes a pointer to * #Eina_Value_List, it's an exact copy of the current structure in @@ -251,9 +518,9 @@ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_LIST; * * eina_value_set() takes an #Eina_Value_Hash where just @c subtype * and @c buckets_power_size are used. If there is an @c hash, it will - * be adopted and its contents must be properly configurable as @c - * subtype expects. eina_value_pset() takes a pointer to an - * #Eina_Value_Hash. For your convenience, use + * be copied (including each item) and its contents must be + * properly configurable as @c subtype expects. eina_value_pset() + * takes a pointer to an #Eina_Value_Hash. For your convenience, use * eina_value_hash_setup(). * * eina_value_get() and eina_value_pget() takes a pointer to @@ -310,9 +577,10 @@ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_BLOB; * @li eina_value_struct_pget() and eina_value_struct_pset() * * eina_value_set() takes an #Eina_Value_Struct where just @c desc is - * used. If there is an @c memory, it will be adopted and its contents - * must be properly configurable as @c desc expects. eina_value_pset() - * takes a pointer to an #Eina_Value_Struct. For your convenience, use + * used. If there is an @c memory, it will be copied (including each + * member) and its contents must be properly configurable as @c desc + * expects. eina_value_pset() takes a pointer to an + * #Eina_Value_Struct. For your convenience, use * eina_value_struct_setup(). * * eina_value_get() and eina_value_pget() takes a pointer to @@ -324,6 +592,23 @@ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_BLOB; EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_STRUCT; /** + * @var EINA_VALUE_TYPE_MODEL + * + * manages Eina_Model type. Use the value get/set to change the model + * in use, it will increase the reference while in use by the value. + * + * eina_value_set() takes a pointer to #Eina_Model, increasing the + * reference. + * + * eina_value_get() takes a pointer to pointer to #Eina_Model, it's an + * exact copy of the current model, no copies are done, no references + * are increased. + * + * @since 1.2 + */ +EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_MODEL; + +/** * @var EINA_ERROR_VALUE_FAILED * Error identifier corresponding to value check failure. * @@ -435,7 +720,7 @@ static inline void eina_value_flush(Eina_Value *value) EINA_ARG_NONNULL(1); * @param copy destination value object * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * - * The @a copy object is considered internalized and its existing + * The @a copy object is considered uninitialized and its existing * contents are overwritten (just as if eina_value_flush() was called on * it). * @@ -812,8 +1097,9 @@ static inline const Eina_Value_Type *eina_value_type_get(const Eina_Value *value /** * @typedef Eina_Value_Array - * Value type for #EINA_VALUE_TYPE_ARRAY + * Value type for #EINA_VALUE_TYPE_ARRAY. * + * @see #_Eina_Value_Array explains fields. * @since 1.2 */ typedef struct _Eina_Value_Array Eina_Value_Array; @@ -821,6 +1107,7 @@ typedef struct _Eina_Value_Array Eina_Value_Array; /** * @struct _Eina_Value_Array * Used to store the array and its subtype. + * @since 1.2 */ struct _Eina_Value_Array { @@ -1433,6 +1720,22 @@ static inline Eina_Bool eina_value_array_pappend(Eina_Value *value, const void *ptr) EINA_ARG_NONNULL(1); /** + * @brief Retrieves a value from the array as an Eina_Value copy. + * @param value source value object + * @param position index of the member + * @param dst where to return the array member + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * The argument @a dst is considered uninitialized and it's setup to + * the type of the member. + * + * @since 1.2 + */ +static inline Eina_Bool eina_value_array_value_get(const Eina_Value *src, + unsigned int position, + Eina_Value *dst) EINA_ARG_NONNULL(1, 3); + +/** * @} */ @@ -1446,8 +1749,9 @@ static inline Eina_Bool eina_value_array_pappend(Eina_Value *value, /** * @typedef Eina_Value_List - * Value type for #EINA_VALUE_TYPE_LIST + * Value type for #EINA_VALUE_TYPE_LIST. * + * @see #_Eina_Value_List explains fields. * @since 1.2 */ typedef struct _Eina_Value_List Eina_Value_List; @@ -1455,6 +1759,7 @@ typedef struct _Eina_Value_List Eina_Value_List; /** * @struct _Eina_Value_List * Used to store the list and its subtype. + * @since 1.2 */ struct _Eina_Value_List { @@ -2067,8 +2372,9 @@ static inline Eina_Bool eina_value_list_pappend(Eina_Value *value, /** * @typedef Eina_Value_Hash - * Value type for #EINA_VALUE_TYPE_HASH + * Value type for #EINA_VALUE_TYPE_HASH. * + * @see #_Eina_Value_Hash explains fields. * @since 1.2 */ typedef struct _Eina_Value_Hash Eina_Value_Hash; @@ -2076,6 +2382,7 @@ typedef struct _Eina_Value_Hash Eina_Value_Hash; /** * @struct _Eina_Value_Hash * Used to store the hash and its subtype. + * @since 1.2 */ struct _Eina_Value_Hash { @@ -2409,19 +2716,25 @@ static inline Eina_Bool eina_value_hash_pget(const Eina_Value *value, /** * @typedef Eina_Value_Blob_Operations * How to manage blob. Any @c NULL callback is ignored. + * @see #_Eina_Value_Blob_Operations explains fields. * @since 1.2 */ typedef struct _Eina_Value_Blob_Operations Eina_Value_Blob_Operations; /** + * @def EINA_VALUE_BLOB_OPERATIONS_VERSION + * Current API version, used to validate #_Eina_Value_Blob_Operations. + */ +#define EINA_VALUE_BLOB_OPERATIONS_VERSION (1) + +/** * @struct _Eina_Value_Blob_Operations * How to manage blob. Any @c NULL callback is ignored. * @since 1.2 */ struct _Eina_Value_Blob_Operations { -#define EINA_VALUE_BLOB_OPERATIONS_VERSION (1) - unsigned int version; /**< must be EINA_VALUE_BLOB_OPERATIONS_VERSION */ + unsigned int version; /**< must be #EINA_VALUE_BLOB_OPERATIONS_VERSION */ void (*free)(const Eina_Value_Blob_Operations *ops, void *memory, size_t size); void *(*copy)(const Eina_Value_Blob_Operations *ops, const void *memory, size_t size); int (*compare)(const Eina_Value_Blob_Operations *ops, const void *data1, size_t size_data1, const void *data2, size_t size_data2); @@ -2441,12 +2754,16 @@ EAPI extern const Eina_Value_Blob_Operations *EINA_VALUE_BLOB_OPERATIONS_MALLOC; /** * @typedef Eina_Value_Blob + * Value type for #EINA_VALUE_TYPE_BLOB. + * + * @see #_Eina_Value_Blob explains fields. * @since 1.2 */ typedef struct _Eina_Value_Blob Eina_Value_Blob; /** * @struct _Eina_Value_Blob + * Used to store the blob information and management operations. * @since 1.2 */ struct _Eina_Value_Blob @@ -2469,6 +2786,11 @@ struct _Eina_Value_Blob /** * @typedef Eina_Value_Struct_Operations * How to manage struct. Any @c NULL callback is ignored. + * + * A structure can specify alternative methods to allocate, free and + * copy itself. See structure definition for all methods. + * + * @see #_Eina_Value_Struct_Operations explains fields. * @since 1.2 */ typedef struct _Eina_Value_Struct_Operations Eina_Value_Struct_Operations; @@ -2476,6 +2798,12 @@ typedef struct _Eina_Value_Struct_Operations Eina_Value_Struct_Operations; /** * @typedef Eina_Value_Struct_Member * Describes a single member of struct. + * + * The member holds a name, type and its byte offset within the struct + * memory. Most Eina_Value_Struct functions takes the member name as + * parameter, as in eina_value_struct_set(). + * + * @see #_Eina_Value_Struct_Member explains fields. * @since 1.2 */ typedef struct _Eina_Value_Struct_Member Eina_Value_Struct_Member; @@ -2483,30 +2811,39 @@ typedef struct _Eina_Value_Struct_Member Eina_Value_Struct_Member; /** * @typedef Eina_Value_Struct_Desc * Describes the struct by listing its size, members and operations. + * @see #_Eina_Value_Struct_Desc explains fields. * @since 1.2 */ typedef struct _Eina_Value_Struct_Desc Eina_Value_Struct_Desc; /** * @typedef Eina_Value_Struct + * Value type for #EINA_VALUE_TYPE_STRUCT. + * + * @see #_Eina_Value_Struct explains fields. * @since 1.2 */ typedef struct _Eina_Value_Struct Eina_Value_Struct; /** + * @def EINA_VALUE_STRUCT_OPERATIONS_VERSION + * Current API version, used to validate #_Eina_Value_Struct_Operations. + */ +#define EINA_VALUE_STRUCT_OPERATIONS_VERSION (1) + +/** * @struct _Eina_Value_Struct_Operations * How to manage struct. Any @c NULL callback is ignored. * @since 1.2 */ struct _Eina_Value_Struct_Operations { -#define EINA_VALUE_STRUCT_OPERATIONS_VERSION (1) - unsigned int version; /**< must be EINA_VALUE_STRUCT_OPERATIONS_VERSION */ - void *(*alloc)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc); - void (*free)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, void *memory); - void *(*copy)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const void *memory); - int (*compare)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const void *data1, const void *data2); - const Eina_Value_Struct_Member *(*find_member)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const char *name); /**< replace the function to find description for member. For huge structures consider using binary search, stringshared, hash or gperf. The default function does linear search using strcmp(). */ + unsigned int version; /**< must be #EINA_VALUE_STRUCT_OPERATIONS_VERSION */ + 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 */ + 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 */ + 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. */ + 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 */ + 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(). */ }; /** @@ -2539,23 +2876,48 @@ EAPI extern const Eina_Value_Struct_Operations *EINA_VALUE_STRUCT_OPERATIONS_STR /** * @struct _Eina_Value_Struct_Member + * Describes a single member of struct. + * + * The name is used to lookup the member description. This is done as + * specified as _Eina_Value_Struct_Operations::find_member(). For + * structures with huge number of members, consider using a better + * find_member function to quickly finding it! There are two helper + * operations provided to help this: + * #EINA_VALUE_STRUCT_OPERATIONS_BINSEARCH and + * #EINA_VALUE_STRUCT_OPERATIONS_STRINGSHARE, both depend on properly + * set #_Eina_Value_Struct_Desc and #_Eina_Value_Struct_Member. + * + * @see #EINA_VALUE_STRUCT_MEMBER + * @see #EINA_VALUE_STRUCT_MEMBER_SENTINEL + * * @since 1.2 */ struct _Eina_Value_Struct_Member { - const char *name; - const Eina_Value_Type *type; - unsigned int offset; + const char *name; /**< member name, used in lookups such as eina_value_struct_get() */ + const Eina_Value_Type *type; /**< how to use this member */ + unsigned int offset; /**< where this member is located within the structure memory */ }; /** + * @def EINA_VALUE_STRUCT_DESC_VERSION + * Current API version, used to validate #_Eina_Value_Struct_Desc. + */ +#define EINA_VALUE_STRUCT_DESC_VERSION (1) + +/** * @struct _Eina_Value_Struct_Desc + * Describes the struct by listing its size, members and operations. + * + * This is the root of Eina_Value knowledge about the memory it's + * handling as a structure. It adds introspection, saying the byte + * size of the structure, its members and how to manage such members. + * * @since 1.2 */ struct _Eina_Value_Struct_Desc { -#define EINA_VALUE_STRUCT_DESC_VERSION (1) - unsigned int version; /**< must be EINA_VALUE_STRUCT_DESC_VERSION */ + unsigned int version; /**< must be #EINA_VALUE_STRUCT_DESC_VERSION */ 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. */ const Eina_Value_Struct_Member *members; /**< array of member descriptions, if @c member_count is zero, then it must be @c NULL terminated. */ unsigned int member_count; /**< if > 0, specifies number of members. If zero then @c members must be NULL terminated. */ @@ -2586,12 +2948,13 @@ struct _Eina_Value_Struct_Desc /** * @struct _Eina_Value_Struct + * Used to store the memory and its description. * @since 1.2 */ struct _Eina_Value_Struct { - const Eina_Value_Struct_Desc *desc; - void *memory; + const Eina_Value_Struct_Desc *desc; /**< How to manage the structure */ + void *memory; /**< The managed structure memory */ }; /** @@ -2702,7 +3065,7 @@ static inline Eina_Bool eina_value_struct_setup(Eina_Value *value, */ static inline Eina_Bool eina_value_struct_set(Eina_Value *value, const char *name, - ...) EINA_ARG_NONNULL(1); + ...) EINA_ARG_NONNULL(1, 2); /** * @brief Get the generic value from an struct member. @@ -2770,7 +3133,7 @@ static inline Eina_Bool eina_value_struct_set(Eina_Value *value, */ static inline Eina_Bool eina_value_struct_get(const Eina_Value *value, const char *name, - ...) EINA_ARG_NONNULL(1); + ...) EINA_ARG_NONNULL(1, 2); /** * @brief Set the generic value in an struct member. @@ -2786,7 +3149,7 @@ static inline Eina_Bool eina_value_struct_get(const Eina_Value *value, */ static inline Eina_Bool eina_value_struct_vset(Eina_Value *value, const char *name, - va_list args) EINA_ARG_NONNULL(1); + va_list args) EINA_ARG_NONNULL(1, 2); /** * @brief Get the generic value from an struct member. @@ -2808,7 +3171,7 @@ static inline Eina_Bool eina_value_struct_vset(Eina_Value *value, */ static inline Eina_Bool eina_value_struct_vget(const Eina_Value *value, const char *name, - va_list args) EINA_ARG_NONNULL(1); + va_list args) EINA_ARG_NONNULL(1, 2); /** * @brief Set the generic value in an struct member from pointer. @@ -2875,7 +3238,7 @@ static inline Eina_Bool eina_value_struct_vget(const Eina_Value *value, */ static inline Eina_Bool eina_value_struct_pset(Eina_Value *value, const char *name, - const void *ptr) EINA_ARG_NONNULL(1, 3); + const void *ptr) EINA_ARG_NONNULL(1, 2, 3); /** * @brief Get the generic value to pointer from an struct member. @@ -2944,7 +3307,62 @@ static inline Eina_Bool eina_value_struct_pset(Eina_Value *value, */ static inline Eina_Bool eina_value_struct_pget(const Eina_Value *value, const char *name, - void *ptr) EINA_ARG_NONNULL(1, 3); + void *ptr) EINA_ARG_NONNULL(1, 2, 3); + +/** + * @brief Get the member as Eina_Value copy + * @param src source value object + * @param name name to find the member + * @param dst where to return the member value. + * + * The argument @a dst is considered uninitialized and it's setup to + * the type of the member. + * + * @since 1.2 + */ +static inline Eina_Bool eina_value_struct_value_get(const Eina_Value *src, + const char *name, + Eina_Value *dst) EINA_ARG_NONNULL(1, 2, 3); + +/** + * @brief Set the member from Eina_Value source + * @param dst destination value object + * @param name name to find the member + * @param src source value + * + * @since 1.2 + */ +static inline Eina_Bool eina_value_struct_value_set(Eina_Value *dst, + const char *name, + const Eina_Value *src) EINA_ARG_NONNULL(1, 2, 3); + +/** + * @brief Get the member as Eina_Value copy given its member description. + * @param src source value object + * @param member the member description to use + * @param dst where to return the member value. + * + * The argument @a dst is considered uninitialized and it's setup to + * the type of the member. + * + * @since 1.2 + */ +static inline Eina_Bool eina_value_struct_member_value_get(const Eina_Value *src, + const Eina_Value_Struct_Member *member, + Eina_Value *dst) EINA_ARG_NONNULL(1, 2, 3); + +/** + * @brief Set the member from Eina_Value source + * @param dst destination value object + * @param member the member description to use + * @param src source value + * + * @since 1.2 + */ +static inline Eina_Bool eina_value_struct_member_value_set(Eina_Value *dst, + const Eina_Value_Struct_Member *member, + const Eina_Value *src) EINA_ARG_NONNULL(1, 2, 3); + /** * @} @@ -2958,6 +3376,12 @@ static inline Eina_Bool eina_value_struct_pget(const Eina_Value *value, */ /** + * @def EINA_VALUE_TYPE_VERSION + * Current API version, used to validate type. + */ +#define EINA_VALUE_TYPE_VERSION (1) + +/** * @struct _Eina_Value_Type * API to access values. * @@ -2965,11 +3389,6 @@ static inline Eina_Bool eina_value_struct_pget(const Eina_Value *value, */ struct _Eina_Value_Type { - /** - * @def EINA_VALUE_TYPE_VERSION - * Current API version, used to validate type. - */ -#define EINA_VALUE_TYPE_VERSION (1) unsigned int version; /**< must be #EINA_VALUE_TYPE_VERSION */ unsigned int value_size; /**< byte size of value */ const char *name; /**< name for debug and introspection */ -- cgit v1.1