mspass::utility::Metadata Class Reference

Inheritance diagram for mspass::utility::Metadata:

Public Member Functions
	Metadata ()
	Metadata (std::ifstream &ifs, const std::string form=std::string("pf"))
	Metadata (const Metadata &mdold)
virtual	~Metadata ()
Metadata &	operator= (const Metadata &mdold)
Metadata &	operator+= (const Metadata &rhs) noexcept
const Metadata	operator+ (const Metadata &other) const
double	get_double (const std::string key) const override
int	get_int (const std::string key) const override
long	get_long (const std::string key) const
std::string	get_string (const std::string key) const override
bool	get_bool (const std::string key) const override
template<typename T >
T	get (const std::string key) const
template<typename T >
T	get (const char *key) const
	Generic get interface for C char array. More...
boost::any	get_any (const std::string key) const
std::string	type (const std::string key) const
template<typename T >
void	put (const std::string key, T val) noexcept
template<typename T >
void	put (const char *key, T val) noexcept
void	put (const std::string key, const double val) override
void	put (const std::string key, const int val) override
void	put (const std::string key, const bool val) override
void	put (const std::string key, const std::string val) override
void	put (const char *key, const char *val)
void	put (std::string key, const char *val)
void	put_object (const std::string key, const pybind11::object val)
void	put_int (const std::string key, const int val)
void	put_string (const std::string key, const std::string val)
void	put_bool (const std::string key, const bool val)
void	put_double (const std::string key, const double val)
void	put_long (const std::string key, const long val)
void	append_chain (const std::string key, const std::string val, const std::string separator=std::string(":"))
std::set< std::string >	modified () const
void	clear_modified ()
	Mark all data as unmodified. More...
std::set< std::string >	keys () const noexcept
bool	is_defined (const std::string key) const noexcept
void	erase (const std::string key)
std::size_t	size () const noexcept
std::map< std::string, boost::any >::const_iterator	begin () const noexcept
std::map< std::string, boost::any >::const_iterator	end () const noexcept
void	change_key (const std::string oldkey, const std::string newkey)
	Change the keyword to access an attribute. More...

Protected Attributes
std::map< std::string, boost::any >	md
std::set< std::string >	changed_or_set

Friends
pybind11::object	serialize_metadata_py (const Metadata &md)
Metadata	restore_serialized_metadata_py (const pybind11::object &sd)
std::ostringstream &	operator<< (std::ostringstream &, const mspass::utility::Metadata &)

Constructor & Destructor Documentation

Metadata() [1/3]

mspass::utility::Metadata::Metadata ( )

inline

Default constructor. Does nothing.

{};

Metadata() [2/3]

mspass::utility::Metadata::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.

Exceptions

MsPASSError

can be thrown for a variety of conditions.

Metadata() [3/3]

mspass::utility::Metadata::Metadata

(

const Metadata &

mdold

)

Standard copy constructor.

Parameters

mdold

- parent object to be copied

  : md(parent.md),changed_or_set(parent.changed_or_set)
{
}

~Metadata()

virtual mspass::utility::Metadata::~Metadata ( )

inlinevirtual

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.

{};

Member Function Documentation

append_chain()

void mspass::utility::Metadata::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 ":")

Exceptions

MsPASSError

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

{
  if(this->is_defined(key))
  {
    string typ=this->type(key);
    if(typ.find("string")==string::npos)
        throw MsPASSError("Metadata::append_chain:  data for key="
          + key + " is not string type but "+typ
          + "\nMust be string type to define a valid chain",
          ErrorSeverity::Invalid);
    string sval=this->get_string(key);
    sval += separator;
    sval += val;
    this->put(key,sval);
  }
  else
  {
    this->put(key,val);
  }
  changed_or_set.insert(key);
}

References is_defined().

begin()

std::map< string, boost::any >::const_iterator mspass::utility::Metadata::begin ( ) const

noexcept

Return iterator to beginning of internal map container.

{
  return md.begin();
}

change_key()

void mspass::utility::Metadata::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.

{
  map<string,boost::any>::iterator mdptr;
  mdptr=md.find(oldkey);
  /* We silently do nothing if old is not found */
  if(mdptr!=md.end())
  {
    md.insert_or_assign(newkey, mdptr->second);
    md.erase(mdptr);
  }
}

