doc: Added explanation of QStringBuilder in QString

The QStringBuilder class documentation is marked \internal.
A section has been added to the documentation for QString
that explains how to use the reimplemented '%' operator of
QStringBuilder to obtain more efficient string concatenation
operations.

3 files changed, 98 insertions, 0 deletions

diff --git a/doc/src/snippets/qstring/stringbuilder.cpp b/doc/src/snippets/qstring/stringbuilder.cpp
new file mode 100644
index 0000000..90803e2
--- /dev/null
+++ b/doc/src/snippets/qstring/stringbuilder.cpp
@@ -0,0 +1,28 @@
+
+//! [0]
+    QString foo;
+    QString type = "long";
+
+    foo->setText(QLatin1String("vector<") + type + QLatin1String(">::iterator"));
+
+    if (foo.startsWith("(" + type + ") 0x"))
+        ...
+//! [0]
+
+//! [3]
+    #define QT_USE_FAST_CONCATENATION        
+//! [3]
+
+//! [4]
+    #define QT_USE_FAST_CONCATENATION 
+    #define QT_USE_FAST_OPERATOR_PLUS 
+//! [4]
+
+//! [5]
+    #include <QStringBuilder>
+
+    QString hello("hello");
+    QStringRef el(&hello, 2, 3);
+    QLatin1String world("world");
+    QString message =  hello % el % world % QChar('!');
+//! [5]
diff --git a/src/corelib/tools/qstring.cpp b/src/corelib/tools/qstring.cpp
index ced6dd5..3b70f44 100644
--- a/src/corelib/tools/qstring.cpp
+++ b/src/corelib/tools/qstring.cpp
@@ -663,6 +663,74 @@ const QString::Null QString::null = { };
     formats, the \e precision represents the maximum number of
     significant digits (trailing zeroes are omitted).
 
+    \section1 More Efficient String Construction 
+
+    Using the QString \c{'+'} operator, it is easy to construct a
+    complex string from multiple substrings. You will often write code
+    like this:
+
+    \snippet doc/src/snippets/qstring/stringbuilder.cpp 0
+
+    There is nothing wrong with either of these string constructions,
+    but there are a few hidden inefficiencies. Beginning with Qt 4.6,
+    you can eliminate them.
+
+    First, multiple uses of the \c{'+'} operator usually means
+    multiple memory allocations. When concatenating \e{n} substrings,
+    where \e{n > 2}, there can be as many as \e{n - 1} calls to the
+    memory allocator.
+
+    Second, QLatin1String does not store its length internally but
+    calls qstrlen() when it needs to know its length.
+
+    In 4.6, an internal template class \c{QStringBuilder} has been
+    added along with a few helper functions. This class is marked
+    internal and does not appear in the documentation, because you
+    aren't meant to instantiate it in your code. Its use will be
+    automatic, as described below. The class is found in
+    \c {src/corelib/tools/qstringbuilder.cpp} if you want to have a
+    look at it.
+
+    \c{QStringBuilder} uses expression templates and reimplements the
+    \c{'%'} operator so that when you use \c{'%'} for string
+    concatenation instead of \c{'+'}, multiple substring
+    concatenations will be postponed until the final result is about
+    to be assigned to a QString. At this point, the amount of memory
+    required for the final result is known. The memory allocator is
+    then called \e{once} to get the required space, and the substrings
+    are copied into it one by one.
+
+    \c{QLatin1Literal} is a second internal class that can replace
+    QLatin1String, which can't be changed for compatibility reasons.
+    \c{QLatin1Literal} stores its length, thereby saving time when
+    \c{QStringBuilder} computes the amount of memory required for the
+    final string.
+
+    Additional efficiency is gained by inlining and reduced reference
+    counting (the QString created from a \c{QStringBuilder} typically
+    has a ref count of 1, whereas QString::append() needs an extra
+    test).
+
+    There are three ways you can access this improved method of string
+    construction. The straightforward way is to include
+    \c{QStringBuilder} wherever you want to use it, and use the
+    \c{'%'} operator instead of \c{'+'} when concatenating strings:
+
+    \snippet doc/src/snippets/qstring/stringbuilder.cpp 5
+
+    A more global approach is to include this define:
+
+    \snippet doc/src/snippets/qstring/stringbuilder.cpp 3
+
+    and use \c{'%'} instead of \c{'+'} for string concatenation
+    everywhere. The third approach, which is the most convenient but
+    not entirely source compatible, is to include two defines:
+
+    \snippet doc/src/snippets/qstring/stringbuilder.cpp 4
+
+    and the \c{'+'} will automatically be performed as the
+    \c{QStringBuilder} \c{'%'} everywhere.
+
     \sa fromRawData(), QChar, QLatin1String, QByteArray, QStringRef
 */
 
diff --git a/src/corelib/tools/qstringbuilder.cpp b/src/corelib/tools/qstringbuilder.cpp
index 17e2cec..fbb784e 100644
--- a/src/corelib/tools/qstringbuilder.cpp
+++ b/src/corelib/tools/qstringbuilder.cpp
@@ -43,6 +43,7 @@
 
 /*!
     \class QLatin1Literal
+    \internal
     \reentrant
     \since 4.6
 
@@ -83,6 +84,7 @@
 
 /*!
     \class QStringBuilder
+    \internal
     \reentrant
     \since 4.6