Класс QXmlStreamReader

Класс QXmlStreamReader предоставляет быстрый парсер для чтения правильно сформированных XML-документов через простой потоковый API. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются повторно входящими.

Типы публичного доступа

Свойства

• Обработка именных пространств : bool

Публичные функции

Подробное описание

QXmlStreamReader предоставляет простой потоковый API для разбора правильно сформированного XML. Это альтернатива предварительной загрузке всего XML в дерево DOM (см. QDomDocument). QXmlStreamReader считывает данные либо из QIODevice (см. setDevice()), либо из исходного QByteArray (см. addData()).

Qt предоставляет QXmlStreamWriter для записи XML.

Основной концепцией потокового ридера является представление документа XML в виде потока токенов, аналогично SAX. Основное различие между QXmlStreamReader и SAX заключается в способе сообщения об этих XML-токенах. В SAX приложение должно предоставить обработчики (обратные функции), которые получают так называемые XML-события от парсера по мере необходимости парсера. В QXmlStreamReader код приложения сам управляет циклом и извлекает токены из ридера по одному, как ему нужно. Это делается с помощью вызова readNext(), где ридер считывает из входного потока, пока не завершит следующий токен, после чего возвращает tokenType(). Затем можно использовать набор удобных функций, включая isStartElement() и text(), чтобы изучить токен и получить информацию о том, что было прочитано. Большим преимуществом такого подхода извлечения является возможность построения парсеров с нисходящим рекурсивным обходом, что означает, что вы можете легко разделить свой код разбора XML на разные методы или классы. Это облегчает отслеживание собственного состояния приложения при разборе XML.

Типичный цикл с QXmlStreamReader выглядит так:

  QXmlStreamReader xml;
  ...
  while (!xml.atEnd()) {
        xml.readNext();
        ... // do processing
  }
  if (xml.hasError()) {
        ... // do error handling
  }

QXmlStreamReader — это парсер правильно сформированного XML 1.0, который не включает внешние анализируемые сущности. Пока не произойдет ошибка, код приложения может быть уверен, что данные, предоставляемые ридером потока, соответствуют критериям W3C для правильно сформированного XML. Например, вы можете быть уверены, что все теги действительно вложены и закрыты должным образом, что ссылки на внутренние сущности были заменены правильным текстом замены и что атрибуты были нормализованы или добавлены в соответствии с внутренней подмножеством DTD.

Если при разборе возникает ошибка, atEnd() и hasError() возвращают true, а error() возвращает произошедшую ошибку. Функции errorString(), lineNumber(), columnNumber() и characterOffset() предназначены для создания соответствующего сообщения об ошибке или предупреждении. Для упрощения кода приложения QXmlStreamReader содержит механизм raiseError(), который позволяет поднимать пользовательские ошибки, которые запускают ту же обработку ошибок, что и описана.

Пример использования закладок потока QXml демонстрирует, как использовать технику нисходящего рекурсивного обхода для чтения файла закладок XML (XBEL) с помощью ридера потока.

Пространства имен

QXmlStream понимает и разрешает пространства имен XML. Например, в случае StartElement namespaceUri() возвращает пространство имен, в котором находится элемент, а name() возвращает локальное имя элемента. Сочетание namespaceUri и name однозначно определяет элемент. Если префикс пространства имен не был объявлен в XML-сущностях, проанализированных ридером, namespaceUri пуст.

Если вы анализируете XML-данные, которые не используют пространства имен в соответствии со спецификацией XML или вообще не используют пространства имен, вы можете использовать qualifiedName() элемента вместо этого. Квалифицированное имя — это префикс prefix() элемента, за которым следует двоеточие и локальное имя name() элемента — точно так же, как элемент отображается в исходных XML-данных. Поскольку сопоставление namespaceUri с префиксом не является ни уникальным, ни универсальным, qualifiedName() следует избегать для XML-данных, совместимых с пространствами имен.

Для разбора автономных документов, использующих необъявленные префиксы пространств имен, вы можете полностью отключить обработку пространств имен с помощью свойства namespaceProcessing.

Инкрементальный разбор

