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 ( )
staticnoexcept

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_ ( )
staticnoexcept

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)
inlinestatic

Converts int 'i' to a string.

Definition at line 594 of file gstr.h.

◆ fromLong()

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

Converts long 'l' to a string.

Definition at line 600 of file gstr.h.

◆ fromShort()

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

Converts short 's' to a string.

Definition at line 606 of file gstr.h.

◆ fromUInt()

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

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)
inlinestatic

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  
)
inlinestatic

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  
)
inlinestatic

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 
)
staticnoexcept

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 
)
staticnoexcept

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)
inlinestatic

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 
)
staticnoexcept

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_ = {} 
)
staticnoexcept

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 
)
staticnoexcept

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 
)
staticnoexcept

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 
)
staticnoexcept

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 
)
staticnoexcept

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)
staticnoexcept

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)
staticnoexcept

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)
staticnoexcept

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 
)
staticnoexcept

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)
staticnoexcept

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)
staticnoexcept

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)
staticnoexcept

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)
staticnoexcept

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)
staticnoexcept

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)
staticnoexcept

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)
staticnoexcept

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 
)
staticnoexcept

Returns true if the two strings are the same.

Definition at line 1392 of file gstr.cpp.

◆ meta()

std::string_view G::Str::meta ( )
staticnoexcept

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 
)
staticnoexcept

Does the same as windows strncpy_s().

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

Definition at line 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 
)
staticnoexcept

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_ = {} 
)
staticnoexcept

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 
)
staticnoexcept

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_ 
)
staticnoexcept

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 
)
staticnoexcept

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 
)
staticnoexcept

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

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

Definition at line 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 
)
staticnoexcept

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 
)
staticnoexcept

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 
)
staticnoexcept

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 ( )
staticnoexcept

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)))
staticconstexpr

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: