QString/doc: correct the record on const char* optimizations

This portion of the documentation was there since the Qt 4.5 import of
the repository and may have been correct at the time. They haven't been
for some time and definitely aren't now. So be clear that even if there
are overloads, some of them are bad ideas.

Pick-to: 6.2 6.3 6.4
Change-Id: I810d70e579eb4e2c8e45fffd1719adefb6f9f3bf
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
This commit is contained in:
Thiago Macieira 2022-09-30 08:46:22 -07:00
parent d3f748c340
commit d46eeffe83
2 changed files with 11 additions and 2 deletions

View File

@ -30,6 +30,9 @@ if (str == QString("auto") || str == QString("extern")
}
//! [4]
//! [4bis]
str.append("Hello ").append("World");
//! [4bis]
//! [5]
if (str == "auto"_L1

View File

@ -9062,8 +9062,8 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size)
\c{const char *} instead of QString. This includes the copy
constructor, the assignment operator, the comparison operators,
and various other functions such as \l{QString::insert()}{insert()},
\l{QString::replace()}{replace()}, and \l{QString::indexOf()}{indexOf()}.
These functions are usually optimized to avoid constructing a
\l{QString::append()}{append()}, and \l{QString::prepend()}{prepend()}.
Some of these functions are optimized to avoid constructing a
QString object for the \c{const char *} data. For example,
assuming \c str is a QString,
@ -9076,6 +9076,12 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size)
because it doesn't construct four temporary QString objects and
make a deep copy of the character data.
However, that is not true for all QString member functions that take
\c{const char *} and therefore applications should assume a temporary will
be created, such as in
\snippet code/src_corelib_text_qstring.cpp 4bis
Applications that define \l QT_NO_CAST_FROM_ASCII (as explained
in the QString documentation) don't have access to QString's
\c{const char *} API. To provide an efficient way of specifying