|
|
||
|
Simple values (boolean, integer, long and double) can be set with a single operation:
Params.Set_Integer ("age", 25);
Above, a new entry named ``age'' is created (or replaces the existing one with the same name) and an integer value 25 is set as its content.
String values are also handled directly:
Params.Set_String ("first_name", "John");
The binary values are handled with the Ada.Streams.Stream_Element_Array type:
declare
Song : Ada.Streams.Stream_Element_Array :=
Get_Song_From_Somewhere;
begin
Params.Set_Binary ("favorite_song", Song);
end;
In both string and binary cases, the arrays are copied into the internal storage of the parameters object, so that the original values that were provided by the user are no longer referenced.
Arrays of simple types are more involving and require the use of generic operations.
Assuming that the following types and array are defined:
declare
type My_Int_Type is new Integer;
type My_Index_Type is new Positive;
type My_Int_Array is array (My_Index_Type range <>)
of My_Int_Type;
My_Numbers : My_Int_Array := (10, 20, 30);
the following generic instantiation is needed to handle the above array:
procedure My_Set_Integer_Array is new Set_Integer_Array
(Integer_Type => My_Int_Type,
Index_Type => My_Index_Type,
Integer_Array_Type => My_Int_Array);
With the above instantiation the array can be set in the newly created entry named ``favorite_numbers'' with:
begin
My_Set_Integer_Array
(Params, "favorite_numbers", My_Numbers);
end;
Arrays of long and double types are handled in the same way except that generic formal parameter names are different (they start with Long_Long_Integer_ and Long_Float_ instead of Integer_).
Arrays of boolean values are also handled in the same way, except that there is no Boolean_Type generic formal parameter and therefore the whole operation has two parameters instead of three.
Arrays of strings do not follow the same strategy. The reason for this is that arrays of strings can be ``ragged'' - that is, the lengths of individual array elements might be different. The string array is set in two phases - it has to be created and then populated with values, as in the following example:
Params.Create_String_Array ("friends", 3);
Params.Set_String_In_Array ("friends", 1, "Alice");
Params.Set_String_In_Array ("friends", 2, "Bob");
Params.Set_String_In_Array ("friends", 3, "Nicole");
After the string array is created within the parameters object, it has the requested length, but all array elements are empty. The individual elements need to be set separately and the element is identified by both the array entry name (``friends'' above) and the array index, starting from 1. Each entry can have different length.
Arrays of binary values are handled in a similar way.
Nested parameters allow to build some form of hierarchic data structures. Nested parameters objects are created within existing parameters objects:
declare
Nested : Parameters_Collection :=
Params.Create_Nested_Parameters ("address");
The Nested object declared above is not a stand-alone object, but refers to the nested entry in the Params object. This means that both objects are coupled and care should be taken so that the containing object (Params) is not finalized before the one that refers to its internals (Nested) - it is recommended to use scoping to ensure proper lifetime management.
Since both Params and Nested know their relation, the contained object will be cleaned up only as part of the finalization of the Params object.
The Nested object declared above can be used just as any regular parameters object, for example:
begin
Nested.Set_String ("street", "Flowery");
Nested.Set_Integer ("house_number", 17);
end;
Similar rules apply for nested parameters arrays, which are also created within already existing parameters objects and then accessed on individual basis.
All the example statements in this section filled a single parameters object with six entries (``age'', ``first_name'', ``favorite_song'', ``favorite_numbers'' ``friends'' and ``address''), one them being an array with 3 elements and one being a nested parameters with 2 entries.