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, 17 insertions, 0 deletions

diff --git a/src/corelib/tools/qbytearray.cpp b/src/corelib/tools/qbytearray.cpp
index 6cc41a8956..c2c2b9de28 100644
--- a/src/corelib/tools/qbytearray.cpp
+++ b/src/corelib/tools/qbytearray.cpp
@@ -1043,6 +1043,23 @@ QByteArray qUncompress(const uchar* data, int nbytes)
     and QByteArray() compares equal to QByteArray(""). We recommend
     that you always use isEmpty() and avoid isNull().
 
+    \section1 Maximum size and out-of-memory conditions
+
+    The current version of QByteArray 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. Raw data blocks are also limited by the use of \c int type in the
+    current version to 2 GB minus 1 byte.
+
+    In case memory allocation fails, QByteArray will throw a \c std::bad_alloc
+    exception. Out of memory conditions in the Qt containers are the only case
+    where Qt will throw exceptions.
+
+    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 QByteArray API.
+
     \section1 Notes on Locale
 
     \section2 Number-String Conversions