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.
static double	toDouble (const std::string &s)
	Converts string 's' to a double.
static int	toInt (const std::string &s)
	Converts string 's' to an int.
static long	toLong (const std::string &s)
	Converts string 's' to a long.
static short	toShort (const std::string &s)
	Converts string 's' to a short.
static unsigned int	toUInt (const std::string &s)
	Converts string 's' to an unsigned int.
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.
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.
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, typically used with escape().
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 &seperators, char escape= '\0', bool remove_escapes=true)
	Splits the string into fields. More...
static bool	splitMatch (const std::string &in, const std::string &s, const std::string &ws=Str::ws())
	Returns true if any of the split parts of 'in' are equal to 's'.
static std::string	splitMatchTail (const std::string &in, const std::string &s, const std::string &ws=Str::ws())
	Splits the input string into parts and looks for a part that starts with 's' and returns the trailing substring. More...
static std::string	join (const std::string &sep, const StringArray &strings)
	Concatenates an array of strings.
static std::string	join (const std::string &sep, const std::set< std::string > &strings)
	Concatenates a set of strings.
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.
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, std::string::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, std::string::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	tailMatch (const std::string &in, const std::string &ending)
	Returns true if the given string has the given ending.
static std::string	ws ()
	A convenience function returning 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 bool	imatch (const std::string &, const std::string &)
	Returns true if the two strings are the same, ignoring case.
static std::string::size_type	ifind (const std::string &s, const std::string &key, std::string::size_type pos=0U)
	Does a case-insensitive std::string::find().
static std::string	unique (std::string s, char c= ' ', char r= ' ')
	Returns a string with repeated 'c' charaters 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

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, std::string::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 off the end.

Definition at line 1037 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 1045 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 250 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 228 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 244 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 266 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 274 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 258 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 561 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 663 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 695 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 134 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 157 of file gstr.cpp.

void G::Str::splitIntoFields ( const std::string &  in, StringArray &  out, const std::string &  seperators, 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 921 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 868 of file gstr.cpp.

std::string G::Str::splitMatchTail ( const std::string &  in, const std::string &  s, const std::string &  ws = Str::ws()  )

static

Splits the input string into parts and looks for a part that starts with 's' and returns the trailing substring.

Definition at line 934 of file gstr.cpp.

std::string G::Str::tail ( const std::string &  in, std::string::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 if off the end.

Definition at line 1051 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 1059 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 556 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.

Definition at line 438 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 433 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.

Definition at line 471 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 576 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.

Definition at line 515 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 104 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 99 of file gstr.cpp.

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

static

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

Single 'c' characters are not replaced.

Definition at line 1144 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 581 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 787 of file gstr.cpp.

---

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

• /home/graeme/videotools/src/glib/gstr.h
• /home/graeme/videotools/src/glib/gstr.cpp