Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members

s11n::property_store Class Reference

property_store is a class for storing arbitrary key/value pairs. More...

#include <property_store.h>

Inheritance diagram for s11n::property_store:

s11n::argv_parser s11n::environment List of all members.

Public Types

typedef std::map< std::string,
std::string > 
map_type
 The map type this object uses to store items internally.
typedef map_type::value_type value_type
typedef std::string key_type
 For compatibility with std::map.
typedef std::string mapped_type
 For compatibility with std::map.
typedef map_type::iterator iterator
 For iterating over properties using STL conventions.
typedef map_type::const_iterator const_iterator
 For iterating over properties using STL conventions.

Public Member Functions

const std::string operator[] (const std::string &key) const
 std::string propval = props["bar"] is functionally identical to get_string("bar").
void insert (const value_type &)
 For compatibility with std::map.
unsigned long count_properties () const
 Returns the number of items in this object.
virtual std::string get_string (const std::string &key, const std::string &defaultVal=std::string()) const
 Returns the value for key, or defaultVal if the key is not set.
virtual void set_string (const std::string &key, const std::string &val)
 Sets the given key to the given value.
template<typename T>
void set (const std::string &key, const T &val)
 See set_string().
void set (const char *key, const char *val)
 The <const char *> variants of get() and set() are to help the developer avoid having to cast so much and to help out compilers which have mediocre template support.
void set (const std::string &key, const char *val)
 Overloaded for strings-via-streams reaons.
void set (const char *key, const std::string &val)
 Overloaded for strings-via-streams reaons.
template<typename T>
get (const std::string &key, const T &val) const
 See get_string().
std::string get (const char *key, const char *val) const
 get(): see set().
std::string get (const std::string &key, const char *val) const
 Overloaded for strings-via-streams reasons.
std::string get (const char *key, const std::string &val) const
 Overloaded for strings-via-streams reasons.
virtual bool is_set (const std::string &key) const
 Returns true if this object contains the given property.
virtual bool unset (const std::string &key)
 Removes the given property from this object.
bool clear_properties ()
 Removes all entries from this object.
void set_bool (const std::string &key, bool val)
 Note that the set/getTYPE() variants are mostly to keep old code working.
bool get_bool (const std::string &key, bool defaultVal) const
 get_bool(key) is an exception to the set/getXXX() rule: it returns true if key's value is true, as evaluated by the static function bool_val().
iterator begin ()
 Returns the first item in the data map.
const_iterator begin () const
 Returns a const_iterator pointing at this object's first property.
iterator end ()
 The after-the-end iterator for the data map.
const_iterator end () const
 The after-the-end iterator for the data map.
virtual map_type::iterator find (const std::string &key)
 Returns end() if the key is not in our map, otherise it returns that iterator.
unsigned int merge (const property_store &src)
 Merges all properties from src into this object.
map_type::size_type size () const
 Returns the number of properties in this object.
map_typeget_map ()
 Returns the internally-used map_type (see the typedefs, above).
const map_typeget_map () const
 Returns the internally-used map_type (see the typedefs, above).

Static Public Member Functions

bool bool_val (const std::string &key)
 Returns the bool value of the passed string.
unsigned int merge (const property_store &src, property_store &dest)
 merge() copies all properties from src to dest.

Detailed Description

property_store is a class for storing arbitrary key/value pairs.

i often find myself needing classes which contain an arbitrary number of arbitrary properties, and this interface has worked very well for me.

It must be strongly stressed that this class is designed solely with utility, ease-of-use and code maintenance costs in mind. Not one iota of concern has been given to optimization! It is not a lightweight object, nor is it efficient. Do not use this class when speed is of the essence! That said, it should fast enough for almost all standard property-list uses. (i often use thousands of them as property containers for game pieces.)

It's get() and set() template functions support any types which are both instreamable and outstreamable (implements both operator<<(std::ostream) and operator>>(std::istream)). It uses s11n::to/from_string to convert types to and from strings, so your own types will be supported as value types if they can be streamed from/to an i/ostream.

It follows STL container conventions, so it can be used in many container contexts and with many generic algorithms.

Years later...

This class is in need of optimization. One thought is to internally use a reference-counted string class instead of std::string, but i need to do some timings.

Definition at line 46 of file property_store.h.


Member Function Documentation

iterator s11n::property_store::begin  ) 
 

Returns the first item in the data map.

You can use this to iterate, STL-style:

   map_type::iterator it = props.begin();
   while( it != props.end() ) { ... ++it; }
 

Note that the iterator represents a std::pair<string,string>, so use (*it).first to get the key and (*it).second to get the value.

bool s11n::property_store::bool_val const std::string &  key  )  [static]
 

Returns the bool value of the passed string.

The following string values are considered equal to true: true, TRUE, True yes, YES, Yes, y, Y 1 Anything else evaluates to false. CASE IS IMPORTANT! (Sorry, when i learn how to easily lowercase a c++ string i'll fix all that.)

unsigned long s11n::property_store::count_properties  )  const
 

Returns the number of items in this object.

This is a constant-time operation.

virtual map_type::iterator s11n::property_store::find const std::string &  key  )  [virtual]
 

Returns end() if the key is not in our map, otherise it returns that iterator.

Use the iterator's .first member to get the key, and .second to get the value. However, you SHOULD call get_string( (*iter).first ) to get the value, so subclasses can do some funniness with the key, like argv_parser does. Thus:

   std::string val = "not found";
   iter = foo.find( "key" );
   if( iter == foo.end() ) { return val; }
   val = foo.get_string( (*iter).first );
 

Such usage helps guaranty polymorphic behaviour.

todo?: make this the master getter, instead of get_string(), for purposes of overriding getXXX() behaviour?

std::string s11n::property_store::get const char *  key,
const char *  val
const [inline]
 

get(): see set().

Same notes apply.

Definition at line 175 of file property_store.h.

template<typename T>
T s11n::property_store::get const std::string &  key,
const T &  val
const [inline]
 

See get_string().

This function is identical except that the returned string is converted to type T. If this type is not possible it will fail at compile time. A value-conversion failure, on the other hand, is not caught at compile time.

Definition at line 166 of file property_store.h.

References s11n::from_string().

virtual std::string s11n::property_store::get_string const std::string &  key,
const std::string &  defaultVal = std::string()
const [virtual]
 

Returns the value for key, or defaultVal if the key is not set.

Note to subclassers: This is the "master" getter, so subclasses which want to generically alter getXXX() behaviour need only override this function. Almost all other getXXX() functions call this one, so do not call them from inside this function.

Reimplemented in s11n::argv_parser.

void s11n::property_store::insert const value_type &   ) 
 

For compatibility with std::map.

Inserts a value_type (i.e., pair<string,string>) into this object. It calls set_string(), so it is compatible with subclasses which do custom handling in that method.

unsigned int s11n::property_store::merge const property_store src  ) 
 

Merges all properties from src into this object.

Returns the number of properties merged.

unsigned int s11n::property_store::merge const property_store src,
property_store dest
[static]
 

merge() copies all properties from src to dest.

It returns the number of properties copied.

This is potentially a very expensive operation.

const std::string s11n::property_store::operator[] const std::string &  key  )  const
 

std::string propval = props["bar"] is functionally identical to get_string("bar").

Unlike std::map and the like, calling this operator with a key which is not in the object does not create a new entry - it simply returns an empty string in that case.

void s11n::property_store::set const char *  key,
const char *  val
[inline]
 

The <const char *> variants of get() and set() are to help the developer avoid having to cast so much and to help out compilers which have mediocre template support.

:/

Definition at line 140 of file property_store.h.

template<typename T>
void s11n::property_store::set const std::string &  key,
const T &  val
[inline]
 

See set_string().

This function is identical except that it converts val to string before saving it. If this type conversion is not possible it will fail at compile time. A value-conversion failure, on the other hand, is not caught at compile time.

Definition at line 129 of file property_store.h.

void s11n::property_store::set_bool const std::string &  key,
bool  val
[inline]
 

Note that the set/getTYPE() variants are mostly to keep old code working.

Please use set() and get() when possible. Sometimes it is more convenient to use these instead of get()/set(), especially with something like:

                   props.set( "foo", false ); // ambiguous: may be bool, const char *, or bool or even int zero :/
                   

Definition at line 223 of file property_store.h.

virtual void s11n::property_store::set_string const std::string &  key,
const std::string &  val
[virtual]
 

Sets the given key to the given value.

See get_string(): same notes apply here.

If key.empty() then this function does nothing.


The documentation for this class was generated from the following file:
Generated on Tue Oct 26 18:26:00 2004 for s11n by  doxygen 1.3.9.1