Generic Value management

Data Structures | Functions
Generic Value management
Eina » Data Types » Containers » Generic Value Storage

## Data Structures
struct | _Eina_Value
| defines the contents of a value More...

## Functions
EINA_API Eina_Value * | eina_value_new (const Eina_Value_Type *type)
| Creates generic value storage. More...
EINA_API void | eina_value_free (Eina_Value *value)
| Frees value and its data. More...
static Eina_Bool | eina_value_setup (Eina_Value *value, const Eina_Value_Type *type)
| Initializes generic value storage. More...
static void | eina_value_flush (Eina_Value *value)
| Empties a generic value storage. More...
EINA_API Eina_Bool | eina_value_copy (const Eina_Value *value, Eina_Value *copy)
| Copies generic value storage. More...
static int | eina_value_compare (const Eina_Value *a, const Eina_Value *b)
| Compares generic value storage. More...
static Eina_Bool | eina_value_set (Eina_Value *value,...)
| Sets the generic value. More...
static Eina_Bool | eina_value_get (const Eina_Value *value,...)
| Gets the generic value. More...
static Eina_Bool | eina_value_vset (Eina_Value *value, va_list args)
| Sets the generic value. More...
static Eina_Bool | eina_value_vget (const Eina_Value *value, va_list args)
| Gets the generic value. More...
static Eina_Bool | eina_value_pset (Eina_Value *value, const void *ptr)
| Sets the generic value from pointer. More...
static Eina_Bool | eina_value_pget (const Eina_Value *value, void *ptr)
| Gets the generic value to pointer. More...
EINA_API Eina_Bool | eina_value_convert (const Eina_Value *value, Eina_Value *convert)
| Converts one value to another type. More...
EINA_API Eina_Binbuf * | eina_value_to_binbuf (Eina_Value *value)
| Converts one value to Eina_Binbuf. More...
EINA_API char * | eina_value_to_string (const Eina_Value *value)
| Converts value to string. More...
static const Eina_Value_Type * | eina_value_type_get (const Eina_Value *value)
| Queries value type. More...

## Detailed Description

## Function Documentation

## ◆ eina_value_new()

EINA_API Eina_Value* eina_value_new | ( | const Eina_Value_Type * | type | ) |

Creates generic value storage.

Parameters

  [in] | type | How 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: e.g.. 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_free(), eina_mempool_malloc(), and eina_value_setup().

Referenced by eina_value_util_time_string_new().

## ◆ eina_value_free()

EINA_API void eina_value_free | ( | Eina_Value * | value | ) |

Frees value and its data.

Parameters

  [in] | value | value object

See also
  eina_value_flush()

Since
  1.2

References eina_mempool_free(), and eina_value_flush().

## ◆ eina_value_setup()

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

Initializes generic value storage.

Parameters

  [out] | value | Value object
  [out] | type | How 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, eina_value_03.c, and prefs_data_example.c.

Referenced by ecore_main_loop_quit(), efl_exit(), eina_promise_all_array(), eina_promise_all_iterator(), eina_promise_as_value(), eina_promise_reject(), eina_value_copy(), eina_value_new(), eina_value_to_binbuf(), and eina_value_to_string().

## ◆ eina_value_flush()

static void eina_value_flush | ( | Eina_Value * | value | ) |
| inlinestatic

Empties a generic value storage.

Parameters

  [in] | value | Value 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, and eina_value_01.c.

Referenced by eina_future_cb_easy_desc_flush(), eina_future_chain_easy_array(), eina_future_resolved(), eina_promise_all_array(), eina_promise_all_iterator(), eina_promise_as_value(), eina_promise_reject(), eina_promise_resolve(), eina_value_copy(), eina_value_free(), and eina_value_to_binbuf().

## ◆ eina_value_copy()

EINA_API Eina_Bool eina_value_copy | ( | const Eina_Value * | value,
|  | Eina_Value * | copy
| ) |  |

Copies generic value storage.

Parameters

  [in] | value | Source value object
  [out] | copy | Destination 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_FALSE, EINA_SAFETY_ON_FALSE_RETURN_VAL, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_TRUE, eina_value_flush(), eina_value_setup(), and eina_value_type_check().

