/MEng/System/Runtime/NamedValMap

ClassPath:	MEng.System.Runtime.NamedValMap
Parent ClassPath:	MEng.Object
Copyable:	No
Final:	Yes

MEng.System.Runtime.NamedValMap provides support for a fairly common data structure, in which one or more key/value pairs are stored under a unique name. For instance, if you wanted to store key/value information about cars, you might have an item named Corvette, and under that you might have key/value pairs like Price=$45,432, HorsePower=375, and so forth. And you might have other items named BMW M3, with it's own key/value pairs, and so forth.

In the documentation below, and in the method parameters and names, the item names are referred to as keys, the keys of of the individual key/value pairs are called sub-keys, and the values are referred to as values. The key, sub-key, and value are all strings.

The keys must be unique within the list of keys, and within each item, the sub-keys must be unique. But there is no requirement that each item contain the same list of sub-keys.

 

Nested Classes:

Enum=NamedValMapErrs
    AddItem : "An error occured while adding a map item %(1). Error=%(2)";
    AddValue : "An error occured while adding a map value %(1).%(2). Error=%(3)";
    ClearItem : "An error occured while clearing map item %(1). Error=%(2)";
    GetValue : "An error occured while getting map value %(1).%(2). Error=%(3)";
    KeyAlreadyExists : "Key %(1) already exists in the map";
    KeyNotFound : "Key %(1) was not found in the map";
    RemoveItem : "An error occured while removing a map item %(1). Error=%(2)";
    RemoveValue : "An error occured while removing map value %(1).%(2). Error=%(3)";
    SetValue : "An error occured while setting a map value %(1).%(2). Error=%(3)";
    SubKeyAlreadyExists : "Sub-key %(1).%(2) already exists in the map";
    SubKeyNotFound : "Sub-key %(1).%(2) was not found";
EndEnum;

This enumerated type defines the named value map specific exceptions that this class might throw. 

 

Constructors:

Constructor();

The default constructor creates an empty map.

 

Final, Const Methods:

GetValue([In] MEng.String Key, [In] MEng.String SubKey) Returns MEng.String;

This method will return the value for the indicated key and sub-key. If either of them doesn't exist, then you will get a KeyNotFound or SubKeyNotFound exception. If you aren't sure it exists, you can either just catch the exception and deal with it, or you can use the GetValueIfExists() method.

GetValueIfExists
(
    [In]    MEng.String Key
    , [In]  MEng.String SubKey
    , [Out] MEng.String ToFill
)   Returns MEng.Boolean;

This method will check to see if the key/sub-key exists, and if so it will fill in the ToFill parameter with the value. It returns a Boolean value to indicate whether the value was returned or not.

IsEmpty() Returns MEng.Boolean;

This method will return True if there are no items in the map, else False.

ItemExists([In] MEng.String Key) Returns MEng.Boolean;

This method will return True if there is an item in the map with the indicated key.

ItemIsEmpty([In] MEng.String Key) Returns MEng.Boolean;

This method will return True if the item with the indicated key is empty (no sub-keys), else it will return False. If the item does not exist, the KeyNotFound exception will be thrown.

SubKeyExists
(
    [In]   MEng.String Key
    , [In] MEng.String SubKey
)   Returns MEng.Boolean;

This method will return True if the indicated key/sub-key exists, else False.

 

Final, Non-Const Methods:

AddItem([In] MEng.String NewKey);

This method will add a new, empty item with the indicated key. Keys must be unique, so if this key already exists, the KeyAlreadyExists exception will be thrown.

AddValue
(
    [In]   MEng.String Key
    , [In] MEng.String NewSubKey
    , [In] MEng.String NewValue
);

This method will add a new value (with the indicated sub-key) to to the item with the indicated key. If the item key does not exist, then a KeyNotFound exception will be thrown. If the new sub-key already exists in the item, then a SubKeyAlreadyExists exception will be thrown.

ClearMap();

This method will remove all the items from the map, leaving it empty.

ClearItem([In] MEng.String Key);

This method will remove all the sub-keys from the item with the passed key. If the item does not exist, then a KeyNotFound exception will be thrown.

RemoveItem([In] MEng.String Key);

This method will remove the indicated key from the map, which of course will remove all of the sub-keys it contains. If the item does not exist, the KeyNotFound exception will be thrown.

RemoveSubKey([In] MEng.String Key, [In] MEng.String SubKey);

This method will remove the indicated sub-key from the item with the indicated key. If the key does not exist or the sub-key does not exist, the KeyNotFound or SubKeyNotFound exceptions will be thrown.