E-MailRelay

Classes | Public Types | 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...

## Public Types
enum class | Eol { CrLf , Cr_Lf_CrLf }

## Static Public Member Functions
static bool | replace (std::string &s, std::string_view from, std::string_view to, std::size_t *pos_p=nullptr)
| A std::string_view overload. 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, std::string_view from, std::string_view to)
| Does a global replace on string 's', replacing all occurrences of sub-string 'from' with 'to'. 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 | removedAll (const std::string &, char)
| Removes all occurrences of the character from the string and returns the result. More...
static std::string & | trimLeft (std::string &s, std::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_view | trimLeftView (std::string_view, std::string_view ws, std::size_t limit=0U) noexcept
| Trims the lhs of s, taking off up to 'limit' of the 'ws' characters. More...
static std::string & | trimRight (std::string &s, std::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_view | trimRightView (std::string_view sv, std::string_view ws, std::size_t limit=0U) noexcept
| Trims the rhs of s, taking off up to 'limit' of the 'ws' characters. More...
static std::string & | trim (std::string &s, std::string_view ws)
| Trims both ends of s, taking off any of the 'ws' characters. More...
static std::string | trimmed (const std::string &s, std::string_view ws)
| Returns a trim()med version of s. More...
static std::string_view | trimmedView (std::string_view s, std::string_view ws) noexcept
| Returns a trim()med view of the input view. More...
static bool | isNumeric (std::string_view s, bool allow_minus_sign=false) noexcept
| Returns true if every character is a decimal digit. More...
static bool | isHex (std::string_view s) noexcept
| Returns true if every character is a hexadecimal digit. More...
static bool | isPrintableAscii (std::string_view s) noexcept
| Returns true if every character is between 0x20 and 0x7e inclusive. More...
static bool | isPrintable (std::string_view s) noexcept
| Returns true if every character is 0x20 or above but not 0x7f. More...
static bool | isSimple (std::string_view s) noexcept
| Returns true if every character is alphanumeric or "-" or "_". More...
static bool | isUShort (std::string_view s) noexcept
| Returns true if the string can be converted into an unsigned short without throwing an exception. More...
static bool | isUInt (std::string_view s) noexcept
| Returns true if the string can be converted into an unsigned integer without throwing an exception. More...
static bool | isULong (std::string_view s) noexcept
| Returns true if the string can be converted into an unsigned long without throwing an exception. More...
static bool | isInt (std::string_view s) noexcept
| 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 std::string | fromULong (unsigned long, const Hex &)
| Converts an unsigned value to a lower-case hex string with no leading zeros. More...
static std::string | fromULongLong (unsigned long long, const Hex &)
| Converts an unsigned value to a lower-case hex string with no leading zeros. More...
static std::string_view | fromULongToHex (unsigned long, char *out) noexcept
| Low-level conversion from an unsigned value to a lower-case hex string with no leading zeros. More...
static std::string_view | fromULongLongToHex (unsigned long long, char *out) noexcept
| Low-level conversion from an unsigned value to a lower-case hex string with no leading zeros. More...
static bool | toBool (std::string_view s)
| Converts string 's' to a bool. More...
static double | toDouble (const std::string &s)
| Converts string 's' to a double. More...
static float | toFloat (const std::string &s)
| Converts string 's' to a float. More...
static int | toInt (std::string_view s)
| Converts string 's' to an int. More...
static long | toLong (std::string_view s)
| Converts string 's' to a long. More...
static short | toShort (std::string_view s)
| Converts string 's' to a short. More...
static unsigned int | toUInt (std::string_view s)
| Converts string 's' to an unsigned int. More...
static int | toInt (std::string_view s1, std::string_view s2)
| Overload that converts the first string if it can be converted without throwing, or otherwise the second string. More...
static unsigned int | toUInt (std::string_view s, Limited)
| Converts string 's' to an unsigned int. More...
static unsigned int | toUInt (std::string_view s1, std::string_view s2)
| Overload that converts the first string if it can be converted without throwing, or otherwise the second string. More...
static unsigned int | toUInt (std::string_view s1, unsigned int default_) noexcept
| Overload that converts the string if it can be converted without throwing, or otherwise returns the default value. More...
static unsigned long | toULong (std::string_view s, Limited)
| Converts string 's' to an unsigned long. More...
static unsigned long | toULong (std::string_view s, Hex)
| An overload for hexadecimal strings. More...
static unsigned long | toULong (std::string_view 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 (std::string_view s)
| Converts string 's' to an unsigned long. More...
static unsigned long | toULong (std::string_view s1, std::string_view s2)
| Overload that converts the first string if it can be converted without throwing, or otherwise the second string. More...
static unsigned short | toUShort (std::string_view s, Limited)
| Converts string 's' to an unsigned short. More...
static unsigned short | toUShort (std::string_view s)
| Converts string 's' to an unsigned short. More...
static void | toUpper (std::string &s)
| Replaces all seven-bit lower-case characters in string 's' by upper-case characters. More...
static void | toLower (std::string &s)
| Replaces all seven-bit upper-case characters in string 's' by lower-case characters. More...
static std::string | upper (std::string_view)
| Returns a copy of 's' in which all seven-bit lower-case characters have been replaced by upper-case characters. More...
static std::string | lower (std::string_view)
| Returns a copy of 's' in which all seven-bit 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 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_view 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 (std::string_view allow_chars, std::string_view s)
| Returns the 's' with all occurrences of the characters not appearing in the first string deleted. More...
static void | escape (std::string &s, char c_escape, std::string_view specials_in, std::string_view 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)
| Overload for 'normal' backslash escaping of whitespace. More...
static std::string | escaped (std::string_view, char c_escape, std::string_view specials_in, std::string_view specials_out)
| Returns the escape()d string. More...
static std::string | escaped (std::string_view)
| Returns the escape()d string. More...
static void | unescape (std::string &s, char c_escape, std::string_view specials_in, std::string_view 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 std::string_view | meta () noexcept
| Returns a list of shell meta-characters with a tilde as the first character. More...
static std::string | readLineFrom (std::istream &stream, std::string_view eol={})
| Reads a line from the stream using the given line terminator. More...
static std::istream & | readLine (std::istream &stream, std::string &result, std::string_view eol={}, bool pre_erase_result=true, std::size_t limit=0U)
| Reads a line from the stream using the given line terminator, which may be multi-character. More...
static std::istream & | readLine (std::istream &stream, std::string &result, Eol, bool pre_erase_result=true, std::size_t limit=0U)
| An overload where lines are terminated with some enumerated combination of CR, LF or CRLF. More...
static void | splitIntoTokens (const std::string &in, StringArray &out, std::string_view ws, char esc='\0')
| Splits the string into 'ws'-delimited tokens. More...
static StringArray | splitIntoTokens (const std::string &in, std::string_view ws=Str::ws(), char esc='\0')
| Overload that returns by value. More...
static void | splitIntoFields (std::string_view in, StringArray &out, char sep, char escape='\0', bool remove_escapes=true)
| Splits the string into fields. More...
static StringArray | splitIntoFields (std::string_view in, char sep)
| Overload that returns by value. More...
static std::string | dequote (const std::string &, char qq='\"' , char esc = '\\' , std::string_view ws = Str::ws() , std::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 (std::string_view sep, const StringArray &strings)
| Concatenates an array of strings with separators. More...
static std::string | join (std::string_view sep, std::string_view s1, std::string_view s2, std::string_view s3={}, std::string_view s4={}, std::string_view s5={}, std::string_view s6={}, std::string_view s7={}, std::string_view s8={}, std::string_view s9={})
| Concatenates a small number of strings with separators. More...
static std::string | join (std::string_view sep, const StringMap &, std::string_view eq, std::string_view tail={})
| Concatenates entries in a map, where an entry is "<key><eq><value><tail>". More...
static StringArray | keys (const StringMap &string_map)
| Extracts the keys from a map of strings. More...
static std::string | head (std::string_view in, std::size_t pos, std::string_view default_={})
| Returns the first part of the string up to just before the given position. More...
static std::string | head (std::string_view, std::string_view 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_view | headView (std::string_view in, std::size_t pos, std::string_view default_={}) noexcept
| Like head() but returning a view into the input string. More...
static std::string_view | headView (std::string_view in, std::string_view sep, bool default_empty=true) noexcept
| Like head() but returning a view into the input string. More...
static std::string | tail (std::string_view in, std::size_t pos, std::string_view default_={})
| Returns the last part of the string after the given position. More...
static std::string | tail (std::string_view in, std::string_view 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_view | tailView (std::string_view in, std::size_t pos, std::string_view default_={}) noexcept
| Like tail() but returning a view into the input string. More...
static std::string_view | tailView (std::string_view in, std::string_view sep, bool default_empty=true) noexcept
| Like tail() but returning a view into the input string. More...
static bool | match (std::string_view, std::string_view) noexcept
| Returns true if the two strings are the same. More...
static bool | iless (std::string_view, std::string_view) noexcept
| Returns true if the first string is lexicographically less than the first, after seven-bit lower-case letters have been folded to upper-case. More...
static bool | imatch (char, char) noexcept
| Returns true if the two characters are the same, ignoring seven-bit case. More...
static bool | imatch (std::string_view, std::string_view) noexcept
| Returns true if the two strings are the same, ignoring seven-bit case. More...
static std::size_t | ifind (std::string_view s, std::string_view key)
| Returns the position of the key in 's' using a seven-bit case-insensitive search. More...
static std::size_t | ifindat (std::string_view s, std::string_view key, std::size_t pos)
| Returns the position of the key in 's' at of after position 'pos' using a seven-bit case-insensitive search. More...
static bool | tailMatch (std::string_view in, std::string_view ending) noexcept
| Returns true if the string has the given ending (or the given ending is empty). More...
static bool | headMatch (std::string_view in, std::string_view head) noexcept
| Returns true if the string has the given start (or head is empty). More...
static std::string_view | ws () noexcept
| Returns a string of standard whitespace characters. More...
static std::string_view | alnum () noexcept
| Returns a string of seven-bit alphanumeric characters, ie A-Z, a-z and 0-9. More...
static std::string_view | alnum_ () noexcept
| Returns alnum() with an additional trailing underscore character. 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 (std::string_view) noexcept
| Returns true if the string has a positive meaning, such as "1", "true", "yes". More...
static bool | isNegative (std::string_view) noexcept
| 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 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 47 of file gstr.h.

## Member Enumeration Documentation

## ◆ Eol

enum class G::Str::Eol
| strong

Definition at line 61 of file gstr.h.

## Member Function Documentation

## ◆ alnum()

std::string_view G::Str::alnum | ( |  | ) |
| static noexcept

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

Definition at line 1273 of file gstr.cpp.

## ◆ alnum_()

std::string_view G::Str::alnum_ | ( |  | ) |
| static noexcept

Returns alnum() with an additional trailing underscore character.

Definition at line 1279 of file gstr.cpp.

## ◆ dequote()

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

## ◆ escape() [1/2]

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

Overload for 'normal' backslash escaping of whitespace.

Definition at line 123 of file gstr.cpp.

## ◆ escape() [2/2]

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

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

The specials-in and specials-out strings must be the same size.

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

Definition at line 100 of file gstr.cpp.

## ◆ escaped() [1/2]

std::string G::Str::escaped | ( | std::string_view | s_in | ) |
| static

Returns the escape()d string.

Definition at line 83 of file gstr.cpp.

## ◆ escaped() [2/2]

std::string G::Str::escaped | ( | std::string_view | s_in,
|  | char | c_escape,
|  | std::string_view | specials_in,
|  | std::string_view | specials_out
| ) |  |
| static

Returns the escape()d string.

Definition at line 92 of file gstr.cpp.

## ◆ fromBool()

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

Converts boolean 'b' to a string.

Definition at line 463 of file gstr.cpp.

## ◆ fromDouble()

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

Converts double 'd' to a string.

Definition at line 470 of file gstr.cpp.

## ◆ fromInt()

std::string G::Str::fromInt | ( | int | i | ) |
| inline static

Converts int 'i' to a string.

Definition at line 594 of file gstr.h.

## ◆ fromLong()

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

Converts long 'l' to a string.

Definition at line 600 of file gstr.h.

## ◆ fromShort()

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

Converts short 's' to a string.

Definition at line 606 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 612 of file gstr.h.

## ◆ fromULong() [1/2]

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

Converts unsigned long 'ul' to a string.

Definition at line 618 of file gstr.h.

## ◆ fromULong() [2/2]

std::string G::Str::fromULong | ( | unsigned long | u,
|  | const Hex & |
| ) |  |
| inline static

Converts an unsigned value to a lower-case hex string with no leading zeros.

Definition at line 630 of file gstr.h.

## ◆ fromULongLong()

std::string G::Str::fromULongLong | ( | unsigned long long | u,
|  | const Hex & |
| ) |  |
| inline static

Converts an unsigned value to a lower-case hex string with no leading zeros.

Definition at line 637 of file gstr.h.

## ◆ fromULongLongToHex()

std::string_view G::Str::fromULongLongToHex | ( | unsigned long long | u,
|  | char * | out
| ) |  |
| static noexcept

Low-level conversion from an unsigned value to a lower-case hex string with no leading zeros.

The output buffer must be sizeof(long long)*2.

Definition at line 794 of file gstr.cpp.

## ◆ fromULongToHex()

std::string_view G::Str::fromULongToHex | ( | unsigned long | u,
|  | char * | out
| ) |  |
| static noexcept

Low-level conversion from an unsigned value to a lower-case hex string with no leading zeros.

The output buffer must be sizeof(long)*2.

Definition at line 787 of file gstr.cpp.

## ◆ fromUShort()

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

Converts unsigned short 'us' to a string.

Definition at line 624 of file gstr.h.

## ◆ head() [1/2]

std::string G::Str::head | ( | std::string_view | in,
|  | std::size_t | pos,
|  | std::string_view | default_ = `{}`
| ) |  |
| 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 1294 of file gstr.cpp.

## ◆ head() [2/2]

std::string G::Str::head | ( | std::string_view | in,
|  | std::string_view | 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 1302 of file gstr.cpp.

## ◆ headMatch()

bool G::Str::headMatch | ( | std::string_view | in,
|  | std::string_view | head
| ) |  |
| static noexcept

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

Definition at line 1359 of file gstr.cpp.

## ◆ headView() [1/2]

std::string_view G::Str::headView | ( | std::string_view | in,
|  | std::size_t | pos,
|  | std::string_view | default_ = `{}`
| ) |  |
| static noexcept

Like head() but returning a view into the input string.

Definition at line 1308 of file gstr.cpp.

## ◆ headView() [2/2]

std::string_view G::Str::headView | ( | std::string_view | in,
|  | std::string_view | sep,
|  | bool | default_empty = `true`
| ) |  |
| static noexcept

Like head() but returning a view into the input string.

Definition at line 1316 of file gstr.cpp.

## ◆ ifind()

std::size_t G::Str::ifind | ( | std::string_view | s,
|  | std::string_view | key
| ) |  |
| static

Returns the position of the key in 's' using a seven-bit case-insensitive search.

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

Definition at line 1433 of file gstr.cpp.

## ◆ ifindat()

std::size_t G::Str::ifindat | ( | std::string_view | s,
|  | std::string_view | key,
|  | std::size_t | pos
| ) |  |
| static

Returns the position of the key in 's' at of after position 'pos' using a seven-bit case-insensitive search.

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

Definition at line 1438 of file gstr.cpp.

## ◆ iless()

bool G::Str::iless | ( | std::string_view | a,
|  | std::string_view | b
| ) |  |
| static noexcept

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

Definition at line 1404 of file gstr.cpp.

## ◆ imatch() [1/2]

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

Returns true if the two characters are the same, ignoring seven-bit case.

Definition at line 1415 of file gstr.cpp.

## ◆ imatch() [2/2]

bool G::Str::imatch | ( | std::string_view | a,
|  | std::string_view | b
| ) |  |
| static noexcept

Returns true if the two strings are the same, ignoring seven-bit case.

The locale is ignored.

Definition at line 1421 of file gstr.cpp.

## ◆ isHex()

bool G::Str::isHex | ( | std::string_view | s | ) |
| static noexcept

Returns true if every character is a hexadecimal digit.

Empty strings return true.

Definition at line 407 of file gstr.cpp.

## ◆ isInt()

bool G::Str::isInt | ( | std::string_view | s | ) |
| static noexcept

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

Definition at line 428 of file gstr.cpp.

## ◆ isNegative()

bool G::Str::isNegative | ( | std::string_view | s_in | ) |
| static noexcept

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

Definition at line 1384 of file gstr.cpp.

## ◆ isNumeric()

bool G::Str::isNumeric | ( | std::string_view | s,
|  | bool | allow_minus_sign = `false`
| ) |  |
| static noexcept

Returns true if every character is a decimal digit.

Empty strings return true.

Definition at line 400 of file gstr.cpp.

## ◆ isPositive()

bool G::Str::isPositive | ( | std::string_view | s_in | ) |
| static noexcept

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

Definition at line 1376 of file gstr.cpp.

## ◆ isPrintable()

bool G::Str::isPrintable | ( | std::string_view | s | ) |
| static noexcept

Returns true if every character is 0x20 or above but not 0x7f.

Empty strings return true.

Definition at line 418 of file gstr.cpp.

## ◆ isPrintableAscii()

bool G::Str::isPrintableAscii | ( | std::string_view | s | ) |
| static noexcept

Returns true if every character is between 0x20 and 0x7e inclusive.

Empty strings return true.

Definition at line 413 of file gstr.cpp.

## ◆ isSimple()

bool G::Str::isSimple | ( | std::string_view | s | ) |
| static noexcept

Returns true if every character is alphanumeric or "-" or "_".

Empty strings return true.

Definition at line 423 of file gstr.cpp.

## ◆ isUInt()

bool G::Str::isUInt | ( | std::string_view | s | ) |
| static noexcept

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

Definition at line 446 of file gstr.cpp.

## ◆ isULong()

bool G::Str::isULong | ( | std::string_view | s | ) |
| static noexcept

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

Definition at line 454 of file gstr.cpp.

## ◆ isUShort()

bool G::Str::isUShort | ( | std::string_view | s | ) |
| static noexcept

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

Definition at line 437 of file gstr.cpp.

## ◆ join() [1/3]

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

Concatenates an array of strings with separators.

Definition at line 1221 of file gstr.cpp.

## ◆ join() [2/3]

std::string G::Str::join | ( | std::string_view | sep,
|  | const StringMap & | map,
|  | std::string_view | eq,
|  | std::string_view | tail = `{}`
| ) |  |
| static

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

Definition at line 1205 of file gstr.cpp.

## ◆ join() [3/3]

std::string G::Str::join | ( | std::string_view | sep,
|  | std::string_view | s1,
|  | std::string_view | s2,
|  | std::string_view | s3 = `{}`,
|  | std::string_view | s4 = `{}`,
|  | std::string_view | s5 = `{}`,
|  | std::string_view | s6 = `{}`,
|  | std::string_view | s7 = `{}`,
|  | std::string_view | s8 = `{}`,
|  | std::string_view | s9 = `{}`
| ) |  |
| static

Concatenates a small number of strings with separators.

In this overload empty strings are ignored.

Definition at line 1232 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 1256 of file gstr.cpp.

## ◆ lower()

std::string G::Str::lower | ( | std::string_view | in | ) |
| static

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

Definition at line 824 of file gstr.cpp.

## ◆ match()

bool G::Str::match | ( | std::string_view | a,
|  | std::string_view | b
| ) |  |
| static noexcept

Returns true if the two strings are the same.

Definition at line 1392 of file gstr.cpp.

## ◆ meta()

std::string_view G::Str::meta | ( |  | ) |
| static noexcept

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

## ◆ negative()

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

Returns a default negative string. See isNegative().

Definition at line 1371 of file gstr.cpp.

## ◆ only()

std::string G::Str::only | ( | std::string_view | allow_chars,
|  | std::string_view | s
| ) |  |
| static

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

Definition at line 276 of file gstr.cpp.

## ◆ positive()

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

Returns a default positive string. See isPositive().

Definition at line 1366 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 913 of file gstr.cpp.

## ◆ printable() [2/2]

std::string G::Str::printable | ( | std::string_view | 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 922 of file gstr.cpp.

## ◆ readLine() [1/2]

std::istream & G::Str::readLine | ( | std::istream & | stream,
|  | std::string & | result,
|  | Eol | eol,
|  | bool | pre_erase_result = `true`,
|  | std::size_t | limit = `0U`
| ) |  |
| static

An overload where lines are terminated with some enumerated combination of CR, LF or CRLF.

Definition at line 994 of file gstr.cpp.

## ◆ readLine() [2/2]

std::istream & G::Str::readLine | ( | std::istream & | stream,
|  | std::string & | result,
|  | std::string_view | eol = `{}`,
|  | bool | pre_erase_result = `true`,
|  | std::size_t | limit = `0U`
| ) |  |
| static

Reads a line from the stream using the given line terminator, which may be multi-character.

Behaves like std::getline() when the trailing parameters are defaulted. Also behaves like std::getline() by not clearing the result if the stream is initially not good(), even if the pre-erase flag is set.

Definition at line 958 of file gstr.cpp.

## ◆ readLineFrom()

std::string G::Str::readLineFrom | ( | std::istream & | stream,
|  | std::string_view | eol = `{}`
| ) |  |
| 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 side-effects on the stream state follow std::getline(): reading an unterminated line at the end of the stream sets eof, but a fully-terminated line does not; if no characters are read (including terminators) (eg. already eof) then failbit is set.

A read loop that processes even incomplete lines at the end of the stream should do:

< while(stream.good()){read(stream);if(stream)process(line)} // or
< while(read(stream)){process(line)}
<

or to process only complete lines:

< while(stream){read(stream);if(stream.good())process(line)} // or
< while(read(stream)&&stream.good()){process(line)}
<

Definition at line 951 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 262 of file gstr.cpp.

## ◆ removedAll()

std::string G::Str::removedAll | ( | const std::string & | s_in,
|  | char | c
| ) |  |
| static

Removes all occurrences of the character from the string and returns the result.

See also only().

Definition at line 268 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 211 of file gstr.cpp.

## ◆ replace() [2/3]

bool G::Str::replace | ( | std::string & | s,
|  | std::string_view | from,
|  | std::string_view | to,
|  | std::size_t * | pos_p = `nullptr`
| ) |  |
| static

A std::string_view overload.

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

## ◆ replaceAll()

unsigned int G::Str::replaceAll | ( | std::string & | s,
|  | std::string_view | from,
|  | std::string_view | 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 247 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 255 of file gstr.cpp.

## ◆ splitIntoFields() [1/2]

G::StringArray G::Str::splitIntoFields | ( | std::string_view | in,
|  | char | sep
| ) |  |
| static

Overload that returns by value.

Definition at line 1197 of file gstr.cpp.

## ◆ splitIntoFields() [2/2]

void G::Str::splitIntoFields | ( | std::string_view | in,
|  | StringArray & | out,
|  | char | sep,
|  | 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 1191 of file gstr.cpp.

## ◆ splitIntoTokens() [1/2]

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

Overload that returns by value.

Definition at line 1127 of file gstr.cpp.

## ◆ splitIntoTokens() [2/2]

void G::Str::splitIntoTokens | ( | const std::string & | in,
|  | StringArray & | out,
|  | std::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() (using the same escape character), and revert the non-breaking spaces afterwards.

Definition at line 1119 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 1490 of file gstr.cpp.

## ◆ tail() [1/2]

std::string G::Str::tail | ( | std::string_view | in,
|  | std::size_t | pos,
|  | std::string_view | default_ = `{}`
| ) |  |
| 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 1322 of file gstr.cpp.

## ◆ tail() [2/2]

std::string G::Str::tail | ( | std::string_view | in,
|  | std::string_view | 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 1330 of file gstr.cpp.

## ◆ tailMatch()

bool G::Str::tailMatch | ( | std::string_view | in,
|  | std::string_view | ending
| ) |  |
| static noexcept

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

Definition at line 1352 of file gstr.cpp.

## ◆ tailView() [1/2]

std::string_view G::Str::tailView | ( | std::string_view | in,
|  | std::size_t | pos,
|  | std::string_view | default_ = `{}`
| ) |  |
| static noexcept

Like tail() but returning a view into the input string.

Definition at line 1337 of file gstr.cpp.

## ◆ tailView() [2/2]

std::string_view G::Str::tailView | ( | std::string_view | in,
|  | std::string_view | sep,
|  | bool | default_empty = `true`
| ) |  |
| static noexcept

Like tail() but returning a view into the input string.

Definition at line 1345 of file gstr.cpp.

## ◆ toBool()

bool G::Str::toBool | ( | std::string_view | s | ) |
| static

Converts string 's' to a bool.

Exception: InvalidFormat

Definition at line 481 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 495 of file gstr.cpp.

## ◆ toFloat()

float G::Str::toFloat | ( | const std::string & | s | ) |
| static

Converts string 's' to a float.

Exception: Overflow Exception: InvalidFormat

Definition at line 517 of file gstr.cpp.

## ◆ toInt() [1/2]

int G::Str::toInt | ( | std::string_view | s | ) |
| static

Converts string 's' to an int.

Exception: Overflow Exception: InvalidFormat

Definition at line 538 of file gstr.cpp.

## ◆ toInt() [2/2]

int G::Str::toInt | ( | std::string_view | s1,
|  | std::string_view | s2
| ) |  |
| static

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

Definition at line 551 of file gstr.cpp.

## ◆ toLong()

long G::Str::toLong | ( | std::string_view | s | ) |
| static

Converts string 's' to a long.

Exception: Overflow Exception: InvalidFormat

Definition at line 567 of file gstr.cpp.

## ◆ toLower()

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

Replaces all seven-bit upper-case characters in string 's' by lower-case characters.

Definition at line 819 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 931 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 input string.

Definition at line 941 of file gstr.cpp.

## ◆ toShort()

short G::Str::toShort | ( | std::string_view | s | ) |
| static

Converts string 's' to a short.

Exception: Overflow Exception: InvalidFormat

Definition at line 600 of file gstr.cpp.

## ◆ toUInt() [1/4]

unsigned int G::Str::toUInt | ( | std::string_view | s | ) |
| static

Converts string 's' to an unsigned int.

Exception: Overflow Exception: InvalidFormat

Definition at line 648 of file gstr.cpp.

## ◆ toUInt() [2/4]

unsigned int G::Str::toUInt | ( | std::string_view | 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 635 of file gstr.cpp.

## ◆ toUInt() [3/4]

unsigned int G::Str::toUInt | ( | std::string_view | s1,
|  | std::string_view | s2
| ) |  |
| static

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

Definition at line 622 of file gstr.cpp.

## ◆ toUInt() [4/4]

unsigned int G::Str::toUInt | ( | std::string_view | s1,
|  | unsigned int | default_
| ) |  |
| static noexcept

Overload that converts the string if it can be converted without throwing, or otherwise returns the default value.

Definition at line 627 of file gstr.cpp.

## ◆ toULong() [1/5]

unsigned long G::Str::toULong | ( | std::string_view | s | ) |
| static

Converts string 's' to an unsigned long.

Exception: Overflow Exception: InvalidFormat

Definition at line 719 of file gstr.cpp.

## ◆ toULong() [2/5]

unsigned long G::Str::toULong | ( | std::string_view | s,
|  | Hex |
| ) |  |
| static

An overload for hexadecimal strings.

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

Definition at line 689 of file gstr.cpp.

## ◆ toULong() [3/5]

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

## ◆ toULong() [4/5]

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

## ◆ toULong() [5/5]

unsigned long G::Str::toULong | ( | std::string_view | s1,
|  | std::string_view | s2
| ) |  |
| static

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

Definition at line 732 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 characters until the first invalid character.

Definition at line 659 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 644 of file gstr.h.

## ◆ toUpper()

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

Replaces all seven-bit lower-case characters in string 's' by upper-case characters.

Definition at line 831 of file gstr.cpp.

## ◆ toUShort() [1/2]

unsigned short G::Str::toUShort | ( | std::string_view | s | ) |
| static

Converts string 's' to an unsigned short.

Exception: Overflow Exception: InvalidFormat

Definition at line 764 of file gstr.cpp.

## ◆ toUShort() [2/2]

unsigned short G::Str::toUShort | ( | std::string_view | 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 750 of file gstr.cpp.

## ◆ trim()

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

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

Returns s.

Definition at line 338 of file gstr.cpp.

## ◆ trimLeft()

std::string & G::Str::trimLeft | ( | std::string & | s,
|  | std::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 288 of file gstr.cpp.

## ◆ trimLeftView()

std::string_view G::Str::trimLeftView | ( | std::string_view | sv,
|  | std::string_view | ws,
|  | std::size_t | limit = `0U`
| ) |  |
| static noexcept

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

Returns a view into the input string.

Definition at line 300 of file gstr.cpp.

## ◆ trimmed()

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

Returns a trim()med version of s.

Definition at line 343 of file gstr.cpp.

## ◆ trimmedView()

std::string_view G::Str::trimmedView | ( | std::string_view | s,
|  | std::string_view | ws
| ) |  |
| static noexcept

Returns a trim()med view of the input view.

Definition at line 351 of file gstr.cpp.

## ◆ trimRight()

std::string & G::Str::trimRight | ( | std::string & | s,
|  | std::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 313 of file gstr.cpp.

## ◆ trimRightView()

std::string_view G::Str::trimRightView | ( | std::string_view | sv,
|  | std::string_view | ws,
|  | std::size_t | limit = `0U`
| ) |  |
| static noexcept

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

Returns a view into the input string.

Definition at line 325 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 175 of file gstr.cpp.

## ◆ unescape() [2/2]

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

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

The specials-in and specials-out strings must be the same length.

Definition at line 180 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 203 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 1474 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 1467 of file gstr.cpp.

## ◆ upper()

std::string G::Str::upper | ( | std::string_view | in | ) |
| static

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

Definition at line 836 of file gstr.cpp.

## ◆ ws()

std::string_view G::Str::ws | ( |  | ) |
| static noexcept

Returns a string of standard whitespace characters.

Definition at line 1265 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 578 of file gstr.h.

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

- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/glib/gstr.h
- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/glib/gstr.cpp