QXmlStreamReader Class▲
-
Header: QXmlStreamReader
-
CMake:
find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
-
qmake: QT += core
-
Group: QXmlStreamReader is part of xml-tools
Detailed Description▲
https:// provides a simple streaming API to parse well-formed XML. It is an alternative to first loading the complete XML into a DOM tree (see QDomDocument). https:// reads data either from a https:// (see https://()), or from a raw https:// (see https://()).
Qt provides https:// for writing XML.
The basic concept of a stream reader is to report an XML document as a stream of tokens, similar to SAX. The main difference between https:// and SAX is how these XML tokens are reported. With SAX, the application must provide handlers (callback functions) that receive so-called XML events from the parser at the parser's convenience. With https://, the application code itself drives the loop and pulls tokens from the reader, one after another, as it needs them. This is done by calling https://(), where the reader reads from the input stream until it completes the next token, at which point it returns the https://(). A set of convenient functions including https://() and https://() can then be used to examine the token to obtain information about what has been read. The big advantage of this pulling approach is the possibility to build recursive descent parsers with it, meaning you can split your XML parsing code easily into different methods or classes. This makes it easy to keep track of the application's own state when parsing XML.
A typical loop with https:// looks like this:
QXmlStreamReader xml;
...
while (!xml.atEnd()) {
xml.readNext();
... // do processing
}
if (xml.hasError()) {
... // do error handling
}https:// is a well-formed XML 1.0 parser that does not include external parsed entities. As long as no error occurs, the application code can thus be assured that the data provided by the stream reader satisfies the W3C's criteria for well-formed XML. For example, you can be certain that all tags are indeed nested and closed properly, that references to internal entities have been replaced with the correct replacement text, and that attributes have been normalized or added according to the internal subset of the DTD.
If an error occurs while parsing, https://() and https://() return true, and https://() returns the error that occurred. The functions https://(), https://(), https://(), and https://() are for constructing an appropriate error or warning message. To simplify application code, https:// contains a https://() mechanism that lets you raise custom errors that trigger the same error handling described.
The QXmlStream Bookmarks Example illustrates how to use the recursive descent technique to read an XML bookmark file (XBEL) with a stream reader.
Namespaces▲
QXmlStream understands and resolves XML namespaces. E.g. in case of a https://, https://() returns the namespace the element is in, and https://() returns the element's local name. The combination of https:// and name uniquely identifies an element. If a namespace prefix was not declared in the XML entities parsed by the reader, the https:// is empty.
If you parse XML data that does not utilize namespaces according to the XML specification or doesn't use namespaces at all, you can use the element's https://() instead. A qualified name is the element's https://() followed by colon followed by the element's local https://() - exactly like the element appears in the raw XML data. Since the mapping https:// to prefix is neither unique nor universal, https://() should be avoided for namespace-compliant XML data.
In order to parse standalone documents that do use undeclared namespace prefixes, you can turn off namespace processing completely with the https:// property.
Incremental Parsing▲
https:// is an incremental parser. It can handle the case where the document can't be parsed all at once because it arrives in chunks (e.g. from multiple files, or over a network connection). When the reader runs out of data before the complete document has been parsed, it reports a https://. When more data arrives, either because of a call to https://() or because more data is available through the network https://(), the reader recovers from the https:// error and continues parsing the new data with the next call to https://().
For example, if your application reads data from the network using a network access manager, you would issue a network request to the manager and receive a network reply in return. Since a QNetworkReply is a https://, you connect its https://() signal to a custom slot, e.g. slotReadyRead() in the code snippet shown in the discussion for QNetworkAccessManager. In this slot, you read all available data with https://() and pass it to the XML stream reader using https://(). Then you call your custom parsing function that reads the XML events from the reader.
Performance and Memory Consumption▲
https:// is memory-conservative by design, since it doesn't store the entire XML document tree in memory, but only the current token at the time it is reported. In addition, https:// avoids the many small string allocations that it normally takes to map an XML document to a convenient and Qt-ish API. It does this by reporting all string data as https:// rather than real https:// objects. Calling https://() on any of those objects returns an equivalent real https:// object.
Member Type Documentation▲
enum QXmlStreamReader::Error▲
This enum specifies different error cases
|
Constant |
Value |
Description |
|---|---|---|
|
https://::NoError |
0 |
No error has occurred. |
|
https://::CustomError |
2 |
A custom error has been raised with https://() |
|
https://::NotWellFormedError |
3 |
The parser internally raised an error due to the read XML not being well-formed. |
|
https://::PrematureEndOfDocumentError |
4 |
The input stream ended before a well-formed XML document was parsed. Recovery from this error is possible if more XML arrives in the stream, either by calling https://() or by waiting for it to arrive on the https://(). |
|
https://::UnexpectedElementError |
1 |
The parser encountered an element that was different to those it expected. |
enum QXmlStreamReader::ReadElementTextBehaviour▲
This enum specifies the different behaviours of https://().
|
Constant |
Value |
Description |
|---|---|---|
|
https://::ErrorOnUnexpectedElement |
0 |
Raise an https:// and return what was read so far when a child element is encountered. |
|
https://::IncludeChildElements |
1 |
Recursively include the text from child elements. |
|
https://::SkipChildElements |
2 |
Skip child elements. |
enum QXmlStreamReader::TokenType▲
This enum specifies the type of token the reader just read.
|
Constant |
Value |
Description |
|---|---|---|
|
https://::NoToken |
0 |
The reader has not yet read anything. |
|
https://::Invalid |
1 |
An error has occurred, reported in https://() and https://(). |
|
https://::StartDocument |
2 |
The reader reports the XML version number in https://(), and the encoding as specified in the XML document in https://(). If the document is declared standalone, https://() returns true; otherwise it returns false. |
|
https://::EndDocument |
3 |
The reader reports the end of the document. |
|
https://::StartElement |
4 |
The reader reports the start of an element with https://() and https://(). Empty elements are also reported as StartElement, followed directly by EndElement. The convenience function https://() can be called to concatenate all content until the corresponding EndElement. Attributes are reported in https://(), namespace declarations in https://(). |
|
https://::EndElement |
5 |
The reader reports the end of an element with https://() and https://(). |
|
https://::Characters |
6 |
The reader reports characters in https://(). If the characters are all white-space, https://() returns true. If the characters stem from a CDATA section, https://() returns true. |
|
https://::Comment |
7 |
The reader reports a comment in https://(). |
|
https://::DTD |
8 |
The reader reports a DTD in https://(), notation declarations in https://(), and entity declarations in https://(). Details of the DTD declaration are reported in in https://(), https://(), and https://(). |
|
https://::EntityReference |
9 |
The reader reports an entity reference that could not be resolved. The name of the reference is reported in https://(), the replacement text in https://(). |
|
https://::ProcessingInstruction |
10 |
The reader reports a processing instruction in https://() and https://(). |
Property Documentation▲
namespaceProcessing : bool▲
This property holds the namespace-processing flag of the stream reader.
This property controls whether or not the stream reader processes namespaces. If enabled, the reader processes namespaces, otherwise it does not.
By default, namespace-processing is enabled.
Access functions:
-
bool namespaceProcessing() const
-
void setNamespaceProcessing(bool)
Member Function Documentation▲
QXmlStreamReader::QXmlStreamReader()▲
[explicit] QXmlStreamReader::QXmlStreamReader(QIODevice *device)▲
[explicit] QXmlStreamReader::QXmlStreamReader(const QByteArray &data)▲
Creates a new stream reader that reads from data.
See Also▲
See also https://(), https://(), https://()
[explicit] QXmlStreamReader::QXmlStreamReader(const QString &data)▲
Creates a new stream reader that reads from data.
See Also▲
See also https://(), https://(), https://()
[explicit] QXmlStreamReader::QXmlStreamReader(const char *data)▲
Creates a new stream reader that reads from data.
See Also▲
See also https://(), https://(), https://()
QXmlStreamReader::~QXmlStreamReader()▲
Destructs the reader.
void QXmlStreamReader::addData(const QByteArray &data)▲
Adds more data for the reader to read. This function does nothing if the reader has a https://().
See Also▲
See also https://(), https://()
void QXmlStreamReader::addData(const QString &data)▲
Adds more data for the reader to read. This function does nothing if the reader has a https://().
See Also▲
See also https://(), https://()
void QXmlStreamReader::addData(const char *data)▲
Adds more data for the reader to read. This function does nothing if the reader has a https://().
See Also▲
See also https://(), https://()
void QXmlStreamReader::addExtraNamespaceDeclaration(const QXmlStreamNamespaceDeclaration &extraNamespaceDeclaration)▲
Adds an extraNamespaceDeclaration. The declaration will be valid for children of the current element, or - should the function be called before any elements are read - for the entire XML document.
See Also▲
See also https://(), https://(), https://()
void QXmlStreamReader::addExtraNamespaceDeclarations(const QXmlStreamNamespaceDeclarations &extraNamespaceDeclarations)▲
Adds a vector of declarations specified by extraNamespaceDeclarations.
See Also▲
See also https://(), https://()
bool QXmlStreamReader::atEnd() const▲
Returns true if the reader has read until the end of the XML document, or if an https://() has occurred and reading has been aborted. Otherwise, it returns false.
When atEnd() and https://() return true and https://() returns https://, it means the XML has been well-formed so far, but a complete XML document has not been parsed. The next chunk of XML can be added with https://(), if the XML is being read from a https://, or by waiting for more data to arrive if the XML is being read from a https://. Either way, atEnd() will return false once more data is available.
See Also▲
See also https://(), https://(), https://(), https://()
QXmlStreamAttributes QXmlStreamReader::attributes() const▲
Returns the attributes of a https://.
qint64 QXmlStreamReader::characterOffset() const▲
void QXmlStreamReader::clear()▲
Removes any https://() or data from the reader and resets its internal state to the initial state.
See Also▲
See also https://()
qint64 QXmlStreamReader::columnNumber() const▲
QIODevice *QXmlStreamReader::device() const▲
Returns the current device associated with the https://, or nullptr if no device has been assigned.
See Also▲
See also https://()
QStringView QXmlStreamReader::documentEncoding() const▲
If the https://() is https://, this function returns the encoding string as specified in the XML declaration. Otherwise an empty string is returned.
QStringView QXmlStreamReader::documentVersion() const▲
If the https://() is https://, this function returns the version string as specified in the XML declaration. Otherwise an empty string is returned.
QStringView QXmlStreamReader::dtdName() const▲
If the https://() is https://, this function returns the DTD's name. Otherwise an empty string is returned.
QStringView QXmlStreamReader::dtdPublicId() const▲
If the https://() is https://, this function returns the DTD's public identifier. Otherwise an empty string is returned.
QStringView QXmlStreamReader::dtdSystemId() const▲
If the https://() is https://, this function returns the DTD's system identifier. Otherwise an empty string is returned.
QXmlStreamEntityDeclarations QXmlStreamReader::entityDeclarations() const▲
If the https://() is https://, this function returns the DTD's unparsed (external) entity declarations. Otherwise an empty vector is returned.
The https:// class is defined to be a https:// of https://.
[since 5.15] int QXmlStreamReader::entityExpansionLimit() const▲
Returns the maximum amount of characters a single entity is allowed to expand into. If a single entity expands past the given limit, the document is not considered well formed.
This function was introduced in Qt 5.15.
See Also▲
See also https://
QXmlStreamEntityResolver *QXmlStreamReader::entityResolver() const▲
Returns the entity resolver, or nullptr if there is no entity resolver.
See Also▲
See also https://()
QXmlStreamReader::Error QXmlStreamReader::error() const▲
Returns the type of the current error, or https:// if no error occurred.
See Also▲
See also https://(), https://()
QString QXmlStreamReader::errorString() const▲
Returns the error message that was set with https://().
See Also▲
See also https://(), https://(), https://(), https://()
bool QXmlStreamReader::hasError() const▲
bool QXmlStreamReader::isCDATA() const▲
Returns true if the reader reports characters that stem from a CDATA section; otherwise returns false.
See Also▲
See also https://(), https://()
bool QXmlStreamReader::isCharacters() const▲
Returns true if https://() equals https://; otherwise returns false.
See Also▲
See also https://(), https://()
bool QXmlStreamReader::isComment() const▲
Returns true if https://() equals https://; otherwise returns false.
bool QXmlStreamReader::isDTD() const▲
Returns true if https://() equals https://; otherwise returns false.
bool QXmlStreamReader::isEndDocument() const▲
Returns true if https://() equals https://; otherwise returns false.
bool QXmlStreamReader::isEndElement() const▲
Returns true if https://() equals https://; otherwise returns false.
bool QXmlStreamReader::isEntityReference() const▲
Returns true if https://() equals https://; otherwise returns false.
bool QXmlStreamReader::isProcessingInstruction() const▲
Returns true if https://() equals https://; otherwise returns false.
bool QXmlStreamReader::isStandaloneDocument() const▲
Returns true if this document has been declared standalone in the XML declaration; otherwise returns false.
If no XML declaration has been parsed, this function returns false.
bool QXmlStreamReader::isStartDocument() const▲
Returns true if https://() equals https://; otherwise returns false.
bool QXmlStreamReader::isStartElement() const▲
Returns true if https://() equals https://; otherwise returns false.
bool QXmlStreamReader::isWhitespace() const▲
Returns true if the reader reports characters that only consist of white-space; otherwise returns false.
See Also▲
See also https://(), https://()
qint64 QXmlStreamReader::lineNumber() const▲
QStringView QXmlStreamReader::name() const▲
Returns the local name of a https://, https://, or an https://.
See Also▲
See also https://(), https://()
QXmlStreamNamespaceDeclarations QXmlStreamReader::namespaceDeclarations() const▲
If the https://() is https://, this function returns the element's namespace declarations. Otherwise an empty vector is returned.
The https:// class is defined to be a https:// of https://.
See Also▲
See also https://(), https://()
QStringView QXmlStreamReader::namespaceUri() const▲
QXmlStreamNotationDeclarations QXmlStreamReader::notationDeclarations() const▲
If the https://() is https://, this function returns the DTD's notation declarations. Otherwise an empty vector is returned.
The https:// class is defined to be a https:// of https://.
QStringView QXmlStreamReader::prefix() const▲
QStringView QXmlStreamReader::processingInstructionData() const▲
Returns the data of a https://.
QStringView QXmlStreamReader::processingInstructionTarget() const▲
Returns the target of a https://.
QStringView QXmlStreamReader::qualifiedName() const▲
Returns the qualified name of a https:// or https://;
A qualified name is the raw name of an element in the XML data. It consists of the namespace prefix, followed by colon, followed by the element's local name. Since the namespace prefix is not unique (the same prefix can point to different namespaces and different prefixes can point to the same namespace), you shouldn't use qualifiedName(), but the resolved https://() and the attribute's local https://().
See Also▲
See also https://(), https://(), https://()
void QXmlStreamReader::raiseError(const QString &message = QString())▲
QString QXmlStreamReader::readElementText(QXmlStreamReader::ReadElementTextBehaviour behaviour = ErrorOnUnexpectedElement)▲
Convenience function to be called in case a https:// was read. Reads until the corresponding https:// and returns all text in-between. In case of no error, the current token (see https://()) after having called this function is https://.
The function concatenates https://() when it reads either https:// or https:// tokens, but skips https:// and https://. If the current token is not https://, an empty string is returned.
The behaviour defines what happens in case anything else is read before reaching https://. The function can include the text from child elements (useful for example for HTML), ignore child elements, or raise an https:// and return what was read so far (default).
QXmlStreamReader::TokenType QXmlStreamReader::readNext()▲
Reads the next token and returns its type.
With one exception, once an https://() is reported by readNext(), further reading of the XML stream is not possible. Then https://() returns true, https://() returns true, and this function returns https://.
The exception is when https://() returns https://. This error is reported when the end of an otherwise well-formed chunk of XML is reached, but the chunk doesn't represent a complete XML document. In that case, parsing can be resumed by calling https://() to add the next chunk of XML, when the stream is being read from a https://, or by waiting for more data to arrive when the stream is being read from a https://().
See Also▲
See also https://(), https://()
bool QXmlStreamReader::readNextStartElement()▲
Reads until the next start element within the current element. Returns true when a start element was reached. When the end element was reached, or when an error occurred, false is returned.
The current element is the element matching the most recently parsed start element of which a matching end element has not yet been reached. When the parser has reached the end element, the current element becomes the parent element.
This is a convenience function for when you're only concerned with parsing XML elements. The QXmlStream Bookmarks Example makes extensive use of this function.
See Also▲
See also https://()
void QXmlStreamReader::setDevice(QIODevice *device)▲
Sets the current device to device. Setting the device resets the stream to its initial state.
See Also▲
See also https://(), https://()
[since 5.15] void QXmlStreamReader::setEntityExpansionLimit(int limit)▲
Sets the maximum amount of characters a single entity is allowed to expand into to limit. If a single entity expands past the given limit, the document is not considered well formed.
The limit is there to prevent DoS attacks when loading unknown XML documents where recursive entity expansion could otherwise exhaust all available memory.
The default value for this property is 4096 characters.
This function was introduced in Qt 5.15.
See Also▲
See also https://
void QXmlStreamReader::setEntityResolver(QXmlStreamEntityResolver *resolver)▲
Makes resolver the new https://().
The stream reader does not take ownership of the resolver. It's the callers responsibility to ensure that the resolver is valid during the entire life-time of the stream reader object, or until another resolver or nullptr is set.
See Also▲
See also https://()
void QXmlStreamReader::skipCurrentElement()▲
Reads until the end of the current element, skipping any child nodes. This function is useful for skipping unknown elements.
The current element is the element matching the most recently parsed start element of which a matching end element has not yet been reached. When the parser has reached the end element, the current element becomes the parent element.
QStringView QXmlStreamReader::text() const▲
Returns the text of https://, https://, https://, or https://.
QString QXmlStreamReader::tokenString() const▲
QXmlStreamReader::TokenType QXmlStreamReader::tokenType() const▲
Returns the type of the current token.
The current token can also be queried with the convenience functions https://(), https://(), https://(), https://(), https://(), https://(), https://(), https://(), and https://().
See Also▲
See also https://()


