YAMI4 - C++ general-purpose interface
yami::parameters Class Reference

Collection of message parameters. More...

#include <parameters.h>

Inherits yami::serializable.

List of all members.

Classes

class  iterator
 Iterator class for inspecting entries in the collection. More...

Public Member Functions

 parameters ()
 Constructor.
 parameters (core::parameters *external)
 Constructor.
 parameters (const parameters &other)
 Copy constructor.
void operator= (const parameters &other)
 Assignment operator.
void swap (parameters &other)
 Swap operation.
 ~parameters ()
 Destructor.
void set_boolean (const std::string &name, bool value)
 Inserts new entry of type bool.
bool get_boolean (const std::string &name) const
 Extracts the bool value from the given entry.
void set_integer (const std::string &name, int value)
 Inserts new entry of type int.
int get_integer (const std::string &name) const
 Extracts the int value from the given entry.
void set_long_long (const std::string &name, long long value)
 Inserts new entry of type long long.
long long get_long_long (const std::string &name) const
 Extracts the long long value from the given entry.
void set_double_float (const std::string &name, double value)
 Inserts new entry of type double.
double get_double_float (const std::string &name) const
 Extracts the double value from the given entry.
void set_string (const std::string &name, const std::string &value)
 Inserts new entry of type string.
void set_string_shallow (const std::string &name, const char *value, std::size_t value_length)
 Inserts new entry of type string.
std::string get_string (const std::string &name) const
 Extracts the string value from the given entry.
const char * get_string (const std::string &name, std::size_t &length) const
 Extracts the string value from the given entry.
void set_binary (const std::string &name, const void *value, std::size_t value_length)
 Inserts new entry of type binary.
void set_binary_shallow (const std::string &name, const void *value, std::size_t value_length)
 Inserts new entry of type binary.
const void * get_binary (const std::string &name, std::size_t &length) const
 Extracts the binary value from the given entry.
void set_boolean_array (const std::string &name, const bool *values, std::size_t array_length)
 Inserts new entry of type bool array.
void set_boolean_array_shallow (const std::string &name, const bool *values, std::size_t array_length)
 Inserts new entry of type bool array.
bool * get_boolean_array (const std::string &name, std::size_t &array_length) const
 Extracts the array of bool values from the given entry.
void set_integer_array (const std::string &name, const int *values, std::size_t array_length)
 Inserts new entry of type int array.
void set_integer_array_shallow (const std::string &name, const int *values, std::size_t array_length)
 Inserts new entry of type int array.
int * get_integer_array (const std::string &name, std::size_t &array_length) const
 Extracts the array of int values from the given entry.
void set_long_long_array (const std::string &name, const long long *values, std::size_t array_length)
 Inserts new entry of type long long array.
void set_long_long_array_shallow (const std::string &name, const long long *values, std::size_t array_length)
 Inserts new entry of type long long array.
long long * get_long_long_array (const std::string &name, std::size_t &array_length) const
 Extracts the array of long long values from the given entry.
void set_double_float_array (const std::string &name, const double *values, std::size_t array_length)
 Inserts new entry of type double array.
void set_double_float_array_shallow (const std::string &name, const double *values, std::size_t array_length)
 Inserts new entry of type double array.
double * get_double_float_array (const std::string &name, std::size_t &array_length) const
 Extracts the array of double values from the given entry.
void create_string_array (const std::string &name, std::size_t array_length)
 Creates new empty entry of type string array.
void set_string_in_array (const std::string &name, std::size_t index, const std::string &value)
 Inserts new string value to string array.
std::size_t get_string_array_length (const std::string &name) const
 Extracts the length of string array.
std::string get_string_in_array (const std::string &name, std::size_t index) const
 Extracts string value from string array.
const char * get_string_in_array (const std::string &name, std::size_t index, std::size_t &length) const
 Extracts string value from string array.
void create_binary_array (const std::string &name, std::size_t array_length)
 Creates new empty entry of type binary array.
void set_binary_in_array (const std::string &name, std::size_t index, const void *value, std::size_t value_length)
 Inserts new binary value to binary array.
std::size_t get_binary_array_length (const std::string &name) const
 Extracts the length of binary array.
const void * get_binary_in_array (const std::string &name, std::size_t index, std::size_t &length) const
 Extracts binary value from binary array.
core::parameters * create_nested_parameters (const std::string &name)
 Creates nested parameters entry.
