E-MailRelay
Classes | Public Types | Public Member Functions | Static Public Member Functions | List of all members
G::Str Class Reference

A static class which provides string helper functions. More...

#include <gstr.h>

Classes

struct  Limited
 Overload discrimiator for G::Str::toUWhatever() More...
 

Public Types

typedef std::string::size_type size_type
 

Public Member Functions

 G_EXCEPTION_CLASS (Overflow,"string conversion error: over/underflow")
 
 G_EXCEPTION_CLASS (InvalidFormat,"string conversion error: invalid format")
 
 G_EXCEPTION_CLASS (NotEmpty,"internal error: string container not empty")
 

Static Public Member Functions

static bool replace (std::string &s, const std::string &from, const std::string &to, size_type *pos_p=nullptr)
 Replaces 'from' with 'to', starting at offset '*pos_p'. More...
 
static unsigned int replaceAll (std::string &s, const std::string &from, const std::string &to)
 Does a global replace on string 's', replacing all occurances of sub-string 'from' with 'to'. More...
 
static unsigned int replaceAll (std::string &s, const char *from, const char *to)
 A c-string overload, provided for performance reasons.
 
static void removeAll (std::string &, char)
 Removes all occurrences of the character from the string.
 
static void trimLeft (std::string &s, const std::string &ws, size_type limit=0U)
 Trims the lhs of s, taking off up to 'limit' of the 'ws' characters.
 
static void trimRight (std::string &s, const std::string &ws, size_type limit=0U)
 Trims the rhs of s, taking off up to 'limit' of the 'ws' characters.
 
static void trim (std::string &s, const std::string &ws)
 Trims both ends of s, taking off any of the 'ws' characters.
 
static std::string trimmed (const std::string &s, const std::string &ws)
 Returns a trim()med version of s.
 
static bool isNumeric (const std::string &s, bool allow_minus_sign=false)
 Returns true if every character is a decimal digit. More...
 
