From 1d9cbee73b51078e92bca26dbbf4e7d33bf72471 Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Tue, 14 Jul 2009 12:56:08 +0200 Subject: 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 --- src/qt3support/tools/q3cstring.cpp | 32 +++++++++++++++++++++++++++----- 1 file 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 -- cgit v0.12