QStringRef Class
The QStringRef class provides a thin wrapper around QString substrings. More...
Header: | #include <QStringRef> |
qmake: | QT += core |
Since: | Qt 4.3 |
This class was introduced in Qt 4.3.
Note: All functions in this class are reentrant.
Public Types
typedef | const_iterator |
typedef | const_reverse_iterator |
Public Functions
QStringRef | appendTo(QString *string) const |
int | count(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
int | count(QChar ch, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
int | count(const QStringRef &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
bool | endsWith(QLatin1String str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
bool | endsWith(QChar ch, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
bool | endsWith(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
bool | endsWith(const QStringRef &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
int | indexOf(const QString &str, int from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
int | indexOf(QChar ch, int from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
int | indexOf(QLatin1String str, int from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
int | indexOf(const QStringRef &str, int from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
bool | isRightToLeft() const |
int | lastIndexOf(const QString &str, int from = -1, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
int | lastIndexOf(QChar ch, int from = -1, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
int | lastIndexOf(QLatin1String str, int from = -1, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
int | lastIndexOf(const QStringRef &str, int from = -1, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
QVector<QStringRef> | split(const QString &sep, QString::SplitBehavior behavior = QString::KeepEmptyParts, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
QVector<QStringRef> | split(QChar sep, QString::SplitBehavior behavior = QString::KeepEmptyParts, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
bool | startsWith(QLatin1String str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
bool | startsWith(QChar ch, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
bool | startsWith(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
bool | startsWith(const QStringRef &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
double | toDouble(bool *ok = nullptr) const |
float | toFloat(bool *ok = nullptr) const |
int | toInt(bool *ok = nullptr, int base = 10) const |
QByteArray | toLatin1() const |
QByteArray | toLocal8Bit() const |
qlonglong | toLongLong(bool *ok = nullptr, int base = 10) const |
short | toShort(bool *ok = nullptr, int base = 10) const |
QString | toString() const |
uint | toUInt(bool *ok = nullptr, int base = 10) const |
qulonglong | toULongLong(bool *ok = nullptr, int base = 10) const |
ushort | toUShort(bool *ok = nullptr, int base = 10) const |
QVector<uint> | toUcs4() const |
QByteArray | toUtf8() const |
QStringRef | trimmed() const |
Related Non-Members
bool | operator<(const QStringRef &s1, const QStringRef &s2) |
bool | operator==(const QStringRef &s1, const QStringRef &s2) |
bool | operator==(const QString &s1, const QStringRef &s2) |
bool | operator==(QLatin1String s1, const QStringRef &s2) |
Detailed Description
QStringRef provides a read-only subset of the QString API.
A string reference explicitly references a portion of a string() with a given size(), starting at a specific position(). Calling toString() returns a copy of the data as a real QString instance.
This class is designed to improve the performance of substring handling when manipulating substrings obtained from existing QString instances. QStringRef avoids the memory allocation and reference counting overhead of a standard QString by simply referencing a part of the original string. This can prove to be advantageous in low level code, such as that used in a parser, at the expense of potentially more complex code.
For most users, there are no semantic benefits to using QStringRef instead of QString since QStringRef requires attention to be paid to memory management issues, potentially making code more complex to write and maintain.
Warning: A QStringRef is only valid as long as the referenced string exists. If the original string is deleted, the string reference points to an invalid memory location.
We suggest that you only use this class in stable code where profiling has clearly identified that performance improvements can be made by replacing standard string operations with the optimized substring handling provided by this class.
See also Implicitly Shared Classes.
Member Type Documentation
typedef QStringRef::const_iterator
This typedef provides an STL-style const iterator for QStringRef.
This typedef was introduced in Qt 5.4.
See also QStringRef::const_reverse_iterator.
typedef QStringRef::const_reverse_iterator
This typedef provides an STL-style const reverse iterator for QStringRef.
This typedef was introduced in Qt 5.7.
See also QStringRef::const_iterator.
Member Function Documentation
QStringRef QStringRef::appendTo(QString *string) const
Appends the string reference to string, and returns a new reference to the combined string data.
int QStringRef::count(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
Returns the number of (potentially overlapping) occurrences of the string str in this string reference.
If cs is Qt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.
This function was introduced in Qt 4.8.
See also QString::count(), contains(), and indexOf().
int QStringRef::count(QChar ch, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
This function overloads count().
Returns the number of occurrences of the character ch in the string reference.
If cs is Qt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.
This function was introduced in Qt 4.8.
See also QString::count(), contains(), and indexOf().
int QStringRef::count(const QStringRef &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
This function overloads count().
Returns the number of (potentially overlapping) occurrences of the string reference str in this string reference.
If cs is Qt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.
This function was introduced in Qt 4.8.
See also QString::count(), contains(), and indexOf().
bool QStringRef::endsWith(QLatin1String str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
This function overloads endsWith().
This function was introduced in Qt 4.8.
See also QString::endsWith() and endsWith().
bool QStringRef::endsWith(QChar ch, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
This function overloads endsWith().
Returns true
if the string reference ends with ch; otherwise returns false
.
If cs is Qt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.
This function was introduced in Qt 4.8.
See also QString::endsWith() and endsWith().
bool QStringRef::endsWith(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
Returns true
if the string reference ends with str; otherwise returns false
.
If cs is Qt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.
This function was introduced in Qt 4.8.
See also QString::endsWith() and startsWith().
bool QStringRef::endsWith(const QStringRef &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
This function overloads endsWith().
This function was introduced in Qt 4.8.
See also QString::endsWith() and endsWith().
int QStringRef::indexOf(const QString &str, int from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
Returns the index position of the first occurrence of the string str in this string reference, searching forward from index position from. Returns -1 if str is not found.
If cs is Qt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.
If from is -1, the search starts at the last character; if it is -2, at the next to last character and so on.
This function was introduced in Qt 4.8.
See also QString::indexOf(), lastIndexOf(), contains(), and count().
int QStringRef::indexOf(QChar ch, int from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
This function overloads indexOf().
Returns the index position of the first occurrence of the character ch in the string reference, searching forward from index position from. Returns -1 if ch could not be found.
This function was introduced in Qt 4.8.
See also QString::indexOf(), lastIndexOf(), contains(), and count().
int QStringRef::indexOf(QLatin1String str, int from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
Returns the index position of the first occurrence of the string str in this string reference, searching forward from index position from. Returns -1 if str is not found.
If cs is Qt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.
If from is -1, the search starts at the last character; if it is -2, at the next to last character and so on.
This function was introduced in Qt 4.8.
See also QString::indexOf(), lastIndexOf(), contains(), and count().
int QStringRef::indexOf(const QStringRef &str, int from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
This function overloads indexOf().
Returns the index position of the first occurrence of the string reference str in this string reference, searching forward from index position from. Returns -1 if str is not found.
If cs is Qt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.
This function was introduced in Qt 4.8.
See also QString::indexOf(), lastIndexOf(), contains(), and count().
bool QStringRef::isRightToLeft() const
Returns true
if the string is read right to left.
This function was introduced in Qt 5.9.
See also QString::isRightToLeft().
int QStringRef::lastIndexOf(const QString &str, int from = -1, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
Returns the index position of the last occurrence of the string str in this string reference, searching backward from index position from. If from is -1 (default), the search starts at the last character; if from is -2, at the next to last character and so on. Returns -1 if str is not found.
If cs is Qt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.
This function was introduced in Qt 4.8.
See also QString::lastIndexOf(), indexOf(), contains(), and count().
int QStringRef::lastIndexOf(QChar ch, int from = -1, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
This function overloads lastIndexOf().
Returns the index position of the last occurrence of the character ch, searching backward from position from.
This function was introduced in Qt 4.8.
See also QString::lastIndexOf(), indexOf(), contains(), and count().
int QStringRef::lastIndexOf(QLatin1String str, int from = -1, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
This function overloads lastIndexOf().
Returns the index position of the last occurrence of the string str in this string reference, searching backward from index position from. If from is -1 (default), the search starts at the last character; if from is -2, at the next to last character and so on. Returns -1 if str is not found.
If cs is Qt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.
This function was introduced in Qt 4.8.
See also QString::lastIndexOf(), indexOf(), contains(), and count().
int QStringRef::lastIndexOf(const QStringRef &str, int from = -1, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
This function overloads lastIndexOf().
Returns the index position of the last occurrence of the string reference str in this string reference, searching backward from index position from. If from is -1 (default), the search starts at the last character; if from is -2, at the next to last character and so on. Returns -1 if str is not found.
If cs is Qt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.
This function was introduced in Qt 4.8.
See also QString::lastIndexOf(), indexOf(), contains(), and count().
QVector<QStringRef> QStringRef::split(const QString &sep, QString::SplitBehavior behavior = QString::KeepEmptyParts, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
Splits the string into substrings references wherever sep occurs, and returns the list of those strings.
See QString::split() for how sep, behavior and cs interact to form the result.
Note: All references are valid as long this string is alive. Destroying this string will cause all references to be dangling pointers.
This function was introduced in Qt 5.4.
QVector<QStringRef> QStringRef::split(QChar sep, QString::SplitBehavior behavior = QString::KeepEmptyParts, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
This is an overloaded function.
This function was introduced in Qt 5.4.
bool QStringRef::startsWith(QLatin1String str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
This function overloads startsWith().
This function was introduced in Qt 4.8.
See also QString::startsWith() and endsWith().
bool QStringRef::startsWith(QChar ch, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
This function overloads startsWith().
Returns true
if the string reference starts with ch; otherwise returns false
.
If cs is Qt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.
This function was introduced in Qt 4.8.
See also QString::startsWith() and endsWith().
bool QStringRef::startsWith(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
Returns true
if the string reference starts with str; otherwise returns false
.
If cs is Qt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.
This function was introduced in Qt 4.8.
See also QString::startsWith() and endsWith().
bool QStringRef::startsWith(const QStringRef &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
This function overloads startsWith().
This function was introduced in Qt 4.8.
See also QString::startsWith() and endsWith().
double QStringRef::toDouble(bool *ok = nullptr) const
Returns the string converted to a double
value.
Returns an infinity if the conversion overflows or 0.0 if the conversion fails for other reasons (e.g. underflow).
If ok is not nullptr
, failure is reported by setting *ok to false
, and success by setting *ok to true
.
The string conversion will always happen in the 'C' locale. For locale dependent conversion use QLocale::toDouble()
For historic reasons, this function does not handle thousands group separators. If you need to convert such numbers, use QLocale::toDouble().
This function was introduced in Qt 5.1.
See also QString::toDouble().
float QStringRef::toFloat(bool *ok = nullptr) const
Returns the string converted to a float
value.
Returns an infinity if the conversion overflows or 0.0 if the conversion fails for other reasons (e.g. underflow).
If ok is not nullptr
, failure is reported by setting *ok to false
, and success by setting *ok to true
.
The string conversion will always happen in the 'C' locale. For locale dependent conversion use QLocale::toFloat()
This function was introduced in Qt 5.1.
See also QString::toFloat().
int QStringRef::toInt(bool *ok = nullptr, int base = 10) const
Returns the string converted to an int
using base base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.
If ok is not nullptr
, failure is reported by setting *ok to false
, and success by setting *ok to true
.
If base is 0, the C language convention is used: 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 string conversion will always happen in the 'C' locale. For locale dependent conversion use QLocale::toInt()
This function was introduced in Qt 5.1.
See also QString::toInt().
QByteArray QStringRef::toLatin1() const
Returns a Latin-1 representation of the string as a QByteArray.
The returned byte array is undefined if the string contains non-Latin1 characters. Those characters may be suppressed or replaced with a question mark.
This function was introduced in Qt 4.8.
See also toUtf8(), toLocal8Bit(), and QTextCodec.
QByteArray QStringRef::toLocal8Bit() const
Returns the local 8-bit representation of the string as a QByteArray. The returned byte array is undefined if the string contains characters not supported by the local 8-bit encoding.
QTextCodec::codecForLocale() is used to perform the conversion from Unicode. If the locale encoding could not be determined, this function does the same as toLatin1().
If this string contains any characters that cannot be encoded in the locale, the returned byte array is undefined. Those characters may be suppressed or replaced by another.
This function was introduced in Qt 4.8.
See also toLatin1(), toUtf8(), and QTextCodec.
qlonglong QStringRef::toLongLong(bool *ok = nullptr, int base = 10) const
Returns the string converted to a long long
using base base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.
If ok is not nullptr
, failure is reported by setting *ok to false
, and success by setting *ok to true
.
If base is 0, the C language convention is used: 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 string conversion will always happen in the 'C' locale. For locale dependent conversion use QLocale::toLongLong()
This function was introduced in Qt 5.1.
See also QString::toLongLong().
short QStringRef::toShort(bool *ok = nullptr, int base = 10) const
Returns the string converted to a short
using base base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.
If ok is not nullptr
, failure is reported by setting *ok to false
, and success by setting *ok to true
.
If base is 0, the C language convention is used: 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 string conversion will always happen in the 'C' locale. For locale dependent conversion use QLocale::toShort()
This function was introduced in Qt 5.1.
See also QString::toShort().
QString QStringRef::toString() const
Returns a copy of the string reference as a QString object.
If the string reference is not a complete reference of the string (meaning that position() is 0 and size() equals string()->size()), this function will allocate a new string to return.
See also string().
uint QStringRef::toUInt(bool *ok = nullptr, int base = 10) const
Returns the string converted to an unsigned int
using base base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.
If ok is not nullptr
, failure is reported by setting *ok to false
, and success by setting *ok to true
.
If base is 0, the C language convention is used: 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 string conversion will always happen in the 'C' locale. For locale dependent conversion use QLocale::toUInt()
This function was introduced in Qt 5.1.
See also QString::toUInt().
qulonglong QStringRef::toULongLong(bool *ok = nullptr, int base = 10) const
Returns the string converted to an unsigned long long
using base base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.
If ok is not nullptr
, failure is reported by setting *ok to false
, and success by setting *ok to true
.
If base is 0, the C language convention is used: 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 string conversion will always happen in the 'C' locale. For locale dependent conversion use QLocale::toULongLong()
This function was introduced in Qt 5.1.
See also QString::toULongLong().
ushort QStringRef::toUShort(bool *ok = nullptr, int base = 10) const
Returns the string converted to an unsigned short
using base base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.
If ok is not nullptr
, failure is reported by setting *ok to false
, and success by setting *ok to true
.
If base is 0, the C language convention is used: 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 string conversion will always happen in the 'C' locale. For locale dependent conversion use QLocale::toUShort()
This function was introduced in Qt 5.1.
See also QString::toUShort().
QVector<uint> QStringRef::toUcs4() const
Returns a UCS-4/UTF-32 representation of the string as a QVector<uint>.
UCS-4 is a Unicode codec and therefore it is lossless. All characters from this string will be encoded in UCS-4. Any invalid sequence of code units in this string is replaced by the Unicode's replacement character (QChar::ReplacementCharacter, which corresponds to U+FFFD
).
The returned vector is not NUL terminated.
This function was introduced in Qt 4.8.
See also toUtf8(), toLatin1(), toLocal8Bit(), and QTextCodec.
QByteArray QStringRef::toUtf8() const
Returns a UTF-8 representation of the string as a QByteArray.
UTF-8 is a Unicode codec and can represent all characters in a Unicode string like QString.
This function was introduced in Qt 4.8.
See also toLatin1(), toLocal8Bit(), and QTextCodec.
QStringRef QStringRef::trimmed() const
Returns a string that has whitespace removed from the start and the end.
Whitespace means any character for which QChar::isSpace() returns true
. This includes the ASCII characters '\t', '\n', '\v', '\f', '\r', and ' '.
Unlike QString::simplified(), trimmed() leaves internal whitespace alone.
This function was introduced in Qt 5.1.
See also QString::trimmed().
Related Non-Members
bool QStringRef::operator<(const QStringRef &s1, const QStringRef &s2)
Returns true
if string reference s1 is lexically less than string reference s2; otherwise returns false
.
The comparison is based exclusively on the numeric Unicode values of the characters and is very fast, but is not what a human would expect. Consider sorting user-interface strings using the QString::localeAwareCompare() function.
bool QStringRef::operator==(const QStringRef &s1, const QStringRef &s2)
Returns true
if string reference s1 is lexically equal to string reference s2; otherwise returns false
.
bool QStringRef::operator==(const QString &s1, const QStringRef &s2)
Returns true
if string s1 is lexically equal to string reference s2; otherwise returns false
.
bool QStringRef::operator==(QLatin1String s1, const QStringRef &s2)
Returns true
if string s1 is lexically equal to string reference s2; otherwise returns false
.