static bool isPrintableAscii (const std::string &s)
 Returns true if every character is a 7-bit, non-control character (ie. More...
 
static bool isUShort (const std::string &s)
 Returns true if the string can be converted into an unsigned short without throwing an exception. More...
 
static bool isUInt (const std::string &s)
 Returns true if the string can be converted into an unsigned integer without throwing an exception. More...
 
static bool isULong (const std::string &s)
 Returns true if the string can be converted into an unsigned long without throwing an exception. More...
 
static bool isInt (const std::string &s)
 Returns true if the string can be converted into an integer without throwing an exception. More...
 
static std::string fromBool (bool b)
 Converts boolean 'b' to a string.
 
static std::string fromDouble (double d)
 Converts double 'd' to a string.
 
static std::string fromInt (int i)
 Converts int 'i' to a string.
 
static std::string fromLong (long l)
 Converts long 'l' to a string.
 
static std::string fromShort (short s)
 Converts short 's' to a string.
 
static std::string fromUInt (unsigned int ui)
 Converts unsigned int 'ui' to a string.
 
static std::string fromULong (unsigned long ul)
 Converts unsigned long 'ul' to a string.
 
static std::string fromUShort (unsigned short us)
 Converts unsigned short 'us' to a string.
 
static bool toBool (const std::string &s)
 Converts string 's' to a bool. More...
 
static double toDouble (const std::string &s)
 Converts string 's' to a double. More...
 
static int toInt (const std::string &s)
 Converts string 's' to an int. More...
 
static long toLong (const std::string &s)
 Converts string 's' to a long. More...
 
static short toShort (const std::string &s)
 Converts string 's' to a short. More...
 
static unsigned int toUInt (const std::string &s)
 Converts string 's' to an unsigned int. More...
 
static unsigned int toUInt (const std::string &s, Limited)
 Converts string 's' to an unsigned int. More...
 
static unsigned int toUInt (const std::string &s1, const std::string &s2)
 Overload that converts the first string if it can be converted without throwing, or otherwise the second string. More...
 
static unsigned long toULong (const std::string &s, Limited)
 Converts string 's' to an unsigned long. More...
 
static unsigned long toULong (const std::string &s)
 Converts string 's' to an unsigned long. More...
 
static unsigned short toUShort (const std::string &s, Limited)
 Converts string 's' to an unsigned short. More...
 
static unsigned short toUShort (const std::string &s)
 Converts string 's' to an unsigned short. More...
 
static void toUpper (std::string &s)
 Replaces all Latin-1 lowercase characters in string 's' by uppercase characters. More...
 
static void toLower (std::string &s)
 Replaces all Latin-1 uppercase characters in string 's' by lowercase characters. More...
 
static std::string upper (const std::string &s)
 Returns a copy of 's' in which all Latin-1 lowercase characters have been replaced by uppercase characters. More...
 
static std::string lower (const std::string &s)
 Returns a copy of 's' in which all Latin-1 uppercase characters have been replaced by lowercase characters. More...
 
static std::string toPrintableAscii (char c, char escape= '\\')
 Returns a 7-bit printable representation of the given input character.
 
static std::string toPrintableAscii (const std::string &in, char escape= '\\')
 Returns a 7-bit printable representation of the given input string.
 
static std::string toPrintableAscii (const std::wstring &in, wchar_t escape=L'\\')
 Returns a 7-bit printable representation of the given wide input string.
 
static std::string printable (const std::string &in, char escape= '\\')
 Returns a printable represention of the given input string. More...
 
static void escape (std::string &s, char c_escape, const std::string &specials_in, const std::string &specials_out)
 Prefixes each occurrence of one of the special-in characters with the escape character and its corresponding special-out character. More...
 
static void escape (std::string &s, char c_escape, const char *specials_in, const char *specials_out)
 Overload for c-style 'special' strings.
 
static void escape (std::string &s)
 Overload for 'normal' backslash escaping of whitespace.
 
static std::string escaped (const std::string &, char c_escape, const std::string &specials_in, const std::string &specials_out)
 Returns the escape()d string.
 
static std::string escaped (const std::string &, char c_escape, const char *specials_in, const char *specials_out)
 Returns the escape()d string.
 
static std::string escaped (const std::string &)
 Returns the escape()d string.
 
static void unescape (std::string &s, char c_escape, const char *specials_in, const char *specials_out)
 Unescapes the string by replacing e-e with e, e-special-in with special-out, and e-other with other. More...
 
static void unescape (std::string &s)
 Overload for "normal" unescaping where the string has backslash escaping of whitespace. More...
 
static std::string unescaped (const std::string &s)
 Returns the unescape()d version of s.
 
static std::string meta ()
 Returns a list of shell meta-characters with a tilde as the first character. More...
 
static std::string readLineFrom (std::istream &stream, const std::string &eol=std::string())
 Reads a line from the stream using the given line terminator. More...
 
static void readLineFrom (std::istream &stream, const std::string &eol, std::string &result, bool pre_erase_result=true)
 An overload which avoids string copying.
 
static std::string wrap (std::string text, const std::string &prefix_first_line, const std::string &prefix_subsequent_lines, size_type width=70U)
 Does word-wrapping. More...
 
static void splitIntoTokens (const std::string &in, StringArray &out, const std::string &ws)
 Splits the string into 'ws'-delimited tokens. More...
 
static StringArray splitIntoTokens (const std::string &in, const std::string &ws=Str::ws())
 Overload that returns by value.
 
static void splitIntoFields (const std::string &in, StringArray &out, const std::string &separators, char escape= '\0', bool remove_escapes=true)
 Splits the string into fields. More...
 
static StringArray splitIntoFields (const std::string &in, const std::string &ws=Str::ws())
 Overload that returns by value.
 
static std::string dequote (const std::string &, char qq= '\"' , char esc = '\\' , const std::string & ws = Str::ws() )
 Dequotes a string by removing unescaped quotes and escaping quoted whitespace, so "qq-aaa-esc-qq-bbb-ws-ccc-qq" becomes "aaa-qq-bbb-esc-ws-ccc". More...
 
static std::string join (const std::string &sep, const StringArray &strings)
 Concatenates an array of strings with separators.
 
static std::string join (const std::string &sep, const std::set< std::string > &strings)
 Concatenates a set of strings with separators.
 
static std::string join (const std::string &sep, const std::string &s1, const std::string &s2, const std::string &s3=std::string(), const std::string &s4=std::string(), const std::string &s5=std::string(), const std::string &s6=std::string(), const std::string &s7=std::string(), const std::string &s8=std::string(), const std::string &s9=std::string())
 Concatenates a small number of strings with separators. More...
 
static std::string join (const std::string &sep, const StringMap &, const std::string &eq=std::string(1U,'='), const std::string &tail=std::string())
 Contatenates entries in a map, where an entry is "<key><eq><value><tail>".
 
static std::set< std::string > keySet (const StringMap &string_map)
 Extracts the keys from a map of strings.
 
static std::string head (const std::string &in, size_type pos, const std::string &default_=std::string())
 Returns the first part of the string up to just before the given position. More...
 
static std::string head (const std::string &in, const std::string &sep, bool default_empty=true)
 Overload taking a separator string, and with the default as either the input string or the empty string. More...
 
static std::string tail (const std::string &in, size_type pos, const std::string &default_=std::string())
 Returns the last part of the string after the given position. More...
 
static std::string tail (const std::string &in, const std::string &sep, bool default_empty=true)
 Overload taking a separator string, and with the default as either the input string or the empty string. More...
 
static bool match (const std::string &, const std::string &)
 Returns true if the two strings are the same.
 
static bool match (const StringArray &, const std::string &)
 Returns true if any string in the array matches the given string.
 
static bool imatch (const std::string &, const std::string &)
 Returns true if the two strings are the same, ignoring Latin-1 case. More...
 
static bool imatch (const StringArray &, const std::string &)
 Returns true if any string in the array matches the given string, ignoring Latin-1 case. More...
 
static bool tailMatch (const std::string &in, const std::string &ending)
 Returns true if the string has the given ending (or ending is empty).
 
static bool tailMatch (const StringArray &in, const std::string &ending)
 Returns true if any string in the array has the given ending (or ending is empty). More...
 
static bool headMatch (const std::string &in, const std::string &head)
 Returns true if the string has the given start (or head is empty).
 
static bool headMatch (const StringArray &in, const std::string &head)
 Returns true if any string in the array has the given start (or head is empty). More...
 
static std::string headMatchResidue (const StringArray &in, const std::string &head)
 Returns the unmatched part of the first string in the array that has the given start. More...
 
static std::string ws ()
 Returns a string of standard whitespace characters.
 
static std::string positive ()
 Returns a default positive string. See isPositive().
 
static std::string negative ()
 Returns a default negative string. See isNegative().
 
static bool isPositive (const std::string &)
 Returns true if the string has a positive meaning, such as "1", "true", "yes".
 
static bool isNegative (const std::string &)
 Returns true if the string has a negative meaning, such as "0", "false", "no".
 
static size_type ifind (const std::string &s, const std::string &key, size_type pos=0U)
 Returns the position of the key in 's' using a Latin-1 case-insensitive search. More...
 
static std::string unique (std::string s, char c= ' ', char r= ' ')
 Returns a string with repeated 'c' characters replaced by one 'r' character. More...
 

Detailed Description

A static class which provides string helper functions.

Definition at line 42 of file gstr.h.

Member Function Documentation

std::string G::Str::dequote ( const std::string &  s,
char  qq = '\"',
char  esc = '\\',
const std::string &  ws = Str::ws() 
)
static

Dequotes a string by removing unescaped quotes and escaping quoted whitespace, so "qq-aaa-esc-qq-bbb-ws-ccc-qq" becomes "aaa-qq-bbb-esc-ws-ccc".

Definition at line 99 of file gstr.cpp.

void G::Str::escape ( std::string &  s,
char  c_escape,
const std::string &  specials_in,
const std::string &  specials_out 
)
static

Prefixes each occurrence of one of the special-in characters with the escape character and its corresponding special-out character.

If the specials-in string contains the nul character it must be at the end, otherwise the two specials strings must be the same length. The specials-out string cannot contain the nul character.

The specials-in string should normally include the escape character itself, otherwise unescaping will not recover the original.

Definition at line 66 of file gstr.cpp.

std::string G::Str::head ( const std::string &  in,
size_type  pos,
const std::string &  default_ = std::string() 
)
static

Returns the first part of the string up to just before the given position.

The character at pos is not returned. Returns the supplied default if pos is npos. Returns the whole string if pos is one-or-more off the end.

Definition at line 1088 of file gstr.cpp.

std::string G::Str::head ( const std::string &  in,
const std::string &  sep,
bool  default_empty = true 
)
static

Overload taking a separator string, and with the default as either the input string or the empty string.

If the separator occurs more than once in the input then only the first occurence is relevant.

Definition at line 1096 of file gstr.cpp.

bool G::Str::headMatch ( const StringArray &  in,
const std::string &  head 
)
static

Returns true if any string in the array has the given start (or head is empty).

Definition at line 1155 of file gstr.cpp.

std::string G::Str::headMatchResidue ( const StringArray &  in,
const std::string &  head 
)
static

Returns the unmatched part of the first string in the array that has the given start.

Returns the empty string if nothing matches or if the first match is an exact match.

Definition at line 1161 of file gstr.cpp.

std::string::size_type G::Str::ifind ( const std::string &  s,
const std::string &  key,
size_type  pos = 0U 
)
static

Returns the position of the key in 's' using a Latin-1 case-insensitive search.

The locale is ignored.

Definition at line 1236 of file gstr.cpp.

bool G::Str::imatch ( const std::string &  a,
const std::string &  b 
)
static

Returns true if the two strings are the same, ignoring Latin-1 case.

The locale is ignored.

Definition at line 1220 of file gstr.cpp.

bool G::Str::imatch ( const StringArray &  a,
const std::string &  b 
)
static

Returns true if any string in the array matches the given string, ignoring Latin-1 case.

The locale is ignored.

Definition at line 1225 of file gstr.cpp.

bool G::Str::isInt ( const std::string &  s)
static

Returns true if the string can be converted into an integer without throwing an exception.

Definition at line 288 of file gstr.cpp.

bool G::Str::isNumeric ( const std::string &  s,
bool  allow_minus_sign = false 
)
static

Returns true if every character is a decimal digit.

Empty strings return true.

Definition at line 266 of file gstr.cpp.

bool G::Str::isPrintableAscii ( const std::string &  s)
static

Returns true if every character is a 7-bit, non-control character (ie.

0x20<=c<0x7f). Empty strings return true.

Definition at line 282 of file gstr.cpp.

bool G::Str::isUInt ( const std::string &  s)
static

Returns true if the string can be converted into an unsigned integer without throwing an exception.

Definition at line 304 of file gstr.cpp.

bool G::Str::isULong ( const std::string &  s)
static

Returns true if the string can be converted into an unsigned long without throwing an exception.

Definition at line 312 of file gstr.cpp.

bool G::Str::isUShort ( const std::string &  s)
static

Returns true if the string can be converted into an unsigned short without throwing an exception.

Definition at line 296 of file gstr.cpp.

std::string G::Str::join ( const std::string &  sep,
const std::string &  s1,
const std::string &  s2,
const std::string &  s3 = std::string(),
const std::string &  s4 = std::string(),
const std::string &  s5 = std::string(),
const std::string &  s6 = std::string(),
const std::string &  s7 = std::string(),
const std::string &  s8 = std::string(),
const std::string &  s9 = std::string() 
)
static

Concatenates a small number of strings with separators.

In this overload empty strings are ignored.

Definition at line 1039 of file gstr.cpp.

std::string G::Str::lower ( const std::string &  s)
static

Returns a copy of 's' in which all Latin-1 uppercase characters have been replaced by lowercase characters.

Definition at line 599 of file gstr.cpp.

std::string G::Str::meta ( )
static

Returns a list of shell meta-characters with a tilde as the first character.

Does not contain the nul character. This is typically used with escape().

Definition at line 1083 of file gstr.cpp.

std::string G::Str::printable ( const std::string &  in,
char  escape = '\\' 
)
static

Returns a printable represention of the given input string.

Typically used to prevent escape sequences getting into log files.

Definition at line 701 of file gstr.cpp.

std::string G::Str::readLineFrom ( std::istream &  stream,
const std::string &  eol = std::string() 
)
static

Reads a line from the stream using the given line terminator.

The line terminator is not part of the returned string. The terminator defaults to the newline.

Note that alternatives in the standard library such as std::istream::getline() or std::getline(stream,string) in the standard "string" header are limited to a single character as the terminator.

The stream's fail bit is set if (1) an empty string was returned because the stream was already at eof or (2) the string overflowed. Therefore, ignoring overflow, if the stream ends in an incomplete line that line fragment is returned with the stream's eof flag set but the fail bit reset and the next attempted read will return an empty string with the fail bit set. If the stream ends with a complete line then the last line is returned with eof and fail bits reset and the next attempted read will return an empty string with eof and fail bits set.

Boolean tests on a stream are equivalent to using fail(), and fail() tests for failbit or badbit, so to process even incomplete lines at the end we can use a read loop like "while(s.good()){read(s);if(s)...}".

Definition at line 733 of file gstr.cpp.

bool G::Str::replace ( std::string &  s,
const std::string &  from,
const std::string &  to,
size_type *  pos_p = nullptr 
)
static

Replaces 'from' with 'to', starting at offset '*pos_p'.

Returns true if a substitution was made, and adjusts '*pos_p' by to.length().

Definition at line 172 of file gstr.cpp.

unsigned int G::Str::replaceAll ( std::string &  s,
const std::string &  from,
const std::string &  to 
)
static

Does a global replace on string 's', replacing all occurances of sub-string 'from' with 'to'.

Returns the number of substitutions made. Consider using in a while loop if 'from' is more than one character.

Definition at line 195 of file gstr.cpp.

void G::Str::splitIntoFields ( const std::string &  in,
StringArray &  out,
const std::string &  separators,
char  escape = '\0',
bool  remove_escapes = true 
)
static

Splits the string into fields.

Duplicated, leading and trailing separator characters are all significant. Ths output array is cleared first.

If a non-null escape character is given then escaped separators do not result in a split. If the 'remove-escapes' parameter is true then all unescaped escapes are removed from the output; this is generally the preferred behaviour for nested escaping. If the 'remove-escapes' parameter is false then escapes are not removed; unescaped escapes are used to prevent splitting but they remain in the output.

Definition at line 975 of file gstr.cpp.

void G::Str::splitIntoTokens ( const std::string &  in,
StringArray &  out,
const std::string &  ws 
)
static

Splits the string into 'ws'-delimited tokens.

The behaviour is like strtok() in that adjacent delimiters count as one and leading and trailing delimiters are ignored. The output array is cleared first.

Definition at line 908 of file gstr.cpp.

std::string G::Str::tail ( const std::string &  in,
size_type  pos,
const std::string &  default_ = std::string() 
)
static

Returns the last part of the string after the given position.

The character at pos is not returned. Returns the supplied default if pos is npos. Returns the empty string if pos is one-or-more off the end.

Definition at line 1102 of file gstr.cpp.

std::string G::Str::tail ( const std::string &  in,
const std::string &  sep,
bool  default_empty = true 
)
static

Overload taking a separator string, and with the default as either the input string or the empty string.

If the separator occurs more than once in the input then only the first occurence is relevant.

Definition at line 1110 of file gstr.cpp.

bool G::Str::tailMatch ( const StringArray &  in,
const std::string &  ending 
)
static

Returns true if any string in the array has the given ending (or ending is empty).

Definition at line 1133 of file gstr.cpp.

bool G::Str::toBool ( const std::string &  s)
static

Converts string 's' to a bool.

Exception: InvalidFormat

Definition at line 374 of file gstr.cpp.

double G::Str::toDouble ( const std::string &  s)
static

Converts string 's' to a double.

Exception: Overflow Exception: InvalidFormat

Definition at line 392 of file gstr.cpp.

int G::Str::toInt ( const std::string &  s)
static

Converts string 's' to an int.

Exception: Overflow Exception: InvalidFormat

Definition at line 406 of file gstr.cpp.

long G::Str::toLong ( const std::string &  s)
static

Converts string 's' to a long.

Exception: Overflow Exception: InvalidFormat

Definition at line 427 of file gstr.cpp.

void G::Str::toLower ( std::string &  s)
static

Replaces all Latin-1 uppercase characters in string 's' by lowercase characters.

Definition at line 594 of file gstr.cpp.

short G::Str::toShort ( const std::string &  s)
static

Converts string 's' to a short.

Exception: Overflow Exception: InvalidFormat

Definition at line 450 of file gstr.cpp.

unsigned int G::Str::toUInt ( const std::string &  s)
static

Converts string 's' to an unsigned int.

Exception: Overflow Exception: InvalidFormat

Definition at line 488 of file gstr.cpp.

unsigned int G::Str::toUInt ( const std::string &  s,
Limited   
)
static

Converts string 's' to an unsigned int.

Very large numeric strings are limited to the maximum value of the numeric type, without an Overflow exception.

Exception: InvalidFormat

Definition at line 476 of file gstr.cpp.

unsigned int G::Str::toUInt ( const std::string &  s1,
const std::string &  s2 
)
static

Overload that converts the first string if it can be converted without throwing, or otherwise the second string.

Definition at line 471 of file gstr.cpp.

unsigned long G::Str::toULong ( const std::string &  s,
Limited   
)
static

Converts string 's' to an unsigned long.

Very large numeric strings are limited to the maximum value of the numeric type, without an Overflow exception.

Exception: InvalidFormat

Definition at line 509 of file gstr.cpp.

unsigned long G::Str::toULong ( const std::string &  s)
static

Converts string 's' to an unsigned long.

Exception: Overflow Exception: InvalidFormat

Definition at line 521 of file gstr.cpp.

void G::Str::toUpper ( std::string &  s)
static

Replaces all Latin-1 lowercase characters in string 's' by uppercase characters.

Definition at line 614 of file gstr.cpp.

unsigned short G::Str::toUShort ( const std::string &  s,
Limited   
)
static

Converts string 's' to an unsigned short.

Very large numeric strings are limited to the maximum value of the numeric type, without an Overflow exception.

Exception: InvalidFormat

Definition at line 553 of file gstr.cpp.

unsigned short G::Str::toUShort ( const std::string &  s)
static

Converts string 's' to an unsigned short.

Exception: Overflow Exception: InvalidFormat

Definition at line 565 of file gstr.cpp.

void G::Str::unescape ( std::string &  s,
char  c_escape,
const char *  specials_in,
const char *  specials_out 
)
static

Unescapes the string by replacing e-e with e, e-special-in with special-out, and e-other with other.

If the specials-out string includes the nul character then it must be at the end, otherwise the two specials strings must be the same length.

Definition at line 142 of file gstr.cpp.

void G::Str::unescape ( std::string &  s)
static

Overload for "normal" unescaping where the string has backslash escaping of whitespace.

Definition at line 137 of file gstr.cpp.

std::string G::Str::unique ( std::string  s,
char  c = ' ',
char  r = ' ' 
)
static

Returns a string with repeated 'c' characters replaced by one 'r' character.

Single 'c' characters are not replaced.

Definition at line 1268 of file gstr.cpp.

std::string G::Str::upper ( const std::string &  s)
static

Returns a copy of 's' in which all Latin-1 lowercase characters have been replaced by uppercase characters.

Definition at line 619 of file gstr.cpp.

std::string G::Str::wrap ( std::string  text,
const std::string &  prefix_first_line,
const std::string &  prefix_subsequent_lines,
size_type  width = 70U 
)
static

Does word-wrapping.

The return value is a string with embedded newlines.

Definition at line 827 of file gstr.cpp.


The documentation for this class was generated from the following files: