1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doc: Unify terminology for '\0'-terminated strings

Browse Source 
The documentation for QByteArray and QString is using different
notations for '\0'-terminated strings. Unify them by using
'\0'-terminated everywhere.

Change-Id: Ia26ec5c50635bebba1b54b7fe227ff0bcca4f2ad
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Samuel Gaist <samuel.gaist@idiap.ch>
This commit is contained in:
Christian Ehrlicher 2019-03-11 22:01:17 +01:00 committed by Aapo Keskimolo
parent 2c6593b721
commit b0f17780df
2 changed files with 21 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
src/corelib/tools/qbytearray.cpp
View File

@ -523,7 +523,7 @@ int qstrnicmp(const char *str1, const char *str2, uint len)
A helper for QByteArray::compare. Compares \a len1 bytes from \a str1 to \a A helper for QByteArray::compare. Compares \a len1 bytes from \a str1 to \a
len2 bytes from \a str2. If \a len2 is -1, then \a str2 is expected to be len2 bytes from \a str2. If \a len2 is -1, then \a str2 is expected to be
null-terminated. '\\0'-terminated.
*/ */
int qstrnicmp(const char *str1, qsizetype len1, const char *str2, qsizetype len2) int qstrnicmp(const char *str1, qsizetype len1, const char *str2, qsizetype len2)
{ {
@ -1765,9 +1765,10 @@ void QByteArray::chop(int n)
If \a data is 0, a null byte array is constructed. If \a data is 0, a null byte array is constructed.
If \a size is negative, \a data is assumed to point to a nul-terminated If \a size is negative, \a data is assumed to point to a
string and its length is determined dynamically. The terminating '\\0'-terminated string and its length is determined dynamically.
nul-character is not considered part of the byte array. The terminating \\0 character is not considered part of the
byte array.
QByteArray makes a deep copy of the string data. QByteArray makes a deep copy of the string data.
@ -1924,7 +1925,7 @@ void QByteArray::expand(int i)
/*! /*!
\internal \internal
Return a QByteArray that is sure to be NUL-terminated. Return a QByteArray that is sure to be '\\0'-terminated.
By default, all QByteArray have an extra NUL at the end, By default, all QByteArray have an extra NUL at the end,
guaranteeing that assumption. However, if QByteArray::fromRawData guaranteeing that assumption. However, if QByteArray::fromRawData
@ -2336,8 +2337,8 @@ QByteArray &QByteArray::replace(int pos, int len, const QByteArray &after)
\overload \overload
Replaces \a len bytes from index position \a pos with the zero terminated Replaces \a len bytes from index position \a pos with the
string \a after. '\\0'-terminated string \a after.
Notice: this can change the length of the byte array. Notice: this can change the length of the byte array.
*/ */
@ -2415,7 +2416,7 @@ QByteArray &QByteArray::replace(const char *c, const QByteArray &after)
Replaces every occurrence of the string \a before with the string \a after. Replaces every occurrence of the string \a before with the string \a after.
Since the sizes of the strings are given by \a bsize and \a asize, they Since the sizes of the strings are given by \a bsize and \a asize, they
may contain zero characters and do not need to be zero-terminated. may contain zero characters and do not need to be '\\0'-terminated.
*/ */
QByteArray &QByteArray::replace(const char *before, int bsize, const char *after, int asize) QByteArray &QByteArray::replace(const char *before, int bsize, const char *after, int asize)
@ -4541,7 +4542,7 @@ QByteArray QByteArray::number(double n, char f, int prec)
\snippet code/src_corelib_tools_qbytearray.cpp 43 \snippet code/src_corelib_tools_qbytearray.cpp 43
\warning A byte array created with fromRawData() is \e not \warning A byte array created with fromRawData() is \e not
null-terminated, unless the raw data contains a 0 character at '\\0'-terminated, unless the raw data contains a 0 character at
position \a size. While that does not matter for QDataStream or position \a size. While that does not matter for QDataStream or
functions like indexOf(), passing the byte array to a function functions like indexOf(), passing the byte array to a function
accepting a \c{const char *} expected to be '\\0'-terminated will accepting a \c{const char *} expected to be '\\0'-terminated will

26
src/corelib/tools/qstring.cpp
View File

@ -1468,7 +1468,7 @@ const QString::Null QString::null = { };
In all of the QString functions that take \c{const char *} In all of the QString functions that take \c{const char *}
parameters, the \c{const char *} is interpreted as a classic parameters, the \c{const char *} is interpreted as a classic
C-style '\\0'-terminated string encoded in UTF-8. It is legal for 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: You can also provide string data as an array of \l{QChar}s:
@ -2041,7 +2041,7 @@ const QString::Null QString::null = { };
the size of wchar. If wchar is 4 bytes, the \a string is interpreted as UCS-4, 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 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() \sa fromUtf16(), fromLatin1(), fromLocal8Bit(), fromUtf8(), fromUcs4(), fromStdWString()
*/ */
@ -2107,7 +2107,7 @@ int QString::toUcs4_helper(const ushort *uc, int length, uint *out)
If \a unicode is 0, a null string is constructed. 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 array and its length is determined dynamically. The terminating
nul-character is not considered part of the string. nul-character is not considered part of the string.
@ -5448,7 +5448,7 @@ static QVector<uint> qt_convert_to_ucs4(QStringView string);
this string is replaced by the Unicode's replacement character this string is replaced by the Unicode's replacement character
(QChar::ReplacementCharacter, which corresponds to \c{U+FFFD}). (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() \sa fromUtf8(), toUtf8(), toLatin1(), toLocal8Bit(), QTextCodec, fromUcs4(), toWCharArray()
*/ */
@ -5480,7 +5480,7 @@ static QVector<uint> qt_convert_to_ucs4(QStringView string)
this string is replaced by the Unicode's replacement character this string is replaced by the Unicode's replacement character
(QChar::ReplacementCharacter, which corresponds to \c{U+FFFD}). (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(), \sa QString::toUcs4(), QStringView::toUcs4(), QtPrivate::convertToLatin1(),
QtPrivate::convertToLocal8Bit(), QtPrivate::convertToUtf8() QtPrivate::convertToLocal8Bit(), QtPrivate::convertToUtf8()
@ -5638,8 +5638,7 @@ QString QString::fromUtf8_helper(const char *str, int size)
Returns a QString initialized with the first \a size characters Returns a QString initialized with the first \a size characters
of the Unicode string \a unicode (ISO-10646-UTF-16 encoded). of the Unicode string \a unicode (ISO-10646-UTF-16 encoded).
If \a size is -1 (default), \a unicode must be terminated If \a size is -1 (default), \a unicode must be \\0'-terminated.
with a 0.
This function checks for a Byte Order Mark (BOM). If it is missing, This function checks for a Byte Order Mark (BOM). If it is missing,
host byte order is assumed. host byte order is assumed.
@ -5670,8 +5669,7 @@ QString QString::fromUtf16(const ushort *unicode, int size)
Returns a QString initialized with the first \a size characters Returns a QString initialized with the first \a size characters
of the Unicode string \a str (ISO-10646-UTF-16 encoded). of the Unicode string \a str (ISO-10646-UTF-16 encoded).
If \a size is -1 (default), \a str must be terminated If \a size is -1 (default), \a str must be \\0'-terminated.
with a 0.
This function checks for a Byte Order Mark (BOM). If it is missing, This function checks for a Byte Order Mark (BOM). If it is missing,
host byte order is assumed. host byte order is assumed.
@ -5691,8 +5689,7 @@ QString QString::fromUtf16(const ushort *unicode, int size)
Returns a QString initialized with the first \a size characters Returns a QString initialized with the first \a size characters
of the Unicode string \a str (ISO-10646-UCS-4 encoded). of the Unicode string \a str (ISO-10646-UCS-4 encoded).
If \a size is -1 (default), \a str must be terminated If \a size is -1 (default), \a str must be \\0'-terminated.
with a 0.
\sa toUcs4(), fromUtf16(), utf16(), setUtf16(), fromWCharArray(), fromStdU32String() \sa toUcs4(), fromUtf16(), utf16(), setUtf16(), fromWCharArray(), fromStdU32String()
*/ */
@ -5703,8 +5700,7 @@ QString QString::fromUtf16(const ushort *unicode, int size)
Returns a QString initialized with the first \a size characters Returns a QString initialized with the first \a size characters
of the Unicode string \a unicode (ISO-10646-UCS-4 encoded). of the Unicode string \a unicode (ISO-10646-UCS-4 encoded).
If \a size is -1 (default), \a unicode must be terminated If \a size is -1 (default), \a unicode must be \\0'-terminated.
with a 0.
\sa toUcs4(), fromUtf16(), utf16(), setUtf16(), fromWCharArray(), fromStdU32String() \sa toUcs4(), fromUtf16(), utf16(), setUtf16(), fromWCharArray(), fromStdU32String()
*/ */
@ -10354,7 +10350,7 @@ ownership of it, no memory is freed when instances are destroyed.
Returns a Unicode representation of the string reference. Since Returns a Unicode representation of the string reference. Since
the data stems directly from the referenced string, it is not 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. null terminator.
\sa string() \sa string()
@ -11896,7 +11892,7 @@ QByteArray QStringRef::toUtf8() const
this string is replaced by the Unicode's replacement character this string is replaced by the Unicode's replacement character
(QChar::ReplacementCharacter, which corresponds to \c{U+FFFD}). (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 \sa toUtf8(), toLatin1(), toLocal8Bit(), QTextCodec
*/ */