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

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

#include <gstr.h>

Classes

struct  Hex
 Overload discrimiator for G::Str::toUWhatever() indicating hexadecimal strings. More...
 
struct  Limited
 Overload discrimiator for G::Str::toUWhatever() requesting a range-limited result. More...
 

Static Public Member Functions

static bool replace (std::string &s, const std::string &from, const std::string &to, std::size_t *pos_p=nullptr)
 Replaces 'from' with 'to', starting at offset '*pos_p'. More...
 
static void replace (std::string &s, char from, char to)
 Replaces all 'from' characters with 'to'. More...
 
static void replace (StringArray &, char from, char to)
 Replaces 'from' characters with 'to' in all the strings in the array. 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 occurrences 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. More...
 
static std::string replaced (const std::string &s, char from, char to)
 Returns the string 's' with all occurrences of 'from' replaced by 'to'. More...
 
static void removeAll (std::string &, char)
 Removes all occurrences of the character from the string. See also only(). More...
 
static std::string & trimLeft (std::string &s, string_view ws, std::size_t limit=0U)
 Trims the lhs of s, taking off up to 'limit' of the 'ws' characters. More...
 
static std::string & trimRight (std::string &s, string_view ws, std::size_t limit=0U)
 Trims the rhs of s, taking off up to 'limit' of the 'ws' characters. More...
 
static std::string & trim (std::string &s, string_view ws)
 Trims both ends of s, taking off any of the 'ws' characters. More...
 
static std::string trimmed (const std::string &s, string_view ws)
 Returns a trim()med version of s. More...
 
static std::string trimmed (std::string &&s, string_view ws)
 Returns a trim()med version of s. More...
 
static bool isNumeric (const std::string &s, bool allow_minus_sign=false)
 Returns true if every character is a decimal digit. More...
 
static bool isHex (const std::string &s)
 Returns true if every character is a hexadecimal 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. More...
 
static std::string fromDouble (double d)
 Converts double 'd' to a string. More...
 
static std::string fromInt (int i)
 Converts int 'i' to a string. More...
 
static std::string fromLong (long l)
 Converts long 'l' to a string. More...
 
static std::string fromShort (short s)
 Converts short 's' to a string. More...
 
static std::string fromUInt (unsigned int ui)
 Converts unsigned int 'ui' to a string. More...
 
static std::string fromULong (unsigned long ul)
 Converts unsigned long 'ul' to a string. More...
 
static std::string fromUShort (unsigned short us)
 Converts unsigned short 'us' to a string. More...
 
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, Hex)
 An overload for hexadecimal strings. More...
 
static unsigned long toULong (const std::string &s, Hex, Limited)
 An overload for hexadecimal strings where overflow results in the return of the maximum value. More...
 
template<typename T >
static T toUnsigned (const char *p, const char *end, bool &overflow, bool &invalid) noexcept
 Low-level conversion from an unsigned decimal string to a number. More...
 
template<typename T >
static T toUnsigned (const char *&p, const char *end, bool &overflow) noexcept
 Low-level conversion from an unsigned decimal string to a number. More...
 
static unsigned long toULong (const std::string &s)
 Converts string 's' to an unsigned long. More...
 
