|
|
||
|
Reading existing entries of fundamental types is straightforward:
int age = params.get_integer("age");
Strings can be similarly extracted with a single function call:
std::string first_name = params.get_string("first_name");
For performance reasons it is also possible to extract strings in the ``shallow'' way, without creating additional string objects and without allocating any additional buffers.
In the following example the length variable is passed by reference and is filled with proper string length.
std::size_t length;
const char * first_name =
params.get_string("first_name", length);
Binary buffers are handled as a pair of void * and std::size_t values:
std::size_t song_size;
const void * song_buffer =
params.get_binary("favorite_song", song_size);
Above, the song_size parameter is passed by reference and is filled with proper buffer length.
It should be noted that when reading the binary entry, the data is not copied and no additional buffer is allocated - the above example returns a pointer to the internal buffer. In a sense, even though binary entries can be set either by copy or in the ``shallow'' way, they are always returned by ``shallow'' reference.
Extracting arrays of fundamental types is very similar to handling of binary buffers - the buffer pointer to parameters internal storage is returned and the length variable is filled with appropriate array length.
For example:
std::size_t array_length;
int * my_numbers =
params.get_integer_array("favorite_numbers", array_length);
Arrays of boolean, long and double types are handled in the same way.
Arrays of strings do not follow the same mold and somehow mirror the way they are created. In order to read the string array element, the name of the whole array and its index, starting from 0, need to be provided:
std::string first_friend =
params.get_string_in_array("friends", 0);
std::string second_friend =
params.get_string_in_array("friends", 1);
std::string third_friend =
params.get_string_in_array("friends", 2);
There are also variants of the above function that return the string by direct pointer to internal buffer.
Arrays of binary values are handled in a similar way, except that the ``shallow'' mode is the only supported one.
Nested parameters can be extracted with a separate function that returns the value that can be immediately wrapped by a parameters object. Such an object is aware of its relation with the whole container, so that it does not invalidate the referenced entry during its own destruction:
parameters nested(params.get_nested_parameters("address"));
Care should be taken to ensure that such object does not live longer than the parameters object representing the whole container - it is recommended to use scoping to ensure proper lifetime management.
Note:
If the entry given by name does not exist, each of the reading functions will throw the yami_logic_error exception. Similarly, when the given entry exists but its type does not correspond to the expected type of the reading function, the same exception will be thrown. The reason for this exception choice is that such situations are considered to be programming errors. Code that needs to read entries that might not exist or with flexibility in type handling should use the methods described in later sections devoted to entry searches.