Document OOM conditions in the QArrayData-based containers

The other containers probably don't handle as well, so I just documented
the ones that I know how they work.

Fixes: QTBUG-75470
Change-Id: I95ecabe2f50e450c991afffd159a0483aac35a79
Reviewed-by: Allan Sandfeld Jensen <allan.jensen@qt.io>
Reviewed-by: Albert Astals Cid <aacid@kde.org>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

1 files changed, 18 insertions, 0 deletions

diff --git a/src/corelib/tools/qvector.qdoc b/src/corelib/tools/qvector.qdoc
index 75b17a4207..ad5821e73b 100644
--- a/src/corelib/tools/qvector.qdoc
+++ b/src/corelib/tools/qvector.qdoc
@@ -173,6 +173,24 @@
     For a detailed discussion comparing Qt containers with each other and
     with STL containers, see \l {Understand the Qt Containers}.
 
+    \section1 Maximum size and out-of-memory conditions
+
+    The current version of QVector is limited to just under 2 GB (2^31 bytes)
+    in size. The exact value is architecture-dependent, since it depends on the
+    overhead required for managing the data block, but is no more than 32
+    bytes. The number of elements that can be stored in a QVector is that size
+    divided by the size of each element.
+
+    In case memory allocation fails, QVector will use the \l Q_CHECK_PTR macro,
+    which will throw a \c std::bad_alloc exception if the application is being
+    compiled with exception support. If exceptions are disabled, then running
+    out of memory is undefined behavior.
+
+    Note that the operating system may impose further limits on applications
+    holding a lot of allocated memory, especially large, contiguous blocks.
+    Such considerations, the configuration of such behavior or any mitigation
+    are outside the scope of the Qt API.
+
     \sa QVectorIterator, QMutableVectorIterator, QList, QLinkedList
 */