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 | ) |
| inline static

Converts int 'i' to a string.

Definition at line 561 of file gstr.h.

## ◆ fromLong()

std::string G::Str::fromLong | ( | long | l | ) |
| inline static

Converts long 'l' to a string.

Definition at line 567 of file gstr.h.

## ◆ fromShort()

std::string G::Str::fromShort | ( | short | s | ) |
| inline static

Converts short 's' to a string.

Definition at line 573 of file gstr.h.

## ◆ fromUInt()

std::string G::Str::fromUInt | ( | unsigned int | ui | ) |
| inline static

Converts unsigned int 'ui' to a string.

Definition at line 579 of file gstr.h.

## ◆ fromULong()

std::string G::Str::fromULong | ( | unsigned long | ul | ) |
| inline static

Converts unsigned long 'ul' to a string.

Definition at line 585 of file gstr.h.

## ◆ fromUShort()

std::string G::Str::fromUShort | ( | unsigned short | us | ) |
| inline static

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
| ) |  |
| static noexcept

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
| ) |  |
| static noexcept

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
| ) |  |
| static noexcept

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)))
| static constexpr

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:

- /usr/src/slapt-src-x86_64/network/emailrelay/emailrelay-2.3/src/glib/gstr.h
- /usr/src/slapt-src-x86_64/network/emailrelay/emailrelay-2.3/src/glib/gstr.cpp