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

#include <AnyMap.h>

Inheritance diagram for AnyMap:

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 430 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

AnyValue &	operator[] (const string &key)
	Get the value of the item stored in `key`.

const AnyValue &	operator[] (const string &key) const

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.

const AnyValue &	at (const string &key) const
	Get the value of the item stored in `key`.

bool	empty () const
	Return boolean indicating whether AnyMap is empty.

bool	hasKey (const string &key) const
	Returns `true` if the map contains an item named `key`.

void	erase (const string &key)
	Erase the value held by `key`.

void	clear ()
	Erase all items in the mapping.

void	update (const AnyMap &other, bool keepExisting=true)
	Add items from `other` to this AnyMap.

void	exclude (const string &key)
	Mark `key` as excluded from this map.

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

set< string >	keys () const
	Return an unordered set of keys.

void	setMetadata (const string &key, const AnyValue &value)
	Set a metadata value that applies to this AnyMap and its children.

void	copyMetadata (const AnyMap &other)
	Copy metadata including input line/column from an existing AnyMap.

void	propagateMetadata (shared_ptr< AnyMap > &file)
	Propagate metadata to any child elements.

bool	getBool (const string &key, bool default_) const
	If `key` exists, return it as a `bool`, otherwise return `default_`.

long int	getInt (const string &key, long int default_) const
	If `key` exists, return it as a `long int`, otherwise return `default_`.

double	getDouble (const string &key, double default_) const
	If `key` exists, return it as a `double`, otherwise return `default_`.

const string &	getString (const string &key, const string &default_) const
	If `key` exists, return it as a `string`, otherwise return `default_`.

