This class forms a mapping tree to store all kinds of properties (path : value), where:

value is:
- a util::PropertyValue-container holding the value of the property (this may be empty/unset)
- another PropertyMap containing a subtree (a branch of the mapping tree)
path is one or more case insensitive key names separated by "/" to locate both, branches or properties, in the tree.

#include <propmap.hpp>

Inheritance diagram for isis::util::PropertyMap:

Data Structures
struct	invalidP
	true when entry is a leaf, needed and empty
struct	listP
	true when entry is not a scalar
class	NeededsList
struct	PropPath
	"Path" type used to locate entries in the tree More...
struct	treeInvalidP
	true when entry is a leaf, needed and empty of entry is a invalid branch
struct	trueP
	allways true
struct	walkTree
Public Types
typedef std::map< KeyType, std::pair< PropertyValue, PropertyValue >, key_compare >	DiffMap
	a flat map matching keys to pairs of values
typedef std::map< KeyType, PropertyValue >	FlatMap
	a flat map, matching complete paths as keys to the corresponding values
typedef std::set< KeyType, key_compare >	KeyList
	a list to store keys only (without the corresponding values)
typedef key_type	KeyType
	type of the keys forming a path
Public Member Functions
PropertyMap &	branch (const PropPath &path)
	Access the branch referenced by the path, create it if its not there.
const PropertyMap &	branch (const PropPath &path) const
	Access the branch referenced by the path.
KeyType	find (KeyType key, bool allowProperty=true, bool allowBranch=false) const
	Search for a property/branch in the whole Tree.
KeyList	findLists () const
	find all non scalar entries
DiffMap	getDifference (const PropertyMap &second) const
	Get a difference map of this tree and another.
FlatMap	getFlatMap () const
const KeyList	getKeys () const
	Get a list of the paths of all properties.
const KeyList	getMissing () const
	Get a list of missing properties.
template<typename T >
T	getPropertyAs (const PropPath &path) const
	Request a property via the given key in the given type.
bool	hasBranch (const PropPath &path) const
	check if branch of the tree is available
bool	hasProperty (const PropPath &path) const
	check if a property is available
bool	isEmpty () const
bool	isValid () const
	Check if every property marked as needed is set.
PropertyMap::KeyList	join (const PropertyMap &other, bool overwrite=false)
	Add Properties from another tree.
bool	operator== (const PropertyMap &src) const
std::ostream &	print (std::ostream &out, bool label=false) const
	"Print" the property tree.
	PropertyMap ()
	PropertyMap (const Container &src)
const PropertyValue &	propertyValue (const PropPath &path) const
	Access the property referenced by the path.
PropertyValue &	propertyValue (const PropPath &path)
	Access the property referenced by the path, create it if its not there.
bool	remove (const PropertyMap &removeMap, bool keep_needed=false)
	remove every property which is also in the given tree (regardless of the value)
bool	remove (const PropPath &path)
	Remove the property adressed by the path.
bool	remove (const KeyList &removeList, bool keep_needed=false)
	remove every property which is also in the given list (regardless of the value)
bool	rename (const PropPath &from, const PropPath &to)
	Rename a given property/branch.
template<typename T >
PropertyValue &	setPropertyAs (const PropPath &path, const T &val)
	Set the given property to a given value/type.
bool	transform (const PropPath &from, const PropPath &to, int dstID, bool delSource=true)
	Transform an existing property into another.
template<typename DST >
bool	transform (const PropPath &from, const PropPath &to, bool delSource=true)
	Transform an existing property into another (statically typed version).
Protected Member Functions
void	addNeeded (const PropPath &path)
	Adds a property with status needed.
template<class Predicate >
const KeyList	genKeyList () const
	create a list of keys for every entry for which the given scalar predicate is true.
void	makeFlatMap (FlatMap &out, KeyType key_prefix="") const
	copy the tree into a flat key/property-map
std::vector< PropertyValue > &	propertyValueVec (const PropPath &path)
	Access the property vector referenced by the path-key, create it if its not there.
const std::vector < PropertyValue > &	propertyValueVec (const PropPath &path) const
	Access the property vector referenced by the path.
void	removeEqual (const PropertyMap &other, bool removeNeeded=false)
	Remove every PropertyValue which is also in the other PropertyMap and where operator== returns true.
void	toCommonUnique (PropertyMap &common, std::set< KeyType > &uniques, bool init) const
	Get common and unique properties from the tree.

Detailed Description

This class forms a mapping tree to store all kinds of properties (path : value), where:

