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 "e="\'") |
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. |
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 std::map<std::string,std::string> s11n::io::strtool::entity_map |
typedef std::map<std::string,std::string> s11n::io::strtool::entity_map |
A policy enum used by trim_string().
TrimLeading | Trim only leading spaces. |
TrimTrailing | Trim only trailing spaces. |
TrimAll | Trim leading and trailing spaces. |
Definition at line 144 of file strtool.hpp.
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: '\', '\'', '"'.
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.
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.
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.
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().
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.
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().