[pclasses-cvs] pclasses2/include/pclasses/Util SimplePropertyStore.h,NONE,1.1

[stephan b. <sg...@us...>]

Update of /cvsroot/pclasses/pclasses2/include/pclasses/Util
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv16561/include/pclasses/Util

Added Files:
	SimplePropertyStore.h 
Log Message:
egg: LexT-based very simple property store. Still need to add multimap support.

--- NEW FILE: SimplePropertyStore.h ---
////////////////////////////////////////////////////////////////////////
// SimplePropertyStore - exactly that.
//
// Author: stephan beal <st...@s1...>
// License: Public Domain
////////////////////////////////////////////////////////////////////////
#ifndef  p_Util_SIMPLEPROPERTYSTORE_H_INCLUDED
#define  p_Util_SIMPLEPROPERTYSTORE_H_INCLUDED

#include <iostream>
#include <map>
#include <sstream>
#include <pclasses/Util/LexT.h>

namespace P { namespace Util {
	/**
           SimplePropertyStore 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 follows STL container conventions, so it can be used in
           many container contexts and with many generic algorithms.


        */
	class SimplePropertyStore
	{
	      public:

                /**
                   The map type this object uses to store items
                   internally.
                 */
		typedef std::map < std::string, LexT > map_type;
		typedef map_type::value_type value_type;

                /** For compatibility with std::map */
                typedef std::string key_type; 
                /** For compatibility with std::map */
                typedef map_type::mapped_type mapped_type; 

                /**
                   For iterating over properties using STL
                   conventions.
                 */
		typedef map_type::iterator iterator;

                /**
                   For iterating over properties using STL
                   conventions.
                 */
		typedef map_type::const_iterator const_iterator;

		/**
                   std::string propval = props["bar"] is functionally
                   identical to get("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.
                */
		const key_type operator[] ( const key_type & key ) const;

                /**
                   For compatibility with std::map. Inserts a
                   value_type (i.e., pair<string,string>) into this
                   object.  It calls setString(), so it is compatible
                   with subclasses which do custom handling in that
                   method.
                 */
                void insert( const value_type & );

                SimplePropertyStore();
                virtual ~SimplePropertyStore();

		/**
                   Returns the number of items in this object. This is
                   a constant-time operation.
                */
		unsigned long count() const;



                /**
                   Returns true if this object contains the given property.
                */
		virtual bool isSet( const key_type & key ) const;

                /**
                   Removes the given property from this object.
                */
		virtual bool unset( const key_type & key );

		/**
                   Removes all entries from this object.
                 */
		bool clear();

		/**
                   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:
                   
                   <pre>
                   props.set( "foo", false ); // ambiguous: may be bool, const char *, or bool or even int zero :/
                   </pre>

                */
		inline void setBool( const key_type & key, bool val )
		{
			return this->set( key, val );
		}

		/**
                   getBool(key) is an exception to the rule:
                   it returns true if key's value evaluates to true, as
                   evaluated by the static function boolVal().
                */
		bool getBool( const key_type & key, bool defaultVal ) const;



		/**
                 * 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 SIGNIFICANT!
                 */
		static bool boolVal( const key_type & key );


		/**
                 * Returns the first item in the data map.
                 * You can use this to iterate, STL-style:
                 * <pre>
                 *   map_type::iterator it = props.begin();
                 *   while( it != props.end() ) { ... ++it; }
                 * </pre>
                 *
                 * 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.
                 */
		iterator begin();

                /**
                   Returns a const_iterator pointing at this object's first property.
                */
		const_iterator begin() const;

		/**
                 * The after-the-end iterator for the data map.
                 */
		iterator end();
		/**
                 * The after-the-end iterator for the data map.
                 */
		const_iterator end() const;

		/**
                 * Returns the value for key, or defaultVal if the key
                 * is not set. 
                 *
                 */
		virtual mapped_type get( const key_type & key, const mapped_type & defaultVal = mapped_type() )const;

		/**
                   Sets the given key to the given value.

                   If key.empty() then this function does nothing.
                */
		virtual void set( const key_type & key, const mapped_type & val );

		/**
                 * 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 getString( (*iter).first )
                 * to get the value, so subclasses can do some funniness with the key,
                 * like argvParser does. Thus:
                 * <pre>
                 *   SimplePropertyStore::key_type val = "not found";
                 *   iter = foo.find( "key" );
                 *   if( iter == foo.end() ) { return val; }
                 *   val = foo.getString( (*iter).first );
                 * </pre>
                 *
                 * Such usage helps guaranty polymorphic behaviour.
                 *
                 * todo?: make this the master getter, instead of
                 * getString(), for purposes of overriding getXXX()
                 * behaviour?
                 */
		virtual map_type::iterator find( const key_type & key );

		/**
                   merge() copies all properties from src to dest. It returns the
                   number of properties copied.

                   This is potentially a very expensive operation.
                */
		static unsigned int merge( const SimplePropertyStore & src, SimplePropertyStore & dest );
		/**
                   Merges all properties from src into this object. Returns the number
                   of properties merged.
                */
		unsigned int merge( const SimplePropertyStore & src );


                /**
                   Returns the number of properties in this object.
                */
                map_type::size_type size() const;

		/**
                 * Returns the internally-used map_type (see the typedefs, above).
                 */
		map_type & getMap();
		/**
                 * Returns the internally-used map_type (see the typedefs, above).
                 */
		const map_type & getMap() const;

	protected:

	      private:
		map_type m_map;
	};			// class SimplePropertyStore


} }				// namespace P::Util
#endif //  p_Util_SIMPLEPROPERTYSTORE_H_INCLUDED