QXmlStreamReader — это инкрементальный парсер. Он может обрабатывать случаи, когда документ не может быть проанализирован целиком, потому что он поступает частями (например, из нескольких файлов или по сетевому соединению). Когда ридер исчерпывает данные, прежде чем документ будет полностью проанализирован, он сообщает об ошибке PrematureEndOfDocumentError. При поступлении дополнительных данных, либо из-за вызова addData(), либо из-за наличия дополнительных данных через сетевой device(), ридер восстанавливается от ошибки PrematureEndOfDocumentError и продолжает разбор новых данных при следующем вызове readNext().

Например, если ваше приложение считывает данные из сети с использованием менеджера сетевого доступа, вы выпустите сетевой запрос к менеджеру и получите сетевой ответ в ответ. Поскольку QNetworkReply является QIODevice, вы подключите его сигнал readyRead() к пользовательскому слоту, например slotReadyRead() в фрагменте кода, показанном в обсуждении QNetworkAccessManager. В этом слоте вы читаете все доступные данные с помощью readAll() и передаете их ридеру потока XML с помощью addData(). Затем вы вызываете свою пользовательскую функцию разбора, которая считывает XML-события из ридера.

Производительность и потребление памяти

QXmlStreamReader по умолчанию экономит память, так как он не хранит все дерево документа XML в памяти, а только текущий токен в момент его отчета. Кроме того, QXmlStreamReader избегает множества небольших выделений строк, которые обычно требуются для сопоставления XML-документа с удобным и Qt-совместимым API. Он делает это, сообщая все строковые данные как QStringView, а не как фактические объекты QString. Вызов toString() для любого из этих объектов возвращает эквивалентный фактический объект QString.

Документация по типам членов

Перечисление QXmlStreamReader::Error

Это перечисление определяет различные случаи ошибок

Перечисление QXmlStreamReader::ReadElementTextBehaviour

Это перечисление определяет различные варианты поведения readElementText().

Перечисление QXmlStreamReader::TokenType

Это перечисление определяет тип только что прочитанного токена.

Документация функций-членов

QXmlStreamReader::QXmlStreamReader(const char *data)

Создаёт новый потоковый читатель, который считывает из data.

См. также addData(), clear() и setDevice().

QXmlStreamReader::QXmlStreamReader(const QString &data)

Создаёт новый потоковый читатель, который считывает из data.

См. также addData(), clear() и setDevice().

QXmlStreamReader::QXmlStreamReader(const QByteArray &data)

Создаёт новый потоковый читатель, который считывает из data.

См. также addData(), clear() и setDevice().

QXmlStreamReader::QXmlStreamReader(QIODevice *device)

Создаёт новый потоковый читатель, который считывает из device.

См. также setDevice() и clear().

QXmlStreamReader::QXmlStreamReader()

Конструирует потоковый читатель.

См. также setDevice() и addData().

QXmlStreamReader::~QXmlStreamReader()

Деструктор читателя.

void QXmlStreamReader::addData(const QByteArray &data)

Добавляет дополнительные данные для чтения читателем. Эта функция ничего не делает, если у читателя есть device().

См. также readNext() и clear().

void QXmlStreamReader::addData(const QString &data)

Добавляет дополнительные данные для чтения читателем. Эта функция ничего не делает, если у читателя есть device().

См. также readNext() и clear().

void QXmlStreamReader::addData(const char *data)

Добавляет дополнительные данные для чтения читателем. Эта функция ничего не делает, если у читателя есть device().

См. также readNext() и clear().

void QXmlStreamReader::addExtraNamespaceDeclaration(const QXmlStreamNamespaceDeclaration &extraNamespaceDeclaration)

Добавляет extraNamespaceDeclaration. Объявление будет действительным для дочерних элементов текущего элемента, или, если функция вызвана до чтения каких-либо элементов, — для всего XML-документа.

См. также namespaceDeclarations(), addExtraNamespaceDeclarations() и setNamespaceProcessing().

void QXmlStreamReader::addExtraNamespaceDeclarations(const QXmlStreamNamespaceDeclarations &extraNamespaceDeclarations)

Добавляет вектор объявлений, указанных в extraNamespaceDeclarations.

См. также namespaceDeclarations() и addExtraNamespaceDeclaration().

bool QXmlStreamReader::atEnd() const

Возвращает true если читатель прочитал до конца XML-документа или если произошла ошибка (error()) и чтение было прервано. В противном случае возвращает false.

Когда atEnd() и hasError() возвращают true, и error() возвращает PrematureEndOfDocumentError, это означает, что XML был хорошо сформирован до этого момента, но весь XML-документ не был проанализирован. Следующий фрагмент XML можно добавить с помощью addData(), если XML считывается из QByteArray, или ожидая получения дополнительных данных, если XML считывается из QIODevice. В любом случае atEnd() вернёт false, как только появятся дополнительные данные.

См. также hasError(), error(), device() и QIODevice::atEnd().

QXmlStreamAttributes QXmlStreamReader::attributes() const

Возвращает атрибуты StartElement.

qint64 QXmlStreamReader::characterOffset() const

Возвращает текущую позицию символа, начиная с 0.

См. также lineNumber() и columnNumber().

void QXmlStreamReader::clear()

Удаляет любые данные или устройство() из ридера и сбрасывает его внутреннее состояние до начального.

См. также addData().

qint64 QXmlStreamReader::columnNumber() const

Возвращает текущий номер столбца, начиная с 0.

См. также lineNumber() и characterOffset().

QIODevice *QXmlStreamReader::device() const

Возвращает текущее устройство, связанное с QXmlStreamReader, или nullptr если устройство не назначено.

См. также setDevice().

QStringView QXmlStreamReader::documentEncoding() const

Если tokenType() равен StartDocument, эта функция возвращает строку кодировки, как указано в декларации XML. В противном случае возвращается пустая строка.

QStringView QXmlStreamReader::documentVersion() const

Если tokenType() равен StartDocument, эта функция возвращает строку версии, как указано в декларации XML. В противном случае возвращается пустая строка.

QStringView QXmlStreamReader::dtdName() const

Если tokenType() равен DTD, эта функция возвращает имя DTD. В противном случае возвращается пустая строка.

QStringView QXmlStreamReader::dtdPublicId() const

Если tokenType() равен DTD, эта функция возвращает общедоступный идентификатор DTD. В противном случае возвращается пустая строка.

QStringView QXmlStreamReader::dtdSystemId() const

Если tokenType() равен DTD, эта функция возвращает системный идентификатор DTD. В противном случае возвращается пустая строка.

QXmlStreamEntityDeclarations QXmlStreamReader::entityDeclarations() const

Если tokenType() равен DTD, эта функция возвращает объявления необработанных (внешних) сущностей DTD. В противном случае возвращается пустой вектор.

Класс QXmlStreamEntityDeclarations определён как QList из QXmlStreamEntityDeclaration.

[since 5.15] int QXmlStreamReader::entityExpansionLimit() const

Возвращает максимальное количество символов, на которые может расшириться отдельная сущность. Если отдельная сущность расширяется более чем на заданный предел, документ не считается хорошо сформированным.

Эта функция была добавлена в Qt 5.15.

См. также setEntityExpansionLimit.

QXmlStreamEntityResolver *QXmlStreamReader::entityResolver() const

Возвращает решатель сущностей или nullptr если решатель сущностей отсутствует.

См. также setEntityResolver().

QXmlStreamReader::Error QXmlStreamReader::error() const

Возвращает тип текущей ошибки или NoError если ошибок нет.

См. также errorString() и raiseError().

QString QXmlStreamReader::errorString() const

Возвращает сообщение об ошибке, установленное с помощью raiseError().

См. также error(), lineNumber(), columnNumber() и characterOffset().

bool QXmlStreamReader::hasError() const

Возвращает true если произошла ошибка, в противном случае false.

См. также errorString() и error().

bool QXmlStreamReader::isCDATA() const

Возвращает true если ридер сообщает о символах, происходящих из раздела CDATA; в противном случае возвращает false.

См. также isCharacters() и text().

bool QXmlStreamReader::isCharacters() const

Возвращает true если tokenType() равно Characters; в противном случае возвращает false.

