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

Task-number:  	 QTBUG-5121
(cherry picked from commit 51078f1ef008c8395ddb76ac2f444daa511a4507)

2 files changed, 32 insertions, 3 deletions

diff --git a/doc/src/snippets/code/src_corelib_tools_qbytearray.cpp b/doc/src/snippets/code/src_corelib_tools_qbytearray.cpp
index e48ca8c..8bb2566 100644
--- a/doc/src/snippets/code/src_corelib_tools_qbytearray.cpp
+++ b/doc/src/snippets/code/src_corelib_tools_qbytearray.cpp
@@ -401,5 +401,22 @@ QByteArray text = QByteArray::fromHex("517420697320677265617421");
 text.data();            // returns "Qt is great!"
 //! [45]
 
+//! [46]
+QString tmp = "test";
+QByteArray text = tmp.toLocal8Bit();
+char *data = new char[text.size()]
+strcpy(data, text.data());
+delete [] data; 
+//! [46]
+
+//! [47]
+QString tmp = "test";
+QByteArray text = tmp.toLocal8Bit();
+char *data = new char[text.size() + 1]
+strcpy(data, text.data());
+delete [] data;
+//! [47]
+
 }
 
+
diff --git a/src/corelib/tools/qbytearray.cpp b/src/corelib/tools/qbytearray.cpp
index 517927a..c572fb1 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.