value is:
- a util::PropertyValue-container holding the value of the property (this may be empty/unset)
- another PropertyMap containing a subtree (a branch of the mapping tree)
path is one or more case insensitive key names separated by "/" to locate both, branches or properties, in the tree.

Nevertheless there are separate access functions for branches and properties. Trying to access a branch as a property value,or to access a property value as a branch will cause error messages and give empty results.

Paths can be created from other paths and from strings (c-strings and util::istring, but not std::string). So both can be used for functions which expect paths, but the usage of c-strings is slower.

To describe the minimum of needed metadata needed by specific data structures / subclasses properties can be marked as "needed" and there are functions to verify that they are not empty.

Definition at line 52 of file propmap.hpp.

Member Typedef Documentation

typedef std::map<KeyType, std::pair<PropertyValue, PropertyValue>, key_compare> isis::util::PropertyMap::DiffMap

a flat map matching keys to pairs of values

Definition at line 60 of file propmap.hpp.

typedef std::map<KeyType, PropertyValue> isis::util::PropertyMap::FlatMap

a flat map, matching complete paths as keys to the corresponding values

Definition at line 62 of file propmap.hpp.

typedef std::set<KeyType, key_compare> isis::util::PropertyMap::KeyList

a list to store keys only (without the corresponding values)

Definition at line 58 of file propmap.hpp.

typedef key_type isis::util::PropertyMap::KeyType

type of the keys forming a path

Definition at line 56 of file propmap.hpp.

Constructor & Destructor Documentation

API_EXCLUDE_BEGIN _internal API_EXCLUDE_END isis::util::PropertyMap::PropertyMap ( const Container & src )

Definition at line 58 of file propmap.cpp.

isis::util::PropertyMap::PropertyMap ( )

Definition at line 66 of file propmap.cpp.

Member Function Documentation

void isis::util::PropertyMap::addNeeded ( const PropPath & path ) [protected]

Adds a property with status needed.

Parameters:

path	identifies the property to be added or if already existsing to be flagged as needed

Definition at line 492 of file propmap.cpp.

PropertyMap & isis::util::PropertyMap::branch ( const PropPath & path )

Access the branch referenced by the path, create it if its not there.

Parameters:

path	the path to the branch

Returns:: a reference to the branching PropertyMap

Definition at line 209 of file propmap.cpp.

const PropertyMap & isis::util::PropertyMap::branch ( const PropPath & path ) const

Access the branch referenced by the path.

If the branch does not exist, an empty dummy will returned.

Parameters:

path	the path to the branch

Returns:: a reference to the branching PropertyMap

Definition at line 196 of file propmap.cpp.

PropertyMap::KeyType isis::util::PropertyMap::find	(	PropertyMap::KeyType	key,
		bool	allowProperty = `true`,
		bool	allowBranch = `false`
	)		const

Search for a property/branch in the whole Tree.

Parameters:

