A class organizing a tree of key-value pairs. More...

#include <property_map.hpp>

Public Types
typedef EntryMap::const_iterator	ConstEntryIterator
	const entry iterator type More...

typedef SectionMap::const_iterator	ConstSectionIterator
	const section iterator type More...

typedef EntryMap::iterator	EntryIterator
	entry iterator type More...

typedef std::map< String, String, String::NoCaseLess >	EntryMap
	entry-map type More...

typedef SectionMap::iterator	SectionIterator
	section iterator type More...

typedef std::map< String, std::shared_ptr< PropertyMap >, String::NoCaseLess >	SectionMap
	section-map type More...

Public Member Functions
	PropertyMap (const PropertyMap &)=delete
	Delete copy constructor.

	PropertyMap (PropertyMap *parent=nullptr)
	Default Constructor. More...

virtual	~PropertyMap ()
	Virtual Destructor. More...

bool	add_entry (String key, String value, bool replace=true)
	Adds a new key-value pair to this map. More...

PropertyMap *	add_section (String name)
	Adds a new sub-section to this map. More...

EntryIterator	begin_entry ()
	Returns the first entry iterator. More...

ConstEntryIterator	begin_entry () const
	Returns the first entry iterator. More...

SectionIterator	begin_section ()
	Returns the first section iterator. More...

ConstSectionIterator	begin_section () const
	Returns the first section iterator. More...

EntryIterator	end_entry ()
	Returns the last entry iterator. More...

ConstEntryIterator	end_entry () const
	Returns the last entry iterator. More...

SectionIterator	end_section ()
	Returns the last section iterator. More...

ConstSectionIterator	end_section () const
	Returns the last section iterator. More...

bool	erase_entry (String key)
	Erases a key-value pair. More...

bool	erase_section (String name)
	Erases a sub-section. More...

std::pair< String, bool >	get_entry (String key) const
	Retrieves a value by its key. More...

EntryMap &	get_entry_map ()
	Returns a reference to the entry map. More...

const EntryMap &	get_entry_map () const
	Returns a reference to the entry map. More...

PropertyMap *	get_parent ()
	Returns a pointer to the parent section. More...

const PropertyMap *	get_parent () const
	Returns a pointer to the parent section. More...

PropertyMap *	get_root ()
	Returns a pointer to the root section. More...

const PropertyMap *	get_root () const
	Returns a pointer to the root section. More...

PropertyMap *	get_sub_section (String name)
	Retrieves a sub-section by its name. More...

const PropertyMap *	get_sub_section (String name) const

void	merge (const PropertyMap &section, bool replace=true)
	Merges another PropertyMap into `this`. More...

PropertyMap &	operator= (const PropertyMap &)=delete
	Delete copy assignment operator.

template<typename T_ >
bool	parse_entry (const String &key, T_ &x, bool rtn_non_exist=true) const
	Parses an object from the value of an entry. More...

std::pair< String, bool >	query (String key_path) const
	Queries a value by its key path. More...

String	query (String key_path, String default_value) const
	Queries a value by its key path. More...

PropertyMap *	query_section (String sec_path)
	Queries a section by its section path. More...

const PropertyMap *	query_section (String sec_path) const
	Queries a section by its section path. More...

void	read (const Dist::Comm &comm, String filename, bool replace=true)
	Parses a file in INI-format. More...

void	read (std::istream &ifs, bool replace=true)
	Parses an input stream. More...

void	read (String filename, bool replace=true)
	Parses a file in INI-format. More...

std::unique_ptr< PropertyMap >	treeify_structures () const
	Builds a new property map by inserting subsection based on section names. More...

void	write (const Dist::Comm &comm, String filename) const
	Writes the property map into a file. More...

void	write (std::ostream &os, String::size_type indent=0) const
	Writes the property map into an output stream. More...

void	write (String filename) const
	Writes the property map into a file. More...

Protected Attributes
PropertyMap *	_parent
	pointer to the parent node More...

