s11n::io::strtool Namespace Reference

The strtool namespace encapsulates a set of utility functions for working with string objects. More...


Classes

struct  entity_translator
 YAGNI! More...
struct  default_escapes_initializer
 Internal-use initializer for setting up an entity translation map for default quote-escaping behaviour. More...
struct  strtool_sharing_context
 Internal marker type. More...
class  string_tokenizer
 string_tokenizer is a. More...
class  stdstring_tokenizer
 stdstring_tokenizer: More...

Namespaces

namespace  STPrivate
 The functions in the Private namespace should not be used by client code.

Typedefs

typedef std::map
< std::string,
std::string > 
entity_map
 Convenience typedef for use with translate_entities().
typedef std::map
< std::string,
std::string > 
entity_map
 See translate_entities() for details.

Enumerations

enum  TrimPolicy { TrimLeading = 0x01, TrimTrailing = 0x02, TrimAll = TrimLeading | TrimTrailing }
 A policy enum used by trim_string(). More...

Functions

std::size_t translate_entities (std::string &buffer, const entity_map &translation_map, bool reverse_translation=false)
 For each entry in the input string, the characters are mapped to string sequences using the given translation_map.
std::size_t trim_string (std::string &, TrimPolicy=TrimAll)
 Trims leading and trailing whitespace from the input string and returns the number of whitespace characters removed.
std::string trim_string (const std::string &, TrimPolicy=TrimAll)
 Trims leading and trailing whitespace from the input string and returns the trimmed string.
std::size_t strip_slashes (std::string &str, const char slash= '\\')
 Attempts to remove all backslash-escaped chars from str.
std::size_t escape_string (std::string &instring, const std::string &chars_to_escape, const std::string &escape_seq="\\")
 Adds an escape sequence in front of any characters in instring which are also in the list of chars_to_escape.
void normalize_string (std::string &)
 normalize_string() is like trim_string() and strip_slashes(), combined, plus it removes leading/trailing quotes:
std::string first_token (const std::string &)
 Returns the first whitespace-delimited token from the given string, or an empty string if there is no such token.
std::string after_first_token (const std::string &)
 Returns the passed-in string, minus the first whitespace-delimited token.
int int4hexchar (char character)
 Returns int values for chars '0'-'9', 'a'-'f' and 'A'-'F', else -1.
int hex2int (const std::string &wd)
 Returns decimal value of wd, which is assumed to be a hex-encoded number.
template<typename ValueT>
std::string to (const ValueT &v)
 Lexically casts v to a string.
template<typename ValueT>
ValueT from (const std::string &v, const ValueT &dflt=ValueT())
 Lexically casts v to a ValueT, or returns dflt if conversion fails.
const entity_mapdefault_escapes_translations ()
 Returns the default entity translation map, which can be used to [un]slash-escape the folling entities: '\', '\'', '"'.
