find_array

template <class T>
void find_array(const std::string& key, std::vector<T>& vec) const;

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

To be interpreted as an array, an array string must adhere to a specific format. The array must be enclosed in square brackets ([]). The array values should be comma separated (commas inside single or double quotes are assumed to be a value not a delimiter). Array values themselves must be valid parameter template types. If square brackets are not used, the entire string will be assumed to be a single array value. The function is designed to accept the string that is generated when a Python list 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 vector. 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++ vectors do not support mixed types, the Python array string should not mix types.

Examples of valid array strings:

• [1, 2, 3, 4, 5]
• ['1', '2', '3', '4', '5']

Parameters

• key (std::string) Parameter key to search for
• vec (std::vector<T>) Vector with type T to populate from the parameter's value.
• returns none

Example

Excerpt from sst-elements/src/sst/elements/simpleElementExample/basicParams.cc

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

    /* Some other constructor stuff */

    std::vector<int> intArray;
    params.find_array<int>("array_param", intArray);

    out->output("Read an array from array_param. Elements are: \n");
    for (std::vector<int>::iterator it = intArray.begin(); it != intArray.end(); it++)
    {
        out->output("%d, ", *it);
    }
    out->output("\n");
}

Additional information on parsing

For those interested in a more detailed description of how this function parses a string into an array of tokens, read on. The function is tailored to the type strings you get when passing a Python list as the param string. When you call addParam() on a Python list in the input file, it will call the str() function on the list, which creates a string with the format: [item1, item2, item3].

The format of the items depends on where they came from. The string for each item is generated by calling the repr() function on it. 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 an array 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 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