SectionMap	_sections
	a map storing the sub-sections More...

EntryMap	_values
	a map storing the key-value-pairs More...

Detailed Description

A class organizing a tree of key-value pairs.

See also: INI Data File Format

Path Specification:
Some functions of this class, namely the query() and query_section() functions, use paths for their search. Paths allow to search for sections and key-value pairs (either relatively or absolutely) within the whole property map tree instead of only within the current property map represented by the ProperyMap object itself.

For this, three characters are reserved as special characters in the path:

The forward slash / represents a path separator (just as in file-system paths).
The exclamation mark ! represents the root section.
The tilde ~ represents the parent section (as the double-dot .. in file-system paths).

Examples:

SecName/KeyName: searches for a key named KeyName inside a sub-section named SecName within the current section.
!/SecName/KeyName: searches for key named KeyName inside a sub-section named SecName within the root section; independent of which section is represented by the current section.
~/KeyName: searches for a key named KeyName inside the parent section of the current section.

Author: Constantin Christof; Peter Zajac

Definition at line 47 of file property_map.hpp.

Member Typedef Documentation

◆ ConstEntryIterator

typedef EntryMap::const_iterator FEAT::PropertyMap::ConstEntryIterator

const entry iterator type

Definition at line 58 of file property_map.hpp.

◆ ConstSectionIterator

typedef SectionMap::const_iterator FEAT::PropertyMap::ConstSectionIterator

const section iterator type

Definition at line 62 of file property_map.hpp.

◆ EntryIterator

typedef EntryMap::iterator FEAT::PropertyMap::EntryIterator

entry iterator type

Definition at line 56 of file property_map.hpp.

◆ EntryMap

typedef std::map<String, String, String::NoCaseLess> FEAT::PropertyMap::EntryMap

entry-map type

Definition at line 51 of file property_map.hpp.

◆ SectionIterator

typedef SectionMap::iterator FEAT::PropertyMap::SectionIterator

section iterator type

Definition at line 60 of file property_map.hpp.

◆ SectionMap

typedef std::map<String, std::shared_ptr<PropertyMap>, String::NoCaseLess> FEAT::PropertyMap::SectionMap

section-map type

Definition at line 53 of file property_map.hpp.

Constructor & Destructor Documentation

◆ PropertyMap()

FEAT::PropertyMap::PropertyMap ( PropertyMap * parent = nullptr )

explicit

Default Constructor.

Definition at line 16 of file property_map.cpp.

◆ ~PropertyMap()

FEAT::PropertyMap::~PropertyMap ( )

virtual

Virtual Destructor.

Definition at line 21 of file property_map.cpp.

Member Function Documentation

◆ add_entry()

bool FEAT::PropertyMap::add_entry	(	String	key,
		String	value,
		bool	replace = `true`
	)

Adds a new key-value pair to this map.

This function adds a new key-value pair to this section or, if desired, overwrites an existing one.

Parameters

[in]	key	A String containing the key of the entry.
[in]	value	A String containing the value of the entry.
[in]	replace	Specifies the behavior when an entry with the same key already exists in the section: If `replace` = `true`, then the old value of the entry is replaced by the `value` parameter passed to this function. If `replace` = `false`, then the old value of the entry is kept and this function returns `false`.

Returns: true, if the key-value-pair has been stored or false, if an entry with the key already exists and replace was set to false.

Definition at line 25 of file property_map.cpp.

References _values, and FEAT::value.

Referenced by merge(), and read().

◆ add_section()

PropertyMap * FEAT::PropertyMap::add_section ( String name )

Adds a new sub-section to this map.

This function adds a new sub-section and returns a pointer to it. If a sub-section with the corresponding name already exists, a pointer to that section is returned instead of allocating a new one.

Parameters

[in] name The name of the section to be added.

Returns: A pointer to a the PropertyMap associated to the name.

Note: The returned pointer is managed by this object and therefore the object must not be deleted by the caller!

