Cantera  3.1.0a1
AnyMap Class Reference

A map of string keys to values whose type can vary at runtime. More...

#include <AnyMap.h>

Inheritance diagram for AnyMap:
[legend]

Detailed Description

A map of string keys to values whose type can vary at runtime.

Values in an AnyMap are held by instances of AnyValue. Instances of AnyMap can be nested to form a tree.

Setting elements

AnyMap breakfast;
breakfast["spam"] = 123.4; // Creates a value of type 'double'
breakfast["eggs"] = "scrambled"; // Creates a value of type 'string'
// Create a nested AnyMap named "beans" which has a key named "baked"
// whose value is a vector<double>
vector<double> v{3.14, 1.59, 2.65};
breakfast["beans"]["baked"] = v;
// Create a nested AnyMap with values of the same type
map<string, double> breads{{"wheat", 4.0}, {"white", 2.5}};
breakfast["toast"] = breads;
// Equivalent to:
breakfast["toast"]["wheat"] = 4.0
breakfast["toast"]["white"] = 2.5

Accessing elements

double val1 = breakfast["spam"].asDouble();
string val2 = breakfast["eggs"].asString();
vector<double> val3 = breakfast["beans"]["baked"].asVector<double>();
map<string, double> = breakfast["toast"].asMap<double>();

Checking for elements

try {
breakfast["waffle"].asDouble();
} except (std::exception& err) {
// Exception will be thrown.
// 'breakfast' will have an empty key named 'waffle' unless 'breakfast'
// is a 'const AnyMap'.
}
try {
breakfast.at("grits").asDouble();
} except (std::exception& err) {
// Exception will be thrown and no new key will be added
}
if (breakfast.hasKey("grits")) {
// do something with this entry
}

Checking element types

if (breakfast["sausage"].is<vector<double>>()) {
// access using asVector<double>
} else if (breakfast["sausage"].type() == typeid(vector<string>)) {
// access using asVector<string>
}

Definition at line 426 of file AnyMap.h.

Classes

class  Iterator
 Defined to allow use with range-based for loops. More...
 
class  OrderedIterator
 Defined to allow the OrderedProxy class to be used with range-based for loops. More...
 
class  OrderedProxy
 Proxy for iterating over an AnyMap in the defined output ordering. More...
 

Public Member Functions

string toYamlString () const
 
AnyValueoperator[] (const string &key)
 Get the value of the item stored in key. More...
 
const AnyValueoperator[] (const string &key) const
 
AnyValuecreateForYaml (const string &key, int line, int column)
 Used to create a new item which will be populated from a YAML input string, where the item with key occurs at the specified line and column within the string. More...
 
const AnyValueat (const string &key) const
 Get the value of the item stored in key. More...
 
bool empty () const
 Return boolean indicating whether AnyMap is empty. More...
 
bool hasKey (const string &key) const
 Returns true if the map contains an item named key. More...
 
void erase (const string &key)
 Erase the value held by key. More...
 
void clear ()
 Erase all items in the mapping. More...
 
void update (const AnyMap &other, bool keepExisting=true)
 Add items from other to this AnyMap. More...
 
string keys_str () const
 Return a string listing the keys in this AnyMap, for use in error messages, for example. More...
 
set< string > keys () const
 Return an unordered set of keys. More...
 
void setMetadata (const string &key, const AnyValue &value)
 Set a metadata value that applies to this AnyMap and its children. More...
 
void copyMetadata (const AnyMap &other)
 Copy metadata including input line/column from an existing AnyMap. More...
 
void propagateMetadata (shared_ptr< AnyMap > &file)
 Propagate metadata to any child elements. More...
 
bool getBool (const string &key, bool default_) const
 If key exists, return it as a bool, otherwise return default_. More...
 
long int getInt (const string &key, long int default_) const
 If key exists, return it as a long int, otherwise return default_. More...
 
double getDouble (const string &key, double default_) const
 If key exists, return it as a double, otherwise return default_. More...
 
const string & getString (const string &key, const string &default_) const
 If key exists, return it as a string, otherwise return default_. More...
 
double convert (const string &key, const string &units) const
 Convert the item stored by the given key to the units specified in units. More...
 
double convert (const string &key, const Units &units) const
 
double convert (const string &key, const string &units, double default_) const
 Convert the item stored by the given key to the units specified in units. More...
 
