find_map

template <class keyT, class valT>
void find_map(const std::string& key, std::map<keyT, valT>& map) const;

Search for the specified key and return its value as a map in the provided argument map. The map will be empty if the key is not found. The function is parameterized on a types keyT and valT which must be valid Params parameter types (e.g., numeric including bool, string, or other class with a constructor that accepts a single string).

To be interpreted as a map, a map string must adhere to a specific format. The map must be enclosed in curly braces (). The key/value pairs should be comma separated (commas inside single or double quotes will not be considered a delimiter). Each pair should consist of a key and value separated by a colon (colons inside single or double quotes will not be considered a delimiter). If there are no curly braces , the function will throw a std::invalid_argument exception without adding anything to the map. The function is designed to accept the string that is generated when a Python dictionary is passed as a parameter value in the input configuration file. The function will then call the appropriate conversion function on the string to the templated type requested by the map. If a conversion does not exist (e.g., attempting to convert the string "hi" to an int), the function will throw an invalid_argument exception. Similarly, because C++ maps do not support mixed types, the Python map string should not mix types for either keys or values.

Examples of valid map strings in Python. These can be read into C++ maps of type std::map<std:;string,int> or std::map<std::string,std::string>.

• {"one" : 1, "two" : 2, "three" : 3, "four" : 4}
• {"one" : '1', "two" : '2', "three" : '3', "four" : '4'}
• {"one" : 1, "two" : "2", "three" : 3, "four" : "4"}

Example of an invalid map string in Python (mixed types cannot be converted):

• {"one" : 1, "two" : "two", "three" : False, "four" : 4}

Parameters

• key (std::string) Parameter key to search for
• map (std::map<keyT, valT>) Map templated on types keyT and valT to populate from the parameter's value
• returns none

Example

example::example(ComponentId_t id, Params& params) : Component(id)
{
    out = new Output("", 1, 0, Output::STDOUT);

    /* Some other constructor stuff */

    // For a parameter called "probabilities" that contains a mapping of outcome IDs (ints) to outcome probabilities (doubles)
    std::map<int,double> probMap;
    params.find_map<int,double>("probabilities", probMap);

    out->output("Probabilities are: \n");
    for (std::map<int,double>::iterator it = probMap.begin(); it != probMap.end(); it++)
    {
        out->output("Outcome: %d, Probability: %f\n", it->first, it->second);
    }
}

Additional information on parsing

For those interested in a more detailed description of how this function parses a string into a map, read on. The function is tailored to the type strings you get when passing a Python dictionary as the param value. When you call addParam() on a Python dictionary in the input file, it will call the str() function on the dictionary, which creates a string with the format: {key1 : value1, key2 : value2, key3 : value3}.

The format of each item depends on where it came from. The string for each key and value is generated by calling the repr() function on the item. For strings, this means they will typically be enclosed in single quotes. It is possible that they end up enclosed in double quotes if the string itself contains a single quote. For strings which contain both single and double quotes, the repr() will create a single quoted string with all internal single quotes escaped with ''. Most other items used in SST do not enclose the string in quotes, though any string that contains a comma would need to be enclosed in quotes, since the comma is the delimiter character used. This is not done automatically, so if you have something that generates a comma in the string created by repr(), you may need to create a map string manually. Also, any string that starts with a quote character, must end with the same quote character.

Tokens are generated by splitting the string on commas and colons that are not within quotes (double or single). All whitespace at the beginning and end of a token is ignored (unless inside quotes). Once the tokens are generated, any quoted string will have the front and back quotes removed. The '' for any escaped quote of the same type as the front and back is also removed.

Examples of parsing strings using double and/or single quotes:

• 'This is "a" test' -> This is "a" test
• "This is 'a' test" -> This is 'a' test
• 'This "is 'a'" test' -> This "is 'a''" test
• 'This "is "a"" test' -> This "is "a"" test

Header

The Params header file is included with any SST object that supports Params.

#include <sst/core/component.h> // or
#include <sst/core/subcomponent.h> // or
#include <sst/core/componentExtension.h> // or
#include <sst/core/params.h> // if not included in base class