core::parameters * get_nested_parameters (const std::string &name) const
 Extracts the nested parameters object from the given entry.
void create_nested_array (const std::string &name, std::size_t array_length)
 Creates nested parameters array entry.
std::size_t get_nested_array_length (const std::string &name) const
 Extracts the length of nested parameters array.
core::parameters * get_nested_in_array (const std::string &name, std::size_t index) const
 Extracts nested parameters value from nested array.
std::size_t size () const
 Returns the size of the collection.
parameter_type type (const std::string &name) const
 Extracts the type of the given entry.
iterator begin () const
 Extracts the starting iterator for this collection.
iterator end () const
 Extracts the ending iterator for this collection.
bool find (const std::string &name, parameter_entry &entry) const
 Finds the given entry.
void remove (const std::string &name)
 Removes the given entry.
void remove (iterator it)
 Removes the entry given by its iterator.
void merge_from (const parameters &other)
 Merges entries from the given parameters object.
void clear ()
 Clears the collection of entries.
virtual std::size_t serialize_buffer_size () const
 Returns the total size of serialization buffer.
virtual void serialize (char **buffers, std::size_t *buffer_sizes, std::size_t num_of_buffers) const
 Serializes current content into given buffer(s).
void deserialize (const char **buffers, std::size_t *buffer_sizes, std::size_t num_of_buffers)
 Deserializes from the given buffer(s).
virtual const core::parameters & get_core_object () const
 Provides access to the underlying core object.

Detailed Description

The collection of message parameters, which are typed {name, value} pairs.

Each entry in this collection has a unique name and can have one of the following types:

  • bool or bool array
  • int or int array
  • long long or long long array
  • double or double array
  • string or string array
  • binary or binary array
  • nested parameters object, which provides its own scope for naming.

This class is not thread-safe, although distinct instances of this class can be used by different threads without synchronization.

Note: The entries are ordered - the order in which they are created influences the final serialized form of the message payload.
Newly created entries are appended to the end of the collection unless there is an existing empty slot that can be reused - the appropriate slot is searched for from the beginning to the end of the collection and if no free slot is found the collection is extended at the end.
The above guarantee concerns the user code that relies on predictable serialization.

Note: For each function that accepts const std::string & parameter there is also an overloaded function accepting const char *. These additional functions are provided to make it more natural to use strings by pointer or as a hard-code literals. They have exactly the same functionality and are therefore not separately documented.


Constructor & Destructor Documentation

parameters::parameters ( )

Creates an empty parameters object.

parameters::parameters ( core::parameters *  external) [explicit]

Constructor, allows to wrap existing object from the core part of the YAMI library.

yami::parameters::~parameters ( ) [inline]

The destructor cleans all dependent resources.


Member Function Documentation

void parameters::swap ( parameters other)

The (no-throw) swap operation.

void parameters::set_boolean ( const std::string &  name,
bool  value 
)

Inserts a new entry of type bool to the first available slot. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
valueValue to be set.
bool parameters::get_boolean ( const std::string &  name) const

Extracts the bool value from the entry given by its name.

Parameters:
nameName of the entry.
Returns:
Value of the entry if it has correct type.
void parameters::set_integer ( const std::string &  name,
int  value 
)

Inserts a new entry of type int to the first available slot. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
valueValue to be set.
int parameters::get_integer ( const std::string &  name) const

Extracts the int value from the entry given by its name.

Parameters:
nameName of the entry.
Returns:
Value of the entry if it has correct type.
void parameters::set_long_long ( const std::string &  name,
long long  value 
)

Inserts a new entry of type long long to the first available slot. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
valueValue to be set.
long long parameters::get_long_long ( const std::string &  name) const

Extracts the long long value from the entry given by its name.

Parameters:
nameName of the entry.
Returns:
Value of the entry if it has correct type.
void parameters::set_double_float ( const std::string &  name,
double  value 
)

Inserts a new entry of type double to the first available slot. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
valueValue to be set.
double parameters::get_double_float ( const std::string &  name) const

Extracts the double value from the entry given by its name.

Parameters:
nameName of the entry.
Returns:
Value of the entry if it has correct type.
void parameters::set_string ( const std::string &  name,
const std::string &  value 
)

Inserts a new entry of type string to the first available slot. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
valueValue to be set.
void parameters::set_string_shallow ( const std::string &  name,
const char *  value,
std::size_t  value_length 
)

