Generic Value management

Data Structures

struct  _Eina_Value
 defines the contents of a value More...
 

Functions

Eina_Valueeina_value_new (const Eina_Value_Type *type)
 Create generic value storage. More...
 
void eina_value_free (Eina_Value *value)
 Free value and its data. More...
 
static Eina_Bool eina_value_setup (Eina_Value *value, const Eina_Value_Type *type)
 Initialize generic value storage. More...
 
static void eina_value_flush (Eina_Value *value)
 Create generic value storage. More...
 
Eina_Bool eina_value_copy (const Eina_Value *value, Eina_Value *copy)
 Copy generic value storage. More...
 
static int eina_value_compare (const Eina_Value *a, const Eina_Value *b)
 Compare generic value storage. More...
 
static Eina_Bool eina_value_set (Eina_Value *value,...)
 Set the generic value. More...
 
static Eina_Bool eina_value_get (const Eina_Value *value,...)
 Get the generic value. More...
 
static Eina_Bool eina_value_vset (Eina_Value *value, va_list args)
 Set the generic value. More...
 
static Eina_Bool eina_value_vget (const Eina_Value *value, va_list args)
 Get the generic value. More...
 
static Eina_Bool eina_value_pset (Eina_Value *value, const void *ptr)
 Set the generic value from pointer. More...
 
static Eina_Bool eina_value_pget (const Eina_Value *value, void *ptr)
 Get the generic value to pointer. More...
 
Eina_Bool eina_value_convert (const Eina_Value *value, Eina_Value *convert)
 Convert one value to another type. More...
 
char * eina_value_to_string (const Eina_Value *value)
 Convert value to string. More...
 
static const Eina_Value_Typeeina_value_type_get (const Eina_Value *value)
 Query value type. More...
 

Detailed Description

Function Documentation

Eina_Value* eina_value_new ( const Eina_Value_Type type)

Create generic value storage.

Parameters
typehow to manage this value.
Returns
The new value or NULL on failure.

Create a new generic value storage. The members are managed using the description specified by type.

Some types may specify more operations: eg. EINA_VALUE_TYPE_ARRAY uses eina_value_array_set(), eina_value_array_get() and so on.

On failure, NULL is returned.

Note
this calls creates from mempool and then uses eina_value_setup(). Consider using eina_value_flush() and eina_value_setup() instead to avoid memory allocations.
See also
eina_value_free()
Since
1.2

References eina_mempool_malloc(), and eina_value_setup().

void eina_value_free ( Eina_Value value)

Free value and its data.

Parameters
valuevalue object
See also
eina_value_flush()
Since
1.2

References eina_mempool_free(), and eina_value_flush().

static Eina_Bool eina_value_setup ( Eina_Value value,
const Eina_Value_Type type 
)
inlinestatic

Initialize generic value storage.

Parameters
valuevalue object
typehow to manage this value.
Returns
EINA_TRUE on success, EINA_FALSE otherwise.

Initializes existing generic value storage. The members are managed using the description specified by type.

Some types may specify more operations, as an example EINA_VALUE_TYPE_ARRAY uses eina_value_array_set(), eina_value_array_get() and so on.

Note
Existing contents are ignored! If the value was previously used, then use eina_value_flush() first.

On failure, EINA_FALSE is returned.

See also
eina_value_flush()
Since
1.2
Examples:
eina_value_01.c, and eina_value_03.c.

Referenced by eina_value_copy(), eina_value_new(), and eina_value_to_string().

static void eina_value_flush ( Eina_Value value)
inlinestatic

Create generic value storage.

Parameters
valuevalue object

Releases all the resources associated with an Eina_Value. The value must be already set with eina_value_setup() or eina_value_new().

After this call returns, the contents of the value are undefined, but the value can be reused by calling eina_value_setup() again.

See also
eina_value_setup()
eina_value_free()
Since
1.2
Examples:
complex-types-client-eina-value.c, eina_value_01.c, and eina_value_03.c.

Referenced by eina_value_copy(), and eina_value_free().

Eina_Bool eina_value_copy ( const Eina_Value value,
Eina_Value copy 
)

Copy generic value storage.

Parameters
valuesource value object
copydestination value object
Returns
EINA_TRUE on success, EINA_FALSE otherwise.

The copy object is considered uninitialized and its existing contents are overwritten (just as if eina_value_flush() was called on it).

The copy happens by calling eina_value_setup() on copy, followed by getting the contents of value and setting it to copy.

Since
1.2

References _Eina_Value_Type::copy, EINA_FALSE, eina_value_flush(), eina_value_setup(), eina_value_type_check(), and _Eina_Value::type.

static int eina_value_compare ( const Eina_Value a,
const Eina_Value b 
)
inlinestatic

Compare generic value storage.

Parameters
aleft side of comparison
bright side of comparison
Returns
less than zero if a < b, greater than zero if a > b, zero if a == b
Since
1.2
static Eina_Bool eina_value_set ( Eina_Value value,
  ... 
)
inlinestatic

Set the generic value.

Parameters
valuesource value object
Returns
EINA_TRUE on success, EINA_FALSE otherwise.

The variable argument is dependent on chosen type. The list for basic types:

  • EINA_VALUE_TYPE_UCHAR: unsigned char
  • EINA_VALUE_TYPE_USHORT: unsigned short
  • EINA_VALUE_TYPE_UINT: unsigned int
  • EINA_VALUE_TYPE_ULONG: unsigned long
  • EINA_VALUE_TYPE_UINT64: uint64_t
  • EINA_VALUE_TYPE_CHAR: char
  • EINA_VALUE_TYPE_SHORT: short
  • EINA_VALUE_TYPE_INT: int
  • EINA_VALUE_TYPE_LONG: long
  • EINA_VALUE_TYPE_INT64: int64_t
  • EINA_VALUE_TYPE_FLOAT: float
  • EINA_VALUE_TYPE_DOUBLE: double
  • EINA_VALUE_TYPE_STRINGSHARE: const char *
  • EINA_VALUE_TYPE_STRING: const char *
  • EINA_VALUE_TYPE_ARRAY: Eina_Value_Array
  • EINA_VALUE_TYPE_LIST: Eina_Value_List
  • EINA_VALUE_TYPE_HASH: Eina_Value_Hash
  • EINA_VALUE_TYPE_TIMEVAL: struct timeval
  • EINA_VALUE_TYPE_BLOB: Eina_Value_Blob
  • EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct
int x = 567;
eina_value_set(value, 1234);
eina_value_set(value, x);
eina_value_set(value, "hello world!");
Note
for array member see eina_value_array_set()
for list member see eina_value_list_set()
for hash member see eina_value_hash_set()
See also
eina_value_get()
eina_value_vset()
eina_value_pset()
Since
1.2
Examples:
eina_value_01.c, and eina_value_03.c.
static Eina_Bool eina_value_get ( const Eina_Value value,
  ... 
)
inlinestatic

Get the generic value.

Parameters
valuesource value object
Returns
EINA_TRUE on success, EINA_FALSE otherwise.

The value is returned in the variable argument parameter, the actual value is type-dependent, but usually it will be what is stored inside the object. There shouldn't be any memory allocation, thus the contents should not be freed.

The variable argument is dependent on chosen type. The list for basic types:

  • EINA_VALUE_TYPE_UCHAR: unsigned char*
  • EINA_VALUE_TYPE_USHORT: unsigned short*
  • EINA_VALUE_TYPE_UINT: unsigned int*
  • EINA_VALUE_TYPE_ULONG: unsigned long*
  • EINA_VALUE_TYPE_UINT64: uint64_t*
  • EINA_VALUE_TYPE_CHAR: char*
  • EINA_VALUE_TYPE_SHORT: short*
  • EINA_VALUE_TYPE_INT: int*
  • EINA_VALUE_TYPE_LONG: long*
  • EINA_VALUE_TYPE_INT64: int64_t*
  • EINA_VALUE_TYPE_FLOAT: float*
  • EINA_VALUE_TYPE_DOUBLE: double*
  • EINA_VALUE_TYPE_STRINGSHARE: const char **
  • EINA_VALUE_TYPE_STRING: const char **
  • EINA_VALUE_TYPE_ARRAY: Eina_Value_Array*
  • EINA_VALUE_TYPE_LIST: Eina_Value_List*
  • EINA_VALUE_TYPE_HASH: Eina_Value_Hash*
  • EINA_VALUE_TYPE_TIMEVAL: struct timeval*
  • EINA_VALUE_TYPE_BLOB: Eina_Value_Blob*
  • EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct*
