This was developed to read the xml dictionary that Maurizio uses for GEMC. More...

#include <EvioXMLDictionary.h>

Public Member Functions
	EvioXMLDictionary (std::string const &path)
	Create an EvioXMLDictionary from an xml file. More...

	EvioXMLDictionary (std::string const &xml, int dummy)
	Create an EvioXMLDictionary from an xml string. More...

void	parseXML (pugi::xml_parse_result &domDocument)
	Create an EvioXMLDictionary from an xml Document object. More...

size_t	size () const
	Get the number of entries in this dictionary. More...

const std::unordered_map < std::string, std::shared_ptr < EvioDictionaryEntry > > &	getMap () const
	Get the map in which the key is the entry name and the value is an object containing its data (tag, num, type, etc.). More...

std::string	getName (std::shared_ptr< BaseStructure > &structure)
	Returns the name of a given evio structure. More...

std::string	getName (uint16_t tag)
	Returns the name associated with the given tag. More...

std::string	getName (uint16_t tag, uint8_t num)
	Returns the name associated with the given tag and num. More...

std::string	getName (uint16_t tag, uint8_t num, uint16_t tagEnd)
	Returns the name associated with the given tag, num, and tagEnd. More...

std::string	getName (uint16_t tag, uint8_t num, uint16_t tagEnd, uint16_t pTag, uint8_t pNum, uint16_t pTagEnd)
	Returns the name associated with the given tag, num, and tagEnd. More...

std::string	getName (uint16_t tag, uint8_t num, uint16_t tagEnd, uint16_t pTag, uint8_t pNum, uint16_t pTagEnd, bool numValid=true, bool parentValid=false, bool parentNumValid=false)
	Returns the name associated with the given tag, num, and tagEnd. More...

std::string	getDescription (uint16_t tag, uint8_t num)
	Returns the description, if any, associated with the given tag and num. More...

std::string	getDescription (uint16_t tag, uint8_t num, uint16_t tagEnd)
	Returns the description, if any, associated with the given tag, num, and tagEnd. More...

std::string	getDescription (std::string const &name)
	Returns the description, if any, associated with the name of a dictionary entry. More...

std::string	getFormat (uint16_t tag, uint8_t num)
	Returns the format, if any, associated with the given tag and num. More...

std::string	getFormat (uint16_t tag, uint8_t num, uint16_t tagEnd)
	Returns the format, if any, associated with the given tag, num, and tagEnd. More...

std::string	getFormat (std::string const &name)
	Returns the format, if any, associated with the name of a dictionary entry. More...

DataType	getType (uint16_t tag, uint8_t num)
	Returns the type, if any, associated with the given tag and num. More...

DataType	getType (uint16_t tag, uint8_t num, uint16_t tagEnd)
	Returns the type, if any, associated with the given tag, num, and tagEnd. More...

DataType	getType (std::string const &name)
	Returns the type, if any, associated with the name of a dictionary entry. More...

bool	getTagNum (std::string const &name, uint16_t tag, uint8_t num, uint16_t *tagEnd)
	Returns the tag/num/tagEnd values, in an Integer object array, corresponding to the name of a dictionary entry. More...

bool	getTag (std::string const &name, uint16_t *tag)
	Returns the tag corresponding to the name of a dictionary entry. More...

bool	getTagEnd (std::string const &name, uint16_t *tagEnd)
	Returns the tagEnd corresponding to the name of a dictionary entry. More...

bool	getNum (std::string const &name, uint8_t *num)
	Returns the num corresponding to the name of a dictionary entry. More...

std::string	toString ()
	Get a string representation of the dictionary. More...

Static Public Member Functions
static const std::string &	NO_NAME_STRING ()
	Get a string used to indicate that no name can be determined. More...

Public Attributes
std::unordered_map < std::shared_ptr < EvioDictionaryEntry > , std::string >	tagNumMap
	This is the heart of the dictionary in which a key is composed of a tag/num pair & other entry data and its corresponding value is a name. More...