template<typename ValueT>
std::string translate (const ValueT &v, const entity_map &trans, bool reverse)
 Converts v to a string, applies translate_entities(.
template<typename ValueT>
std::string escape (const ValueT &v, const entity_map &trans=default_escapes_translations())
 Calls translate( v,trans, false);.
template<typename ValueT>
std::string unescape (const ValueT &v, const entity_map &trans=default_escapes_translations())
 Calls translate( v, trans, true );.
template<typename ValueT>
std::string quote (const ValueT &v, const std::string &quote="\'")
 Returns v as a quoted string, using the given quote character.
std::string expand_dollar_refs (const std::string &text, const entity_map &src)
 Exactly like expand_dollar_refs_inline() but returns a new string which results from the expansions.
std::size_t expand_dollar_refs_inline (std::string &buffer, const entity_map &src)
 Parsed env vars out of buffer, replacing them with their values, as defined in the src map.


Detailed Description

The strtool namespace encapsulates a set of utility functions for working with string objects.

This mini-lib has unfortunately followed me from source tree to source tree like a little virus. While i have no special love for this code, it has proven useful time and time again.


Typedef Documentation

typedef std::map<std::string,std::string> s11n::io::strtool::entity_map

See translate_entities() for details.

Definition at line 275 of file strtool.hpp.

typedef std::map<std::string,std::string> s11n::io::strtool::entity_map

Convenience typedef for use with translate_entities().

Definition at line 111 of file strtool.hpp.


Enumeration Type Documentation

enum s11n::io::strtool::TrimPolicy

A policy enum used by trim_string().

Enumerator:
TrimLeading  Trim only leading spaces.
TrimTrailing  Trim only trailing spaces.
TrimAll  Trim leading and trailing spaces.

Definition at line 144 of file strtool.hpp.


Function Documentation

std::string s11n::io::strtool::after_first_token ( 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.

const entity_map& s11n::io::strtool::default_escapes_translations (  ) 

Returns the default entity translation map, which can be used to [un]slash-escape the folling entities: '\', '\'', '"'.

template<typename ValueT>
std::string s11n::io::strtool::escape ( const ValueT &  v,
const entity_map &  trans = default_escapes_translations() 
) [inline]

Calls translate( v,trans, false);.

Definition at line 357 of file strtool.hpp.

References translate().

std::size_t s11n::io::strtool::escape_string ( std::string &  instring,
const std::string &  chars_to_escape,
const std::string &  escape_seq = "\\" 
)

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:

           escape_string( mystring, "$%\\", "\\" );
           

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

std::string s11n::io::strtool::expand_dollar_refs ( const std::string &  text,
const entity_map &  src 
)

Exactly like expand_dollar_refs_inline() but returns a new string which results from the expansions.

The returned string may be the same as the original.

std::size_t s11n::io::strtool::expand_dollar_refs_inline ( std::string &  buffer,
const entity_map &  src 
)

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"].

Referencing a variable which is not set does not expand the variable to an empty value: it is left as-is. Thus expanding ${FOO} when "FOO" is not set will result in "${FOO}".

To get a dollar sign into the resulting string, escape it with a single backslash: this keeps it from being parsed as a ${variable}.

Returns the number of variables expanded.

Note that this function is much *more* efficient than using translate_entities() 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.

Known misgivings:

std::string s11n::io::strtool::first_token ( const std::string &   ) 

Returns the first whitespace-delimited token from the given string, or an empty string if there is no such token.

template<typename ValueT>
ValueT s11n::io::strtool::from ( const std::string &  v,
const ValueT &  dflt = ValueT() 
) [inline]

Lexically casts v to a ValueT, or returns dflt if conversion fails.

Definition at line 266 of file strtool.hpp.

References s11n::Detail::Private::from_string().

int s11n::io::strtool::hex2int ( const std::string &  wd  ) 

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 -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 s11n::io::strtool::int4hexchar ( char  character  ) 

Returns int values for chars '0'-'9', 'a'-'f' and 'A'-'F', else -1.

void s11n::io::strtool::normalize_string ( std::string &   ) 

normalize_string() is like trim_string() and strip_slashes(), combined, plus it removes leading/trailing quotes:

           "this is a \
           sample multi-line, backslash-escaped \
           string."
           

Will translate to:

           this is a sample multi-line, backslash-escaped string.
           

template<typename ValueT>
std::string s11n::io::strtool::quote ( const ValueT &  v,
const std::string &  quote = "\'" 
) [inline]

Returns v as a quoted string, using the given quote character.

Definition at line 377 of file strtool.hpp.

References to().

std::size_t s11n::io::strtool::strip_slashes ( std::string &  str,
const char  slash = '\\' 
)

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.

template<typename ValueT>
std::string s11n::io::strtool::to ( const ValueT &  v  )  [inline]

Lexically casts v to a string.

Definition at line 256 of file strtool.hpp.

References s11n::Detail::Private::to_string().

Referenced by s11n::io::key_value_serializer< NodeType >::operator()(), quote(), and translate().

template<typename ValueT>
std::string s11n::io::strtool::translate ( const ValueT &  v,
const entity_map &  trans,
bool  reverse 
) [inline]

Converts v to a string, applies translate_entities(.

..,trans,reverse ), and returns the resulting string.

Definition at line 343 of file strtool.hpp.

References to(), translate_entities(), and s11n::val().

Referenced by escape(), and unescape().

std::size_t s11n::io::strtool::translate_entities ( std::string &  buffer,
const entity_map &  translation_map,
bool  reverse_translation = false 
)

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.

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 for inclusion in the header.

Referenced by s11n::io::strtool::entity_translator::operator()(), s11n::io::key_value_serializer< NodeType >::operator()(), and translate().

std::string s11n::io::strtool::trim_string ( const std::string &  ,
TrimPolicy  = TrimAll 
)

Trims leading and trailing whitespace from the input string and returns the trimmed string.

std::size_t s11n::io::strtool::trim_string ( std::string &  ,
TrimPolicy  = TrimAll 
)

Trims leading and trailing whitespace from the input string and returns the number of whitespace characters removed.

template<typename ValueT>
std::string s11n::io::strtool::unescape ( const ValueT &  v,
const entity_map &  trans = default_escapes_translations() 
) [inline]

Calls translate( v, trans, true );.

Definition at line 367 of file strtool.hpp.

References translate().


Generated on Sun Apr 27 13:16:05 2008 for libs11n by  doxygen 1.5.3