mspass::utility::Metadata

class Metadata : public mspass::utility::BasicMetadata

Subclassed by mspass::seismic::Ensemble< T >, mspass::seismic::CoreSeismogram, mspass::seismic::CoreTimeSeries, mspass::seismic::Ensemble< Tdata >, mspass::seismic::PowerSpectrum, mspass::utility::AntelopePf

Public Functions

inline Metadata()

Default constructor. Does nothing.

Metadata(std::ifstream &ifs, const std::string form = std::string("pf"))

Construct from a file.

This simple file based constructor assumes the file contains only a set lines with this format: key value type where type must be one of: real, integer, bool, or string. Note int is actually always promoted to a long. The optional format variable is there to allow alternative formats in the future.

Parameters:

• ifs – - ifstream from which to read data

• format – - optional format specification. Currently only default of “text” is accepted.

Throws:

MsPASSError – can be thrown for a variety of conditions.

Metadata(const Metadata &mdold)

Standard copy constructor.

Parameters:

mdold – - parent object to be copied

inline virtual ~Metadata()

Destructor - has to be explicitly implemented and declared virtual for reasons found in textbooks and various web forums. A very subtle feature of C++ inheritance.

Metadata &operator=(const Metadata &mdold)

Standard assignment operator.

Parameters:

mdold – - parent object to copy

Metadata &operator+=(const Metadata &rhs) noexcept

Append additional metadata with replacement.

A plus operator implies addition, but this overloading does something very different. A simple way to describe the effect is that on completion the left hand side Metadata object will contain a duplicate of the right hand side plus any attributes in the rhs that were not present on the lhs. Another way to clarify this is to describe the algorithm. We take each attribute on the right and search for it in the lhs. If it is not in the lhs it will be added. If it is there already, the rhs value will replace the old value on the lhs. This is most useful when an algorithm creates a new set of attributes that we want to use in downstream processing but retain all the other attributes.

Parameters:

rhs – is the new metadata to be insert/replace on the lhs.

const Metadata operator+(const Metadata &other) const

Add two Metadata objects. Uses operator+=

inline virtual double get_double(const std::string key) const override

Get a real number from the Metadata object.

Throws:

MetadataGetError – if requested parameter is not found or there is a type mismatch.

Parameters:

key – keyword associated with requested metadata member.

inline virtual int get_int(const std::string key) const override

Get an integer from the Metadata object.

Throws:

MetadataGetError – if requested parameter is not found or there is a type mismatch.

Parameters:

key – keyword associated with requested metadata member.

inline long get_long(const std::string key) const

Get a long integer from the Metadata object.

Throws:

MetadataGetError – if requested parameter is not found or there is a type mismatch.

Parameters:

key – keyword associated with requested metadata member.

inline virtual std::string get_string(const std::string key) const override

Get a string from the Metadata object.

Note the string in this case can be quite large. If the string was parsed from an Antelope Pf nested Tbl and Arrs can be extracted this way and parsed with pf routines.

Throws:

MetadataGetError – if requested parameter is not found or there is a type mismatch.

Parameters:

key – keyword associated with requested metadata member.

inline virtual bool get_bool(const std::string key) const override

Get a boolean parameter from the Metadata object.

This method never throws an exception assuming that if the requested parameter is not found it is false.

Parameters:

key – keyword associated with requested metadata member.

template<typename T>
T get(const std::string key) const

Generic get interface.

This is a generic interface most useful for template procedures that need to get a Metadata component. Since this object only can contain simple types the type requested must be simple. Currently supports only int, long, short, double, float, and string. C char* is intentionally not supported. Calls to anything but the supported types will throw an exception.

Parameters:

key – is the name tag of desired component.

Throws:

- – will throw a MetadataGetError (child of MsPASSError) for type mismatch or in an overflow or underflow condition.

template<typename T>
inline T get(const char *key) const

Generic get interface for C char array.