int x;
const char *s;
eina_value_set(value, 1234);
eina_value_get(value, &x);
eina_value_set(value, "hello world!");
eina_value_get(value, &s);
Note
for array member see eina_value_array_get()
for list member see eina_value_list_get()
for hash member see eina_value_hash_get()
See also
eina_value_set()
eina_value_vset()
eina_value_pset()
Since
1.2
Examples:
complex-types-client-eina-value.c, and eina_value_01.c.
static Eina_Bool eina_value_vset ( Eina_Value value,
va_list  args 
)
inlinestatic

Set the generic value.

Parameters
valuesource value object
argsvariable argument
Returns
EINA_TRUE on success, EINA_FALSE otherwise.
Note
for array member see eina_value_array_vset()
for list member see eina_value_list_vset()
for hash member see eina_value_hash_vset()
See also
eina_value_vget()
eina_value_set()
eina_value_pset()
Since
1.2
static Eina_Bool eina_value_vget ( const Eina_Value value,
va_list  args 
)
inlinestatic

Get the generic value.

Parameters
valuesource value object
argsvariable argument
Returns
EINA_TRUE on success, EINA_FALSE otherwise.

The value is returned in the variable argument parameter, the actual value is type-dependent, but usually it will be what is stored inside the object. There shouldn't be any memory allocation, thus the contents should not be freed.

Note
for array member see eina_value_array_vget()
for list member see eina_value_list_vget()
for hash member see eina_value_hash_vget()
See also
eina_value_vset()
eina_value_get()
eina_value_pget()
Since
1.2
static Eina_Bool eina_value_pset ( Eina_Value value,
const void *  ptr 
)
inlinestatic

Set the generic value from pointer.

Parameters
valuesource value object
ptrpointer to specify the contents.
Returns
EINA_TRUE on success, EINA_FALSE otherwise.

The pointer type is dependent on chosen value type. The list for basic types:

  • EINA_VALUE_TYPE_UCHAR: unsigned char*
  • EINA_VALUE_TYPE_USHORT: unsigned short*
  • EINA_VALUE_TYPE_UINT: unsigned int*
  • EINA_VALUE_TYPE_ULONG: unsigned long*
  • EINA_VALUE_TYPE_UINT64: uint64_t*
  • EINA_VALUE_TYPE_CHAR: char*
  • EINA_VALUE_TYPE_SHORT: short*
  • EINA_VALUE_TYPE_INT: int*
  • EINA_VALUE_TYPE_LONG: long*
  • EINA_VALUE_TYPE_INT64: int64_t*
  • EINA_VALUE_TYPE_FLOAT: float*
  • EINA_VALUE_TYPE_DOUBLE: double*
  • EINA_VALUE_TYPE_STRINGSHARE: const char **
  • EINA_VALUE_TYPE_STRING: const char **
  • EINA_VALUE_TYPE_ARRAY: Eina_Value_Array*
  • EINA_VALUE_TYPE_LIST: Eina_Value_List*
  • EINA_VALUE_TYPE_HASH: Eina_Value_Hash*
  • EINA_VALUE_TYPE_TIMEVAL: struct timeval*
  • EINA_VALUE_TYPE_BLOB: Eina_Value_Blob*
  • EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct*
