Enforce that statically allocated array-like containers have 0 capacity

It has been the case for both QStringLiteral and QByteArrayLiteral
since Qt 5.0, and Q_ARRAY_LITERAL since Qt 6.0.

Since it's definitely surprising, add a note in the docs, which
is "somehow" consistent with the interpretation of capacity as
the biggest possible size before we reallocate. Since it's 0,
any manipulation of the size will cause a reallocation.
(Alternatively: the capacity() is for how many elements memory was
requested from the free store. No memory was allocated, so 0...)

Task-number: QTBUG-84069
Change-Id: I5c7d21a22d1bd8b8d9b71143e33d537ca0224acd
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

6 files changed, 52 insertions, 5 deletions

diff --git a/src/corelib/text/qbytearray.cpp b/src/corelib/text/qbytearray.cpp
index 8d70955065..32642b83e3 100644
--- a/src/corelib/text/qbytearray.cpp
+++ b/src/corelib/text/qbytearray.cpp
@@ -1281,6 +1281,9 @@ QByteArray &QByteArray::operator=(const char *str)
     ever need to call this function. If you want to know how many
     bytes are in the byte array, call size().
 
+    \note a statically allocated byte array will report a capacity of 0,
+    even if it's not empty.
+
     \sa reserve(), squeeze()
 */
 
diff --git a/src/corelib/text/qstring.cpp b/src/corelib/text/qstring.cpp
index b70e2a3ed2..1e227a09ba 100644
--- a/src/corelib/text/qstring.cpp
+++ b/src/corelib/text/qstring.cpp
@@ -2283,6 +2283,9 @@ void QString::resize(int size, QChar fillChar)
     need to call this function. If you want to know how many
     characters are in the string, call size().
 
+    \note a statically allocated string will report a capacity of 0,
+    even if it's not empty.
+
     \sa reserve(), squeeze()
 */
 
diff --git a/src/corelib/tools/qvector.qdoc b/src/corelib/tools/qvector.qdoc
index cbb118ddb9..88baaab8c1 100644
--- a/src/corelib/tools/qvector.qdoc
+++ b/src/corelib/tools/qvector.qdoc
@@ -438,6 +438,9 @@
     need to call this function. If you want to know how many items are
     in the vector, call size().
 
+    \note a statically allocated vector will report a capacity of 0,
+    even if it's not empty.
+
     \sa reserve(), squeeze()
 */
 
diff --git a/tests/auto/corelib/text/qbytearray/tst_qbytearray.cpp b/tests/auto/corelib/text/qbytearray/tst_qbytearray.cpp
index e3009a78fb..67259c04dc 100644
--- a/tests/auto/corelib/text/qbytearray/tst_qbytearray.cpp
+++ b/tests/auto/corelib/text/qbytearray/tst_qbytearray.cpp
@@ -2271,18 +2271,22 @@ void tst_QByteArray::literals()
     QByteArray str(QByteArrayLiteral("abcd"));
 
     QVERIFY(str.length() == 4);
+    QCOMPARE(str.capacity(), 0);
     QVERIFY(str == "abcd");
     QVERIFY(str.data_ptr()->isStatic());
 
     const char *s = str.constData();
     QByteArray str2 = str;
     QVERIFY(str2.constData() == s);
+    QCOMPARE(str2.capacity(), 0);
 
     // detach on non const access
     QVERIFY(str.data() != s);
+    QVERIFY(str.capacity() >= str.length());
 
     QVERIFY(str2.constData() == s);
     QVERIFY(str2.data() != s);
+    QVERIFY(str2.capacity() >= str2.length());
 }
 
 void tst_QByteArray::toUpperLower_data()
diff --git a/tests/auto/corelib/text/qstring/tst_qstring.cpp b/tests/auto/corelib/text/qstring/tst_qstring.cpp
index 8af644d012..cefcd4f2e5 100644
--- a/tests/auto/corelib/text/qstring/tst_qstring.cpp
+++ b/tests/auto/corelib/text/qstring/tst_qstring.cpp
@@ -6543,18 +6543,22 @@ void tst_QString::literals()
     QString str(QStringLiteral("abcd"));
 
     QVERIFY(str.length() == 4);
+    QCOMPARE(str.capacity(), 0);
     QVERIFY(str == QLatin1String("abcd"));
     QVERIFY(str.data_ptr()->isStatic());
 
     const QChar *s = str.constData();
     QString str2 = str;
     QVERIFY(str2.constData() == s);
+    QCOMPARE(str2.capacity(), 0);
 
     // detach on non const access
     QVERIFY(str.data() != s);
+    QVERIFY(str.capacity() >= str.length());
 
     QVERIFY(str2.constData() == s);
     QVERIFY(str2.data() != s);
+    QVERIFY(str2.capacity() >= str2.length());
 }
 #endif
 
diff --git a/tests/auto/corelib/tools/qarraydata/tst_qarraydata.cpp b/tests/auto/corelib/tools/qarraydata/tst_qarraydata.cpp
index 1366eebf97..7b42b27f6e 100644
--- a/tests/auto/corelib/tools/qarraydata/tst_qarraydata.cpp
+++ b/tests/auto/corelib/tools/qarraydata/tst_qarraydata.cpp
@@ -1231,6 +1231,21 @@ void tst_QArrayData::literals()
     }
 
     {
+        QVector<char> v(Q_ARRAY_LITERAL(char, "ABCDEFGHIJ"));
+        QCOMPARE(v.size(), 11);
+        QCOMPARE(v.capacity(), 0);
+        for (int i = 0; i < 10; ++i)
+            QCOMPARE(v.at(i), char('A' + i));
+
+        (void)v.begin(); // "detach"
+
+        QCOMPARE(v.size(), 11);
+        QVERIFY(v.capacity() >= v.size());
+        for (int i = 0; i < 10; ++i)
+            QCOMPARE(v[i], char('A' + i));
+    }
+
+    {
         // wchar_t is not necessarily 2-bytes
         QArrayDataPointer<wchar_t> d = Q_ARRAY_LITERAL(wchar_t, L"ABCDEFGHIJ");
         QCOMPARE(d.size, 10u + 1u);
@@ -1254,17 +1269,32 @@ void tst_QArrayData::literals()
         QCOMPARE(const_(v)[10], char('\0'));
     }
 
-    {
-        struct LiteralType {
-            int value;
-            Q_DECL_CONSTEXPR LiteralType(int v = 0) : value(v) {}
-        };
+    struct LiteralType {
+        int value;
+        Q_DECL_CONSTEXPR LiteralType(int v = 0) : value(v) {}
+    };
 
+    {
         QArrayDataPointer<LiteralType> d = Q_ARRAY_LITERAL(LiteralType, LiteralType(0), LiteralType(1), LiteralType(2));
         QCOMPARE(d->size, 3);
         for (int i = 0; i < 3; ++i)
             QCOMPARE(d->data()[i].value, i);
     }
+
+    {
+        QVector<LiteralType> v(Q_ARRAY_LITERAL(LiteralType, LiteralType(0), LiteralType(1), LiteralType(2)));
+        QCOMPARE(v.size(), 3);
+        QCOMPARE(v.capacity(), 0);
+        for (int i = 0; i < 3; ++i)
+            QCOMPARE(v.at(i).value, i);
+
+        (void)v.begin(); // "detach"
+
+        QCOMPARE(v.size(), 3);
+        QVERIFY(v.capacity() >= v.size());
+        for (int i = 0; i < 3; ++i)
+            QCOMPARE(v[i].value, i);
+    }
 }
 
 // Variadic Q_ARRAY_LITERAL need to be available in the current configuration.