This is a generic interface most useful for template procedures
that need to get a Metadata component.   Since this object only
can contain simple types the type requested must be simple.
Currently supports only int, long, short, double, float, and string.
C char* is intentionally not supported. This is largely a wrapper
on the string key version of this same generic function.

\param key is the name tag of desired component.

\exception - will throw a MetadataGetError (child of MsPASSError) for
   type mismatch or in an overflow or underflow condition.

inline boost::any get_any(const std::string key) const

Get the boost::any container from the Metadata object.

This method is mostly for Python bindings so that a generic get method can work in Python.

Parameters:

key – is the name tag of desired component.

Throws:

- – MetadataGetError if requested parameter is not found.

inline void put(const char *key, const char *val)

Put a C string literal. Requires special handling because it is not copy constructable (see warning in boost docs: https://theboostcpplibraries.com/boost.any

void append_chain(const std::string key, const std::string val, const std::string separator = std::string(":"))

Create or append to a chained string.

A chain conceptually is identical to a list of string data. We implement it in Metadata because sometimes (e.g. MongoDB interaction and some constructs like the unix shell PATH variable) handling a full scale container like list<std::string> would be awkward. If more extensive capability like that is needed it would be better to add a class that inherits Metadata and does so. AntelopePf more or less does this, for example, handling Tbl sections. In any case, this usage is more for one word strings separated by a common separator: e.g. path=/usr/local/bin:/bin uses : as the separator. /usr/local/bin and /bin are the chain.

If the key related to the chain does not yet exist it is silently created. If it already exists and we append to it.

Parameters:

• key – is the key that defines the string.

• val – is the the new string to append to the chain

• separator – is the string used for a separator (default “:”)

Throws:

MsPASSError – will be thrown if data is found in key and it is not of type string.

inline std::set<std::string> modified() const

Return the keys of all altered Metadata values.

inline void clear_modified()

Mark all data as unmodified.

There are situations where it is necessary to clear the data structure used to mark changed metadata. The best example know is when data objects interact with a database and try to do updates. Effort can be wasted in unnecessary updates if metadata are improperly marked as modified. This method clears the entire container that defines changed data.

std::set<std::string> keys() const noexcept

Return all keys without any type information.

bool is_defined(const std::string key) const noexcept

Test if a key has an associated value. Returns true if a value is defined.

void erase(const std::string key)

Overload for C string

Clear data associated with a particular key.

std::size_t size() const noexcept

Overload for C string

Return the size of the internal map container.

std::map<std::string, boost::any>::const_iterator begin() const noexcept

Return iterator to beginning of internal map container.

std::map<std::string, boost::any>::const_iterator end() const noexcept

Return iterator to end of internal map container.

void change_key(const std::string oldkey, const std::string newkey)

Change the keyword to access an attribute.

Sometimes it is useful to change the key used to access a particular piece of data. Doing so, for example, is one way to implement an alias (alternative name) for something. The entry for the old key is copied to a entry accessible by the new key. The entry for old is then deleted. This avoids downstream inconsistencies a the cost of possible failures from the translation. This method always returns and will silently do nothing if old is not defined. If the new key is already defined, its content will be replaced by the old’s.

Parameters:

• oldkey – is the key to search for to be changed

• newkey – is the new key to use for the replacement.

Friends

friend pybind11::object serialize_metadata_py(const Metadata &md)

Serialize Metadata to a python bytes object. This function is needed to support pickle in the python interface. It cast the C++ object to a Python dict and calls pickle against that dict directly to generate a Python bytes object. This may not be the most elegant approach, but it should be bombproof.

Parameters:

md – is the Metadata object to be serialized

Returns:

pickle serialized data object.

friend Metadata restore_serialized_metadata_py(const pybind11::object &sd)

Unpack serialized Metadata.

This function is the inverse of the serialize function. It recreates a Metadata object serialized previously with the serialize function.

Parameters:

sd – is the serialized data to be unpacked

Returns:

Metadata derived from sd

friend std::ostringstream &operator<<(std::ostringstream&, const mspass::utility::Metadata&)

Standard operator for overloading output to a stringstream