clear_modified()

void mspass::utility::Metadata::clear_modified ( )

inline

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.

  {
      changed_or_set.clear();
  };

end()

std::map< string, boost::any >::const_iterator mspass::utility::Metadata::end ( ) const

noexcept

Return iterator to end of internal map container.

{
  return md.end();
}

erase()

void mspass::utility::Metadata::erase

(

const std::string

key

)

Overload for C string

Clear data associated with a particular key.

{
  map<string,boost::any>::iterator iptr;
  iptr=md.find(key);
  if(iptr!=md.end())
    md.erase(iptr);
  /* Also need to modify this set if the key is found there */
  set<std::string>::iterator sptr;
  sptr=changed_or_set.find(key);
  if(sptr!=changed_or_set.end())
      changed_or_set.erase(sptr);
}

get() [1/2]

template<typename T >

T mspass::utility::Metadata::get ( const char *  key ) const

inline

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.

  {
    try{
      T val;
      val=get<T>(std::string(key));
      return val;
    }catch(...){throw;};
  }

get() [2/2]

template<typename T >

T mspass::utility::Metadata::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.

Exceptions

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

{
  T result;
  std::map<std::string,boost::any>::const_iterator iptr;
  iptr=md.find(key);
  if(iptr==md.end())
  {
    throw MetadataGetError(key,typeid(T).name());
  }
  boost::any aval=iptr->second;
  try{
    result=boost::any_cast<T>(aval);
  }catch(boost::bad_any_cast& err)
  {
    const std::type_info &ti = aval.type();
    throw MetadataGetError(err.what(),key,typeid(T).name(),ti.name());
  };
  return result;
}

get_any()

boost::any mspass::utility::Metadata::get_any ( const std::string  key ) const

inline

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.

Exceptions

-	MetadataGetError if requested parameter is not found.

                                              {
    std::map<std::string,boost::any>::const_iterator iptr;
    iptr=md.find(key);
    if(iptr==md.end())
    {
      throw MetadataGetError(key,typeid(boost::any).name());
    }
    return iptr->second;
  };

get_bool()

bool mspass::utility::Metadata::get_bool ( const std::string  key ) const

inlineoverridevirtual

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.

Implements mspass::utility::BasicMetadata.

                                                   {
    try{
      bool val;
      val=get<bool>(key);
      return val;
    }catch(...){throw;};
  };

get_double()

double mspass::utility::Metadata::get_double ( const std::string  key ) const

inlineoverridevirtual

Get a real number from the Metadata object.

Exceptions

MetadataGetError

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

Parameters

key	keyword associated with requested metadata member.

Implements mspass::utility::BasicMetadata.

                                                       {
    try{
      double val;
      val=get<double>(key);
      return val;
    }catch(MetadataGetError& merr)
    {
    /* Try a float if that failed */
      try{
        float fval;
        fval=get<float>(key);
        return fval;
      }catch(MetadataGetError& merr)
      {
    throw merr;
      }
    }
  };

get_int()

int mspass::utility::Metadata::get_int ( const std::string  key ) const

inlineoverridevirtual

Get an integer from the Metadata object.

Exceptions

MetadataGetError

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

Parameters

key	keyword associated with requested metadata member.

Implements mspass::utility::BasicMetadata.

  {
      try{
        int val;
        val=get<int>(key);
        return val;
      }
      catch(MetadataGetError& merr)
      {
    try{
          long lval;
      lval=get<long>(key);
      return static_cast<int>(lval);
    }catch(MetadataGetError& merr)
    {
      throw merr;
    }
      }
  };

get_long()

long mspass::utility::Metadata::get_long ( const std::string  key ) const

inline

Get a long integer from the Metadata object.

Exceptions

MetadataGetError

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

Parameters

key	keyword associated with requested metadata member.

  {
      try{
        long val;
        val=get<long>(key);
        return val;
      }
      catch(MetadataGetError& merr)
      {
    try{
          int ival;
      ival=get<int>(key);
      return static_cast<long>(ival);
    }catch(MetadataGetError& merr)
    {
      throw merr;
    }
      }
  };

get_string()