double	convert (const string &key, const string &units) const
	Convert the item stored by the given `key` to the units specified in `units`.

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`.

vector< double >	convertVector (const string &key, const string &units, size_t nMin=npos, size_t nMax=npos) const
	Convert a vector of dimensional values.

Iterator	begin () const
	Defined to allow use with range-based for loops.

Iterator	end () const
	Defined to allow use with range-based for loops.

OrderedProxy	ordered (bool withUnits=false) const
	Return a proxy object that allows iteration in an order determined by the order of insertion, the location in an input file, and rules specified by the addOrderingRules() method.

size_t	size () const
	Returns the number of elements in this map.

bool	operator== (const AnyMap &other) const

bool	operator!= (const AnyMap &other) const

const UnitSystem &	units () const
	Return the default units that should be used to convert stored values.

shared_ptr< UnitSystem >	unitsShared () const
	Return the default units that should be used to convert stored values.

void	applyUnits ()
	Use the supplied UnitSystem to set the default units, and recursively process overrides from nodes named `units`.

void	applyUnits (shared_ptr< UnitSystem > &units)
	See applyUnits()

void	setUnits (const UnitSystem &units)
	Set the unit system for this AnyMap.

void	setFlowStyle (bool flow=true)
	Use "flow" style when outputting this AnyMap to YAML.

Public Member Functions inherited from AnyBase
AnyBase &	operator= (const AnyBase &other)

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.

const AnyValue &	getMetadata (const string &key) const
	Get a value from the metadata applicable to the AnyMap tree containing this node.

Static Public Member Functions
static AnyMap	fromYamlFile (const string &name, const string &parent_name="")
	Create an AnyMap from a YAML file.

static AnyMap	fromYamlString (const string &yaml)
	Create an AnyMap from a string containing a YAML document.

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.

static void	clearCachedFile (const string &filename)
	Remove the specified file from the input cache if it is present.

Private Attributes
std::unordered_map< string, AnyValue >	m_data
	The stored data.

shared_ptr< UnitSystem >	m_units
	The default units that are used to convert stored values.

Static Private Attributes
static std::unordered_map< string, pair< AnyMap, std::filesystem::file_time_type > >	s_cache
	Cache for previously-parsed input (YAML) files.

static std::unordered_map< string, vector< string > >	s_headFields
	Information about fields that should appear first when outputting to YAML.

static std::unordered_map< string, vector< string > >	s_tailFields
	Information about fields that should appear last when outputting to YAML.

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.

int	m_column = 0
	If m_line >= 0, the column where this value occurs in the input file.

shared_ptr< AnyMap >	m_metadata
	Metadata relevant to an entire AnyMap tree, such as information about.

Constructor & Destructor Documentation

◆ AnyMap()

AnyMap ( )

Definition at line 1407 of file AnyMap.cpp.

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 1841 of file AnyMap.cpp.

◆ fromYamlString()

AnyMap fromYamlString ( const string & yaml )

static

Create an AnyMap from a string containing a YAML document.

Definition at line 1824 of file AnyMap.cpp.

◆ toYamlString()

string toYamlString ( ) const

Definition at line 1900 of file AnyMap.cpp.

◆ operator[]() [1/2]

AnyValue & operator[] ( const string & key )

Get the value of the item stored in key.

Definition at line 1412 of file AnyMap.cpp.

◆ operator[]() [2/2]

const AnyValue & operator[] ( const string & key ) const

Definition at line 1436 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 1446 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 1458 of file AnyMap.cpp.

◆ empty()

bool empty ( ) const

Return boolean indicating whether AnyMap is empty.

Definition at line 1468 of file AnyMap.cpp.

◆ hasKey()

bool hasKey ( const string & key ) const

Returns true if the map contains an item named key.

Definition at line 1477 of file AnyMap.cpp.

◆ erase()

void erase ( const string & key )

Erase the value held by key.

Definition at line 1483 of file AnyMap.cpp.

◆ clear()

void clear ( )

Erase all items in the mapping.

Definition at line 1488 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. Local units defined in other are not retained.

Definition at line 1493 of file AnyMap.cpp.

◆ exclude()

void exclude ( const string & key )

Mark key as excluded from this map.

This prevents key from being added by update(). Explicitly setting a value for key overrides this exclusion.

Definition at line 1502 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 1507 of file AnyMap.cpp.

◆ keys()

set< string > keys ( ) const

Return an unordered set of keys.

Since: New in Cantera 3.0.

Definition at line 1522 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 1541 of file AnyMap.cpp.

◆ copyMetadata()

void copyMetadata ( const AnyMap & other )

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

Definition at line 1553 of file AnyMap.cpp.

◆ propagateMetadata()

void propagateMetadata ( shared_ptr< AnyMap > & file )

Propagate metadata to any child elements.

Definition at line 1533 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 1575 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 1585 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 1580 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 1590 of file AnyMap.cpp.

◆ convert() [1/3]

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 1595 of file AnyMap.cpp.

◆ convert() [2/3]

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

Definition at line 1600 of file AnyMap.cpp.

◆ convert() [3/3]

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 1605 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

key	Location of the vector in this AnyMap
units	Units to convert to
nMin	Minimum 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.
nMax	Maximum allowed length of the vector. An exception is thrown if this condition is not met.

Definition at line 1615 of file AnyMap.cpp.

◆ begin()

Iterator begin ( ) const

inline

Defined to allow use with range-based for loops.

Definition at line 572 of file AnyMap.h.

◆ end()

Iterator end ( ) const

inline

Defined to allow use with range-based for loops.

Definition at line 577 of file AnyMap.h.

◆ ordered()

OrderedProxy ordered ( bool withUnits = false ) const

inline

Return a proxy object that allows iteration in an order determined by the order of insertion, the location in an input file, and rules specified by the addOrderingRules() method.

The withUnits flag determines whether to include a units directive, if any local units are defined (for use by the YAML emitter).

Definition at line 629 of file AnyMap.h.

◆ size()

size_t size ( ) const

Returns the number of elements in this map.

Definition at line 1728 of file AnyMap.cpp.

◆ operator==()

bool operator== ( const AnyMap & other ) const

Definition at line 1738 of file AnyMap.cpp.

◆ operator!=()

bool operator!= ( const AnyMap & other ) const

Definition at line 1756 of file AnyMap.cpp.

◆ units()

const UnitSystem & units ( ) const

inline

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

Definition at line 640 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 643 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 1761 of file AnyMap.cpp.

◆ applyUnits() [2/2]

void applyUnits ( shared_ptr< UnitSystem > & units )

See applyUnits()

Definition at line 1766 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 1782 of file AnyMap.cpp.

◆ setFlowStyle()

void setFlowStyle ( bool flow = true )

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

Definition at line 1794 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. Keys are output in the order provided to this method.

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";
}

Parameters

objectType	Apply rules to maps where the hidden `__type__` key has the corresponding value.
specs	A 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 1798 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 1816 of file AnyMap.cpp.

Friends And Related Symbol Documentation

◆ AnyValue

friend class AnyValue

friend

Definition at line 733 of file AnyMap.h.

Member Data Documentation

◆ m_data

std::unordered_map<string, AnyValue> m_data

private

The stored data.

Definition at line 712 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 715 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 721 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 726 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 731 of file AnyMap.h.

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

Detailed Description

Setting elements

Accessing elements

Checking for elements

Checking element types

Classes

Public Member Functions

Static Public Member Functions

Private Attributes

Static Private Attributes

Friends

Additional Inherited Members

Constructor & Destructor Documentation

◆ AnyMap()

Member Function Documentation

◆ fromYamlFile()

◆ fromYamlString()

◆ toYamlString()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ createForYaml()

◆ at()

◆ empty()

◆ hasKey()

◆ erase()

◆ clear()

◆ update()

◆ exclude()

◆ keys_str()

◆ keys()

◆ setMetadata()

◆ copyMetadata()

◆ propagateMetadata()

◆ getBool()

◆ getInt()

◆ getDouble()

◆ getString()

◆ convert() [1/3]

◆ convert() [2/3]

◆ convert() [3/3]

◆ convertVector()

◆ begin()

◆ end()

◆ ordered()

◆ size()

◆ operator==()

◆ operator!=()

◆ units()

◆ unitsShared()

◆ applyUnits() [1/2]

◆ applyUnits() [2/2]

◆ setUnits()

◆ setFlowStyle()

◆ addOrderingRules()

◆ clearCachedFile()

Friends And Related Symbol Documentation

◆ AnyValue

Member Data Documentation

◆ m_data

◆ m_units

◆ s_cache

◆ s_headFields

◆ s_tailFields