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

strtool.hpp File Reference

#include <string>
#include <map>
#include <locale>
#include <iostream>
#include <sstream>

Go to the source code of this file.

Namespaces

namespace  s11n
namespace  s11n::io
namespace  s11n::io::strtool
namespace  s11n::io::strtool::STPrivate

Defines

#define s11n_net_s11n_STRINGTOOL_HPP_INCLUDED   1

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

template<typename value_type>
value_type from_string (const std::string &str, const value_type &errorVal) throw ()
 Lexically casts str to a value_type, returning errorVal if the conversion fails.
template<typename value_type>
std::string to_string (const value_type &obj) throw ()
 Returns a string representation of the given object, which must be ostreamble.
std::string from_string (const std::string &str, const std::string &errorVal) throw ()
 Convenience/efficiency overload.
std::string from_string (const char *str, const char *errorVal) throw ()
 Convenience/efficiency overload.
std::string to_string (const char *obj) throw ()
 Convenience/efficiency overload.
std::string to_string (const std::string &obj) throw ()
 Convenience/efficiency overload.
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.


Define Documentation

#define s11n_net_s11n_STRINGTOOL_HPP_INCLUDED   1
 

Definition at line 2 of file strtool.hpp.


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 s11n::io::strtool::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().

std::string from_string const char *  str,
const char *  errorVal
throw () [inline]
 

Convenience/efficiency overload.

Definition at line 84 of file strtool.hpp.

std::string from_string const std::string &  str,
const std::string &  errorVal
throw () [inline]
 

Convenience/efficiency overload.

Definition at line 76 of file strtool.hpp.

template<typename value_type>
value_type from_string const std::string &  str,
const value_type &  errorVal
throw ()
 

Lexically casts str to a value_type, returning errorVal if the conversion fails.

TODO: implement the following suggestion from Kai Unger <kai.unger@hacon.de> (21 Sept 2004):

When the cast is done, you should check if there are unread characters left. For example, casting "1.2this_definitly_is_not_a_number" to double will not result in returning the error value, because conversion of "1.2" to 1.2d succeeds and the rest of the string is ignored.

Definition at line 42 of file strtool.hpp.

Referenced by s11n::Detail::variant::cast_to(), and s11n::io::strtool::from().

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 s11n::io::strtool::quote(), and s11n::io::strtool::to().

Referenced by s11n::io::strtool::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()(), s11n::io::strtool::quote(), and s11n::io::strtool::translate().

std::string to_string const std::string &  obj  )  throw () [inline]
 

Convenience/efficiency overload.

Definition at line 100 of file strtool.hpp.

std::string to_string const char *  obj  )  throw () [inline]
 

Convenience/efficiency overload.

Definition at line 92 of file strtool.hpp.

template<typename value_type>
std::string to_string const value_type &  obj  )  throw ()
 

Returns a string representation of the given object, which must be ostreamble.

Definition at line 58 of file strtool.hpp.

Referenced by s11n::Detail::variant::operator=(), s11n::io::strtool::to(), and s11n::Detail::variant::variant().

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 s11n::io::strtool::to(), s11n::io::strtool::translate_entities(), and s11n::val().

Referenced by s11n::io::strtool::escape(), and s11n::io::strtool::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 s11n::io::strtool::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 s11n::io::strtool::translate().


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