doc: Clarified what happens with a null Q3CString.

If you call data() on a default constructed Q3CString, it returns
a non-null pointer and from then on isNull() returns false. You
have to use constData() to prevent the shared class from detaching
the null representation and replacing it with an empty representation.

Task-number: 210895

1 files changed, 27 insertions, 5 deletions

diff --git a/src/qt3support/tools/q3cstring.cpp b/src/qt3support/tools/q3cstring.cpp
index 39f1c43..b33b9b6 100644
--- a/src/qt3support/tools/q3cstring.cpp
+++ b/src/qt3support/tools/q3cstring.cpp
@@ -77,11 +77,23 @@ QT_BEGIN_NAMESPACE
     and '\0' (NUL byte) terminated; otherwise the results are
     undefined.
 
-    A Q3CString that has not been assigned to anything is \e null, i.e.
-    both the length and the data pointer is 0. A Q3CString that
-    references the empty string ("", a single '\0' char) is \e empty.
-    Both null and empty Q3CStrings are legal parameters to the methods.
-    Assigning \c{const char *} 0 to Q3CString produces a null Q3CString.
+    A default constructed Q3CString is \e null, i.e. both the length
+    and the data pointer are 0 and isNull() returns true.
+    
+    \note However, if you ask for the data pointer of a null Q3CString
+    by calling data(), then because the internal representation of the
+    null Q3CString is shared, it will be detached and replaced with a
+    non-shared, empty representation, a non-null data pointer will be
+    returned, and subsequent calls to isNull() will return false. But
+    if you ask for the data pointer of a null Q3CString by calling
+    constData(), the shared internal representation is not detached, a
+    null data pointer is returned, and subsequent calls to isNull()
+    will continue to return true.
+
+    A Q3CString that references the empty string ("", a single '\0'
+    char) is \e empty, i.e. isEmpty() returns true.  Both null and
+    empty Q3CStrings are legal parameters to the methods.  Assigning
+    \c{const char *} 0 to Q3CString produces a null Q3CString.
 
     The length() function returns the length of the string; resize()
     resizes the string and truncate() truncates the string. A string
@@ -321,6 +333,16 @@ QT_BEGIN_NAMESPACE
     Returns true if the string is null, i.e. if data() == 0; otherwise
     returns false. A null string is also an empty string.
 
+    \note If you ask for the data pointer of a null Q3CString by
+    calling data(), then because the internal representation of the
+    null Q3CString is shared, it will be detached and replaced with a
+    non-shared, empty representation, a non-null data pointer will be
+    returned, and subsequent calls to isNull() will return false. But
+    if you ask for the data pointer of a null Q3CString by calling
+    constData(), the shared internal representation is not detached, a
+    null data pointer is returned, and subsequent calls to isNull()
+    will continue to return true.
+
     Example:
     \snippet doc/src/snippets/code/src.qt3support.tools.q3cstring.cpp 1