Definition at line 44 of file property_map.cpp.

References _sections.

Referenced by merge(), and read().

◆ begin_entry() [1/2]

EntryIterator FEAT::PropertyMap::begin_entry ( )

inline

Returns the first entry iterator.

Definition at line 319 of file property_map.hpp.

References _values.

◆ begin_entry() [2/2]

ConstEntryIterator FEAT::PropertyMap::begin_entry ( ) const

inline

Returns the first entry iterator.

Definition at line 325 of file property_map.hpp.

References _values.

◆ begin_section() [1/2]

SectionIterator FEAT::PropertyMap::begin_section ( )

inline

Returns the first section iterator.

Definition at line 343 of file property_map.hpp.

References _sections.

◆ begin_section() [2/2]

ConstSectionIterator FEAT::PropertyMap::begin_section ( ) const

inline

Returns the first section iterator.

Definition at line 349 of file property_map.hpp.

References _sections.

◆ end_entry() [1/2]

EntryIterator FEAT::PropertyMap::end_entry ( )

inline

Returns the last entry iterator.

Definition at line 331 of file property_map.hpp.

References _values.

◆ end_entry() [2/2]

ConstEntryIterator FEAT::PropertyMap::end_entry ( ) const

inline

Returns the last entry iterator.

Definition at line 337 of file property_map.hpp.

References _values.

◆ end_section() [1/2]

SectionIterator FEAT::PropertyMap::end_section ( )

inline

Returns the last section iterator.

Definition at line 355 of file property_map.hpp.

References _sections.

◆ end_section() [2/2]

ConstSectionIterator FEAT::PropertyMap::end_section ( ) const

inline

Returns the last section iterator.

Definition at line 361 of file property_map.hpp.

References _sections.

◆ erase_entry()

bool FEAT::PropertyMap::erase_entry ( String key )

Erases a key-value pair.

Parameters

[in] key The key of the entry to be erased.

Returns: true if the entry was erased or false if no entry with that key was found.

Definition at line 59 of file property_map.cpp.

References _values.

◆ erase_section()

bool FEAT::PropertyMap::erase_section ( String name )

Erases a sub-section.

Parameters

[in] name The name of the sub-section to be erased.

Returns: true if the section was erased or false if no section with that name was found.

Definition at line 70 of file property_map.cpp.

References _sections.

◆ get_entry()

std::pair< String, bool > FEAT::PropertyMap::get_entry ( String key ) const

Retrieves a value by its key.

Note: This function only searches the current section represented by this for the key. If you want to search whole paths, use the query() function instead.

Parameters

[in] key The key of the entry whose value is to be returned.

Returns: A pair<String, bool>, where the second component marks, whether an entry with the key has been found or not. If the bool-component is true, then the String-component contains the value associated with the key, otherwise the String-component is empty.

Definition at line 165 of file property_map.cpp.

References _values.

Referenced by FEAT::Solver::IterativeSolver< Vector_ >::IterativeSolver(), FEAT::Solver::NLOptLS< Functional_, Filter_ >::NLOptLS(), parse_entry(), and query().

◆ get_entry_map() [1/2]

EntryMap & FEAT::PropertyMap::get_entry_map ( )

inline

Returns a reference to the entry map.

Returns: A (const) reference to the entry map.

Definition at line 307 of file property_map.hpp.

References _values.

◆ get_entry_map() [2/2]

const EntryMap & FEAT::PropertyMap::get_entry_map ( ) const

inline

Returns a reference to the entry map.

Returns: A (const) reference to the entry map.

Definition at line 313 of file property_map.hpp.

References _values.

◆ get_parent() [1/2]

PropertyMap * FEAT::PropertyMap::get_parent ( )

inline

Returns a pointer to the parent section.

Returns: A pointer to the parent section or nullptr if this section has no parent.

Definition at line 277 of file property_map.hpp.

References _parent.

Referenced by query_section().

