diff options
Diffstat (limited to 'src/corelib/tools/qstring.cpp')
-rw-r--r-- | src/corelib/tools/qstring.cpp | 125 |
1 files changed, 60 insertions, 65 deletions
diff --git a/src/corelib/tools/qstring.cpp b/src/corelib/tools/qstring.cpp index 4852d20082..ee9d486eb8 100644 --- a/src/corelib/tools/qstring.cpp +++ b/src/corelib/tools/qstring.cpp @@ -120,7 +120,7 @@ QT_BEGIN_NAMESPACE * Whenever multiple alternatives are equivalent or near so, we prefer the one * using instructions from SSE2, since SSE2 is guaranteed to be enabled for all * 64-bit builds and we enable it for 32-bit builds by default. Use of higher - * SSE versions should be done when there's a clear performance benefit and + * SSE versions should be done when there is a clear performance benefit and * requires fallback code to SSE2, if it exists. * * Performance measurement in the past shows that most strings are short in @@ -1472,7 +1472,7 @@ const QString::Null QString::null = { }; In all of the QString functions that take \c{const char *} parameters, the \c{const char *} is interpreted as a classic C-style '\\0'-terminated string encoded in UTF-8. It is legal for - the \c{const char *} parameter to be 0. + the \c{const char *} parameter to be \nullptr. You can also provide string data as an array of \l{QChar}s: @@ -1556,7 +1556,7 @@ const QString::Null QString::null = { }; functions. The former searches forward starting from a given index position, the latter searches backward. Both return the index position of the character or substring if they find it; otherwise, - they return -1. For example, here's a typical loop that finds all + they return -1. For example, here is a typical loop that finds all occurrences of a particular substring: \snippet qstring/main.cpp 6 @@ -1685,10 +1685,9 @@ const QString::Null QString::null = { }; \snippet qstring/main.cpp 8 All functions except isNull() treat null strings the same as empty - strings. For example, toUtf8().constData() returns a pointer to a - '\\0' character for a null string (\e not a null pointer), and - QString() compares equal to QString(""). We recommend that you - always use the isEmpty() function and avoid isNull(). + strings. For example, toUtf8().constData() returns a valid pointer + (\e not nullptr) to a '\\0' character for a null string. We + recommend that you always use the isEmpty() function and avoid isNull(). \section1 Argument Formats @@ -2045,7 +2044,7 @@ const QString::Null QString::null = { }; the size of wchar. If wchar is 4 bytes, the \a string is interpreted as UCS-4, if wchar is 2 bytes it is interpreted as UTF-16. - If \a size is -1 (default), the \a string has to be 0 terminated. + If \a size is -1 (default), the \a string has to be \\0'-terminated. \sa fromUtf16(), fromLatin1(), fromLocal8Bit(), fromUtf8(), fromUcs4(), fromStdWString() */ @@ -2111,7 +2110,7 @@ int QString::toUcs4_helper(const ushort *uc, int length, uint *out) If \a unicode is 0, a null string is constructed. - If \a size is negative, \a unicode is assumed to point to a nul-terminated + If \a size is negative, \a unicode is assumed to point to a \\0'-terminated array and its length is determined dynamically. The terminating nul-character is not considered part of the string. @@ -4553,7 +4552,7 @@ int QString::indexOf(const QRegularExpression& re, int from) const expression \a re in the string, searching forward from index position \a from. Returns -1 if \a re didn't match anywhere. - If the match is successful and \a rmatch is not a null pointer, it also + If the match is successful and \a rmatch is not \nullptr, it also writes the results of the match into the QRegularExpressionMatch object pointed to by \a rmatch. @@ -4604,7 +4603,7 @@ int QString::lastIndexOf(const QRegularExpression &re, int from) const expression \a re in the string, which starts before the index position \a from. Returns -1 if \a re didn't match anywhere. - If the match is successful and \a rmatch is not a null pointer, it also + If the match is successful and \a rmatch is not \nullptr, it also writes the results of the match into the QRegularExpressionMatch object pointed to by \a rmatch. @@ -4655,14 +4654,14 @@ bool QString::contains(const QRegularExpression &re) const Returns \c true if the regular expression \a re matches somewhere in this string; otherwise returns \c false. - If the match is successful and \a match is not a null pointer, it also + If the match is successful and \a rmatch is not \nullptr, it also writes the results of the match into the QRegularExpressionMatch object - pointed to by \a match. + pointed to by \a rmatch. \sa QRegularExpression::match() */ -bool QString::contains(const QRegularExpression &re, QRegularExpressionMatch *match) const +bool QString::contains(const QRegularExpression &re, QRegularExpressionMatch *rmatch) const { if (!re.isValid()) { qWarning("QString::contains: invalid QRegularExpression object"); @@ -4670,8 +4669,8 @@ bool QString::contains(const QRegularExpression &re, QRegularExpressionMatch *ma } QRegularExpressionMatch m = re.match(*this); bool hasMatch = m.hasMatch(); - if (hasMatch && match) - *match = qMove(m); + if (hasMatch && rmatch) + *rmatch = qMove(m); return hasMatch; } @@ -5452,7 +5451,7 @@ static QVector<uint> qt_convert_to_ucs4(QStringView string); this string is replaced by the Unicode's replacement character (QChar::ReplacementCharacter, which corresponds to \c{U+FFFD}). - The returned vector is not NUL terminated. + The returned vector is not \\0'-terminated. \sa fromUtf8(), toUtf8(), toLatin1(), toLocal8Bit(), QTextCodec, fromUcs4(), toWCharArray() */ @@ -5484,7 +5483,7 @@ static QVector<uint> qt_convert_to_ucs4(QStringView string) this string is replaced by the Unicode's replacement character (QChar::ReplacementCharacter, which corresponds to \c{U+FFFD}). - The returned vector is not NUL terminated. + The returned vector is not \\0'-terminated. \sa QString::toUcs4(), QStringView::toUcs4(), QtPrivate::convertToLatin1(), QtPrivate::convertToLocal8Bit(), QtPrivate::convertToUtf8() @@ -5642,8 +5641,7 @@ QString QString::fromUtf8_helper(const char *str, int size) Returns a QString initialized with the first \a size characters of the Unicode string \a unicode (ISO-10646-UTF-16 encoded). - If \a size is -1 (default), \a unicode must be terminated - with a 0. + If \a size is -1 (default), \a unicode must be \\0'-terminated. This function checks for a Byte Order Mark (BOM). If it is missing, host byte order is assumed. @@ -5674,8 +5672,7 @@ QString QString::fromUtf16(const ushort *unicode, int size) Returns a QString initialized with the first \a size characters of the Unicode string \a str (ISO-10646-UTF-16 encoded). - If \a size is -1 (default), \a str must be terminated - with a 0. + If \a size is -1 (default), \a str must be \\0'-terminated. This function checks for a Byte Order Mark (BOM). If it is missing, host byte order is assumed. @@ -5695,8 +5692,7 @@ QString QString::fromUtf16(const ushort *unicode, int size) Returns a QString initialized with the first \a size characters of the Unicode string \a str (ISO-10646-UCS-4 encoded). - If \a size is -1 (default), \a str must be terminated - with a 0. + If \a size is -1 (default), \a str must be \\0'-terminated. \sa toUcs4(), fromUtf16(), utf16(), setUtf16(), fromWCharArray(), fromStdU32String() */ @@ -5707,8 +5703,7 @@ QString QString::fromUtf16(const ushort *unicode, int size) Returns a QString initialized with the first \a size characters of the Unicode string \a unicode (ISO-10646-UCS-4 encoded). - If \a size is -1 (default), \a unicode must be terminated - with a 0. + If \a size is -1 (default), \a unicode must be \\0'-terminated. \sa toUcs4(), fromUtf16(), utf16(), setUtf16(), fromWCharArray(), fromStdU32String() */ @@ -6718,7 +6713,7 @@ namespace QUnicodeTables { this function requires to be a valid, empty string) and \c{s} contains the only copy of the string, without reallocation (thus, \a it is still valid). - There's one pathological case left: when the in-place conversion needs to + There is one pathological case left: when the in-place conversion needs to reallocate memory to grow the buffer. In that case, we need to adjust the \a it pointer. */ @@ -6876,7 +6871,7 @@ QString &QString::sprintf(const char *cformat, ...) \warning We do not recommend using QString::asprintf() in new Qt code. Instead, consider using QTextStream or arg(), both of which support Unicode strings seamlessly and are type-safe. - Here's an example that uses QTextStream: + Here is an example that uses QTextStream: \snippet qstring/main.cpp 64 @@ -7237,7 +7232,7 @@ QString QString::vasprintf(const char *cformat, va_list ap) base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails. - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. If \a base is 0, the C language convention is used: If the string @@ -7279,7 +7274,7 @@ qlonglong QString::toIntegral_helper(const QChar *data, int len, bool *ok, int b base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails. - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. If \a base is 0, the C language convention is used: If the string @@ -7323,7 +7318,7 @@ qulonglong QString::toIntegral_helper(const QChar *data, uint len, bool *ok, int base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails. - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. If \a base is 0, the C language convention is used: If the string @@ -7354,7 +7349,7 @@ long QString::toLong(bool *ok, int base) const base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails. - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. If \a base is 0, the C language convention is used: If the string @@ -7384,7 +7379,7 @@ ulong QString::toULong(bool *ok, int base) const base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails. - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. If \a base is 0, the C language convention is used: If the string @@ -7413,7 +7408,7 @@ int QString::toInt(bool *ok, int base) const base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails. - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. If \a base is 0, the C language convention is used: If the string @@ -7442,7 +7437,7 @@ uint QString::toUInt(bool *ok, int base) const base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails. - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. If \a base is 0, the C language convention is used: If the string @@ -7471,7 +7466,7 @@ short QString::toShort(bool *ok, int base) const base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails. - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. If \a base is 0, the C language convention is used: If the string @@ -7502,7 +7497,7 @@ ushort QString::toUShort(bool *ok, int base) const Returns an infinity if the conversion overflows or 0.0 if the conversion fails for other reasons (e.g. underflow). - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. \snippet qstring/main.cpp 66 @@ -7541,7 +7536,7 @@ double QString::toDouble(bool *ok) const Returns an infinity if the conversion overflows or 0.0 if the conversion fails for other reasons (e.g. underflow). - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. \warning The QString content may only contain valid numerical characters @@ -7843,7 +7838,7 @@ QStringList QString::split(const QString &sep, SplitBehavior behavior, Qt::CaseS the result. \note All references are valid as long this string is alive. Destroying this - string will cause all references be dangling pointers. + string will cause all references to be dangling pointers. \since 5.4 \sa QStringRef split() @@ -7877,7 +7872,7 @@ QVector<QStringRef> QString::splitRef(QChar sep, SplitBehavior behavior, Qt::Cas the result. \note All references are valid as long this string is alive. Destroying this - string will cause all references be dangling pointers. + string will cause all references to be dangling pointers. \since 5.4 */ @@ -7926,17 +7921,17 @@ static ResultList splitString(const QString &source, MidMethod mid, const QRegEx does not match anywhere in the string, split() returns a single-element list containing this string. - Here's an example where we extract the words in a sentence + Here is an example where we extract the words in a sentence using one or more whitespace characters as the separator: \snippet qstring/main.cpp 59 - Here's a similar example, but this time we use any sequence of + Here is a similar example, but this time we use any sequence of non-word characters as the separator: \snippet qstring/main.cpp 60 - Here's a third example where we use a zero-length assertion, + Here is a third example where we use a zero-length assertion, \b{\\b} (word boundary), to split the string into an alternating sequence of non-word and word tokens: @@ -7959,7 +7954,7 @@ QStringList QString::split(const QRegExp &rx, SplitBehavior behavior) const single-element vector containing this string reference. \note All references are valid as long this string is alive. Destroying this - string will cause all references be dangling pointers. + string will cause all references to be dangling pointers. \sa QStringRef split() */ @@ -8008,17 +8003,17 @@ static ResultList splitString(const QString &source, MidMethod mid, const QRegul does not match anywhere in the string, split() returns a single-element list containing this string. - Here's an example where we extract the words in a sentence + Here is an example where we extract the words in a sentence using one or more whitespace characters as the separator: \snippet qstring/main.cpp 90 - Here's a similar example, but this time we use any sequence of + Here is a similar example, but this time we use any sequence of non-word characters as the separator: \snippet qstring/main.cpp 91 - Here's a third example where we use a zero-length assertion, + Here is a third example where we use a zero-length assertion, \b{\\b} (word boundary), to split the string into an alternating sequence of non-word and word tokens: @@ -8041,7 +8036,7 @@ QStringList QString::split(const QRegularExpression &re, SplitBehavior behavior) single-element vector containing this string reference. \note All references are valid as long this string is alive. Destroying this - string will cause all references be dangling pointers. + string will cause all references to be dangling pointers. \sa split() QStringRef */ @@ -9178,7 +9173,7 @@ bool QString::isRightToLeft() const to create a deep copy of the data, ensuring that the raw data isn't modified. - Here's an example of how we can use a QRegularExpression on raw data in + Here is an example of how we can use a QRegularExpression on raw data in memory without requiring to copy the data into a QString: \snippet qstring/main.cpp 22 @@ -9446,11 +9441,11 @@ QString &QString::setRawData(const QChar *unicode, int size) The range \c{[first,last)} must remain valid for the lifetime of this Latin-1 string object. - Passing \c nullptr as \a first is safe if \a last is \c nullptr, + Passing \nullptr as \a first is safe if \a last is \nullptr, too, and results in a null Latin-1 string. The behavior is undefined if \a last precedes \a first, \a first - is \c nullptr and \a last is not, or if \c{last - first > + is \nullptr and \a last is not, or if \c{last - first > INT_MAX}. */ @@ -10337,8 +10332,8 @@ ownership of it, no memory is freed when instances are destroyed. /*! \fn bool QStringRef::isNull() const - Returns \c true if string() returns a null pointer or a pointer to a - null string; otherwise returns \c true. + Returns \c true if this string reference does not reference a string or if + the string it references is null (i.e. QString::isNull() is true). \sa size() */ @@ -10358,7 +10353,7 @@ ownership of it, no memory is freed when instances are destroyed. Returns a Unicode representation of the string reference. Since the data stems directly from the referenced string, it is not - null-terminated unless the string reference includes the string's + \\0'-terminated unless the string reference includes the string's null terminator. \sa string() @@ -11900,7 +11895,7 @@ QByteArray QStringRef::toUtf8() const this string is replaced by the Unicode's replacement character (QChar::ReplacementCharacter, which corresponds to \c{U+FFFD}). - The returned vector is not NUL terminated. + The returned vector is not \\0'-terminated. \sa toUtf8(), toLatin1(), toLocal8Bit(), QTextCodec */ @@ -11939,7 +11934,7 @@ QStringRef QStringRef::trimmed() const base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails. - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. If \a base is 0, the C language convention is used: If the string @@ -11964,7 +11959,7 @@ qint64 QStringRef::toLongLong(bool *ok, int base) const base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails. - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. If \a base is 0, the C language convention is used: If the string @@ -11991,7 +11986,7 @@ quint64 QStringRef::toULongLong(bool *ok, int base) const base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails. - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. If \a base is 0, the C language convention is used: If the string @@ -12018,7 +12013,7 @@ long QStringRef::toLong(bool *ok, int base) const base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails. - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. If \a base is 0, the C language convention is used: If the string @@ -12044,7 +12039,7 @@ ulong QStringRef::toULong(bool *ok, int base) const base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails. - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. If \a base is 0, the C language convention is used: If the string @@ -12069,7 +12064,7 @@ int QStringRef::toInt(bool *ok, int base) const base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails. - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. If \a base is 0, the C language convention is used: If the string @@ -12094,7 +12089,7 @@ uint QStringRef::toUInt(bool *ok, int base) const base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails. - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. If \a base is 0, the C language convention is used: If the string @@ -12119,7 +12114,7 @@ short QStringRef::toShort(bool *ok, int base) const base, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails. - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. If \a base is 0, the C language convention is used: If the string @@ -12146,7 +12141,7 @@ ushort QStringRef::toUShort(bool *ok, int base) const Returns an infinity if the conversion overflows or 0.0 if the conversion fails for other reasons (e.g. underflow). - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. The string conversion will always happen in the 'C' locale. For locale @@ -12172,7 +12167,7 @@ double QStringRef::toDouble(bool *ok) const Returns an infinity if the conversion overflows or 0.0 if the conversion fails for other reasons (e.g. underflow). - If \a ok is not \c nullptr, failure is reported by setting *\a{ok} + If \a ok is not \nullptr, failure is reported by setting *\a{ok} to \c false, and success by setting *\a{ok} to \c true. The string conversion will always happen in the 'C' locale. For locale |