key	the single key for the branch/property to search for (paths will be stripped to the rightmost key)
allowProperty	if false the search will ignore properties
allowBranch	if false the search will ignore branches (it will still search into the branches, but the branches themself won't be considered a valid finding)

Returns:: full path to the property (including the properties name) if it is found, empty string elsewhise

Definition at line 504 of file propmap.cpp.

PropertyMap::KeyList isis::util::PropertyMap::findLists ( ) const

find all non scalar entries

Definition at line 476 of file propmap.cpp.

template<class Predicate >

const KeyList isis::util::PropertyMap::genKeyList ( ) const [inline, protected]

create a list of keys for every entry for which the given scalar predicate is true.

Definition at line 130 of file propmap.hpp.

PropertyMap::DiffMap isis::util::PropertyMap::getDifference ( const PropertyMap & second ) const

Get a difference map of this tree and another.

Out of the names of differing properties a mapping from paths to std::pair<PropertyValue,PropertyValue> is created with following rules:

if a Property is empty in this tree but set in second,
- it will be added with the first PropertyValue emtpy and the second PropertyValue taken from second
if a Property is set in this tree but empty in second,
- it will be added with the first PropertyValue taken from this and the second PropertyValue empty
if a Property is set in both, but not equal,
- it will be added with the first PropertyValue taken from this and the second PropertyValue taken from second
if a Property is set in both and equal, or is empty in both,
- it wont be added
  Parameters:
  
  second the other tree to compare with
  
  Returns:
  a map of property paths and pairs of the corresponding different values

Definition at line 280 of file propmap.cpp.

PropertyMap::FlatMap isis::util::PropertyMap::getFlatMap ( ) const

Returns:: a flat representation of the whole property tree

Definition at line 433 of file propmap.cpp.

const PropertyMap::KeyList isis::util::PropertyMap::getKeys ( ) const

Get a list of the paths of all properties.

Returns:: a flat list of the paths to all properties in the PropertyMap

Definition at line 469 of file propmap.cpp.

const PropertyMap::KeyList isis::util::PropertyMap::getMissing ( ) const

Get a list of missing properties.

Returns:: a list of the paths for all properties which are marked as needed and but are empty.

Definition at line 484 of file propmap.cpp.

template<typename T >

T isis::util::PropertyMap::getPropertyAs ( const PropPath & path ) const

Request a property via the given key in the given type.

If the requested type is not equal to type the property is stored with, an automatic conversion is done. If that conversion failes an error is send to Runtime.

 getPropertyAs<fvector4>( "MyPropertyName" );

Parameters:

path	the path to the property

Returns:: the property with given type, if not set yet T() is returned.

Definition at line 514 of file propmap.hpp.

bool isis::util::PropertyMap::hasBranch ( const PropPath & path ) const

check if branch of the tree is available

Parameters:

path	the path to the branch

Returns:: true if the given branch does exist and is not empty, false otherwise

Definition at line 538 of file propmap.cpp.

bool isis::util::PropertyMap::hasProperty ( const PropPath & path ) const

check if a property is available

Parameters:

path	the path to the property

Returns:: true if the given property does exist and is not empty, false otherwise

Definition at line 498 of file propmap.cpp.

bool isis::util::PropertyMap::isEmpty ( ) const

Returns:: true if the PropertyMap is empty, false otherwhise

Reimplemented in isis::data::Image.

Definition at line 275 of file propmap.cpp.

bool isis::util::PropertyMap::isValid ( ) const

Check if every property marked as needed is set.

Returns:: true if ALL needed properties are NOT empty, false otherwhise.

Definition at line 268 of file propmap.cpp.

PropertyMap::KeyList isis::util::PropertyMap::join	(	const PropertyMap &	other,
		bool	overwrite = `false`
	)

Add Properties from another tree.

Parameters:

other	the other tree to join with
overwrite	if existing properties shall be replaced

Returns:: a list of the rejected properties that couldn't be inserted, for success this should be empty

Definition at line 383 of file propmap.cpp.

void isis::util::PropertyMap::makeFlatMap	(	FlatMap &	out,
		KeyType	key_prefix = `""`
	)		const `[protected]`

copy the tree into a flat key/property-map

Definition at line 420 of file propmap.cpp.

bool isis::util::PropertyMap::operator== ( const PropertyMap & src ) const

Definition at line 60 of file propmap.cpp.

std::ostream & isis::util::PropertyMap::print	(	std::ostream &	out,
		bool	label = `false`
	)		const

"Print" the property tree.

Will send the name and the result of PropertyValue->toString(label) to the given ostream. Is equivalent to common streaming operation but has the option to print the type of the printed properties.

Parameters:

out	the output stream to use
label	print the type of the property (see Value::toString())

Definition at line 577 of file propmap.cpp.

const PropertyValue & isis::util::PropertyMap::propertyValue ( const PropPath & path ) const

Access the property referenced by the path.

If the property does not exist, an empty dummy will returned.

Parameters:

path	the path to the property

Returns:: a reference to the PropertyValue

Definition at line 184 of file propmap.cpp.

PropertyValue & isis::util::PropertyMap::propertyValue ( const PropPath & path )

Access the property referenced by the path, create it if its not there.

Parameters:

path	the path to the property

Returns:: a reference to the PropertyValue

Definition at line 189 of file propmap.cpp.

const std::vector< PropertyValue > & isis::util::PropertyMap::propertyValueVec ( const PropPath & path ) const [protected]

Access the property vector referenced by the path.

If the property does not exist, an empty dummy will be returned.

Parameters:

path	the path to the property

Returns:: a reference to the PropertyValue

Definition at line 163 of file propmap.cpp.

std::vector< PropertyValue > & isis::util::PropertyMap::propertyValueVec ( const PropPath & path ) [protected]

Access the property vector referenced by the path-key, create it if its not there.

Parameters:

path	the path to the property

Returns:: a reference to the PropertyValue

Definition at line 176 of file propmap.cpp.

bool isis::util::PropertyMap::remove ( const PropPath & path )

Remove the property adressed by the path.

This actually only removes properties. Non-empty branches are not deleted. And if an branch becomes empty after deletion of its last entry, it is deleted automatically.

Parameters:

path	the path to the property

Returns:: true if successful, false otherwise

Definition at line 215 of file propmap.cpp.

bool isis::util::PropertyMap::remove	(	const KeyList &	removeList,
		bool	keep_needed = `false`
	)

remove every property which is also in the given list (regardless of the value)

Parameters:

removeList	a list of paths naming the properties to be removed
keep_needed	when true needed properties are kept even if they would be removed otherwise

Returns:: true if all properties removed succesfully, false otherwise

Definition at line 220 of file propmap.cpp.

bool isis::util::PropertyMap::remove	(	const PropertyMap &	removeMap,
		bool	keep_needed = `false`
	)

remove every property which is also in the given tree (regardless of the value)

Parameters:

removeMap	the tree of properties to be removed
keep_needed	when true needed properties are kept even if they would be removed otherwise

Returns:: true if all properties removed succesfully, false otherwise

Definition at line 234 of file propmap.cpp.

void isis::util::PropertyMap::removeEqual	(	const PropertyMap &	other,
		bool	removeNeeded = `false`
	)		`[protected]`

Remove every PropertyValue which is also in the other PropertyMap and where operator== returns true.

Parameters:

other	the other property tree to compare to
removeNeeded	if a property should also be deleted it is needed

Definition at line 344 of file propmap.cpp.

bool isis::util::PropertyMap::rename	(	const PropPath &	from,
		const PropPath &	to
	)

Rename a given property/branch.

This is implemented as copy+delete and can also be used between branches.

if the target exist a warning will be send, but it will still be overwritten
if the source does not exist a warning will be send and nothing is done
Parameters:

from the path of the existing property to be moved

to the destinaton path of the move

Returns:
true if renaming/moving was successful

Definition at line 544 of file propmap.cpp.

template<typename T >

PropertyValue& isis::util::PropertyMap::setPropertyAs	(	const PropPath &	path,
		const T &	val
	)		`[inline]`

Set the given property to a given value/type.

The needed flag (if set) will be kept. If the property is already set to a value of another type an error is send to Runtime and nothing will be set. But a property of the same type will be overwritten.

 setPropertyAs("MyPropertyName", isis::util::fvector4(1,0,1,0))

Parameters:

path	the path to the property
val	the value to set of type T

Returns:: a reference to the PropertyValue (this can be used later, e.g. if a vector is filled step by step the reference can be used to not ask for the Property each time)

Definition at line 364 of file propmap.hpp.

void isis::util::PropertyMap::toCommonUnique	(	PropertyMap &	common,
		std::set< KeyType > &	uniques,
		bool	init
	)		const `[protected]`

Get common and unique properties from the tree.

For every entry of the tree this checks if it is common/unique and removes/adds it accordingly. This is done by:

generating a difference (using diff) between the current common and the tree
- the resulting diff_map contains all newly unique properties (properties which has been in common, but are not euqual in the tree)
these newly diffent properties are removed from common and added to unique.
if init is true uniques is cleared and common is replaced by a copy of the tree (shall be done at first step)
Parameters:

common reference of the common-tree

uniques reference of the unique-tree

init if initialisation shall be done instead of normal seperation

Definition at line 561 of file propmap.cpp.

bool isis::util::PropertyMap::transform	(	const PropPath &	from,
		const PropPath &	to,
		int	dstID,
		bool	delSource = `true`
	)

Transform an existing property into another.

Converts the value of the given property into the requested type and stores it with the given new path.

Parameters:

from	the path of the property to be transformed
to	the path for the new property
dstID	the type-ID of the new property value
delSource	if the original property shall be deleted after the tramsformation was done

Returns:: true if the transformation was done, false it failed

Definition at line 441 of file propmap.cpp.

template<typename DST >

bool isis::util::PropertyMap::transform	(	const PropPath &	from,
		const PropPath &	to,
		bool	delSource = `true`
	)		`[inline]`

Transform an existing property into another (statically typed version).

Converts the value of the given property into the requested type and stores it with the given new path. A compile-time check is done to test if the requested type is available.

Parameters:

from	the path of the property to be transformed
to	the path for the new property
delSource	if the original property shall be deleted after the tramsformation was done

Returns:: true if the transformation was done, false it failed

Definition at line 342 of file propmap.hpp.

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

/scr/tee1/isis/lib/Core/CoreUtils/propmap.hpp
/scr/tee1/isis/lib/Core/CoreUtils/propmap.cpp

from	the path of the existing property to be moved
to	the destinaton path of the move

common	reference of the common-tree
uniques	reference of the unique-tree
init	if initialisation shall be done instead of normal seperation

isis::util::PropertyMap Class Reference

Data Structures

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation