mspass::utility::AttributeMap Class Reference

An object to map internal and external attribute names. More...

#include <AttributeMap.h>

Public Member Functions
	AttributeMap ()
	Default constructor. The default assumes the css3.0 schema and will load the name definitions defined for that schema.
	AttributeMap (const std::string tag)
	Create mapping for a specified namespace tag (usually a schema name). More...
	AttributeMap (const AttributeMap &am0)
AttributeMap &	operator= (const AttributeMap &am0)
AttributeProperties	operator[] (const std::string key) const
AttributeProperties	operator[] (const char *key) const
std::map< std::string, AttributeProperties >	aliases (const std::string key) const
std::map< std::string, AttributeProperties >	aliases (const char *key) const
std::list< std::string >	aliastables (const std::string key) const
std::list< std::string >	aliastables (const char *key) const
bool	is_alias (const std::string key) const
bool	is_alias (const char *key) const

Public Attributes
std::map< std::string, AttributeProperties >	attributes
	Maps internal to external names. This object is little more than a wrapper around this Standard Template library map container. The map is keyed by the internal name used to for a particular parameter. Each internal name known to the object will have an AttributeProperties associated with it through this map (same as an associative array for perl and tcl geeks). The user will need to be familiar with the STL map container to deal with this object correctly. I made an intentional design decision to not hide this beast behind the interface because the STL has become a standardized component of C++. I took the attitude that STL would outlast my interface definition and cost of hiding this was too high in computational burden. The key thing a user must know is the proper way to retrieve an element from a map and handle the possibility that the requested item is not known to the map. Consult the web or the source code for libMsPASS if you don't know how to do this.

Detailed Description

An object to map internal and external attribute names.

This object is used to link a set of internally defined parameters tagged with a name to an external name convention. The working model for external names is attribute names defined in a relational database schema, but the concept involved is more general. That is, the intent of this interface is a general way to between one set of parameter names and another. This could be used, for example, to map between header variable names in SEGY or SAC and some internal name convention. The relation of the map defined by this object is implicitly assumed to be one-to-one because of the use of the STL map to define the relationship. Because the map is keyed by the internal name lookup is also intended only for finding the external names associated with a particular internal parameter. The primary use of this object in the MsPASS library is to define a global mapping operator for a particular database schema. That is, the most common construct is to build this object early on using a call like: AttributeMap("css3.0").

Constructor & Destructor Documentation

AttributeMap() [1/2]

mspass::utility::AttributeMap::AttributeMap

(

const std::string

tag

)

Create mapping for a specified namespace tag (usually a schema name).

This is the normal constructor for this object. A one word tag is used to define a particular title to a namespace mapping. Normally this is a database schema name like css3.0 or Trace4.0, but the interface allows it to be anything. For example, although it isn't currently defined one could easily create a "SacHeader" definition that defined mapping between SAC header fields and an internal name convention. The interface simply assumes this keyword can be used to establish a mechanism for creating this beast through an unspecified mechanism. i.e. the interface is blind to the details and assumes what you want is to know how to map between A and B and someone else worried about the format for doing this already. In the current implementation we use an Antelope parameter file to create this object, but this interface does not depend upon that choice.

Parameters

tag	name tag used to define this map (usually a schema name).

AttributeMap() [2/2]

mspass::utility::AttributeMap::AttributeMap

(

const AttributeMap &

am0

)

Standard copy constructor.

{
    attributes = am.attributes;
    aliasmap=am.aliasmap;
}

References attributes.

Member Function Documentation

aliases() [1/2]

map< string, AttributeProperties > mspass::utility::AttributeMap::aliases

(

const char *

key

)

const

Overload for literals.

{
    try{
        return this->aliases(string(key));
    }catch(...){throw;};
}

aliases() [2/2]

std::map<std::string,AttributeProperties> mspass::utility::AttributeMap::aliases

(

const std::string

key

)

const

Returns a list of aliases for a key.

A universal issue in a relational database interface is that an attribute can occur in more than one table. One can give a fully qualified name through this interface, but it is often convenient to have a simple name (the alias) that is a shorthand for a particular instance of that attribute in one table. Further, it is sometimes useful to have a list of possible meanings for an alias that can be searched in order. Thus this method returns a list of AttributeProperties that are tied to an alias. The idea would be that the caller would try each member of this list in order before throwing an error.

Parameters

alias

is the alias name to search.

Returns

STL map of AttributeProperties that are aliases for the given keyword. The map is keyed by the table name. This provides a clean interface for output of attributes as it allows an output function to use an alias efficiently. The assumption in all cases is that the alias name provides the unique tag or an attribute. An application must avoid modifying attributes that are part of the alias definition. The alias name is the only one that should normally be assumed current.

Exceptions

MsPASSError

is thrown if an attribute listed in aliases is not defined for the AttributeMap itself. This always indicates an error in the definition of the AttributeMap.

aliastables() [1/2]

list< string > mspass::utility::AttributeMap::aliastables

(

const char *

key

)

const

Overload for literals

{
    try{
        return this->aliastables(string(key));
    }catch(...){throw;};
}

aliastables() [2/2]

std::list<std::string> mspass::utility::AttributeMap::aliastables

(

const std::string

key

)

const

Returns an ordered list of table names to try in extracting an alias named.

Aliases present an issue on input. Because many attribute names appear in multiple tables (an essential thing, in fact, for a relational database to work) input of an attribute that is a generic label for such an attribute can be problematic. This method returns an ordered list of tables that provide guidance for extracting an attribute defined by such a generic name. The order is very important as readers will generally need to try qualfied names for each table in the list returned by this method. Hence the order matters and the list should be inclusive but no longer than necessary as long lists could generate some overead problems in some situations.

Parameters

key	is the alias name for which this information is desired.

Returns

list of table names in a recommended order of access.

Exceptions

MsPASSError

will be thrown if there are inconsistencies

is_alias() [1/2]

bool mspass::utility::AttributeMap::is_alias

(

const char *

key

)

const

Overloaded for string literal.

{
    return this->is_alias(string(key));
}

is_alias() [2/2]

bool mspass::utility::AttributeMap::is_alias

(

const std::string

key

)

const

Check if an attribute name is an alias.

For efficiency and convience it is useful to have a simple way to ask if an attribute name is defined as an alias. This abstracts this process.

Parameters

key	is the attribute name to be tested.

Returns

true if key is an alias. Otherwise return false.

operator=()

AttributeMap & mspass::utility::AttributeMap::operator=

(

const AttributeMap &

am0

)

Standard assignment operator.

{
    if(this!=&am)
    {
        attributes = am.attributes;
        aliasmap=am.aliasmap;
    }
    return (*this);
}

References attributes.

operator[]() [1/2]

AttributeProperties mspass::utility::AttributeMap::operator[]

(

const char *

key

)

const

Overloaded operator for C strings constants.

{
    try{
        return this->operator[](string(key));
    }catch(...){throw;};
}

operator[]() [2/2]

AttributeProperties mspass::utility::AttributeMap::operator[]

(

const std::string

key

)

const

Fetch attribute properties by internal name key.

This is the more conventional interface and the bombproof version to fetch AttributeProperties using a specified key. It is safe because if the key does not match the map an exception will be thrown.

Parameters

key	is the internal name for which properties are requested.

Returns

AttributeProperties that are defined for that name key.

Exceptions

MsPASSError

thrown if the key is not found.

{
    map<std::string,AttributeProperties>::const_iterator amptr;
    amptr=attributes.find(key);
    if(amptr==attributes.end())
    {
        throw MsPASSError(string("AttributeMap::opertor[]: key=")
                + key + " has not entry in this AttributeMap");
    }
    else
    {
        return amptr->second;
    }
}

---

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

• /home/runner/work/mspass/mspass/cxx/include/mspass/utility/AttributeMap.h
• /home/runner/work/mspass/mspass/cxx/src/lib/utility/AttributeMap.cc