## ◆ eina_value_compare()

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

Compares generic value storage.

Parameters

  [in] | a | left side of comparison
  [in] | b | right side of comparison

Returns
  less than zero if a < b, greater than zero if a > b, zero if a == b

Since
  1.2

## ◆ eina_value_set()

static Eina_Bool eina_value_set | ( | Eina_Value * | value,
|  |  | ...
| ) |  |
| inlinestatic

Sets the generic value.

Parameters

  [in,out] | value | Source value object
  [in] | ... | Data to set.

Returns
  EINA_TRUE on success, EINA_FALSE otherwise.

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

- EINA_VALUE_TYPE_VALUE: Eina_Value
- EINA_VALUE_TYPE_ERROR: Eina_Error
- 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
- EINA_VALUE_TYPE_TM: struct tm*

Eina_Value *value = eina_value_new(EINA_VALUE_TYPE_INT);
int x = 567;
eina_value_set(value, 1234);
eina_value_set(value, x);
eina_value_flush(value);
eina_value_setup(value, EINA_VALUE_TYPE_STRING);
eina_value_set(value, "hello world!");
eina_value_free(value);
EINA_VALUE_TYPE_INT
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_INT
manages int type.
Definition: eina_value.c:5602
EINA_VALUE_TYPE_STRING
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_STRING
manages string type.
Definition: eina_value.c:5608
eina_value_free
EINA_API void eina_value_free(Eina_Value *value)
Frees value and its data.
Definition: eina_value.c:5645
eina_value_flush
static void eina_value_flush(Eina_Value *value)
Empties a generic value storage.
eina_value_set
static Eina_Bool eina_value_set(Eina_Value *value,...)
Sets the generic value.
eina_value_setup
static Eina_Bool eina_value_setup(Eina_Value *value, const Eina_Value_Type *type)
Initializes generic value storage.
eina_value_new
EINA_API Eina_Value * eina_value_new(const Eina_Value_Type *type)
Creates generic value storage.
Definition: eina_value.c:5627
_Eina_Value
defines the contents of a value
Definition: eina_value.h:662

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, eina_value_03.c, prefs_data_example.c, prefs_example_01.c, and prefs_example_02.c.

Referenced by ecore_main_loop_quit(), efl_exit(), eina_promise_reject(), and eina_value_util_time_string_new().

## ◆ eina_value_get()

static Eina_Bool eina_value_get | ( | const Eina_Value * | value,
|  |  | ...
| ) |  |
| inlinestatic

Gets the generic value.

Parameters

  [in] | value | Source value object.
  [out] | ... | Data value retrieved.

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_VALUE: Eina_Value*
- EINA_VALUE_TYPE_ERROR: Eina_Error*
- 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*
- EINA_VALUE_TYPE_TM: struct tm*

Eina_Value *value = eina_value_new(EINA_VALUE_TYPE_INT);
int x;
const char *s;
eina_value_set(value, 1234);
eina_value_get(value, &x);
eina_value_flush(value);
eina_value_setup(value, EINA_VALUE_TYPE_STRING);
eina_value_set(value, "hello world!");
eina_value_get(value, &s);
eina_value_free(value);
eina_value_get
static Eina_Bool eina_value_get(const Eina_Value *value,...)
Gets the generic value.

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, eina_value_01.c, and prefs_example_03.c.

Referenced by eina_value_to_binbuf().

## ◆ eina_value_vset()

static Eina_Bool eina_value_vset | ( | Eina_Value * | value,
|  | va_list | args
| ) |  |
| inlinestatic

Sets the generic value.

Parameters

  [in,out] | value | Source value object
  [in] | args | Variable 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

## ◆ eina_value_vget()

static Eina_Bool eina_value_vget | ( | const Eina_Value * | value,
|  | va_list | args
| ) |  |
| inlinestatic

Gets the generic value.

Parameters

  [in] | value | Source value object
  [out] | args | Variable 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

## ◆ eina_value_pset()

