CopperSpice API  1.7.2
QStringParser Class Reference

Provides functionality for parsing a string. More...

Public Typedefs

using SectionFlags = QFlags< SectionFlag >
 

Public Types

enum  SectionFlag
 
enum  SplitBehavior
 

Static Public Methods

template<typename T , typename V , typename = typename std::enable_if<! std::is_arithmetic<typename std::remove_reference<V>::type>::value>::type>
static T formatArg (const T &str, V &&value, int fieldwidth=0, QChar32 fillChar=QChar32 (' '))
 
template<typename T , typename V , typename = typename std::enable_if<std::is_floating_point<V>::value>::type>
static T formatArg (const T &str, V value, int fieldwidth=0, char format= 'g', int precision=6, QChar32 fillChar=QChar32 (' '))
 
template<typename T , typename V , typename = typename std::enable_if<std::is_integral<V>::value>::type>
static T formatArg (const T &str, V value, int fieldwidth=0, int base=10, QChar32 fillChar=QChar32 (' '))
 
template<typename T , typename... Ts>
static T formatArgs (const T &str, Ts...args)
 
template<typename T , typename V >
static T join (const QList< T > &list, const V &separator)
 
template<typename T = QString8>
static T number (double value, char format= 'g', int precision=6)
 
template<typename T = QString8, typename V >
static T number (V value, int base=10)
 
template<typename T >
static T section (const T &str, const T &separator, int firstSection, int lastSection=-1, SectionFlags flags=SectionDefault)
 
template<typename T >
static T section (const T &str, QChar32 separator, int firstSection, int lastSection=-1, SectionFlags flags=SectionDefault)
 
template<typename T >
static QList< T > split (const T &str, const QRegularExpression &regExp, SplitBehavior behavior=KeepEmptyParts)
 
template<typename T >
static QList< T > split (const T &str, const T &separator, SplitBehavior behavior=KeepEmptyParts, Qt::CaseSensitivity cs=Qt::CaseSensitive)
 
template<typename T >
static QList< T > split (const T &str, QChar32 separator, SplitBehavior behavior=KeepEmptyParts, Qt::CaseSensitivity cs=Qt::CaseSensitive)
 
template<typename T = QString8>
static double toDouble (const T &str, bool *ok=nullptr)
 
template<typename T = QString8>
static float toFloat (const T &str, bool *ok=nullptr)
 
template<typename R , typename T = QString8>
static R toInteger (const T &str, bool *ok=nullptr, int base=10)
 

Detailed Description

This class provides functionality to parse an existing string.

This class provides several methods for converting strings into numbers. Refer to setNum() number(), toInt(), toDouble(), and similar methods. There are also several methods for converting numbers into strings. Refer to formatArg() and formatArgs().

To split a string into a substrings based on a separator, use split(). To merge a list of strings into one single string with a specified separator, use join().

Argument Format and Precision

In methods where an argument format can be specified the argument can be any of those shown in the following table. The value for precision represents the maximum number of significant digits (trailing zeroes are omitted).

FormatDescription
eformat as [-]9.9e[+|-]999
Eformat as [-]9.9E[+|-]999
fformat as [-]9.9
guse e or f format, whichever is the most concise
Guse E or f format, whichever is the most concise

Member Typedef Documentation

SectionFlags is a typedef for QFlags<SectionFlag>. It stores an OR combination of SectionFlag values.

Member Enumeration Documentation

This enum specifies flags which can be used to affect the outcome of the section() method.

ConstantValueDescription
QStringParser::SectionDefault 0x00 Empty section are counted, leading and trailing separators are not included, and the separator is compared case sensitively.
QStringParser::SectionSkipEmpty 0x01 Treat empty sections as if they do not exist.
QStringParser::SectionIncludeLeadingSep 0x02 Include the leading separator (if any) in the result string.
QStringParser::SectionIncludeTrailingSep 0x04 Include the trailing separator (if any) in the string.
QStringParser::SectionCaseInsensitiveSeps 0x08 Compare the separator case-insensitively.
See also
section()

This enum specifies how split() should behave with respect to empty strings.

ConstantValueDescription
QStringParser::KeepEmptyParts0 If a section is empty keep it in the result.
QStringParser::SkipEmptyParts1 If a section is empty do not include it in the result.
See also
split()

Method Documentation