std::unordered_map < std::shared_ptr < EvioDictionaryEntry > , std::string >	tagOnlyMap
	Some dictionary entries have only a tag and no num. More...

std::unordered_map < std::shared_ptr < EvioDictionaryEntry > , std::string >	tagRangeMap
	Some dictionary entries have only a tag range and no num. More...

Detailed Description

This was developed to read the xml dictionary that Maurizio uses for GEMC.

An assumption in the following class is that each unique tag/num/tagEnd group corresponds to an equally unique name. In other words, 2 different groups cannot have the same name. And 2 different names cannot map to the same group.

An entry with only a tag value and no num is allowed. It will match a tag/num pair if no exact match exists but the tag matches. For such an entry, no additional existence of type, format, or description is allowed.

Similarly, an entry with a range of tags is also allowed. In this case, no num & type is allowed. It will match a tag/num pair if no exact match exists but the tag is in the range (inclusive).

Author: heddle; timmer

Constructor & Destructor Documentation

evio::EvioXMLDictionary::EvioXMLDictionary ( std::string const & path )

explicit

Create an EvioXMLDictionary from an xml file.

Parameters

path	file containing xml.

References parseXML(), tagNumMap, tagOnlyMap, and tagRangeMap.

evio::EvioXMLDictionary::EvioXMLDictionary	(	std::string const &	xml,
		int	dummy
	)

Create an EvioXMLDictionary from an xml string.

Parameters

xml	string containing xml.
dummy	here only to differentiate from other constructor, value unused.

References parseXML(), tagNumMap, tagOnlyMap, and tagRangeMap.

Member Function Documentation

std::string evio::EvioXMLDictionary::getDescription	(	uint16_t	tag,
		uint8_t	num
	)

Returns the description, if any, associated with the given tag and num.

Parameters

tag	to find the description of
num	to find the description of

Returns: description or null if none found

std::string evio::EvioXMLDictionary::getDescription	(	uint16_t	tag,
		uint8_t	num,
		uint16_t	tagEnd
	)

Returns the description, if any, associated with the given tag, num, and tagEnd.

Parameters

tag	to find the description of
num	to find the description of
tagEnd	to find the description of

Returns: description or empty string if none found

std::string evio::EvioXMLDictionary::getDescription ( std::string const & name )

Returns the description, if any, associated with the name of a dictionary entry.

Parameters

name	dictionary name

Returns: description; empty string if name or is unknown or no description is associated with it

std::string evio::EvioXMLDictionary::getFormat	(	uint16_t	tag,
		uint8_t	num
	)

Returns the format, if any, associated with the given tag and num.

Parameters

tag	to find the format of
num	to find the format of

Returns: the format or null if none found

std::string evio::EvioXMLDictionary::getFormat	(	uint16_t	tag,
		uint8_t	num,
		uint16_t	tagEnd
	)

Returns the format, if any, associated with the given tag, num, and tagEnd.

Parameters

tag	to find the format of
num	to find the format of
tagEnd	to find the format of

Returns: format or null if none found

std::string evio::EvioXMLDictionary::getFormat ( std::string const & name )

Returns the format, if any, associated with the name of a dictionary entry.

Parameters

name	dictionary name

Returns: format; null if name or is unknown or no format is associated with it

const std::unordered_map< std::string, std::shared_ptr< EvioDictionaryEntry > > & evio::EvioXMLDictionary::getMap ( ) const

Get the map in which the key is the entry name and the value is an object containing its data (tag, num, type, etc.).

Returns: map in which the key is the entry name and the value is an object containing its data (tag, num, type, etc.).

std::string evio::EvioXMLDictionary::getName ( std::shared_ptr< BaseStructure > & structure )

Returns the name of a given evio structure.

This is the method used in BaseStructure.toString() to assign a dictionary entry to a particular evio structure.

Parameters

structure the structure to find the name of.

Returns: a descriptive name or ??? if none found

References evio::DataType::getDataType(), evio::DataType::isBank(), and NO_NAME_STRING().

Referenced by evio::StructureFinder::getMatchingChild(), evio::StructureFinder::getMatchingParent(), evio::StructureFinder::getMatchingStructures(), and getName().

std::string evio::EvioXMLDictionary::getName ( uint16_t tag )

Returns the name associated with the given tag.

A search is made for an entry of a tag only. If nothing found, ??? is returned.

Parameters

tag	tag of dictionary entry to find

Returns: descriptive name or ??? if none found

References getName().

std::string evio::EvioXMLDictionary::getName	(	uint16_t	tag,
		uint8_t	num
	)

Returns the name associated with the given tag and num.

A search is made for:

an entry of a tag/num pair. If that fails,
an entry of a tag only.

Argument values which have no match result in "???" being returned.

Parameters

tag	tag of dictionary entry to find
num	num of dictionary entry to find

Returns: descriptive name or ??? if none found

References getName().

std::string evio::EvioXMLDictionary::getName	(	uint16_t	tag,
		uint8_t	num,
		uint16_t	tagEnd
	)

Returns the name associated with the given tag, num, and tagEnd.

A search is made for:

an entry of a tag/num pair. If that fails,
an entry of a tag only. If that fails,
an entry of a tag range.

If a valid tag range is given (different valid tag and tagEnd with no num), a search is made for an entry of a tag range. Note: tag and tagEnd being the same value or tagEnd being 0 mean that no range is defined - it's equivalent to only specifying a tag.

Argument values which have no match result in "???" being returned.

Parameters

tag	tag of dictionary entry to find
num	num of dictionary entry to find
tagEnd	tagEnd of dictionary entry to find

Returns: descriptive name or ??? if none found

References getName().

std::string evio::EvioXMLDictionary::getName	(	uint16_t	tag,
		uint8_t	num,
		uint16_t	tagEnd,
		uint16_t	pTag,
		uint8_t	pNum,
		uint16_t	pTagEnd
	)

Returns the name associated with the given tag, num, and tagEnd.

If a valid tag and num are given (>= 0) a search is made for:

an entry of a tag/num pair. If that fails,
an entry of a tag only. If that fails,
an entry of a tag range.

If a valid tag range is given (different valid tag and tagEnd with no num), a search is made for an entry of a tag range. Note: tag and tagEnd being the same value or tagEnd being 0 mean that no range is defined - it's equivalent to only specifying a tag.

Argument values which have no match result in "???" being returned.

Things are actually more complicated due to parent structures. Duplicate entries (same tag, num, and tagEnd) are permitted only as long their parent entries are different. Say, for example, that this dictionary is defined as follows:

     <bank name="B1" tag="1" num="1" >
          <bank name="sub1" tag="5" num="5" />
          <bank name="sub2" tag="5" num="5" />
          <leaf name="tagNum"   tag="10" num="10" />
          <leaf name="tagOnly"  tag="20" />
          <leaf name="tagRange" tag="30-40" />
     </bank>
     <bank name="B2" tag="2" num="2" >
          <leaf name="tagNum"   tag="10" num="10" />
          <leaf name="tagOnly"  tag="20" />
          <leaf name="tagRange" tag="30-40" />
     </bank>

You can see that the leaf entries under bank "B1" are identical to those under "B2". This is permitted since B1 and B2 have different tag & num values so there is a way to tell the difference between the 2 instances of tagNum, tagOnly and tagRange.

It is not possible to specify parents using the "dictEntry" XML element and consequently duplicates are not allowed if using this form of dictionary definition. Think of things like this: no parents = no duplicates.

Parameters