Note
the pointer contents are written using the size defined by type. It can be larger than void* or uint64_t.
int x = 567;
const char *s = "hello world!";
eina_value_pset(value, &x);
eina_value_pset(value, &s);
Note
for array member see eina_value_array_pset()
for list member see eina_value_list_pset()
for hash member see eina_value_hash_pset()
See also
eina_value_pget()
eina_value_set()
eina_value_vset()
Since
1.2
static Eina_Bool eina_value_pget ( const Eina_Value value,
void *  ptr 
)
inlinestatic

Get the generic value to pointer.

Parameters
valuesource value object
ptrpointer to receive the contents.
Returns
EINA_TRUE on success, EINA_FALSE otherwise.

The value is returned in pointer contents, the actual value is type-dependent, but usually it will be what is stored inside the object. There shouldn't be any memory allocation, thus the contents should not be freed.

The pointer type is dependent on chosen value type. The list for basic types:

  • EINA_VALUE_TYPE_UCHAR: unsigned char*
  • EINA_VALUE_TYPE_USHORT: unsigned short*
  • EINA_VALUE_TYPE_UINT: unsigned int*
  • EINA_VALUE_TYPE_ULONG: unsigned long*
  • EINA_VALUE_TYPE_UINT64: uint64_t*
  • EINA_VALUE_TYPE_CHAR: char*
  • EINA_VALUE_TYPE_SHORT: short*
  • EINA_VALUE_TYPE_INT: int*
  • EINA_VALUE_TYPE_LONG: long*
  • EINA_VALUE_TYPE_INT64: int64_t*
  • EINA_VALUE_TYPE_FLOAT: float*
  • EINA_VALUE_TYPE_DOUBLE: double*
  • EINA_VALUE_TYPE_STRINGSHARE: const char **
  • EINA_VALUE_TYPE_STRING: const char **
  • EINA_VALUE_TYPE_ARRAY: Eina_Value_Array*
  • EINA_VALUE_TYPE_LIST: Eina_Value_List*
  • EINA_VALUE_TYPE_HASH: Eina_Value_Hash*
  • EINA_VALUE_TYPE_TIMEVAL: struct timeval*
  • EINA_VALUE_TYPE_BLOB: Eina_Value_Blob*
  • EINA_VALUE_TYPE_BLOB: Eina_Value_Blob*
int x;
const char *s;
eina_value_set(value, 1234);
eina_value_pget(value, &x);
eina_value_set(value, "hello world!");
eina_value_pget(value, &s);
Note
for array member see eina_value_array_get()
for list member see eina_value_list_get()
for hash member see eina_value_hash_get()
See also
eina_value_set()
eina_value_vset()
eina_value_pset()
Since
1.2
Eina_Bool eina_value_convert ( const Eina_Value value,
Eina_Value convert 
)

Convert one value to another type.

Parameters
valuesource value object.
convertdestination value object.
Returns
EINA_TRUE if converted, EINA_FALSE otherwise.

Converts one value to another trying first value type convert_to() function. If unsuccessful, tries using convert_from() function in convert.

Conversion functions are type defined, and the basic types can convert between themselves, but conversion is strict! That is, if converting from negative value to unsigned type, it will fail. It also fails on value overflow.

It is recommended that all types implement at least convert to string, used by eina_value_to_string().

Note
Both objects must have eina_value_setup() called on them beforehand!
Since
1.2

References _Eina_Value_Type::convert_from, _Eina_Value_Type::convert_to, EINA_FALSE, eina_value_type_check(), and _Eina_Value::type.

Referenced by eina_value_to_string().

char* eina_value_to_string ( const Eina_Value value)

Convert value to string.

Parameters
valuevalue object.
Returns
newly allocated memory or NULL on failure.
See also
eina_value_convert()
Since
1.2

References eina_value_convert(), eina_value_setup(), eina_value_type_check(), _Eina_Value_Union::ptr, _Eina_Value::type, and _Eina_Value::value.

static const Eina_Value_Type* eina_value_type_get ( const Eina_Value value)
inlinestatic

Query value type.

Parameters
valuevalue object.
Returns
type instance or NULL if type is invalid.

Check if value type is valid and returns it. A type is invalid if it does not exist or if it is using a different version field.

See also
eina_value_type_check()
Since
1.2