Avis Client Library: avis/values.h File Reference

# avis/values.h File Reference

## Detailed Description

Polymorphic values.

`#include <string.h>`
`#include <avis/stdtypes.h>`
`#include <avis/arrays.h>`
`#include <avis/defs.h>`

Go to the source code of this file.

## Data Structures
struct | Value
| A polymorphic value: either an int32, int64, real64, string or opaque (an array of bytes). More...
## Defines
#define | value_clone(source) value_copy (value_create (), source)
| Create a value cloned from a source value.
#define | value_create() ((Value *)avis_emalloc (sizeof (Value)))
| Create an uninitialised value on the heap.
#define | value_destroy(value) (value_free (value), free (value), value = NULL)
| Destroy (free and NULL) a value instance.
#define | value_create_int32(value) (value_init (value_create (), TYPE_INT32, (int32_t)(value)))
| Allocate and init an int32 value.
#define | value_create_int64(value) (value_init (value_create (), TYPE_INT64, (int64_t)(value)))
| Allocate and init an int64 value.
#define | value_create_real64(value) (value_init (value_create (), TYPE_REAL64, (real64_t)(value)))
| Allocate and init a real64 value.
#define | value_create_string(value) (value_init (value_create (), TYPE_STRING, avis_estrdup (value)))
| Allocate and init a string value.
#define | value_create_string_nocopy(value) (value_init (value_create (), TYPE_STRING, value))
| Allocate and init a string value, without copying it first.
#define | value_create_opaque(value) (value_init (value_create (), TYPE_OPAQUE, value))
| Allocate and init an opaque value.
#define | array_create(item_type, item_count)
| Create a new array instance on the heap.
#define | array_destroy(value) (array_free (value), free (value), value = NULL)
| Destroy an array created with array_create().
#define | array_get(array, index, item_type) (((item_type *)array->items) [index])
| Get an item of a given type.
## Enumerations
enum | ValueType { TYPE_INT32 = 1, TYPE_INT64 = 2, TYPE_REAL64 = 3, TYPE_STRING = 4, TYPE_OPAQUE = 5 }
| The type tag for polymorphic values. More...
## Functions
AVIS_PUBLIC Value * | value_init (Value *value, ValueType type,...)
| Initialise a polymorphic value.
AVIS_PUBLIC void | value_free (Value *value)
| Free any resources held by a value instance.
AVIS_PUBLIC Value * | value_copy (Value *target, const Value *source)
| Copy a value from a source to a target.
AVIS_PUBLIC Array * | array_init (Array *array, size_t item_count, size_t item_length)
| Initialise an array.
AVIS_PUBLIC void | array_free (Array *array)
| Free resources held by an array.
AVIS_PUBLIC bool | array_equals (Array *array1, Array *array2)
| Test if two arrays are bitwise identical.

## Define Documentation

#define array_create | ( | item_type,
|  | item_count |  | ) |

Value:

    (array_init ((Array *)avis_emalloc (sizeof (Array)), \
                   item_count, sizeof (item_type)))

Create a new array instance on the heap.

See also:
  array_destroy()

  array_init()

#define array_destroy | ( | value |  | ) | (array_free (value), free (value), value = NULL)

Destroy an array created with array_create().

#define array_get | ( | array,
|  | index,
|  | item_type |  | ) | (((item_type *)array->items) [index])

Get an item of a given type.

Parameters:

  | array | The array.
  | index | The index of the item.
  | item_type | The type of items in the array.

#define value_clone | ( | source |  | ) | value_copy (value_create (), source)

Create a value cloned from a source value.

Parameters:

  | source | The source to copy from.

Returns:
  A pointer to the target.

See also:
  value_copy()

#define value_create | ( |  | ) | ((Value *)avis_emalloc (sizeof (Value)))

Create an uninitialised value on the heap.

#define value_create_int32 | ( | value |  | ) | (value_init (value_create (), TYPE_INT32, (int32_t)(value)))

Allocate and init an int32 value.

Use value_destroy() when done.

#define value_create_int64 | ( | value |  | ) | (value_init (value_create (), TYPE_INT64, (int64_t)(value)))

Allocate and init an int64 value.

Use value_destroy() when done.

#define value_create_opaque | ( | value |  | ) | (value_init (value_create (), TYPE_OPAQUE, value))

Allocate and init an opaque value.

Use value_destroy() when done. Unlike string values, this will NOT be copied before being added to the set.

Parameters:

  | value | An Array instance representing the opaque data.

See also:
  value_init()

#define value_create_real64 | ( | value |  | ) | (value_init (value_create (), TYPE_REAL64, (real64_t)(value)))

Allocate and init a real64 value.

Use value_destroy() when done.

#define value_create_string | ( | value |  | ) | (value_init (value_create (), TYPE_STRING, avis_estrdup (value)))

Allocate and init a string value.

Use value_destroy() when done. The string is duplicated before being added.

See also:
  value_init()

  value_create_string_nocopy()

#define value_create_string_nocopy | ( | value |  | ) | (value_init (value_create (), TYPE_STRING, value))

Allocate and init a string value, without copying it first.

Use value_destroy() when done, which will free the string passed in here.

See also:
  value_init()

  value_create_string()

#define value_destroy | ( | value |  | ) | (value_free (value), free (value), value = NULL)

Destroy (free and NULL) a value instance.

## Enumeration Type Documentation

enum ValueType

The type tag for polymorphic values.

These are the same as the type codes from the client protocol spec.

Enumerator:

  TYPE_INT32 |
  TYPE_INT64 |
  TYPE_REAL64 |
  TYPE_STRING |
  TYPE_OPAQUE |

## Function Documentation

AVIS_PUBLIC bool array_equals | ( | Array * | array1,
|  | Array * | array2 |
| ) |  |  |

Test if two arrays are bitwise identical.

AVIS_PUBLIC void array_free | ( | Array * | array | ) |

Free resources held by an array.

AVIS_PUBLIC Array* array_init | ( | Array * | array,
|  | size_t | item_count,
|  | size_t | item_length |
| ) |  |  |

Initialise an array.

Parameters:

  | array | The array to initialise.
  | item_count | The initial item count.
  | item_length | The length of an item.

See also:
  array_create()

AVIS_PUBLIC Value* value_copy | ( | Value * | target,
|  | const Value * | source |
| ) |  |  |

Copy a value from a source to a target.

Parameters:

  | target | The target for the copy.
  | source | The source to copy from.

Returns:
  A pointer to the target.

See also:
  value_clone()

AVIS_PUBLIC void value_free | ( | Value * | value | ) |

Free any resources held by a value instance.

AVIS_PUBLIC Value* value_init | ( | Value * | value,
|  | ValueType | type,
|  |  | ... |
| ) |  |  |

Initialise a polymorphic value.

Parameters:

  | value | The value to init.
  | type | The type of value.

The next param is the value to be assigned. For strings and opaques, this value is "owned" by the poly value and will be free'd on calling value_free(), so constant strings passed in here should be copied before being used in a value that will be value_free()'d. No type checking is done for the value parameter.