template<typename T , typename V , typename = typename std::enable_if<! std::is_arithmetic<typename std::remove_reference<V>::type>::value>::type>
T QStringParser::formatArg ( const T &  str,
V &&  value,
int  fieldwidth = 0,
QChar32  fillChar = QChar32(' ') 
)
nodiscardinlinestatic

Returns a copy of string str with the lowest numbered place marker replaced by the value. Place marker numbers must be in the range 1 to 99 and preceded with a % sign.

The fieldwidth specifies the minimum amount of space the argument shall occupy. If str requires less space than fieldwidth the output is padded to fieldwidth with character fillChar. A positive value for fieldwidth produces right-aligned text whereas a negative fieldwidth produces left-aligned text.

QString8 str1 = "Good %1, Hal";
printf("%s\n", QStringParser::formatArg(str1, "morning").constData()); // Good morning, Hal
printf("%s\n", QStringParser::formatArg(str1, "morning", 10).constData()); // Good morning, Hal
printf("%s\n", QStringParser::formatArg(str1, "morning", -10).constData()); // Good morning , Hal
printf("%s\n", QStringParser::formatArg(str1, "morning", 10, '*').constData()); // Good ***morning, Hal
printf("%s\n", QStringParser::formatArg(str1, "morning", -10, '*').constData()); // Good morning***, Hal

The data type for the template parameter V can be char, QChar, QChar32, QString, QString8, QString16, or any data type can be appended to the data type of the string.

template<typename T , typename V , typename = typename std::enable_if<std::is_floating_point<V>::value>::type>
T QStringParser::formatArg ( const T &  str,
value,
int  fieldwidth = 0,
char  format = 'g',
int  precision = 6,
QChar32  fillChar = QChar32(' ') 
)
nodiscardinlinestatic

Returns a copy of the string str with the lowest numbered place marker replaced by value formatted according to the specified format and precision. Place marker numbers must be in the range 1 to 99 and preceded with a % sign.

The fieldwidth specifies the minimum amount of space the argument shall occupy. If str requires less space than fieldwidth the output is padded to fieldwidth with character fillChar. A positive value for fieldwidth produces right-aligned text whereas a negative fieldwidth produces left-aligned text.

double d = 12.34;
QString8 str = QString("Delta: %1").formatArg(d, 0, 'E', 3); // str == "delta: 1.234E+01"

The '%' can be followed by an 'L' in which case the sequence is replaced with a localized representation of value. The conversion uses the default locale set by QLocale::setDefaultLocale(). If no default locale was specified the "C" locale is used.

Refer to Argument Formats for details.

See also
QLocale::toString()
template<typename T , typename V , typename = typename std::enable_if<std::is_integral<V>::value>::type>
T QStringParser::formatArg ( const T &  str,
value,
int  fieldwidth = 0,
int  base = 10,
QChar32  fillChar = QChar32(' ') 
)
nodiscardinlinestatic

Returns a copy of the string str with the lowest numbered place marker replaced by value using the base specified by base. Place marker numbers must be in the range 1 to 99 and preceded with a % sign.

The value is expressed in base base, which is 10 by default and must be between 2 and 36.

The fieldwidth specifies the minimum amount of space the argument shall occupy. If str requires less space than fieldwidth the output is padded to fieldwidth with character fillChar. A positive value for fieldwidth produces right-aligned text whereas a negative fieldwidth produces left-aligned text.

The '%' used in the place marker can be followed by an 'L' in which case the sequence is replaced with a localized representation of value. The conversion uses the default locale set by QLocale::setDefaultLocale(). If no default locale was specified the "C" locale is used.

The data type for the template parameter V can be int, short, ushort, long, qint64, quint64, or any integral data type.

str = QString8("Decimal 63 is %1 in hex").formatArg(63, 0, 16); // str == "Decimal 63 is 3f in hex"
QLocale::setDefault(QLocale(QLocale::English, QLocale::UnitedStates));
str = QString("%1 %L2 %L3").formatArg(12345).formatArg(12345).formatArg(12345, 0, 16); // str == "12345 12,345 3039"

Refer to Argument Formats for more details.

template<typename T , typename... Ts>
T QStringParser::formatArgs ( const T &  str,
Ts...  args 
)
nodiscardinlinestatic

Returns a copy of string str with the numbered place markers replaced by the arguments args. The number of arguments for args is variable and unlimited.

This following shows two different ways to create a string used to display a progress status. The code to format status1 and status2 will produce the same result. The second example one is faster and more accurate since the arguments will be replaced in one pass.