tag	tag of dictionary entry to find
num	num of dictionary entry to find
tagEnd	tagEnd of dictionary entry to find
pTag	tag of dictionary entry's parent
pNum	num of dictionary entry's parent
pTagEnd	tagEnd of dictionary entry's parent

Returns: descriptive name or "???" if none found

References getName().

std::string evio::EvioXMLDictionary::getName	(	uint16_t	tag,
		uint8_t	num,
		uint16_t	tagEnd,
		uint16_t	pTag,
		uint8_t	pNum,
		uint16_t	pTagEnd,
		bool	numValid = `true`,
		bool	parentValid = `false`,
		bool	parentNumValid = `false`
	)

Returns the name associated with the given tag, num, and tagEnd.

If a valid tag and num are given (>= 0) a search is made for:

an entry of a tag/num pair. If that fails,
an entry of a tag only. If that fails,
an entry of a tag range.

If only a valid tag is given, a search is made for:

an entry of a tag only. If that fails,
an entry of a tag range.

If a valid tag range is given (different valid tag and tagEnd with no num), a search is made for an entry of a tag range. Note: tag and tagEnd being the same value or tagEnd being 0 mean that no range is defined - it's equivalent to only specifying a tag.

Argument values which have no match result in "???" being returned.

Things are actually more complicated due to parent structures. Duplicate entries (same tag, num, and tagEnd) are permitted only as long their parent entries are different. Say, for example, that this dictionary is defined as follows:

     <bank name="B1" tag="1" num="1" >
          <bank name="sub1" tag="5" num="5" />
          <bank name="sub2" tag="5" num="5" />
          <leaf name="tagNum"   tag="10" num="10" />
          <leaf name="tagOnly"  tag="20" />
          <leaf name="tagRange" tag="30-40" />
     </bank>
     <bank name="B2" tag="2" num="2" >
          <leaf name="tagNum"   tag="10" num="10" />
          <leaf name="tagOnly"  tag="20" />
          <leaf name="tagRange" tag="30-40" />
     </bank>

You can see that the leaf entries under bank "B1" are identical to those under "B2". This is permitted since B1 and B2 have different tag & num values so there is a way to tell the difference between the 2 instances of tagNum, tagOnly and tagRange.

It is not possible to specify parents using the "dictEntry" XML element and consequently duplicates are not allowed if using this form of dictionary definition. Think of things like this: no parents = no duplicates.

Parameters

tag	tag of dictionary entry to find
num	num of dictionary entry to find
tagEnd	tagEnd of dictionary entry to find
pTag	tag of dictionary entry's parent
pNum	num of dictionary entry's parent
pTagEnd	tagEnd of dictionary entry's parent
numValid	is num being used?
parentValid	is parent being used?
parentNumValid	if parent is being used, is its num also being used?

Returns: descriptive name or "???" if none found

References getName(), and evio::DataType::UNKNOWN32.

bool evio::EvioXMLDictionary::getNum	(	std::string const &	name,
		uint8_t *	num
	)

Returns the num corresponding to the name of a dictionary entry.

Parameters

name	dictionary name.
num	pointer which gets filled with entry's num value.

Returns: true if entry found, else false.

bool evio::EvioXMLDictionary::getTag	(	std::string const &	name,
		uint16_t *	tag
	)

Returns the tag corresponding to the name of a dictionary entry.

Parameters

name	dictionary name
tag	pointer which gets filled with tag value.

Returns: true if entry found, else false.

bool evio::EvioXMLDictionary::getTagEnd	(	std::string const &	name,
		uint16_t *	tagEnd
	)

Returns the tagEnd corresponding to the name of a dictionary entry.

Parameters

name	dictionary name
tagEnd	pointer which gets filled with tagEnd value.

Returns: true if entry found, else false.

bool evio::EvioXMLDictionary::getTagNum	(	std::string const &	name,
		uint16_t *	tag,
		uint8_t *	num,
		uint16_t *	tagEnd
	)

Returns the tag/num/tagEnd values, in an Integer object array, corresponding to the name of a dictionary entry.