Inserts a new entry of type string to the first available slot. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
valuePointer to the value buffer to be set. The buffer can contain zeros.
value_lengthLength of the value buffer.

Note: The value is not copied to the internal buffer and the user has to ensure that the given buffer is valid as long as this object refers to it.

std::string parameters::get_string ( const std::string &  name) const

Extracts the string value from the entry given by its name.

Parameters:
nameName of the entry.
Returns:
Value of the entry if it has correct type.
const char * parameters::get_string ( const std::string &  name,
std::size_t &  length 
) const

Extracts the string value from the entry given by its name by accessing the buffer directly.

Parameters:
nameName of the entry.
lengthLength of the internal buffer.
Returns:
Value of the entry if it has correct type.
void parameters::set_binary ( const std::string &  name,
const void *  value,
std::size_t  value_length 
)

Inserts a new entry of type binary to the first available slot. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
valueValue to be set.
value_lengthLength of the value buffer.
void parameters::set_binary_shallow ( const std::string &  name,
const void *  value,
std::size_t  value_length 
)

Inserts a new entry of type binary to the first available slot. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
valuePointer to the value buffer to be set. The buffer can contain zeros.
value_lengthLength of the value buffer.

Note: The value is not copied to the internal buffer and the user has to ensure that the given buffer is valid as long as this object refers to it.

const void * parameters::get_binary ( const std::string &  name,
std::size_t &  length 
) const

Extracts the binary value from the entry given by its name by accessing the buffer directly.

Parameters:
nameName of the entry.
lengthLength of the internal buffer.
Returns:
Value of the entry if it has correct type.
void parameters::set_boolean_array ( const std::string &  name,
const bool *  values,
std::size_t  array_length 
)

Inserts a new entry of type bool array to the first available slot. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
valuesPointer to the array of values to be set.
array_lengthLength of the array of values.

Note: The array of values is copied to the internal buffer.

void parameters::set_boolean_array_shallow ( const std::string &  name,
const bool *  values,
std::size_t  array_length 
)

Inserts a new entry of type bool array to the first available slot. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
valuesPointer to the array of values to be set.
array_lengthLength of the array of values.

Note: The array of values is not copied to the internal buffer and the user has to ensure that the given buffer is valid as long as this object refers to it.

bool * parameters::get_boolean_array ( const std::string &  name,
std::size_t &  array_length 
) const

Extracts the array of bool values from the entry given by its name.

Parameters:
nameName of the entry.
array_lengthLength of the internal array.
Returns:
Pointer to the internal array buffer.

Note: this function gives read-write access to the underlying array, even if it was set as a shallow-copy.

void parameters::set_integer_array ( const std::string &  name,
const int *  values,
std::size_t  array_length 
)

Inserts a new entry of type int array to the first available slot. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
valuesPointer to the array of values to be set.
array_lengthLength of the array of values.

Note: The array of values is copied to the internal buffer.

void parameters::set_integer_array_shallow ( const std::string &  name,
const int *  values,
std::size_t  array_length 
)

Inserts a new entry of type int array to the first available slot. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
valuesPointer to the array of values to be set.
array_lengthLength of the array of values.

Note: The array of values is not copied to the internal buffer and the user has to ensure that the given buffer is valid as long as this object refers to it.

int * parameters::get_integer_array ( const std::string &  name,
std::size_t &  array_length 
) const

Extracts the array of int values from the entry given by its name.

Parameters:
nameName of the entry.
array_lengthLength of the internal array.
Returns:
Pointer to the internal array buffer.

Note: this function gives read-write access to the underlying array, even if it was set as a shallow-copy.

void parameters::set_long_long_array ( const std::string &  name,
const long long *  values,
std::size_t  array_length 
)

Inserts a new entry of type long long array to the first available slot. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
valuesPointer to the array of values to be set.
array_lengthLength of the array of values.

Note: The array of values is copied to the internal buffer.

void parameters::set_long_long_array_shallow ( const std::string &  name,
const long long *  values,
std::size_t  array_length 
)

Inserts a new entry of type long long array to the first available slot. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
valuesPointer to the array of values to be set.
array_lengthLength of the array of values.

Note: The array of values is not copied to the internal buffer and the user has to ensure that the given buffer is valid as long as this object refers to it.

long long * parameters::get_long_long_array ( const std::string &  name,
std::size_t &  array_length 
) const

Extracts the array of long long values from the entry given by its name.

Parameters:
nameName of the entry.
array_lengthLength of the internal array.
Returns:
Pointer to the internal array buffer.

