[pclasses-cvs] pclasses2/include/pclasses/Util StringTool.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-serv32078/include/pclasses/Util

Added Files:
	StringTool.h 
Log Message:
egg

--- NEW FILE: StringTool.h ---
#ifndef p_Util_STRINGTOOL_HPP_INCLUDED
#define p_Util_STRINGTOOL_HPP_INCLUDED 1

#include <string>
#include <map>
#include <pclasses/Phoenix.h>
#include <pclasses/Util/LexT.h>

namespace P {

/**
The StringTool namespace encapsulates a set of utility functions for working
with string objects.
*/
namespace StringTool {

	using ::P::Util::LexT;
        /**
           Convenience typedef for use with translateEntities().
         */
        typedef std::map<std::string,std::string> EntityMap;

        /**
           For each entry in the input string, the characters are
           mapped to string sequences using the given
           translation_map. Where no mappings exist, the input
           sequence is left as-is.

           It returns the number of translations made.

           If reverse_translation == true then a reverse mapping is
           done: map values are treated as keys. 

           This is useful, for example, for doing XML-entity-to-char
           conversions.

           It is amazingly INefficient, but seems to work okay.

        */
        size_t translateEntities( std::string &, const EntityMap & translation_map, bool reverse_translation = false );


        /**
           A policy enum used by trimString().
        */
        enum TrimPolicy {
        /**
           Trim only leading spaces.
         */
        TrimLeading = 0x01,
        /**
           Trim only trailing spaces.
         */
        TrimTrailing = 0x02,
        /**
           Trim leading and trailing spaces.
         */
        TrimAll = TrimLeading + TrimTrailing
        };

        /**
           Trims leading and trailing whitespace from the input string
           and returns the number of whitespace characters removed.
         */
        size_t trimString( std::string &, TrimPolicy = TrimAll );
        /**
           Trims leading and trailing whitespace from the input string
           and returns the trimmed string.
         */
        std::string trimString( const std::string &, TrimPolicy = TrimAll );


        /**
           Attempts to remove all backslash-escaped chars from str.

           Removes backslash-escaped newlines from the input string, including
           any whitespace immediately following each backslash.

           The optional slash parameter defines the escape character.
        */
        size_t stripSlashes( std::string &str, const char slash = '\\' );

        /**
           Adds an escape sequence in front of any characters in
           instring which are also in the list of chars_to_escape.
           Returns the number of escapes added.

           e.g., to escape (with a single backslash) all $, % and \ in
           mystring with a backslash:

           <pre>
           escapeString( mystring, "$%\\", "\\" );
           </pre>

           (WARNING: the doxygen-generated HTML version of these docs
           may incorrectly show single backslashes in the above example!)


        */
        size_t escapeString( std::string & instring, const std::string & chars_to_escape, const std::string & escape_seq = "\\" );

        /**
           normalizeString() is like trimString() and
           strip_slashes(), combined, plus it removes leading/trailing
           quotes:

           <pre>
           "this is a \
           sample multi-line, backslash-escaped \
           string."
           </pre>
           
           Will translate to:
           <pre>
           this is a sample multi-line, backslash-escaped string.
           </pre>
        */
        void normalizeString( std::string & );


        /**
           Returns the first whitespace-delimited token from the given
           string, or an empty string if there is no such token.
        */
        std::string firstToken( const std::string & );

        /**
           Returns the passed-in string, minus the first
           whitespace-delimited token. An empty string is returned if
           there is no second token.
         */
        std::string afterFirstToken( const std::string & );



        /**
           Returns int values for chars '0'-'9', 'a'-'f' and 'A'-'F',
           else -1.
        */
        int int4hexchar( char c );

        /**
           Returns decimal value of wd, which is assumed to be a
           hex-encoded number. wd may optionally be prefixed with '#',
           as in \#ff00ff. Case is insignificant.

           On error 0 is returned, but 0 is also a valid number, so
           there is really no way of knowing if it fails or not. :/
        */
        int hex2int( const std::string & wd );


        /**
           Lexically casts v to a string.
        */
        template <typename ValueT>
        std::string to( const ValueT & v )
        {
		return LexT(v).str();
        }

        /**
           Lexically casts v to a ValueT, or returns dflt if
           conversion fails.
        */
        template <typename ValueT>
        ValueT from( const std::string & v, const ValueT & dflt = ValueT() )
        {
                return LexT(v).template castTo<ValueT>( dflt );
        }


        /**
           See translateEntities() for details.
        */
        typedef std::map<std::string,std::string> EntityMap;


	/**
	   YAGNI!

	   A functor for translating entities in a set of strings.
	   Designed for use with std::for_each().
	*/
        struct EntityTranslator
        {
		/**
		   Sets the map and reverse options to be used from
		   calls to operator().
		*/
                EntityTranslator( const EntityMap & map, bool reverse )
			: m_map(map),m_rev(reverse)
                {
                }

		/**
		   Calls translateEntities( str, MAP, REVERSE ),
		   where MAP and REVERSE are the flags set via the
		   ctor.
		*/
                inline void operator()( std::string & str ) const
                {
                        translateEntities( str, this->m_map, this->m_rev );
                }
        private:
                EntityMap m_map;
                bool m_rev;
                         
        };

        /**
           Internal-use initializer for setting up an entity
           translation map for default quote-escaping behaviour.
        */
        struct defaultEscapesInitializer
        {
		/**
		   Adds the following escape sequences to map:

		   - single backslash (\) == double backslash.

		   - single quote  == backslash, quote

		   - double quote  == backslash, double quote  
		*/
                void operator()( EntityMap & map );
        };


        /** Internal marker type. */
        template <typename ContextT> struct StrSharingContext {};

        /**
           Returns the default entity translation map, which can be used to
           [un]slash-escape the folling entities: '\\', '\'', '"'.
        */
        inline const EntityMap &
        defaultEscapesTranslations()
        {
                typedef ::P::Phoenix<EntityMap,
                        StrSharingContext<EntityMap>,
                        defaultEscapesInitializer
                        > TMap;
                return TMap::instance();
        }

        /**
           Converts v to a string, applies translateEntities(...,trans,reverse ),
           and returns the resulting string.
        */
        template <typename ValueT>
        std::string translate( const ValueT & v,
                               const EntityMap & trans,
                               bool reverse )
        {
                std::string val = to( v );
                translateEntities( val, trans, reverse );
                return val;
        }


        /**
           Calls translate( v,trans, false);
        */
        template <typename ValueT>
        std::string escape( const ValueT & v, const EntityMap & trans = defaultEscapesTranslations() )
        {
                return translate( v, trans, false );
        }


        /**
           Calls translate( v, trans, true );
        */
        template <typename ValueT>
        std::string unescape( const ValueT & v, const EntityMap & trans = defaultEscapesTranslations() )
        {
                return translate( v, trans, true );
        }

        /**
           Returns v as a quoted string, using the given quote
           character.
        */
        template <typename ValueT>
        std::string quote( const ValueT & v, const std::string & quote = "\'" )
        {
                return quote + to( v ) + quote;
        }

}} // namespace P::StringTool


#endif // p_Util_STRINGTOOL_HPP_INCLUDED