static Eina_Bool eina_value_pset | ( | Eina_Value * | value,
|  | const void * | ptr
| ) |  |
| inlinestatic

Sets the generic value from pointer.

Parameters

  [in,out] | value | Source value object
  [in] | ptr | Pointer 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_VALUE: Eina_Value*
- EINA_VALUE_TYPE_ERROR: Eina_Error*
- 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*
- 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.

Eina_Value *value = eina_value_new(EINA_VALUE_TYPE_INT);
int x = 567;
const char *s = "hello world!";
eina_value_pset(value, &x);
eina_value_flush(value);
eina_value_setup(value, EINA_VALUE_TYPE_STRING);
eina_value_pset(value, &s);
eina_value_free(value);
eina_value_pset
static Eina_Bool eina_value_pset(Eina_Value *value, const void *ptr)
Sets the generic value from pointer.

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

Referenced by eina_promise_as_value().

## ◆ eina_value_pget()

static Eina_Bool eina_value_pget | ( | const Eina_Value * | value,
|  | void * | ptr
| ) |  |
| inlinestatic

Gets the generic value to pointer.

Parameters

  [in] | value | Source value object
  [out] | ptr | Pointer 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_VALUE: Eina_Value*
- EINA_VALUE_TYPE_ERROR: Eina_Error*
- 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
- EINA_VALUE_TYPE_TM: struct tm*

Eina_Value *value = eina_value_new(EINA_VALUE_TYPE_INT);
int x;
const char *s;
eina_value_set(value, 1234);
eina_value_pget(value, &x);
eina_value_flush(value);
eina_value_setup(value, EINA_VALUE_TYPE_STRING);
eina_value_set(value, "hello world!");
eina_value_pget(value, &s);
eina_value_free(value);
eina_value_pget
static Eina_Bool eina_value_pget(const Eina_Value *value, void *ptr)
Gets the generic value to pointer.

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_value_convert()

EINA_API Eina_Bool eina_value_convert | ( | const Eina_Value * | value,
|  | Eina_Value * | convert
| ) |  |

Converts one value to another type.

Parameters

  [in] | value | Source value object.
  [out] | convert | Destination 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_FALSE, EINA_SAFETY_ON_FALSE_RETURN_VAL, EINA_SAFETY_ON_NULL_RETURN_VAL, eina_value_type_check(), and _Eina_Value::type.

Referenced by eina_value_to_binbuf(), and eina_value_to_string().

## ◆ eina_value_to_binbuf()

EINA_API Eina_Binbuf* eina_value_to_binbuf | ( | Eina_Value * | value | ) |

Converts one value to Eina_Binbuf.

Parameters

  [in,out] | value | Source value object.

Returns
  `NULL` if it failed to get a memory content, a valid Eina_Binbuf otherwise.

Converts one value to EINA_TYPE_VALUE_BLOB if necessary by calling `eina_value_convert()` function.

Note
  You are responsible for destroying the Eina_Binbuf returned.

See also
  eina_value_to_string()
  eina_value_convert()

Since
  1.20

References eina_binbuf_append_length(), eina_binbuf_new(), eina_value_convert(), EINA_VALUE_EMPTY, eina_value_flush(), eina_value_get(), eina_value_setup(), and EINA_VALUE_TYPE_BLOB.

## ◆ eina_value_to_string()

EINA_API char* eina_value_to_string | ( | const Eina_Value * | value | ) |

Converts value to string.

Parameters

  [in] | value | value object.

Returns
  newly allocated memory or `NULL` on failure.

See also
  eina_value_convert()
  eina_value_to_binbuf()

Since
  1.2

References EINA_SAFETY_ON_FALSE_RETURN_VAL, EINA_SAFETY_ON_NULL_RETURN_VAL, eina_value_convert(), eina_value_setup(), eina_value_type_check(), EINA_VALUE_TYPE_STRING, _Eina_Value_Union::ptr, and _Eina_Value::value.

## ◆ eina_value_type_get()

static const Eina_Value_Type* eina_value_type_get | ( | const Eina_Value * | value | ) |
| inlinestatic

Queries value type.

Parameters

  [in] | value | Value 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