vector< double > convertVector (const string &key, const string &units, size_t nMin=npos, size_t nMax=npos) const
 Convert a vector of dimensional values. More...
 
Iterator begin () const
 Defined to allow use with range-based for loops. More...
 
Iterator end () const
 Defined to allow use with range-based for loops. More...
 
OrderedProxy ordered () const
 
size_t size () const
 Returns the number of elements in this map. More...
 
bool operator== (const AnyMap &other) const
 
bool operator!= (const AnyMap &other) const
 
const UnitSystemunits () const
 Return the default units that should be used to convert stored values. More...
 
shared_ptr< UnitSystemunitsShared () const
 Return the default units that should be used to convert stored values. More...
 
void applyUnits ()
 Use the supplied UnitSystem to set the default units, and recursively process overrides from nodes named units. More...
 
void applyUnits (shared_ptr< UnitSystem > &units)
 See applyUnits() More...
 
void setUnits (const UnitSystem &units)
 Set the unit system for this AnyMap. More...
 
void setFlowStyle (bool flow=true)
 Use "flow" style when outputting this AnyMap to YAML. More...
 
- Public Member Functions inherited from AnyBase
void setLoc (int line, int column)
 For values which are derived from an input file, set the line and column of this value in that file. More...
 
const AnyValuegetMetadata (const string &key) const
 Get a value from the metadata applicable to the AnyMap tree containing this node. More...
 

Static Public Member Functions

static AnyMap fromYamlFile (const string &name, const string &parent_name="")
 Create an AnyMap from a YAML file. More...
 
static AnyMap fromYamlString (const string &yaml)
 Create an AnyMap from a string containing a YAML document. More...
 
static bool addOrderingRules (const string &objectType, const vector< vector< string >> &specs)
 Add global rules for setting the order of elements when outputting AnyMap objects to YAML. More...
 
static void clearCachedFile (const string &filename)
 Remove the specified file from the input cache if it is present. More...
 

Private Attributes

std::unordered_map< string, AnyValuem_data
 The stored data. More...
 
shared_ptr< UnitSystemm_units
 The default units that are used to convert stored values. More...
 

Static Private Attributes

static std::unordered_map< string, pair< AnyMap, std::filesystem::file_time_type > > s_cache
 Cache for previously-parsed input (YAML) files. More...
 
static std::unordered_map< string, vector< string > > s_headFields
 Information about fields that should appear first when outputting to YAML. More...
 
static std::unordered_map< string, vector< string > > s_tailFields
 Information about fields that should appear last when outputting to YAML. More...
 

Friends

class AnyValue
 
YAML::Emitter & YAML::operator<< (YAML::Emitter &out, const AnyMap &rhs)
 

Additional Inherited Members

- Protected Attributes inherited from AnyBase
int m_line = -1
 The line where this value occurs in the input file. More...
 
int m_column = 0
 If m_line >= 0, the column where this value occurs in the input file. More...
 
shared_ptr< AnyMapm_metadata
 Metadata relevant to an entire AnyMap tree, such as information about. More...
 

Member Function Documentation

◆ fromYamlFile()

AnyMap fromYamlFile ( const string &  name,
const string &  parent_name = "" 
)
static

Create an AnyMap from a YAML file.

Searches the directory containing the optionally-specified parent file first, followed by the current working directory and the Cantera include path.

Definition at line 1771 of file AnyMap.cpp.

◆ fromYamlString()

AnyMap fromYamlString ( const string &  yaml)
static

Create an AnyMap from a string containing a YAML document.

Definition at line 1755 of file AnyMap.cpp.

◆ operator[]()

AnyValue & operator[] ( const string &  key)

Get the value of the item stored in key.

Definition at line 1362 of file AnyMap.cpp.

◆ createForYaml()

AnyValue & createForYaml ( const string &  key,
int  line,
int  column 
)

Used to create a new item which will be populated from a YAML input string, where the item with key occurs at the specified line and column within the string.

Definition at line 1396 of file AnyMap.cpp.

◆ at()

const AnyValue & at ( const string &  key) const

Get the value of the item stored in key.

Raises an exception if the value does not exist.

Definition at line 1408 of file AnyMap.cpp.

◆ empty()

bool empty ( ) const

Return boolean indicating whether AnyMap is empty.

Definition at line 1418 of file AnyMap.cpp.

◆ hasKey()

bool hasKey ( const string &  key) const

Returns true if the map contains an item named key.

Definition at line 1423 of file AnyMap.cpp.

◆ erase()

void erase ( const string &  key)

Erase the value held by key.

Definition at line 1428 of file AnyMap.cpp.

◆ clear()

void clear ( )

Erase all items in the mapping.

Definition at line 1433 of file AnyMap.cpp.

◆ update()

void update ( const AnyMap other,
bool  keepExisting = true 
)

Add items from other to this AnyMap.

If keys in other also exist in this AnyMap, the keepExisting option determines which item is used.

Definition at line 1438 of file AnyMap.cpp.

◆ keys_str()

string keys_str ( ) const

Return a string listing the keys in this AnyMap, for use in error messages, for example.

Definition at line 1447 of file AnyMap.cpp.

◆ keys()

set< string > keys ( ) const

Return an unordered set of keys.

Since
New in Cantera 3.0.

Definition at line 1462 of file AnyMap.cpp.

◆ setMetadata()

void setMetadata ( const string &  key,
const AnyValue value 
)

Set a metadata value that applies to this AnyMap and its children.

Mainly for internal use in reading or writing from files.

Definition at line 1481 of file AnyMap.cpp.

◆ copyMetadata()

void copyMetadata ( const AnyMap other)

Copy metadata including input line/column from an existing AnyMap.

Definition at line 1493 of file AnyMap.cpp.

◆ propagateMetadata()

void propagateMetadata ( shared_ptr< AnyMap > &  file)

Propagate metadata to any child elements.

Definition at line 1473 of file AnyMap.cpp.

◆ getBool()

bool getBool ( const string &  key,
bool  default_ 
) const

If key exists, return it as a bool, otherwise return default_.

Definition at line 1515 of file AnyMap.cpp.

◆ getInt()

long int getInt ( const string &  key,
long int  default_ 
) const

If key exists, return it as a long int, otherwise return default_.

Definition at line 1525 of file AnyMap.cpp.

◆ getDouble()

double getDouble ( const string &  key,
double  default_ 
) const

If key exists, return it as a double, otherwise return default_.

Definition at line 1520 of file AnyMap.cpp.

◆ getString()

const string & getString ( const string &  key,
const string &  default_ 
) const

If key exists, return it as a string, otherwise return default_.

Definition at line 1530 of file AnyMap.cpp.

◆ convert() [1/2]

double convert ( const string &  key,
const string &  units 
) const

Convert the item stored by the given key to the units specified in units.

If the stored value is a double, convert it using the default units. If the input is a string, treat this as a dimensioned value, such as '988 kg/m^3' and convert from the specified units.

Definition at line 1535 of file AnyMap.cpp.

◆ convert() [2/2]

double convert ( const string &  key,
const string &  units,
double  default_ 
) const

Convert the item stored by the given key to the units specified in units.

If the stored value is a double, convert it using the default units. If the input is a string, treat this as a dimensioned value, such as '988 kg/m^3' and convert from the specified units. If the key is missing, the default_ value is returned.

Definition at line 1545 of file AnyMap.cpp.

◆ convertVector()

vector< double > convertVector ( const string &  key,
const string &  units,
size_t  nMin = npos,
size_t  nMax = npos 
) const

Convert a vector of dimensional values.

For each item in the vector, if the stored value is a double, convert it using the default units. If the value is a string, treat it as a dimensioned value, such as '988 kg/m^3', and convert from the specified units.

Parameters
keyLocation of the vector in this AnyMap
unitsUnits to convert to
nMinMinimum allowed length of the vector. If nMax is not specified, this is also taken to be the maximum length. An exception is thrown if this condition is not met.
nMaxMaximum allowed length of the vector. An exception is thrown if this condition is not met.

Definition at line 1555 of file AnyMap.cpp.

◆ begin()

Iterator begin ( ) const
inline

Defined to allow use with range-based for loops.

Definition at line 563 of file AnyMap.h.

◆ end()

Iterator end ( ) const
inline

Defined to allow use with range-based for loops.

Definition at line 568 of file AnyMap.h.

◆ size()

size_t size ( ) const
inline

Returns the number of elements in this map.

Definition at line 622 of file AnyMap.h.