If there is an exact match with a tag and num pair, it is returned (last element is null). If not, but there is a match with a tag-only entry, that is returned (last 2 elements are null). If no tag-only match exits, but there is a match with a tag range, that is returned (i.e. second element, the num, is null).

Since: 5.2 now returns 3 Integer objects instead of 2 ints (tag, num) as in previous versions.

Parameters

name	dictionary name
tag	pointer which gets filled with tag value.
num	pointer which gets filled with num value.
tagEnd	pointer which gets filled with tagEnd value.

Returns: true if entry found, else false.

DataType evio::EvioXMLDictionary::getType	(	uint16_t	tag,
		uint8_t	num
	)

Returns the type, if any, associated with the given tag and num.

Parameters

tag	to find the type of
num	to find the type of

Returns: type or null if none found

DataType evio::EvioXMLDictionary::getType	(	uint16_t	tag,
		uint8_t	num,
		uint16_t	tagEnd
	)

Returns the type, if any, associated with the given tag, num, and tagEnd.

Parameters

tag	to find the type of.
num	to find the type of.
tagEnd	to find the type of.

Returns: type or DataType::NOT_A_VALID_TYPE if none found.

References evio::DataType::NOT_A_VALID_TYPE.

DataType evio::EvioXMLDictionary::getType ( std::string const & name )

Returns the type, if any, associated with the name of a dictionary entry.

Parameters

name	dictionary name.

Returns: type; DataType::NOT_A_VALID_TYPE if name or is unknown or no type is associated with it.

References evio::DataType::NOT_A_VALID_TYPE.

const std::string & evio::EvioXMLDictionary::NO_NAME_STRING ( )

static

Get a string used to indicate that no name can be determined.

Returns: string used to indicate that no name can be determined.

References evio::Util::NO_NAME_STRING().

Referenced by getName().

void evio::EvioXMLDictionary::parseXML ( pugi::xml_parse_result & domDocument )

Create an EvioXMLDictionary from an xml Document object.

Parameters

domDocument DOM object representing xml dictionary.

Exceptions

EvioException if parsing error.

References evio::Util::getDataType(), evio::Util::iStrEquals(), evio::DataType::NOT_A_VALID_TYPE, tagNumMap, tagOnlyMap, tagRangeMap, evio::DataType::UNKNOWN32, and evio::DataType::valueOf().

Referenced by EvioXMLDictionary().

size_t evio::EvioXMLDictionary::size ( ) const

Get the number of entries in this dictionary.

Returns: number of entries in this dictionary.

References tagNumMap.

std::string evio::EvioXMLDictionary::toString ( )

Get a string representation of the dictionary.

Returns: a string representation of the dictionary.

Member Data Documentation

std::unordered_map<std::shared_ptr<EvioDictionaryEntry>, std::string> evio::EvioXMLDictionary::tagNumMap

This is the heart of the dictionary in which a key is composed of a tag/num pair & other entry data and its corresponding value is a name.

Using a map ensures entries are unique.

Since: 4.0

Referenced by EvioXMLDictionary(), parseXML(), and size().

std::unordered_map<std::shared_ptr<EvioDictionaryEntry>, std::string> evio::EvioXMLDictionary::tagOnlyMap

Some dictionary entries have only a tag and no num.

It matches a tag/num pair if there is no exact match in tagNumMap, but does match a tag in this map.

Since: 4.1

Referenced by EvioXMLDictionary(), and parseXML().

std::unordered_map<std::shared_ptr<EvioDictionaryEntry>, std::string> evio::EvioXMLDictionary::tagRangeMap

Some dictionary entries have only a tag range and no num.

It matches a tag/num pair if there is no exact match in tagNumMap or in the tagOnlyMap but the tag is within the specified range of an entry.

Since: 5.2

Referenced by EvioXMLDictionary(), and parseXML().

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

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation