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>

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()
 */
 

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()
 */
 

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()
 */
 

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()

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
 

tests/auto/corelib/tools/qarraydata/tst_qarraydata.cpp

@@ -1230,6 +1230,21 @@ void tst_QArrayData::literals()
             QCOMPARE(d.data()[i], char('A' + i));
     }
 
+    {
+        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");
@@ -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.