Note: this function gives read-write access to the underlying array, even if it was set as a shallow-copy.

void parameters::set_double_float_array ( const std::string &  name,
const double *  values,
std::size_t  array_length 
)

Inserts a new entry of type double array to the first available slot. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
valuesPointer to the array of values to be set.
array_lengthLength of the array of values.

Note: The array of values is copied to the internal buffer.

void parameters::set_double_float_array_shallow ( const std::string &  name,
const double *  values,
std::size_t  array_length 
)

Inserts a new entry of type double array to the first available slot. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
valuesPointer to the array of values to be set.
array_lengthLength of the array of values.

Note: The array of values is not copied to the internal buffer and the user has to ensure that the given buffer is valid as long as this object refers to it.

double * parameters::get_double_float_array ( const std::string &  name,
std::size_t &  array_length 
) const

Extracts the array of double values from the entry given by its name.

Parameters:
nameName of the entry.
array_lengthLength of the internal array.
Returns:
Pointer to the internally managed array buffer.

Note: this function gives read-write access to the underlying array, even if it was set as a shallow-copy.

void parameters::create_string_array ( const std::string &  name,
std::size_t  array_length 
)

Creates a new empty entry of type string array. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
array_lengthLength of the newly created array.

Note: After creation the array contains empty strings (that is, strings which length is 0).

void parameters::set_string_in_array ( const std::string &  name,
std::size_t  index,
const std::string &  value 
)

Inserts a new string value (possibly replacing the old one) to already existing string array at the given index.

Parameters:
nameName of the entry containing string array.
indexThe array index (array slot, starting from 0).
valueValue to be set.

Note: The value is copied to the internal buffer.

std::size_t parameters::get_string_array_length ( const std::string &  name) const

Extracts the length of string array that is located at the given entry.

Parameters:
nameName of the entry containing string array.
Returns:
Length of the array.
std::string parameters::get_string_in_array ( const std::string &  name,
std::size_t  index 
) const

Extracts the string value from the given index of string array.

Parameters:
nameName of the entry containing string array.
indexThe array index (array slot to be read, starting from 0).
Returns:
Value from array.
const char * parameters::get_string_in_array ( const std::string &  name,
std::size_t  index,
std::size_t &  length 
) const

Extracts the string value from the given index of string array by accessing the internal buffer directly.

Parameters:
nameName of the entry containing string array.
indexThe array index (array slot to be read, starting from 0).
lengthLength of the value buffer.
Returns:
Value from array.
void parameters::create_binary_array ( const std::string &  name,
std::size_t  array_length 
)

Creates a new empty entry of type binary array. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
array_lengthLength of the newly created array.

Note: After creation the array contains empty binaries (that is, binaries which length is 0).

void parameters::set_binary_in_array ( const std::string &  name,
std::size_t  index,
const void *  value,
std::size_t  value_length 
)

Inserts a new binary value (possibly replacing the old one) to already existing binary array at the given index.

Parameters:
nameName of the entry containing string array.
indexThe array index (array slot, starting from 0).
valuePointer to the value buffer to be set.
value_lengthLength of the value buffer.

Note: The value is copied to the internal buffer.

std::size_t parameters::get_binary_array_length ( const std::string &  name) const

Extracts the length of binary array that is located at the given entry.

Parameters:
nameName of the entry containing binary array.
Returns:
Length of the array.
const void * parameters::get_binary_in_array ( const std::string &  name,
std::size_t  index,
std::size_t &  length 
) const

Extracts the binary value from the given index of binary array by accessing the internal buffer directly.

Parameters:
nameName of the entry containing binary array.
indexThe array index (array slot to be read, starting from 0).
lengthLength of the value buffer.
Returns:
Value from array.
core::parameters * parameters::create_nested_parameters ( const std::string &  name)

Creates a new nested parameters entry in the first available slot. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
Returns:
Pointer to the internally created parameters object; the return value can be used to initialize wrapper parameters object.
core::parameters * parameters::get_nested_parameters ( const std::string &  name) const

Extracts nested parameters from the entry given by its name.

Parameters:
nameName of the entry.
Returns:
Pointer to the internally stored parameters object; the return value can be used to initialize wrapper parameters object.
void parameters::create_nested_array ( const std::string &  name,
std::size_t  array_length 
)

Creates a new nested parameters array entry. If the entry with the given name already exists it is replaced without changing the order of entries.