QString8 count = "1"; // current file #
QString8 total = "5"; // total # of files
QString8 fName = "main.cpp"; // current file name
// example 1
QString8 status1 = QString8("Processing file %1 of %2: %3");
status1 = QStringParser::formatArg(status1, count);
status1 = QStringParser::formatArg(status1, total);
status1 = QStringParser::formatArg(status1, fName); // Processing file 1 of 5: main.cpp
// example 2
QString8 status2 = QString8("Processing file %1 of %2: %3");
status2 = QStringParser::formatArgs(status2, count, total, fName); // Processing file 1 of 5: main.cpp
template<typename T , typename V >
T QStringParser::join ( const QList< T > &  list,
const V &  separator 
)
static

Joins all the strings in a list into one single string with each element separated by the given separator separator. The separator can be empty.

The data type for the template parameter V can be char, QChar, QChar32, QString, QString8, QString16, or any data type can be appended to the data type of the string.

See also
split()
template<typename T = QString8>
T QStringParser::number ( double  value,
char  format = 'g',
int  precision = 6 
)
nodiscardinlinestatic

Returns a string equivalent of the number value formatted according to the specified format and precision. Unlike QLocale::toString() this method does not honor the user's locale settings.

Refer to Argument Formats for details.

See also
QLocale::toString()
template<typename T = QString8, typename V >
T QStringParser::number ( value,
int  base = 10 
)
nodiscardinlinestatic

Returns a string equivalent of the number value according to the specified base. The default base is 10 and must be between 2 and 36. For bases other than 10 value is treated as an unsigned integer.

long a = 63;
QString8 s = QString8::number(a, 16); // s == "3f"
QString8 t = QString8::number(a, 16).toUpper(); // t == "3F"

The data type for the template parameter V can be int, short, ushort, long, qint64, quint64, or any integral data type.

template<typename T >
T QStringParser::section ( const T &  str,
const T &  separator,
int  firstSection,
int  lastSection = -1,
SectionFlags  flags = SectionDefault 
)
static

This method overload is used when the separator and the string are the same data type, namely a string. This is useful when the separator is not a single QChar32.

QString8 data = "firstName**middleName**lastName**phone";
str = QStringParser::section(data, "**", 2, 2); // str == "lastName"
str = QStringParser::section(data, "**", -3, -2); // str == "middleName**lastName"
See also
split()
template<typename T >
T QStringParser::section ( const T &  str,
QChar32  separator,
int  firstSection,
int  lastSection = -1,
SectionFlags  flags = SectionDefault 
)
inlinestatic

This string is treated as a sequence of fields separated by the character separator. The returned string consists of the fields from position firstSection to position lastSection inclusive. If lastSection is not specified all fields from position firstSection to the end of the string are included. Fields are numbered 0, 1, 2, etc., counting from the left, and -1, -2, etc., counting from right to left.

The flags argument can be used to affect some aspects, including case sensitivity, if empty sections should be skipped, and how to deal with leading and trailing separators.

Returns a section of the string.

QStringParser::SectionFlag flag = QStringParser::SectionFlag::SectionSkipEmpty;
QString8 csv = "firstName,middleName,lastName,phone";
str = QStringParser::section(csv, ',', 2, 2); // str == "lastName"
QString8 path = "/usr/local/bin/uic"; // first field is empty
str = QStringParser::section(path, '/', 3, 4); // str == "bin/uic"
str = QStringParser::section(path, '/', 3, 3, flag); // str == "uic"

If firstSection or lastSection are negative sections are counted from the right of the string. The right most section is -1, the previous section is -2, and so on.

str = QStringParser::section(csv, ',', -3, -2); // str == "middleName,lastName"
str = QStringParser::section(path, '/', -1); // str == "uic"
See also
split(), SectionFlags
template<typename T >
QList< T > QStringParser::split ( const T &  str,
const QRegularExpression regExp,
SplitBehavior  behavior = KeepEmptyParts 
)
static

Splits the string into substrings where the regular expression regExp matches. If regExp does not match anywhere in the string, split() returns a single element list containing this string.

The following example extracts the words in a sentence using one or more whitespace characters as the separator.

QString str;
str = "Some text\n\twith odd whitespace.";
list = str.split(QRegularExpression("\s+")); // list = [ "Some", "text", "with", "odd", "whitespace." ]

The following example uses a word boundary assertion to split the string into an alternating sequence of non-word and word tokens.

QString str;
str = "Now: this sentence fragment.";
list = str.split(QRegularExpression("\b")); // list = [ "", "Now", ": ", "this", " ", "sentence", " ", "fragment", "." ]
See also
QStringList::join(), section()
template<typename T >
QList< T > QStringParser::split ( const T &  str,
const T &  separator,
SplitBehavior  behavior = KeepEmptyParts,
Qt::CaseSensitivity  cs = Qt::CaseSensitive 
)
static

Splits the string str into substrings using the string separator as the marker, which indicates where to break. Returns a list of the substrings in a QList. If separator does not match anywhere in the string, split() will return a single element in the list containing the passed string.

The value for cs specifies whether separator should be matched case sensitively or case insensitively.

If behavior is QStringParser::SkipEmptyParts then empty entries do not appear in the result. By default empty entries are retained.

QString8 str = "a,,b,c";
QStringList x = QStringParser::split(str, ","); // [ "a", "", "b", "c" ]
QStringList y = QStringParser::split(str, ",", QStringParser::SkipEmptyParts); // [ "a", "b", "c" ]
See also
join(), section()
template<typename T >
QList< T > QStringParser::split ( const T &  str,
QChar32  separator,
SplitBehavior  behavior = KeepEmptyParts,
Qt::CaseSensitivity  cs = Qt::CaseSensitive 
)
static

Splits the string str into substrings using the code point separator as the marker, which indicates where to break. Returns a list of the substrings in a QList. If separator does not match anywhere in the string, split() will return a single element in the list containing the passed string.

The value for cs specifies whether separator should be matched case sensitively or case insensitively.

If behavior is QStringParser::SkipEmptyParts then empty entries do not appear in the result. By default empty entries are retained.

See also
join(), section()
template<typename T = QString8>
double QStringParser::toDouble ( const T &  str,
bool *  ok = nullptr 
)
inlinestatic

Returns the string str converted to a double value. The return value is 0.0 if the conversion fails. If a conversion error occurs *ok is set to false, otherwise it is set to true.

The string conversion will always happen the 'C' locale. For locale aware string parsing use QLocale methods such as QLocale::toDouble().

QString8 str = "1234.56";
double val = QStringParser::toDouble(str); // val == 1234.56

The string may only contain a valid floating point number, the plus/minus sign, a decimal point, or the characters g and e for scientific notation.

bool ok;
double d;
d = QStringParser::toDouble<QString8>("1234.56e-02", &ok); // ok == true, d == 12.3456
See also
number(), QLocale::setDefault(), QLocale::toDouble()
template<typename T = QString8>
float QStringParser::toFloat ( const T &  str,
bool *  ok = nullptr 
)
inlinestatic

Returns the string str converted to a float value. Returns 0.0 if the conversion fails. If a conversion error occurs *ok is set to false, otherwise it is set to true.

The string conversion will always happen the 'C' locale. For locale aware string parsing use QLocale methods such as QLocale::toFloat().

QString8 str = "1234.56";
QStringParser::toFloat(str); // returns 1234.56

The string may only contain a valid floating point number, the plus/minus sign, a decimal point, or the characters g and e for scientific notation.

bool ok;
QString8 str = "R2D2";
QStringParser::toFloat(str, &ok); // returns 0.0, sets ok to false
See also
number(), toDouble(), toInteger(), QLocale::toFloat()
template<typename R , typename T = QString8>
R QStringParser::toInteger ( const T &  str,
bool *  ok = nullptr,
int  base = 10 
)
inlinestatic

Returns the string str converted to an integer of type T using numeric base base. The base value is 10 by default and must be between 2 and 36. If the base value is 0 the beginning of the string is used to deduce the base. If the string begins with "0x" base 16 is used, if the string begins with "0" base 8 is used, otherwise base 10 is used.

The return value is 0 if the conversion fails. If a conversion error occurs *ok is set to false, otherwise it is set to true.

QString8 str = "FF";
bool ok;
int v1 = QStringParser::toInteger<int>(str, &ok, 16); // v1 == 255, ok == true
int v2 = QStringParser::toInteger<int>(str, &ok, 10); // v2 == 0, ok == false
qint64 v3 = QStringParser::toInteger<qint64>(str, &ok, 16); // v3 == 255, ok == true
str = "-73";
long v4 = QStringParser::toInteger<long>(str); // v4 = -73
str = "45";
uint v5 = QStringParser::toInteger<uint>(str); // v5 = 45
See also
number(), toFloat(), toDouble()