◆ get_parent() [2/2]

const PropertyMap * FEAT::PropertyMap::get_parent ( ) const

inline

Returns a pointer to the parent section.

Returns: A pointer to the parent section or nullptr if this section has no parent.

Definition at line 283 of file property_map.hpp.

References _parent.

◆ get_root() [1/2]

PropertyMap * FEAT::PropertyMap::get_root ( )

inline

Returns a pointer to the root section.

Definition at line 291 of file property_map.hpp.

References _parent, and get_root().

Referenced by get_root(), and query_section().

◆ get_root() [2/2]

const PropertyMap * FEAT::PropertyMap::get_root ( ) const

inline

Returns a pointer to the root section.

Definition at line 297 of file property_map.hpp.

References _parent, and get_root().

◆ get_sub_section() [1/2]

PropertyMap * FEAT::PropertyMap::get_sub_section ( String name )

Retrieves a sub-section by its name.

Note: This function only search the current section represented by this for the sub-section. If you want to search whole paths, use the query_section() function instead.

Parameters

[in] name The name of the sub-section which is to be returned.

Returns: A pointer to the PropertyMap associated with name or nullptr if no section with that name exists.

Note: This method does not allocate new memory, thus modifications to the returned PropertyMap affect the base property map and the returned PropertyMap must not be deleted.

Definition at line 185 of file property_map.cpp.

References _sections.

Referenced by query_section().

◆ get_sub_section() [2/2]

const PropertyMap * FEAT::PropertyMap::get_sub_section ( String name ) const

Definition at line 175 of file property_map.cpp.

References _sections.

◆ merge()

void FEAT::PropertyMap::merge	(	const PropertyMap &	section,
		bool	replace = `true`
	)

Merges another PropertyMap into this.

Parameters

[in]	section	The section to be merged into `this`.
[in]	replace	Specifies the behavior when conflicting key-value pairs are encountered. See add_entry() for more details.

Definition at line 195 of file property_map.cpp.

References _sections, _values, add_entry(), add_section(), and merge().

Referenced by merge().

◆ parse_entry()

template<typename T_ >

bool FEAT::PropertyMap::parse_entry	(	const String &	key,
		T_ &	x,
		bool	rtn_non_exist = `true`
	)		const

inline

Parses an object from the value of an entry.

If an entry for the given key exists, this function is equivalent to this->get_entry(key).first.parse(x).

Parameters

[in]	key	The key of the entry whose value is to be parsed.
[out]	x	A reference to the object that is to be parsed into.
[in]	rtn_non_exist	The value that this function should return if there exists no entry for the given key.

Returns

true, if the entry exists and was parsed successfully,
false, if the entry exists but could not be parsed,
rtn_non_exist, if the entry does not exist

Definition at line 262 of file property_map.hpp.

References get_entry().

◆ query() [1/2]

std::pair< String, bool > FEAT::PropertyMap::query ( String key_path ) const

Queries a value by its key path.

Note: See the documentation of this class for details about paths.

Parameters

[in] key_path A path to the key whose value is to be returned.

Returns: A pair<String,bool>, where the second component marks, whether an entry with the key path has been found or not. If the bool-component is true, then the String-component contains the value associated with the key, otherwise the String-component is empty.

Definition at line 125 of file property_map.cpp.

References get_entry(), query_section(), FEAT::String::trim(), and FEAT::String::trim_me().

◆ query() [2/2]

String FEAT::PropertyMap::query	(	String	key_path,
		String	default_value
	)		const

Queries a value by its key path.

Note: See the documentation of this class for details about paths.

Parameters

[in]	key_path	A path to the key whose value is to be returned.
[in]	default_value	A string that is to be returned in the case that the key was not found.

Returns: A String containing the value corresponding to the key-path, or default_value if no such key was found.

Definition at line 156 of file property_map.cpp.

References query().

◆ query_section() [1/2]

PropertyMap * FEAT::PropertyMap::query_section ( String sec_path )

Queries a section by its section path.

Note: See the documentation of this class for details about paths.

Parameters

[in] sec_path A path to the section that is to be found.

Returns: A (const) pointer to the section represented by path or nullptr if no such section was found.

Note: The returned pointer (if not null) is managed by this PropertyMap object and therefore the returned object must not be deleted by the caller.

Definition at line 81 of file property_map.cpp.

References query_section().

Referenced by FEAT::Control::Meshopt::HyperelasticityFunctionalControl< DT_, IT_, DomainControl_, Hyperelasticity_ >::HyperelasticityFunctionalControl(), FEAT::Meshopt::MeshConcentrationFunctionFactory< Trafo_, RefCellTrafo_ >::create(), FEAT::Control::Meshopt::ControlFactory< DT_, IT_ >::create_dudv_control(), FEAT::Control::Meshopt::ControlFactory< DT_, IT_ >::create_hyperelasticity_control(), FEAT::Control::Meshopt::ControlFactory< DT_, IT_ >::create_meshopt_control(), query(), and query_section().

◆ query_section() [2/2]

const PropertyMap * FEAT::PropertyMap::query_section ( String sec_path ) const

Queries a section by its section path.

Note: See the documentation of this class for details about paths.

Parameters

[in] sec_path A path to the section that is to be found.

Returns: A (const) pointer to the section represented by path or nullptr if no such section was found.

Note: The returned pointer (if not null) is managed by this PropertyMap object and therefore the returned object must not be deleted by the caller.

Definition at line 87 of file property_map.cpp.

References get_parent(), get_root(), get_sub_section(), query_section(), FEAT::String::trim(), and FEAT::String::trim_me().

◆ read() [1/3]

void FEAT::PropertyMap::read	(	const Dist::Comm &	comm,
		String	filename,
		bool	replace = `true`
	)

Parses a file in INI-format.

Parameters

[in]	filename	The name of the file to be parsed.
[in]	replace	Specifies the behavior when an entry with the same key already exists: If `replace` = `true`, then the old value of the entry is replaced by the new `value` If `replace` = `false`, then the old value of the entry is kept.

See also: PropertyMap::read(std::istream&)

Definition at line 217 of file property_map.cpp.

References read(), and FEAT::DistFileIO::read_common().

◆ read() [2/3]

void FEAT::PropertyMap::read	(	std::istream &	ifs,
		bool	replace = `true`
	)

Parses an input stream.

Parameters

[in]	ifs	A reference to an input stream to be parsed.
[in]	replace	Specifies the behavior when an entry with the same key already exists: If `replace` = `true`, then the old value of the entry is replaced by the new `value` If `replace` = `false`, then the old value of the entry is kept.

Definition at line 224 of file property_map.cpp.

References add_entry(), add_section(), FEAT::String::pop_back(), FEAT::String::pop_front(), FEAT::stringify(), FEAT::String::trim(), FEAT::String::trim_me(), and FEAT::value.

◆ read() [3/3]

void FEAT::PropertyMap::read	(	String	filename,
		bool	replace = `true`
	)

inline

Parses a file in INI-format.

Parameters

[in]	filename	The name of the file to be parsed.
[in]	replace	Specifies the behavior when an entry with the same key already exists: If `replace` = `true`, then the old value of the entry is replaced by the new `value` If `replace` = `false`, then the old value of the entry is kept.

See also: PropertyMap::read(std::istream&)

Definition at line 390 of file property_map.hpp.

References read(), and FEAT::Dist::Comm::world().

Referenced by read().

◆ treeify_structures()

std::unique_ptr< PropertyMap > FEAT::PropertyMap::treeify_structures ( ) const

Builds a new property map by inserting subsection based on section names.

This function transforms a all sections consisting of "sec1/sec2" into real subsections. i.e. transform [sec1] \ [sec1] key1=val1 === \ { key1=val1 [sec1/sec2] === / [sec2] key2=val2 / key2=val2 }

This appears to be necessary due to the oversight?! that "/" is not a reserved charset in sections.

Definition at line 518 of file property_map.cpp.

◆ write() [1/3]

void FEAT::PropertyMap::write	(	const Dist::Comm &	comm,
		String	filename
	)		const

Writes the property map into a file.

This function writes the whole property map into a file, which can be parsed by the read() function.

Parameters

[in] filename The name of the file into which to dump to.

See also: PropertyMap::write(std::ostream&, String::size_type) const

Definition at line 445 of file property_map.cpp.

References FEAT::Dist::Comm::rank(), and write().

◆ write() [2/3]

void FEAT::PropertyMap::write	(	std::ostream &	os,
		String::size_type	indent = `0`
	)		const

Writes the property map into an output stream.

This function writes the whole property map into an output stream, which can be parsed.

Parameters

[in,out]	os	A reference to an output stream to which to write to. It is silently assumed that the output stream is open.
[in]	indent	Specifies the number of indenting whitespaces to be inserted at the beginning of each line.

Note: The indent parameter is used internally for output formatting and does not need to be specified by the caller.

Definition at line 465 of file property_map.cpp.

References _sections, and _values.

◆ write() [3/3]

void FEAT::PropertyMap::write ( String filename ) const

inline

Writes the property map into a file.

This function writes the whole property map into a file, which can be parsed by the read() function.

Parameters

[in] filename The name of the file into which to dump to.

See also: PropertyMap::write(std::ostream&, String::size_type) const

Definition at line 434 of file property_map.hpp.

References FEAT::Dist::Comm::world(), and write().

Referenced by write().

Member Data Documentation

◆ _parent

PropertyMap* FEAT::PropertyMap::_parent

protected

pointer to the parent node

Definition at line 66 of file property_map.hpp.

Referenced by get_parent(), and get_root().

◆ _sections

SectionMap FEAT::PropertyMap::_sections

protected

a map storing the sub-sections

Definition at line 72 of file property_map.hpp.

Referenced by add_section(), begin_section(), end_section(), erase_section(), get_sub_section(), merge(), and write().

◆ _values

EntryMap FEAT::PropertyMap::_values

protected

a map storing the key-value-pairs

Definition at line 69 of file property_map.hpp.

Referenced by add_entry(), begin_entry(), end_entry(), erase_entry(), get_entry(), get_entry_map(), merge(), and write().

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

kernel/util/property_map.hpp
kernel/util/property_map.cpp

Public Types

Public Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ ConstEntryIterator

◆ ConstSectionIterator

◆ EntryIterator

◆ EntryMap

◆ SectionIterator

◆ SectionMap

Constructor & Destructor Documentation

◆ PropertyMap()

◆ ~PropertyMap()

Member Function Documentation

◆ add_entry()

◆ add_section()

◆ begin_entry() [1/2]

◆ begin_entry() [2/2]

◆ begin_section() [1/2]

◆ begin_section() [2/2]

◆ end_entry() [1/2]

◆ end_entry() [2/2]

◆ end_section() [1/2]

◆ end_section() [2/2]

◆ erase_entry()

◆ erase_section()

◆ get_entry()

◆ get_entry_map() [1/2]

◆ get_entry_map() [2/2]

◆ get_parent() [1/2]

◆ get_parent() [2/2]

◆ get_root() [1/2]

◆ get_root() [2/2]

◆ get_sub_section() [1/2]

◆ get_sub_section() [2/2]

◆ merge()

◆ parse_entry()

◆ query() [1/2]

◆ query() [2/2]

◆ query_section() [1/2]

◆ query_section() [2/2]

◆ read() [1/3]

◆ read() [2/3]

◆ read() [3/3]

◆ treeify_structures()

◆ write() [1/3]

◆ write() [2/3]

◆ write() [3/3]

Member Data Documentation

◆ _parent

◆ _sections

◆ _values