libs11n-1.2.6: s11n::io::strtool Namespace Reference


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

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:

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

s11n::io::strtool Namespace Reference

Classes

Namespaces

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation