Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

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

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
 See translate_entities() for details.

Enumerations

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

Functions

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.
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.
size_t strip_slashes (std::string &str, const char slash= '\\')
 Attempts to remove all backslash-escaped chars from str.
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(...,trans,reverse ), and returns the resulting string.
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.
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 111 of file strtool.hpp.


Enumeration Type Documentation

enum s11n::io::strtool::TrimPolicy
 

A policy enum used by trim_string().

Enumeration values:
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 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& 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 escape const ValueT &  v,
const entity_map trans = default_escapes_translations()
 

Calls translate( v,trans, false);.

Definition at line 357 of file strtool.hpp.

References translate().

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.

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

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.

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:

  • When buffer contains dollar signs which are preceeded by a slash, the slash is stripped even if the $ does not expand to anything. This is arguably behaviour.

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.

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.

Definition at line 266 of file strtool.hpp.

References s11n::io::strtool::STPrivate::from_string().

int 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 int4hexchar char  character  ) 
 

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

void 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 quote const ValueT &  v,
const std::string &  quote = "\'"
 

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

Definition at line 377 of file strtool.hpp.

References quote(), and to().

Referenced by quote().

size_t 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 to const ValueT &  v  ) 
 

Lexically casts v to a string.

Definition at line 256 of file strtool.hpp.

References s11n::io::strtool::STPrivate::to_string().

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

template<typename ValueT>
std::string translate const ValueT &  v,
const entity_map trans,
bool  reverse
 

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().

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.

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()(), s11n::io::funxml_serializer< NodeType >::serialize(), and translate().

std::string trim_string const std::string &  ,
TrimPolicy  = TrimAll
 

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

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.

template<typename ValueT>
std::string unescape const ValueT &  v,
const entity_map trans = default_escapes_translations()
 

Calls translate( v, trans, true );.

Definition at line 367 of file strtool.hpp.

References translate().


Generated on Thu Sep 29 20:01:16 2005 for libs11n-1.1.3-dev by  doxygen 1.4.1