См. также isWhitespace() и isCDATA().

bool QXmlStreamReader::isComment() const

Возвращает true если tokenType() равно Comment; в противном случае возвращает false.

bool QXmlStreamReader::isDTD() const

Возвращает true если tokenType() равно DTD; в противном случае возвращает false.

bool QXmlStreamReader::isEndDocument() const

Возвращает true если tokenType() равно EndDocument; в противном случае возвращает false.

bool QXmlStreamReader::isEndElement() const

Возвращает true если tokenType() равно EndElement; в противном случае возвращает false.

bool QXmlStreamReader::isEntityReference() const

Возвращает true если tokenType() равно EntityReference; в противном случае возвращает false.

bool QXmlStreamReader::isProcessingInstruction() const

Возвращает true если tokenType() равно ProcessingInstruction; в противном случае возвращает false.

bool QXmlStreamReader::isStandaloneDocument() const

Возвращает true если этот документ объявлен автономным в декларации XML; в противном случае возвращает false.

Если декларация XML не была обработана, эта функция возвращает false.

bool QXmlStreamReader::isStartDocument() const

Возвращает true если tokenType() равно StartDocument; в противном случае возвращает false.

bool QXmlStreamReader::isStartElement() const

Возвращает true если tokenType() равно StartElement; в противном случае возвращает false.

bool QXmlStreamReader::isWhitespace() const

Возвращает true если ридер сообщает о символах, состоящих только из пробелов; в противном случае возвращает false.

См. также isCharacters() и text().

qint64 QXmlStreamReader::lineNumber() const

Возвращает текущий номер строки, начиная с 1.

См. также columnNumber() и characterOffset().

QStringView QXmlStreamReader::name() const

Возвращает локальное имя элемента StartElement, EndElement или EntityReference.

См. также namespaceUri() и qualifiedName().

QXmlStreamNamespaceDeclarations QXmlStreamReader::namespaceDeclarations() const

Если тип_токена() равен StartElement, эта функция возвращает объявления пространства имён элемента. В противном случае возвращается пустой вектор.

Класс QXmlStreamNamespaceDeclarations определён как QList из QXmlStreamNamespaceDeclaration.

См. также addExtraNamespaceDeclaration() и addExtraNamespaceDeclarations().

QStringView QXmlStreamReader::namespaceUri() const

Возвращает namespaceUri элемента StartElement или EndElement.

См. также name() и qualifiedName().

QXmlStreamNotationDeclarations QXmlStreamReader::notationDeclarations() const

Если тип_токена() равен DTD, эта функция возвращает объявления обозначений DTD. В противном случае возвращается пустой вектор.

Класс QXmlStreamNotationDeclarations определён как QList из QXmlStreamNotationDeclaration.

QStringView QXmlStreamReader::prefix() const

Возвращает префикс элемента StartElement или EndElement.

См. также name() и qualifiedName().

QStringView QXmlStreamReader::processingInstructionData() const

Возвращает данные ProcessingInstruction.

QStringView QXmlStreamReader::processingInstructionTarget() const

Возвращает целевой объект ProcessingInstruction.

QStringView QXmlStreamReader::qualifiedName() const

Возвращает полное имя элемента StartElement или EndElement;

Полное имя — это исходное имя элемента в XML-данных. Оно состоит из префикса пространства имён, за которым следует двоеточие и локальное имя элемента. Поскольку префикс пространства имён не уникален (один и тот же префикс может указывать на разные пространства имён, а разные префиксы могут указывать на одно и то же пространство имён), не следует использовать qualifiedName(), а следует использовать полученное значение namespaceUri() и локальное name() атрибута.

См. также name(), prefix() и namespaceUri().

void QXmlStreamReader::raiseError(const QString &message = QString())

Вызывает пользовательскую ошибку с необязательным сообщением об ошибке message.

См. также error() и errorString().

QString QXmlStreamReader::readElementText(QXmlStreamReader::ReadElementTextBehaviour behaviour = ErrorOnUnexpectedElement)

