[pclasses-cvs] pclasses2/include/pclasses/Util StringTool.h,1.2,1.3

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

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

Modified Files:
	StringTool.h 
Log Message:
More tweaking...

Index: StringTool.h
===================================================================
RCS file: /cvsroot/pclasses/pclasses2/include/pclasses/Util/StringTool.h,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- StringTool.h	26 Dec 2004 11:10:00 -0000	1.2
+++ StringTool.h	26 Dec 2004 11:58:33 -0000	1.3
@@ -9,8 +9,11 @@
 namespace P {
 
 /**
-The StringTool namespace encapsulates a set of utility functions for working
-with string objects.
+The StringTool namespace encapsulates a set of utility functions for
+working with string objects.
+
+Most of these functions were developed to support libs11n, and have a
+proven track-record.
 */
 namespace StringTool {
 
@@ -29,15 +32,23 @@
            It returns the number of translations made.
 
            If reverse_translation == true then a reverse mapping is
-           done: map values are treated as keys. 
+           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.
+	   Complexity is essentially linear, based on a combination of
+	   buffer.size() and translation_map.size(). Best used with
+	   small maps on short strings! The speed can be increased
+	   signifcantly, but probably only if we restrict keys and
+	   values to 1 character each.
 
+	   Design note: this really should be a function template,
+	   accepting any lexically-castable key/val types, but the
+	   function is quite long, and therefore not really suitable
+	   to inclusion in the header.
         */
-        size_t translateEntities( std::string &, const EntityMap & translation_map, bool reverse_translation = false );
+        size_t translateEntities( std::string & buffer, const EntityMap & translation_map, bool reverse_translation = false );
 
 
         /**
@@ -101,7 +112,7 @@
 
         /**
            normalizeString() is like trimString() and
-           strip_slashes(), combined, plus it removes leading/trailing
+           stripSlashes(), combined, plus it removes leading/trailing
            quotes:
 
            <pre>
@@ -137,15 +148,16 @@
            Returns int values for chars '0'-'9', 'a'-'f' and 'A'-'F',
            else -1.
         */
-        int int4hexchar( char c );
+        int int4hexchar( int character );
 
         /**
            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. :/
+           On error -1 is returned, but -1 is also potentially a valid
+           number, so there is really no way of knowing if it fails or
+           not. :/
         */
         int hex2int( const std::string & wd );
 
@@ -189,7 +201,7 @@
 		   calls to operator().
 		*/
                 EntityTranslator( const EntityMap & map, bool reverse )
-			: m_map(map),m_rev(reverse)
+			: m_map(&map),m_rev(reverse)
                 {
                 }
 
@@ -200,10 +212,10 @@
 		*/
                 inline void operator()( std::string & str ) const
                 {
-                        translateEntities( str, this->m_map, this->m_rev );
+                        translateEntities( str, *(this->m_map), this->m_rev );
                 }
         private:
-                EntityMap m_map;
+                const EntityMap * m_map;
                 bool m_rev;
                          
         };
@@ -289,8 +301,17 @@
         }
 
         /**
-           Parsed env vars out of text, replacing them with their
-           values. Accepts variable tokens in the format ${VAR}.
+           Exactly like expandVarsInline() but returns a new string
+           which results from the expansions. The returned string may
+           be the same as the original.
+ 
+         */
+        std::string expandVars( const EntityMap & src, const std::string & text );
+
+        /**
+           Parsed env vars out of buffer, replacing them with their
+           values, as defined in the src map. Accepts variables
+           in the format ${VAR} and $VAR.
 
            e.g., ${foo} corresponds to the value set in src["foo"].
 
@@ -302,15 +323,25 @@
            To get a dollar sign into the resulting string, escape
            it with a single backslash: this keeps it from being
            parsed as a ${variable}.
-         */
-        std::string expandVars( const EntityMap & src, const std::string & text );
 
-        /**
-           Exactly like expandVars() but directly modifies
-           the input string. Returns the number of variables
-           expanded.
+	   Returns the number of variables expanded.
+
+	   Note that this function is much *more* efficient than using
+	   translateEntities() to perform a similar operation.
+	   Because of it's stricter format we can do a single pass
+	   through the string and may not even have to reference the
+	   source map.
+
+	   Complexity depends on the number of ${vars} parts are expanded
+	   in buffer: overall runtime depends on buffer length,
+	   plus a non-determinate amount of time per ${var} expanded.
+
+	   Design note: this really should be a function template,
+	   accepting any lexically-castable key/val types, but the
+	   function is quite long, and therefore not really suitable
+	   to inclusion in the header.
         */
-        size_t expandVarsInline( const EntityMap & src, std::string & text );
+        size_t expandVarsInline( const EntityMap & src, std::string & buffer );