Parameters:
nameName of the new entry or the entry to be replaced.
array_lengthLength of the newly created array.
Returns:
  • ok if operation was successful
  • no_memory if the new entry cannot be allocated

Note: After creation the array contains empty nested objects (that is, parameters objects which do not have any entries).

std::size_t parameters::get_nested_array_length ( const std::string &  name) const

Extracts the length of nested parameters array that is located at the given entry.

Parameters:
nameName of the entry containing nested parameters array.
Returns:
Length of the array.
core::parameters * parameters::get_nested_in_array ( const std::string &  name,
std::size_t  index 
) const

Extracts the nested parameters value from the given index of nested array.

Parameters:
nameName of the entry containing nested parameters array.
indexThe array index (array slot to be read, starting from 0).
Returns:
Pointer to the internally stored parameters object; the return value can be used to initialize wrapper parameters object.
std::size_t parameters::size ( ) const

Returns the size of the collection - that is, the number of all non-empty slots.

Returns:
the size of the collection
parameter_type parameters::type ( const std::string &  name) const

Extracts the type of the entry given by its name.

Parameters:
nameName of the entry.
Returns:
type of the given entry.
parameters::iterator parameters::begin ( ) const

Extracts the iterator pointing to the beginning of the collection, which means the first used slot.

Returns:
the iterator pointing to the beginning of the collection
parameters::iterator parameters::end ( ) const

Extracts the iterator pointing past the end of the collection.

Returns:
the iterator pointing past the end of the collection
bool parameters::find ( const std::string &  name,
parameter_entry entry 
) const

Extracts the view on the entry specified by its name.

Parameters:
nameName of the entry.
entryThe entry view to be returned.
Returns:
  • true if the entry has been found
  • false if the given name cannot be found
void parameters::remove ( const std::string &  name)

Removes the entry given by its name.

Parameters:
nameName of the entry to remove.

Note: The removed entry leaves a hole (empty slot) in the collection that can be reused by newly added entries.

void parameters::remove ( iterator  it)

Removes the entry given by its iterator.

Parameters:
itIterator pointing to the entry to remove.

Note: The removed entry leaves a hole (empty slot) in the collection that can be reused by newly added entries.

void parameters::merge_from ( const parameters other)

Merges the entries from another parameters object. The merged entries can have the same names, in which case the new entries replace existing ones. The merging is deep in the sense that no data is shared between this and other object after the merge - this applies also to those entries that were shallow references in the other object.

Parameters:
otherThe object to be merged into this object.
void parameters::clear ( )

Clears the collection of entries and deallocates dependent structures. After executing the state of this object is as it was immediately after construction.

std::size_t parameters::serialize_buffer_size ( ) const [virtual]

Computes the total size of serialization buffer(s) for the current content of this object.

Implements yami::serializable.

void parameters::serialize ( char **  buffers,
std::size_t *  buffer_sizes,
std::size_t  num_of_buffers 
) const [virtual]

Serializes the current content of this object into the given buffer(s). The serialization buffer does not have to be contiguous and any number of buffer segments is allowed, provided that the size of each buffer segment is a multiple of 4 (32 bits).
The function scatters the serialized data into subsequent buffers as they become filled.
The buffers are provided as array of buffer pointers and their sizes.

Parameters:
buffersPointer to the array of buffer pointers (each of type char *).
buffer_sizesPointer to the array of buffer sizes.
num_of_buffersNumber of buffers described by the array.

Implements yami::serializable.

void parameters::deserialize ( const char **  buffers,
std::size_t *  buffer_sizes,
std::size_t  num_of_buffers 
)

Deserializes content from the given buffer(s). The data buffer does not have to be contiguous and any number of buffer segments is allowed, provided that the size of each buffer segment is a multiple of 4 (32 bits).
The function gathers the serialized data from subsequent buffers as they are consumed.
The buffers are provided as array of buffer pointers and their sizes.

Parameters:
buffersPointer to the array of buffer pointers (each of type const char *).
buffer_sizesPointer to the array of buffer sizes.
num_of_buffersNumber of buffers described by the array.

Note: The current content of this object is not cleared before attempting deserialization and each retrieved data element is merged into the current content as if done by individual calls to appropriate set_XYZ functions.
In most cases deserialization will be performed to the empty parameters object (to reconstruct it to the form that was used for serialization), but deserialization onto non-empty object might be occasionally useful as a way of merging two collections.