std::string mspass::utility::Metadata::get_string ( const std::string  key ) const

inlineoverridevirtual

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.

Exceptions

MetadataGetError

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

Parameters

key	keyword associated with requested metadata member.

Implements mspass::utility::BasicMetadata.

                                                          {
    try{
      std::string val;
      val=get<std::string>(key);
      return val;
    }catch(...){throw;};
  };

is_defined()

bool mspass::utility::Metadata::is_defined ( const std::string  key ) const

noexcept

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

{
  map<string,boost::any>::const_iterator mptr;
  mptr=md.find(key);
  if(mptr!=md.end())
  {
    return true;
  }
  else
  {
    return false;
  }
}

keys()

set< string > mspass::utility::Metadata::keys ( ) const

noexcept

Return all keys without any type information.

{
  set<string> result;
  map<string,boost::any>::const_iterator mptr;
  for(mptr=md.begin();mptr!=md.end();++mptr)
  {
    string key(mptr->first);\
    result.insert(key);
  }
  return result;
}

modified()

std::set<std::string> mspass::utility::Metadata::modified ( ) const

inline

Return the keys of all altered Metadata values.

  {
      return changed_or_set;
  };

operator+()

const Metadata mspass::utility::Metadata::operator+

(

const Metadata &

other

)

const

Add two Metadata objects. Uses operator+=

{
  Metadata result(*this);
  result += other;
  return result;
}

operator+=()

Metadata & mspass::utility::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.

{
  if(this!=(&rhs))
  {
    /* We depend here upon the map container replacing values associated with
    existing keys.  We mark all entries changes anyway.  This is a vastly simpler
    algorithm than the old SEISPP::Metadata.  */
    map<string,boost::any>::const_iterator rhsptr;
    for(rhsptr=rhs.md.begin();rhsptr!=rhs.md.end();++rhsptr)
    {
      md[rhsptr->first]=rhsptr->second;
      changed_or_set.insert(rhsptr->first);
    }
  }
  return *this;
}

operator=()

Metadata & mspass::utility::Metadata::operator=

(

const Metadata &

mdold

)

Standard assignment operator.

Parameters

mdold

- parent object to copy

{
  if(this!=(&parent))
  {
    md=parent.md;
    changed_or_set=parent.changed_or_set;
  }
  return *this;
}

put()

void mspass::utility::Metadata::put ( const char *  key, const char *  val  )

inline

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

  {
    std::string sval(val);
    this->put<std::string>(key,val);
  }

size()

std::size_t mspass::utility::Metadata::size ( ) const

noexcept

Overload for C string

Return the size of the internal map container.

{
  return md.size();
}

Friends And Related Function Documentation

operator<<

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

friend

Standard operator for overloading output to a stringstream

restore_serialized_metadata_py

Metadata restore_serialized_metadata_py ( const pybind11::object &  sd )

friend

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

{
  pybind11::gil_scoped_acquire acquire;
  try
  {
    pybind11::module pickle = pybind11::module::import("pickle");
    pybind11::object loads = pickle.attr("loads");
    pybind11::tuple md_dump = loads(s);
    pybind11::dict md_dict = md_dump[0];
    pybind11::object md_py = pybind11::module_::import("mspasspy.ccore.utility").attr("Metadata")(md_dict);
    Metadata md = md_py.cast<Metadata>();
    md.changed_or_set = md_dump[1].cast<std::set<std::string>>();
    pybind11::gil_scoped_release release;
    return md;
  }
  catch (...)
  {
    pybind11::gil_scoped_release release;
    throw;
  };
}

serialize_metadata_py

pybind11::object serialize_metadata_py ( const Metadata &  md )

friend

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.

{
  pybind11::gil_scoped_acquire acquire;
  try{
    pybind11::dict md_dict = pybind11::cast(md);
    pybind11::set changed_or_set = pybind11::cast(md.changed_or_set);
    pybind11::module pickle = pybind11::module::import("pickle");
    pybind11::object dumps = pickle.attr("dumps");
    pybind11::object md_dump = dumps(pybind11::make_tuple(md_dict, changed_or_set));
    pybind11::gil_scoped_release release;
    return md_dump;
  }catch(...){pybind11::gil_scoped_release release;throw;};
}

---

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

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