Вспомогательная функция, вызываемая в случае чтения StartElement. Читает до соответствующего EndElement и возвращает весь текст между ними. В случае отсутствия ошибок текущий токен (см. тип_токена()) после вызова этой функции равен EndElement.

Функция конкатенирует text() при чтении токенов Characters или EntityReference, но пропускает ProcessingInstruction и Comment. Если текущий токен не равен StartElement, возвращается пустая строка.

Параметр behaviour определяет действия в случае чтения чего-либо другого до достижения EndElement. Функция может включать текст из дочерних элементов (полезно, например, для HTML), игнорировать дочерние элементы или вызывать UnexpectedElementError и возвращать прочитанное до этого (по умолчанию).

QXmlStreamReader::TokenType QXmlStreamReader::readNext()

Читает следующий токен и возвращает его тип.

За исключением одного случая, после того, как readNext() сообщит об ошибке (error()), дальнейшее чтение XML-потока невозможно. В таком случае atEnd() возвращает true, hasError() возвращает true, а эта функция возвращает QXmlStreamReader::Invalid.

Исключением является случай, когда error() возвращает PrematureEndOfDocumentError. Эта ошибка возникает, когда достигается конец хорошо сформированного фрагмента XML, но фрагмент не представляет собой полный XML-документ. В этом случае парсинг можно продолжить, вызвав addData() для добавления следующего фрагмента XML, если поток читается из QByteArray, или ожидая получения дополнительных данных, если поток читается из device().

См. также тип_токена() и строка_токена().

bool QXmlStreamReader::readNextStartElement()

Читает до следующего начального элемента в текущем элементе. Возвращает true при достижении начального элемента. При достижении конечного элемента или при возникновении ошибки возвращается false.

Текущий элемент — это элемент, соответствующий последнему прочитанному начальному элементу, для которого ещё не достигнут соответствующий конечный элемент. Когда парсер достиг конечного элемента, текущий элемент становится родительским элементом.

Это удобная функция, если вас интересует только парсинг XML-элементов. Пример QXmlStream Bookmarks широко использует эту функцию.

См. также readNext().

void QXmlStreamReader::setDevice(QIODevice *device)

Устанавливает текущее устройство в device. Установка устройства сбрасывает поток в начальное состояние.

См. также device() и clear().

[since 5.15] void QXmlStreamReader::setEntityExpansionLimit(int limit)

Устанавливает максимальное количество символов, которое может расширяться одним сущностью, до limit. Если одна сущность расширяется за заданный лимит, документ считается некорректным.

Предел установлен для предотвращения атак типа DoS при загрузке неизвестных XML-документов, где рекурсивное расширение сущностей может иначе исчерпать всю доступную память.

Значение по умолчанию для этого свойства составляет 4096 символов.

Эта функция была добавлена в Qt 5.15.

См. также entityExpansionLimit.

void QXmlStreamReader::setEntityResolver(QXmlStreamEntityResolver *resolver)

Назначает resolver новым entityResolver().

Потоковый читатель не принимает владения resolveром. Ответственность за обеспечение корректности resolveра на протяжении всего жизненного цикла объекта потокового читателя или до назначения другого resolveра или nullptr лежит на вызывающей стороне.

См. также entityResolver().

void QXmlStreamReader::skipCurrentElement()

Читает до конца текущего элемента, пропуская все дочерние узлы. Эта функция полезна для пропуска неизвестных элементов.

Текущий элемент — это элемент, соответствующий последнему прочитанному начальному элементу, для которого ещё не достигнут соответствующий конечный элемент. Когда парсер достиг конечного элемента, текущий элемент становится родительским элементом.

QStringView QXmlStreamReader::text() const

Возвращает текст Characters, Comment, DTD или EntityReference.

QString QXmlStreamReader::tokenString() const

Возвращает текущий токен читателя в виде строки.

См. также тип_токена().

QXmlStreamReader::TokenType QXmlStreamReader::tokenType() const

Возвращает тип текущего токена.

Текущий токен также можно запросить с помощью удобных функций isStartDocument(), isEndDocument(), isStartElement(), isEndElement(), isCharacters(), isComment(), isDTD(), isEntityReference(), и isProcessingInstruction().

См. также tokenString().