Added a behaviour parameter to QXmlStreamReader::readElementText

This makes the function a bit more useful, since previously it was only
safe to use if you were sure that it would not encounter an unexpected
child element, or if you would be alright with canceling the parser on
such an occurrence.

Now it is also possible to have it ignore any unexpected child elements,
or to have it include the text found in any child elements.

Task-number: 231938
Reviewed-by: mae

2 files changed, 57 insertions, 8 deletions

diff --git a/src/corelib/xml/qxmlstream.cpp b/src/corelib/xml/qxmlstream.cpp
index 8b2462e229..a311b991bc 100644
--- a/src/corelib/xml/qxmlstream.cpp
+++ b/src/corelib/xml/qxmlstream.cpp
@@ -129,6 +129,21 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
+    \enum QXmlStreamReader::ReadElementTextBehaviour
+
+    This enum specifies the different behaviours of readElementText().
+
+    \value ErrorOnUnexpectedElement Raise an UnexpectedElementError and return
+    what was read so far when a child element is encountered.
+
+    \value IncludeChildElements Recursively include the text from child elements.
+
+    \value SkipChildElements Skip child elements.
+
+    \since 4.6
+*/
+
+/*!
     \enum QXmlStreamReader::Error
 
     This enum specifies different error cases
@@ -637,6 +652,7 @@ QXmlStreamReader::TokenType QXmlStreamReader::tokenType() const
   this function.
 
   \since 4.6
+  \sa readNext()
  */
 bool QXmlStreamReader::readNextStartElement()
 {
@@ -2070,12 +2086,17 @@ void QXmlStreamReader::addExtraNamespaceDeclarations(const QXmlStreamNamespaceDe
 
   The function concatenates text() when it reads either \l Characters
   or EntityReference tokens, but skips ProcessingInstruction and \l
-  Comment. In case anything else is read before reaching EndElement,
-  the function returns what it read so far and raises an
-  UnexpectedElementError. If the current token is not StartElement, an
-  empty string is returned.
+  Comment. If the current token is not StartElement, an empty string is
+  returned.
+
+  The \a behaviour defines what happens in case anything else is
+  read before reaching EndElement. The function can include the text from
+  child elements (useful for example for HTML), ignore child elements, or
+  raise an UnexpectedElementError and return what was read so far.
+
+  \since 4.6
  */
-QString QXmlStreamReader::readElementText()
+QString QXmlStreamReader::readElementText(ReadElementTextBehaviour behaviour)
 {
     Q_D(QXmlStreamReader);
     if (isStartElement()) {
@@ -2091,16 +2112,37 @@ QString QXmlStreamReader::readElementText()
             case ProcessingInstruction:
             case Comment:
                 break;
+            case StartElement:
+                if (behaviour == SkipChildElements) {
+                    skipCurrentElement();
+                    break;
+                } else if (behaviour == IncludeChildElements) {
+                    result += readElementText(behaviour);
+                    break;
+                }
+                // Fall through (for ErrorOnUnexpectedElement)
             default:
-                if (!d->error)
-                    d->raiseError(UnexpectedElementError, QXmlStream::tr("Expected character data."));
-                return result;
+                if (d->error || behaviour == ErrorOnUnexpectedElement) {
+                    if (!d->error)
+                        d->raiseError(UnexpectedElementError, QXmlStream::tr("Expected character data."));
+                    return result;
+                }
             }
         }
     }
     return QString();
 }
 
+/*!
+  \overload readElementText()
+
+  Calling this function is equivalent to calling readElementText(ErrorOnUnexpectedElement).
+ */
+QString QXmlStreamReader::readElementText()
+{
+    return readElementText(ErrorOnUnexpectedElement);
+}
+
 /*!  Raises a custom error with an optional error \a message.
 
   \sa error(), errorString()
diff --git a/src/corelib/xml/qxmlstream.h b/src/corelib/xml/qxmlstream.h
index 21dcb404e8..71deb66598 100644
--- a/src/corelib/xml/qxmlstream.h
+++ b/src/corelib/xml/qxmlstream.h
@@ -351,6 +351,13 @@ public:
     qint64 characterOffset() const;
 
     QXmlStreamAttributes attributes() const;
+
+    enum ReadElementTextBehaviour {
+        ErrorOnUnexpectedElement,
+        IncludeChildElements,
+        SkipChildElements
+    };
+    QString readElementText(ReadElementTextBehaviour behaviour);
     QString readElementText();
 
     QStringRef name() const;