◆ units()

const UnitSystem& units ( ) const
inline

Return the default units that should be used to convert stored values.

Definition at line 630 of file AnyMap.h.

◆ unitsShared()

shared_ptr<UnitSystem> unitsShared ( ) const
inline

Return the default units that should be used to convert stored values.

Definition at line 633 of file AnyMap.h.

◆ applyUnits() [1/2]

void applyUnits ( )

Use the supplied UnitSystem to set the default units, and recursively process overrides from nodes named units.

If a units node is present in a map that contains other keys, the specified units are taken to be the defaults for that map. If the map contains only a units node, and is the first item in a list of maps, then the specified units are taken to be the defaults for all the maps in the list.

After being processed, the units nodes are removed. This function is called automatically by the fromYamlFile() and fromYamlString() constructors.

Warning
This function is an experimental part of the Cantera API and may be changed or removed without notice.

Definition at line 1693 of file AnyMap.cpp.

◆ applyUnits() [2/2]

void applyUnits ( shared_ptr< UnitSystem > &  units)

See applyUnits()

Definition at line 1698 of file AnyMap.cpp.

◆ setUnits()

void setUnits ( const UnitSystem units)

Set the unit system for this AnyMap.

The applyUnits() method should be called on the root AnyMap object after all desired calls to setUnits() in the tree have been made.

Definition at line 1714 of file AnyMap.cpp.

◆ setFlowStyle()

void setFlowStyle ( bool  flow = true)

Use "flow" style when outputting this AnyMap to YAML.

Definition at line 1726 of file AnyMap.cpp.

◆ addOrderingRules()

bool addOrderingRules ( const string &  objectType,
const vector< vector< string >> &  specs 
)
static

Add global rules for setting the order of elements when outputting AnyMap objects to YAML.

Enables specifying keys that should appear at either the beginning or end of the generated YAML mapping. Only programmatically-added keys are rearranged. Keys which come from YAML input retain their existing ordering, and are output after programmatically-added keys.

This function should be called exactly once for any given spec that is to be added. To facilitate this, the method returns a bool so that it can be called as part of initializing a static variable. To avoid spurious compiler warnings about unused variables, the following structure can be used:

static bool reg = AnyMap::addOrderingRules("Reaction",
{{"head", "equation"}, {"tail", "duplicate"}});
if (reg) {
reactionMap["__type__"] = "Reaction";
}
static bool addOrderingRules(const string &objectType, const vector< vector< string >> &specs)
Add global rules for setting the order of elements when outputting AnyMap objects to YAML.
Definition: AnyMap.cpp:1730
Parameters
objectTypeApply rules to maps where the hidden __type__ key has the corresponding value.
specsA list of rule specifications. Each rule consists of two strings. The first string is either "head" or "tail", and the second string is the name of a key
Returns
true, to facilitate static initialization

Definition at line 1730 of file AnyMap.cpp.

◆ clearCachedFile()

void clearCachedFile ( const string &  filename)
static

Remove the specified file from the input cache if it is present.

Definition at line 1747 of file AnyMap.cpp.

Member Data Documentation

◆ m_data

std::unordered_map<string, AnyValue> m_data
private

The stored data.

Definition at line 701 of file AnyMap.h.

◆ m_units

shared_ptr<UnitSystem> m_units
private

The default units that are used to convert stored values.

Definition at line 704 of file AnyMap.h.

◆ s_cache

std::unordered_map< string, pair< AnyMap, std::filesystem::file_time_type > > s_cache
staticprivate

Cache for previously-parsed input (YAML) files.

The key is the full path to the file, and the second element of the value is the last-modified time for the file, which is used to enable change detection.

Definition at line 710 of file AnyMap.h.

◆ s_headFields

std::unordered_map< string, vector< string > > s_headFields
staticprivate

Information about fields that should appear first when outputting to YAML.

Keys in this map are matched to __type__ keys in AnyMap objects, and values are a list of field names.

Definition at line 715 of file AnyMap.h.

◆ s_tailFields

std::unordered_map< string, vector< string > > s_tailFields
staticprivate

Information about fields that should appear last when outputting to YAML.

Keys in this map are matched to __type__ keys in AnyMap objects, and values are a list of field names.

Definition at line 720 of file AnyMap.h.


The documentation for this class was generated from the following files: