*
* 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
+ * 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:
+ * And now to explore conversions between two types we'll create another value:
* @until eina_value_setup
*
* And make sure @c v and @c others have different types:
* 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,
+ * It comes with pre-defined types for numbers, arrays, lists, hashes,
+ * blobs and structs. It is able to convert between data types,
* including to string.
*
* It is meant for simple data types, providing uniform access and
*/
EAPI void eina_value_free(Eina_Value *value);
-
/**
* @brief Initializes generic value storage.
+ *
* @param value Value object
* @param type How to manage this value.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
/**
* @brief Creates generic value storage.
+ *
* @param value Value object
*
* Releases all the resources associated with an #Eina_Value. The
/**
* @brief Copies generic value storage.
+ *
* @param value Source value object
* @param copy Destination value object
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
/**
* @brief Sets the generic value.
+ *
* @param value Source value object
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
/**
* @brief Gets the generic value.
+ *
* @param value Source value object
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
/**
* @brief Sets the generic value.
+ *
* @param value Source value object
* @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
/**
* @brief Gets the generic value.
+ *
* @param value Source value object
* @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
/**
* @brief Gets the generic value to pointer.
+ *
* @param value Source value object
* @param ptr Pointer to receive the contents.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
/**
* @brief Converts one value to another type.
+ *
* @param value Source value object.
* @param convert Destination value object.
* @return #EINA_TRUE if converted, #EINA_FALSE otherwise.
/**
* @brief Appends a generic value in an array.
+ *
* @param value Source value object
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
/**
* @brief Sets a generic value to an array member.
+ *
* @param value Source value object
* @param position Index of the member
* @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @see eina_value_array_set()
* @see eina_value_array_get()
* @see eina_value_array_pset()
/**
* @brief Gets the generic value from an array member.
+ *
* @param value Source value object
* @param position Index of the member
* @param args Variable argument
va_list args) EINA_ARG_NONNULL(1);
/**
* @brief Inserts a generic value to an array member position.
+ *
* @param value Source value object
* @param position Index of the member
* @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @see eina_value_array_set()
* @see eina_value_array_get()
* @see eina_value_array_vset()
/**
* @brief Appends a generic value to an array.
+ *
* @param value Source value object
* @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @see eina_value_array_set()
* @see eina_value_array_get()
* @see eina_value_array_vget()
/**
* @brief Sets a generic value to an array member from a pointer.
+ *
* @param value Source value object
* @param position Index of the member
* @param ptr Pointer to specify the contents.
/**
* @brief Retrieves a generic value into a pointer from an array member.
+ *
* @param value Source value object
* @param position Index of the member
* @param ptr Pointer to receive the contents.
/**
* @brief Inserts a generic value to an array member position from a pointer.
+ *
* @param value Source value object
* @param position Index of the member
* @param ptr Pointer to specify the contents.
/**
* @brief Retrieves a value from the array as an Eina_Value copy.
+ *
* @param src 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 argument @a dst is considered uninitialized and it's set to
* the type of the member.
*
* @since 1.2
/**
* @brief Creates generic value storage of type list.
+ *
* @param subtype How to manage this list members.
* @return The new value, or @c NULL on failure.
*
/**
* @brief Initializes generic value storage of type list.
+ *
* @param value Value object
* @param subtype How to manage this list members.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
/**
* @brief Queries number of elements in value of list type.
+ *
* @param value value object.
* @return number of child elements.
+ *
* @since 1.2
*/
static inline unsigned int eina_value_list_count(const Eina_Value *value);
/**
* @brief Removes element at given position in value of list type.
+ *
* @param value value object.
* @param position index of the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @since 1.2
*/
static inline Eina_Bool eina_value_list_remove(Eina_Value *value,
unsigned int position) EINA_ARG_NONNULL(1);
/**
- * @brief Sets the generic value in an list member.
+ * @brief Sets the generic value in a list member.
+ *
* @param value Source value object
* @param position Index of the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
...) EINA_ARG_NONNULL(1);
/**
- * @brief Gets the generic value from an list member.
+ * @brief Gets the generic value from a list member.
+ *
* @param value Source value object
* @param position Index of the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
...) EINA_ARG_NONNULL(1);
/**
- * @brief Inserts the generic value in an list member position.
+ * @brief Inserts the generic value in a list member position.
+ *
* @param value Source value object
* @param position Index of the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
/**
- * @brief Appends the generic value in an list.
+ * @brief Appends the generic value in a list.
+ *
* @param value Source value object
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
...) EINA_ARG_NONNULL(1);
/**
- * @brief Sets the generic value in an list member.
+ * @brief Sets the generic value in a list member.
+ *
* @param value Source value object
* @param position Index of the member
* @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @see eina_value_list_set()
* @see eina_value_list_get()
* @see eina_value_list_pset()
va_list args) EINA_ARG_NONNULL(1);
/**
- * @brief Gets the generic value from an list member.
+ * @brief Gets the generic value from a list member.
+ *
* @param value Source value object
* @param position Index of the member
* @param args Variable argument
unsigned int position,
va_list args) EINA_ARG_NONNULL(1);
/**
- * @brief Inserts the generic value in an list member position.
+ * @brief Inserts the generic value in a list member position.
+ *
* @param value Source value object
* @param position Index of the member
* @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @see eina_value_list_set()
* @see eina_value_list_get()
* @see eina_value_list_vset()
va_list args) EINA_ARG_NONNULL(1);
/**
- * @brief Appends the generic value in an list.
+ * @brief Appends the generic value in a list.
+ *
* @param value Source value object
* @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @see eina_value_list_set()
* @see eina_value_list_get()
* @see eina_value_list_vget()
/**
- * @brief Sets the generic value in an list member from pointer.
+ * @brief Sets the generic value in a list member from pointer.
+ *
* @param value Source value object
* @param position Index of the member
* @param ptr Pointer to specify the contents.
const void *ptr) EINA_ARG_NONNULL(1, 3);
/**
- * @brief Gets the generic value to pointer from an list member.
+ * @brief Gets the generic value to pointer from a list member.
+ *
* @param value Source value object
* @param position Index of the member
* @param ptr Pointer to receive the contents.
void *ptr) EINA_ARG_NONNULL(1, 3);
/**
- * @brief Inserts the generic value in an list member position from pointer.
+ * @brief Inserts the generic value in a list member position from pointer.
+ *
* @param value Source value object
* @param position Index of the member
* @param ptr Pointer to specify the contents.
const void *ptr) EINA_ARG_NONNULL(1);
/**
- * @brief Appends the generic value in an list from pointer.
+ * @brief Appends the generic value in a list from pointer.
+ *
* @param value Source value object
* @param ptr Pointer to specify the contents.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
/**
* @brief Creates generic value storage of type hash.
+ *
* @param subtype How to manage this hash members.
* @param buckets_power_size How to allocate hash buckets (2 ^
* buckets_power_size), if zero then a sane value is chosen.
* @return The new value, or @c NULL on failure.
*
- * Create a new generic value storage of type hash. The members are
+ * Creates a new generic value storage of type hash. The members are
* managed using the description specified by @a subtype.
*
* On failure, @c NULL is returned.
/**
* @brief Initializes generic value storage of type hash.
+ *
* @param value Value object
* @param subtype How to manage this hash members.
* @param buckets_power_size How to allocate hash buckets (2 ^
/**
* @brief Queries number of elements in value of hash type.
+ *
* @param value value object.
* @return number of child elements.
+ *
* @since 1.2
*/
static inline unsigned int eina_value_hash_population(const Eina_Value *value);
/**
* @brief Removes element at given position in value of hash type.
+ *
* @param value value object.
* @param key key to find the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @since 1.2
*/
static inline Eina_Bool eina_value_hash_del(Eina_Value *value,
/**
* @brief Sets the generic value in an hash member.
+ *
* @param value Source value object
* @param key Key to find the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
/**
* @brief Gets the generic value from an hash member.
+ *
* @param value Source value object
* @param key Key to find the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
/**
* @brief Sets the generic value in an hash member.
+ *
* @param value Source value object
* @param key Key to find the member
* @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @see eina_value_hash_set()
* @see eina_value_hash_get()
* @see eina_value_hash_pset()
/**
* @brief Gets the generic value from an hash member.
+ *
* @param value Source value object
* @param key Key to find the member
* @param args Variable argument
/**
* @brief Sets the generic value in an hash member from pointer.
+ *
* @param value Source value object
* @param key Key to find the member
* @param ptr Pointer to specify the contents.
/**
* @brief Gets the generic value to pointer from an hash member.
+ *
* @param value Source value object
* @param key Key to find the member
* @param ptr Pointer to receive the contents.
* @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;
/**
* @struct _Eina_Value_Blob_Operations
* How to manage blob. Any @c NULL callback is ignored.
+ *
* @since 1.2
*/
struct _Eina_Value_Blob_Operations
* 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
* 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;
* @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;
* Value type for #EINA_VALUE_TYPE_STRUCT.
*
* @see #_Eina_Value_Struct explains fields.
+ *
* @since 1.2
*/
typedef struct _Eina_Value_Struct Eina_Value_Struct;
/**
* @struct _Eina_Value_Struct_Operations
* How to manage struct. Any @c NULL callback is ignored.
+ *
* @since 1.2
*/
struct _Eina_Value_Struct_Operations
/**
* @brief Creates generic value storage of type struct.
+ *
* @param desc How to manage this struct members.
* @return The new value, or @c NULL on failure.
*
/**
* @brief Initializes generic value storage of type struct.
+ *
* @param value Value object
* @param desc How to manage this struct members.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
/**
* @brief Checks for a struct and get its description.
+ *
* @param value Value object
* @return structure description, with all members and size.
* on failure, #NULL is returned.
static inline const Eina_Value_Struct_Desc *eina_value_struct_desc_get(const Eina_Value *value) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Sets the generic value in an struct member.
+ * @brief Sets the generic value in a struct member.
+ *
* @param value Source value object
* @param name Name to find the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
...) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Gets the generic value from an struct member.
+ * @brief Gets the generic value from a struct member.
+ *
* @param value Source value object
* @param name Name to find the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
...) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Sets the generic value in an struct member.
+ * @brief Sets the generic value in a struct member.
+ *
* @param value Source value object
* @param name Name to find the member
* @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @see eina_value_struct_set()
* @see eina_value_struct_get()
* @see eina_value_struct_pset()
va_list args) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Gets the generic value from an struct member.
+ * @brief Gets the generic value from a struct member.
+ *
* @param value Source value object
* @param name Name to find the member
* @param args Variable argument
va_list args) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Sets the generic value in an struct member from pointer.
+ * @brief Sets the generic value in a struct member from pointer.
+ *
* @param value Source value object
* @param name Name to find the member
* @param ptr Pointer to specify the contents.
* @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob*
* @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct*
* @li EINA_VALUE_TYPE_TM: struct tm*
- *
+ *
* @note the pointer contents are written using the size defined by
* type. It can be larger than void* or uint64_t.
*
const void *ptr) EINA_ARG_NONNULL(1, 2, 3);
/**
- * @brief Gets the generic value to pointer from an struct member.
+ * @brief Gets the generic value to pointer from a struct member.
+ *
* @param value Source value object
* @param name Name to find the member
* @param ptr Pointer to receive the contents.
/**
* @brief Gets the member as Eina_Value copy
+ *
* @param src Source value object
* @param name Name to find the member
- * @param dst Shere to return the member value.
+ * @param dst Where to return the member value.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The argument @a dst is considered uninitialized and it's setup to
/**
* @brief Sets the member from Eina_Value source.
+ *
* @param dst destination value object
* @param name name to find the member
* @param src source value
/**
* @brief Gets 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.
/**
* @brief Sets the member from Eina_Value source.
+ *
* @param dst destination value object
* @param member the member description to use
* @param src source value
/**
* @brief Queries type name.
+ *
* @param type type reference.
* @return string or @c NULL if type is invalid.
+ *
* @since 1.2
*/
EAPI const char *eina_value_type_name_get(const Eina_Value_Type *type) EINA_PURE EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Checks if type is valid.
+ *
* @param type Type reference.
* @return #EINA_TRUE if valid, #EINA_FALSE otherwise.
*
/**
* @brief Initializes memory using type descriptor.
+ *
* @param type type reference.
* @param mem memory to operate, must be of size @c type->value_size.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @since 1.2
*/
static inline Eina_Bool eina_value_type_setup(const Eina_Value_Type *type, void *mem);
/**
* @brief Flushes (clears) memory using type descriptor.
+ *
* @param type type reference.
* @param mem memory to operate, must be of size @c type->value_size.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @since 1.2
*/
static inline Eina_Bool eina_value_type_flush(const Eina_Value_Type *type, void *mem);
/**
* @brief Copies memory using type descriptor.
+ *
* @param type type reference.
* @param src memory to operate, must be of size @c type->value_size.
* @param dst memory to operate, must be of size @c type->value_size.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @since 1.2
*/
static inline Eina_Bool eina_value_type_copy(const Eina_Value_Type *type, const void *src, void *dst);
/**
* @brief Compares memory using type descriptor.
+ *
* @param type type reference.
* @param a memory to operate, must be of size @c type->value_size.
* @param b memory to operate, must be of size @c type->value_size.
* @return less than zero if a < b, greater than zero if a > b, zero if equal.
+ *
* @since 1.2
*/
static inline int eina_value_type_compare(const Eina_Value_Type *type, const void *a, const void *b);
/**
* @brief Converts memory using type descriptor.
+ *
* @param type type reference of the source.
* @param convert type reference of the destination.
* @param type_mem memory to operate, must be of size @c type->value_size.
* @param convert_mem memory to operate, must be of size @c convert->value_size.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @since 1.2
*/
static inline Eina_Bool eina_value_type_convert_to(const Eina_Value_Type *type, const Eina_Value_Type *convert, const void *type_mem, void *convert_mem);
/**
* @brief Converts memory using type descriptor.
+ *
* @param type type reference of the destination.
* @param convert type reference of the source.
* @param type_mem memory to operate, must be of size @c type->value_size.
* @param convert_mem memory to operate, must be of size @c convert->value_size.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @since 1.2
*/
static inline Eina_Bool eina_value_type_convert_from(const Eina_Value_Type *type, const Eina_Value_Type *convert, void *type_mem, const void *convert_mem);
/**
* @brief Sets memory using type descriptor and variable argument.
+ *
* @param type type reference of the source.
* @param mem memory to operate, must be of size @c type->value_size.
* @param args input value.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @since 1.2
*/
static inline Eina_Bool eina_value_type_vset(const Eina_Value_Type *type, void *mem, va_list args);
/**
* @brief Sets memory using type descriptor and pointer.
+ *
* @param type type reference of the source.
* @param mem memory to operate, must be of size @c type->value_size.
* @param ptr pointer to input value.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @since 1.2
*/
static inline Eina_Bool eina_value_type_pset(const Eina_Value_Type *type, void *mem, const void *ptr);
/**
* @brief Gets memory using type descriptor.
+ *
* @param type type reference of the source.
* @param mem memory to operate, must be of size @c type->value_size.
* @param ptr pointer to output.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @since 1.2
*/
static inline Eina_Bool eina_value_type_pget(const Eina_Value_Type *type, const void *mem, void *ptr);
/**
* @brief Creates an empty optional. This is the same as eina_value_new(EINA_VALUE_TYPE_OPTIONAL).
+ *
* @return returns an empty optional eina value.
+ *
* @since 1.17
*/
static inline Eina_Value *eina_value_optional_empty_new(void);
/**
* @brief Creates an optional eina value with the passed value
+ *
* @param subtype Eina_Value_Type of parameter value
* @param value The value to be used to construct optional eina value
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @since 1.17
*/
EAPI Eina_Value *eina_value_optional_new(const Eina_Value_Type *subtype,
/**
* @brief Function to know if an eina optional is empty or not
+ *
* @param value Eina Value Optional
* @param is_empty #EINA_TRUE if optional is empty, #EINA_FALSE otherwise.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @since 1.17
*/
static inline Eina_Bool eina_value_optional_empty_is(const Eina_Value *value,
/**
* @brief Sets the optional with a value
+ *
* @param value Eina Value Optional to be set with subvalue
* @param subtype Type of subvalue
* @param subvalue Value to be set in optional
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @since 1.17
*/
EAPI Eina_Bool eina_value_optional_pset(Eina_Value *value,
/**
* @brief Gets the value from an optional
+ *
* @param value Eina Value Optional to get value from
* @param subvalue Pointer to where value is to be copied to. You must use
* the correct type according to eina_value_optional_type_get
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @since 1.17
*/
EAPI Eina_Bool eina_value_optional_pget(Eina_Value *value,
/**
* @brief Resets eina optional to empty
+ *
* @param value Eina Value Optional
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
* @since 1.17
*/
EAPI Eina_Bool eina_value_optional_reset(Eina_Value *value) EINA_ARG_NONNULL(1);
/**
+ *
* @brief Gets type from value that is stored on Eina Value Optional
* @param value Eina Value Optional
* @return The optional sub-type.
+ *
* @since 1.17
*/
static inline const Eina_Value_Type *eina_value_optional_type_get(Eina_Value *value) EINA_ARG_NONNULL(1);
projects / platform / upstream / efl.git / commitdiff