doc: Added clarification about allocating space for the 0 terminator.

Task-number:  	 QTBUG-5121

1 files changed, 15 insertions, 3 deletions

diff --git a/src/corelib/tools/qbytearray.cpp b/src/corelib/tools/qbytearray.cpp
index c4a84fc..f4a81f2 100644
--- a/src/corelib/tools/qbytearray.cpp
+++ b/src/corelib/tools/qbytearray.cpp
@@ -903,8 +903,8 @@ QByteArray &QByteArray::operator=(const char *str)
     The last byte in the byte array is at position size() - 1. In
     addition, QByteArray ensures that the byte at position size() is
     always '\\0', so that you can use the return value of data() and
-    constData() as arguments to functions that expect
-    '\\0'-terminated strings.
+    constData() as arguments to functions that expect '\\0'-terminated
+    strings.
 
     Example:
     \snippet doc/src/snippets/code/src_corelib_tools_qbytearray.cpp 6
@@ -997,7 +997,9 @@ QByteArray &QByteArray::operator=(const char *str)
 
     Returns a pointer to the data stored in the byte array. The
     pointer can be used to access and modify the bytes that compose
-    the array. The data is '\\0'-terminated.
+    the array. The data is '\\0'-terminated, i.e. the number of
+    bytes in the returned character string is size() + 1 for the
+    '\\0' terminator.
 
     Example:
     \snippet doc/src/snippets/code/src_corelib_tools_qbytearray.cpp 8
@@ -1009,6 +1011,16 @@ QByteArray &QByteArray::operator=(const char *str)
     This function is mostly useful to pass a byte array to a function
     that accepts a \c{const char *}.
 
+    The following example makes a copy of the char* returned by
+    data(), but it will corrupt the heap and cause a crash because it
+    does not allocate a byte for the '\\0' at the end:
+
+    \snippet doc/src/snippets/code/src_corelib_tools_qbytearray.cpp 46
+
+    This one allocates the correct amount of space:
+
+    \snippet doc/src/snippets/code/src_corelib_tools_qbytearray.cpp 47
+
     Note: A QByteArray can store any byte values including '\\0's,
     but most functions that take \c{char *} arguments assume that the
     data ends at the first '\\0' they encounter.