static unsigned long toULong (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 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 lower-case characters in string 's' by upper-case characters. More...
 
static void toLower (std::string &s)
 Replaces all Latin-1 upper-case characters in string 's' by lower-case characters. More...
 
static std::string upper (const std::string &s)
 Returns a copy of 's' in which all Latin-1 lower-case characters have been replaced by upper-case characters. More...
 
static std::string lower (const std::string &s)
 Returns a copy of 's' in which all Latin-1 upper-case characters have been replaced by lower-case characters. More...
 
static std::string toPrintableAscii (const std::string &in, char escape='\\')
 Returns a 7-bit printable representation of the given input string. More...
 
static std::string toPrintableAscii (const std::wstring &in, wchar_t escape=L'\\')
 Returns a 7-bit printable representation of the given wide input string. More...
 
static std::string printable (const std::string &in, char escape='\\')
 Returns a printable representation of the given input string, using chacter code ranges 0x20 to 0x7e and 0xa0 to 0xfe inclusive. More...
 
static std::string printable (std::string &&in, char escape='\\')
 Returns a printable representation of the given input string, using chacter code ranges 0x20 to 0x7e and 0xa0 to 0xfe inclusive. More...
 
static std::string only (const std::string &allow_chars, const std::string &s)
 Returns the 's' with all occurrences of the characters not appearing in the fist string deleted. 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. More...
 
static void escape (std::string &s)
 Overload for 'normal' backslash escaping of whitespace. More...
 
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. More...
 
static std::string escaped (const std::string &, char c_escape, const char *specials_in, const char *specials_out)
 Returns the escape()d string. More...
 
static std::string escaped (const std::string &)
 Returns the escape()d string. More...
 
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. More...
 
static string_view 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. More...
 
static void splitIntoTokens (const std::string &in, StringArray &out, string_view ws, char esc='\0')
 Splits the string into 'ws'-delimited tokens. More...
 
static StringArray splitIntoTokens (const std::string &in, string_view ws=Str::ws(), char esc='\0')
 Overload that returns by value. More...
 
static void splitIntoFields (const std::string &in, StringArray &out, string_view ws, char escape='\0', bool remove_escapes=true)
 Splits the string into fields. More...
 
static StringArray splitIntoFields (const std::string &in, string_view ws=Str::ws())
 Overload that returns by value. More...
 
static std::string dequote (const std::string &, char qq='\"' , char esc = '\\' , string_view ws = Str::ws() , string_view nbws = 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. More...
 
static std::string join (const std::string &sep, const std::set< std::string > &strings)
 Concatenates a set of strings with separators. More...
 
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())
 Concatenates entries in a map, where an entry is "<key><eq><value><tail>". More...
 
static std::set< std::string > keySet (const StringMap &string_map)
 Extracts the keys from a map of strings. More...
 
static StringArray keys (const StringMap &string_map)
 Extracts the keys from a map of strings. More...
 
static std::string head (const std::string &in, std::size_t 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::size_t 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. More...
 
static bool match (const StringArray &, const std::string &)
 Returns true if any string in the array matches the given string. More...
 
static bool iless (const std::string &, const std::string &)
 Returns true if the first string is lexicographically less than the first, after Latin-1 lower-case letters have been folded to upper-case. More...
 
static bool imatch (char, char)
 Returns true if the two characters are the same, ignoring Latin-1 case. More...
 
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 std::size_t ifind (const std::string &s, const std::string &key, std::size_t pos=0U)
 Returns the position of the key in 's' using a Latin-1 case-insensitive search. More...
 
static bool tailMatch (const std::string &in, const std::string &ending)
 Returns true if the string has the given ending (or the given ending is empty). More...
 
static bool tailMatch (const StringArray &in, const std::string &ending)
 Returns true if any string in the array has the given ending (or the given 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). More...
 
static bool headMatch (const std::string &in, const char *head)
 A c-string overload. More...
 
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 string_view ws ()
 Returns a string of standard whitespace characters. More...
 
static string_view alnum ()
 Returns a string of seven-bit alphanumeric characters, ie A-Z, a-z and 0-9. More...
 
static std::string positive ()
 Returns a default positive string. See isPositive(). More...
 
static std::string negative ()
 Returns a default negative string. See isNegative(). More...
 
static bool isPositive (const std::string &)
 Returns true if the string has a positive meaning, such as "1", "true", "yes". More...
 
static bool isNegative (const std::string &)
 Returns true if the string has a negative meaning, such as "0", "false", "no". More...
 
static std::string unique (const std::string &s, char c, char r)
 Returns a string with repeated 'c' characters replaced by one 'r' character. More...
 
static std::string unique (const std::string &s, char c)
 An overload that replaces repeated 'c' characters by one 'c' character. More...
 
static StringArray::iterator keepMatch (StringArray::iterator begin, StringArray::iterator end, const StringArray &match_list, bool ignore_case=false)
 Removes items in the begin/end list that do not match any of the elements in the match-list (whitelist), but keeps everything (by returning 'end') if the match-list is empty. More...
 
static StringArray::iterator removeMatch (StringArray::iterator begin, StringArray::iterator end, const StringArray &match_list, bool ignore_case=false)
 Removes items in the begin/end list that match one of the elements in the match-list (blocklist). More...
 
static errno_t strncpy_s (char *dst, std::size_t n_dst, const char *src, std::size_t count) noexcept
 Does the same as windows strncpy_s(). More...
 

Static Public Attributes

static constexpr std::size_t truncate = (~(static_cast<std::size_t>(0U)))
 A special value for the G::Str::strncpy_s() 'count' parameter. More...
 

Detailed Description

A static class which provides string helper functions.

Definition at line 45 of file gstr.h.

Member Function Documentation

◆ alnum()

G::string_view G::Str::alnum ( )
static

Returns a string of seven-bit alphanumeric characters, ie A-Z, a-z and 0-9.

Definition at line 1261 of file gstr.cpp.

◆ dequote()

std::string G::Str::dequote ( const std::string &  s,
char  qq = '\"',
char  esc = '\\',
string_view  ws = Str::ws(),
string_view  nbws = 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".

Escaped whitespace characters within quotes can optionally be converted to non-breaking equivalents.

Definition at line 167 of file gstr.cpp.

◆ escape() [1/3]

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

Overload for 'normal' backslash escaping of whitespace.

Definition at line 145 of file gstr.cpp.

◆ escape() [2/3]

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

Overload for c-style 'special' strings.

Definition at line 151 of file gstr.cpp.

◆ escape() [3/3]

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 158 of file gstr.cpp.

◆ escaped() [1/3]

std::string G::Str::escaped ( const std::string &  s_in)
static

Returns the escape()d string.

Definition at line 94 of file gstr.cpp.

◆ escaped() [2/3]

std::string G::Str::escaped ( const std::string &  s_in,
char  c_escape,
const char *  specials_in,
const char *  specials_out 
)
static

Returns the escape()d string.

Definition at line 109 of file gstr.cpp.

◆ escaped() [3/3]

std::string G::Str::escaped ( const std::string &  s_in,
char  c_escape,
const std::string &  specials_in,
const std::string &  specials_out 
)
static

Returns the escape()d string.

Definition at line 101 of file gstr.cpp.

◆ fromBool()

std::string G::Str::fromBool ( bool  b)
static

Converts boolean 'b' to a string.

Definition at line 462 of file gstr.cpp.

◆ fromDouble()

std::string G::Str::fromDouble ( double  d)
static

Converts double 'd' to a string.

Definition at line 467 of file gstr.cpp.

◆ fromInt()

std::string G::Str::fromInt ( int  i)
inlinestatic

Converts int 'i' to a string.

Definition at line 561 of file gstr.h.

◆ fromLong()

std::string G::Str::fromLong ( long  l)
inlinestatic

Converts long 'l' to a string.

Definition at line 567 of file gstr.h.

◆ fromShort()

std::string G::Str::fromShort ( short  s)
inlinestatic

Converts short 's' to a string.

Definition at line 573 of file gstr.h.

◆ fromUInt()

std::string G::Str::fromUInt ( unsigned int  ui)
inlinestatic

Converts unsigned int 'ui' to a string.

Definition at line 579 of file gstr.h.

◆ fromULong()

std::string G::Str::fromULong ( unsigned long  ul)
inlinestatic

Converts unsigned long 'ul' to a string.

Definition at line 585 of file gstr.h.

◆ fromUShort()

std::string G::Str::fromUShort ( unsigned short  us)
inlinestatic

Converts unsigned short 'us' to a string.

Definition at line 591 of file gstr.h.

◆ head() [1/2]

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 occurrence is relevant.

Definition at line 1281 of file gstr.cpp.

◆ head() [2/2]

std::string G::Str::head ( const std::string &  in,
std::size_t  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 1273 of file gstr.cpp.

◆ headMatch() [1/3]

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

A c-string overload.

Definition at line 1315 of file gstr.cpp.

◆ headMatch() [2/3]

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

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

Definition at line 1322 of file gstr.cpp.

◆ headMatch() [3/3]

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 1329 of file gstr.cpp.

◆ headMatchResidue()

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 1335 of file gstr.cpp.

◆ ifind()

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

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

Returns std::string::npos if not found. The locale is ignored.

Definition at line 1442 of file gstr.cpp.

◆ iless()

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

Returns true if the first string is lexicographically less than the first, after Latin-1 lower-case letters have been folded to upper-case.

Definition at line 1402 of file gstr.cpp.

◆ imatch() [1/3]

bool G::Str::imatch ( char  c1,
char  c2 
)
static

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

Definition at line 1414 of file gstr.cpp.

◆ imatch() [2/3]

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 1429 of file gstr.cpp.

◆ imatch() [3/3]

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 1435 of file gstr.cpp.

◆ isHex()

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

Returns true if every character is a hexadecimal digit.

Empty strings return true.

Definition at line 414 of file gstr.cpp.

◆ isInt()

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 426 of file gstr.cpp.

◆ isNegative()

bool G::Str::isNegative ( const std::string &  s_in)
static

Returns true if the string has a negative meaning, such as "0", "false", "no".

Definition at line 1362 of file gstr.cpp.

◆ isNumeric()

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 405 of file gstr.cpp.

◆ isPositive()

bool G::Str::isPositive ( const std::string &  s_in)
static

Returns true if the string has a positive meaning, such as "1", "true", "yes".

Definition at line 1356 of file gstr.cpp.

◆ isPrintableAscii()

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 420 of file gstr.cpp.

◆ isUInt()

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 444 of file gstr.cpp.

◆ isULong()

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 453 of file gstr.cpp.

◆ isUShort()

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 435 of file gstr.cpp.

◆ join() [1/4]

std::string G::Str::join ( const std::string &  sep,
const std::set< std::string > &  strings 
)
static

Concatenates a set of strings with separators.

Definition at line 1204 of file gstr.cpp.

◆ join() [2/4]

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 1213 of file gstr.cpp.

◆ join() [3/4]

std::string G::Str::join ( const std::string &  sep,
const StringArray strings 
)
static

Concatenates an array of strings with separators.

Definition at line 1195 of file gstr.cpp.

◆ join() [4/4]

std::string G::Str::join ( const std::string &  sep,
const StringMap map,
const std::string &  eq = std::string(1U,'='),
const std::string &  tail = std::string() 
)
static

Concatenates entries in a map, where an entry is "<key><eq><value><tail>".

Definition at line 1182 of file gstr.cpp.

◆ keepMatch()

G::StringArray::iterator G::Str::keepMatch ( StringArray::iterator  begin,
StringArray::iterator  end,
const StringArray match_list,
bool  ignore_case = false 
)
static

Removes items in the begin/end list that do not match any of the elements in the match-list (whitelist), but keeps everything (by returning 'end') if the match-list is empty.

Returns an iterator for erase().

Definition at line 1498 of file gstr.cpp.

◆ keys()

G::StringArray G::Str::keys ( const StringMap string_map)
static

Extracts the keys from a map of strings.

Definition at line 1246 of file gstr.cpp.

◆ keySet()

std::set< std::string > G::Str::keySet ( const StringMap string_map)
static

Extracts the keys from a map of strings.

Definition at line 1238 of file gstr.cpp.

◆ lower()

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

Returns a copy of 's' in which all Latin-1 upper-case characters have been replaced by lower-case characters.

Definition at line 741 of file gstr.cpp.

◆ match() [1/2]

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

Returns true if the two strings are the same.

Definition at line 1368 of file gstr.cpp.

◆ match() [2/2]

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

Returns true if any string in the array matches the given string.

Definition at line 1373 of file gstr.cpp.

◆ meta()

G::string_view 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 1267 of file gstr.cpp.

◆ negative()

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

Returns a default negative string. See isNegative().

Definition at line 1351 of file gstr.cpp.

◆ only()

std::string G::Str::only ( const std::string &  allow_chars,
const std::string &  s 
)
static

Returns the 's' with all occurrences of the characters not appearing in the fist string deleted.

Definition at line 323 of file gstr.cpp.

◆ positive()

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

Returns a default positive string. See isPositive().

Definition at line 1346 of file gstr.cpp.

◆ printable() [1/2]

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

Returns a printable representation of the given input string, using chacter code ranges 0x20 to 0x7e and 0xa0 to 0xfe inclusive.

Typically used to prevent escape sequences getting into log files.

Definition at line 885 of file gstr.cpp.

◆ printable() [2/2]

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

Returns a printable representation of the given input string, using chacter code ranges 0x20 to 0x7e and 0xa0 to 0xfe inclusive.

Typically used to prevent escape sequences getting into log files.

Definition at line 894 of file gstr.cpp.

◆ readLineFrom() [1/2]

void G::Str::readLineFrom ( std::istream &  stream,
const std::string &  eol,
std::string &  result,
bool  pre_erase_result = true 
)
static

An overload which avoids string copying.

Definition at line 976 of file gstr.cpp.

◆ readLineFrom() [2/2]

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 924 of file gstr.cpp.

◆ removeAll()

void G::Str::removeAll ( std::string &  s,
char  c 
)
static

Removes all occurrences of the character from the string. See also only().

Definition at line 318 of file gstr.cpp.

◆ removeMatch()

G::StringArray::iterator G::Str::removeMatch ( StringArray::iterator  begin,
StringArray::iterator  end,
const StringArray match_list,
bool  ignore_case = false 
)
static

Removes items in the begin/end list that match one of the elements in the match-list (blocklist).

(Removes nothing if the match-list is empty.) Returns an iterator for erase().

Definition at line 1508 of file gstr.cpp.

◆ replace() [1/3]

void G::Str::replace ( std::string &  s,
char  from,
char  to 
)
static

Replaces all 'from' characters with 'to'.

Definition at line 249 of file gstr.cpp.

◆ replace() [2/3]

bool G::Str::replace ( std::string &  s,
const std::string &  from,
const std::string &  to,
std::size_t *  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 264 of file gstr.cpp.

◆ replace() [3/3]

void G::Str::replace ( StringArray a,
char  from,
char  to 
)
static

Replaces 'from' characters with 'to' in all the strings in the array.

Definition at line 258 of file gstr.cpp.

◆ replaceAll() [1/2]

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

A c-string overload, provided for performance reasons.

Definition at line 295 of file gstr.cpp.

◆ replaceAll() [2/2]

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 occurrences 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 287 of file gstr.cpp.

◆ replaced()

std::string G::Str::replaced ( const std::string &  s,
char  from,
char  to 
)
static

Returns the string 's' with all occurrences of 'from' replaced by 'to'.

Definition at line 311 of file gstr.cpp.

◆ splitIntoFields() [1/2]

G::StringArray G::Str::splitIntoFields ( const std::string &  in,
string_view  ws = Str::ws() 
)
static

Overload that returns by value.

Definition at line 1153 of file gstr.cpp.

◆ splitIntoFields() [2/2]

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

Splits the string into fields.

Duplicated, leading and trailing separator characters are all significant. The 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 1146 of file gstr.cpp.

◆ splitIntoTokens() [1/2]

G::StringArray G::Str::splitIntoTokens ( const std::string &  in,
string_view  ws = Str::ws(),
char  esc = '\0' 
)
static

Overload that returns by value.

Definition at line 1082 of file gstr.cpp.

◆ splitIntoTokens() [2/2]

void G::Str::splitIntoTokens ( const std::string &  in,
StringArray out,
string_view  ws,
char  esc = '\0' 
)
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 not cleared first; new tokens are appended to the output list. If the escape character is supplied then it can be used to escape whitespace characters, preventing a split, with those escape characters being consumed in the process. For shell-like tokenising use dequote() before splitIntoTokens(), and revert the non-breaking spaces afterwards.

Definition at line 1073 of file gstr.cpp.

◆ strncpy_s()

errno_t G::Str::strncpy_s ( char *  dst,
std::size_t  n_dst,
const char *  src,
std::size_t  count 
)
staticnoexcept

Does the same as windows strncpy_s().

Copies count characters from src to dst and adds a terminator character, but fails if dst is too small. If the count is 'truncate' then as much of src is copied as will fit in dst, allowing for the terminator character. Returns zero on success or on truncation (unlike windows strncpy_s()).

Definition at line 1528 of file gstr.cpp.

◆ tail() [1/2]

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 occurrence is relevant.

Definition at line 1295 of file gstr.cpp.

◆ tail() [2/2]

std::string G::Str::tail ( const std::string &  in,
std::size_t  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 1287 of file gstr.cpp.

◆ tailMatch() [1/2]

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

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

Definition at line 1302 of file gstr.cpp.

◆ tailMatch() [2/2]

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 the given ending is empty).

Definition at line 1309 of file gstr.cpp.

◆ toBool()

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

Converts string 's' to a bool.

Exception: InvalidFormat

Definition at line 474 of file gstr.cpp.

◆ toDouble()

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

Converts string 's' to a double.

Exception: Overflow Exception: InvalidFormat

Definition at line 487 of file gstr.cpp.

◆ toInt()

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

Converts string 's' to an int.

Exception: Overflow Exception: InvalidFormat

Definition at line 507 of file gstr.cpp.

◆ toLong()

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

Converts string 's' to a long.

Exception: Overflow Exception: InvalidFormat

Definition at line 529 of file gstr.cpp.

◆ toLower()

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

Replaces all Latin-1 upper-case characters in string 's' by lower-case characters.

Definition at line 735 of file gstr.cpp.

◆ toPrintableAscii() [1/2]

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

Returns a 7-bit printable representation of the given input string.

Definition at line 905 of file gstr.cpp.

◆ toPrintableAscii() [2/2]

std::string G::Str::toPrintableAscii ( const std::wstring &  in,
wchar_t  escape = L'\\' 
)
static

Returns a 7-bit printable representation of the given wide input string.

Definition at line 914 of file gstr.cpp.

◆ toShort()

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

Converts string 's' to a short.

Exception: Overflow Exception: InvalidFormat

Definition at line 564 of file gstr.cpp.

◆ toUInt() [1/3]

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

Converts string 's' to an unsigned int.

Exception: Overflow Exception: InvalidFormat

Definition at line 604 of file gstr.cpp.

◆ toUInt() [2/3]

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 591 of file gstr.cpp.

◆ toUInt() [3/3]

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 586 of file gstr.cpp.

◆ toULong() [1/5]

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

Converts string 's' to an unsigned long.

Exception: Overflow Exception: InvalidFormat

Definition at line 675 of file gstr.cpp.

◆ toULong() [2/5]

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

An overload for hexadecimal strings.

To avoid exceptions use isHex() and check the string length.

Definition at line 645 of file gstr.cpp.

◆ toULong() [3/5]

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

An overload for hexadecimal strings where overflow results in the return of the maximum value.

To avoid exceptions use isHex().

Definition at line 639 of file gstr.cpp.

◆ toULong() [4/5]

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 626 of file gstr.cpp.

◆ toULong() [5/5]

unsigned long G::Str::toULong ( 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 688 of file gstr.cpp.

◆ toUnsigned() [1/2]

template<typename T >
T G::Str::toUnsigned ( const char *&  p,
const char *  end,
bool &  overflow 
)
staticnoexcept

Low-level conversion from an unsigned decimal string to a number.

Consumes charaters until the first invalid character.

Definition at line 612 of file gstr.h.

◆ toUnsigned() [2/2]

template<typename T >
T G::Str::toUnsigned ( const char *  p,
const char *  end,
bool &  overflow,
bool &  invalid 
)
staticnoexcept

Low-level conversion from an unsigned decimal string to a number.

All characters in the range are used; any character not 0..9 yields an 'invalid' result.

Definition at line 597 of file gstr.h.

◆ toUpper()

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

Replaces all Latin-1 lower-case characters in string 's' by upper-case characters.

Definition at line 748 of file gstr.cpp.

◆ toUShort() [1/2]

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

Converts string 's' to an unsigned short.

Exception: Overflow Exception: InvalidFormat

Definition at line 713 of file gstr.cpp.

◆ toUShort() [2/2]

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 700 of file gstr.cpp.

◆ trim()

std::string & G::Str::trim ( std::string &  s,
string_view  ws 
)
static

Trims both ends of s, taking off any of the 'ws' characters.

Returns s.

Definition at line 359 of file gstr.cpp.

◆ trimLeft()

std::string & G::Str::trimLeft ( std::string &  s,
string_view  ws,
std::size_t  limit = 0U 
)
static

Trims the lhs of s, taking off up to 'limit' of the 'ws' characters.

Returns s.

Definition at line 335 of file gstr.cpp.

◆ trimmed() [1/2]

std::string G::Str::trimmed ( const std::string &  s,
string_view  ws 
)
static

Returns a trim()med version of s.

Definition at line 364 of file gstr.cpp.

◆ trimmed() [2/2]

std::string G::Str::trimmed ( std::string &&  s,
string_view  ws 
)
static

Returns a trim()med version of s.

Definition at line 370 of file gstr.cpp.

◆ trimRight()

std::string & G::Str::trimRight ( std::string &  s,
string_view  ws,
std::size_t  limit = 0U 
)
static

Trims the rhs of s, taking off up to 'limit' of the 'ws' characters.

Returns s.

Definition at line 347 of file gstr.cpp.

◆ unescape() [1/2]

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

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

Definition at line 213 of file gstr.cpp.

◆ unescape() [2/2]

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 218 of file gstr.cpp.

◆ unescaped()

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

Returns the unescape()d version of s.

Definition at line 242 of file gstr.cpp.

◆ unique() [1/2]

std::string G::Str::unique ( const std::string &  s,
char  c 
)
static

An overload that replaces repeated 'c' characters by one 'c' character.

Definition at line 1480 of file gstr.cpp.

◆ unique() [2/2]

std::string G::Str::unique ( const 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 1472 of file gstr.cpp.

◆ upper()

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

Returns a copy of 's' in which all Latin-1 lower-case characters have been replaced by upper-case characters.

Definition at line 754 of file gstr.cpp.

◆ ws()

G::string_view G::Str::ws ( )
static

Returns a string of standard whitespace characters.

Definition at line 1255 of file gstr.cpp.

Member Data Documentation

◆ truncate

constexpr std::size_t G::Str::truncate = (~(static_cast<std::size_t>(0U)))
staticconstexpr

A special value for the G::Str::strncpy_s() 'count' parameter.

Definition at line 545 of file gstr.h.


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