Класс QXmlStreamReader

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

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

Примечание: Все функции в этом классе являются реентерабельными.

Открытые типы

Свойства

• namespaceProcessing : 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(), который позволяет генерировать пользовательские ошибки, которые вызывают ту же обработку ошибок, что и описано.

Пример QXmlStream Bookmarks Example демонстрирует, как использовать технику рекурсивного спуска для чтения 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().

Например, если ваше приложение считывает данные из сети с помощью менеджера сетевого доступа, вы отправите запрос network request менеджеру и получите ответ network reply в ответ. Поскольку 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()

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

См. также 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-данных. Оно состоит из префикса пространства имён, за которым следует двоеточие и локальное имя элемента. Поскольку префикс пространства имён не уникален (один и тот же префикс может указывать на разные пространства имён, и разные префиксы могут указывать на одно и то же пространство имён), следует использовать resolved namespaceUri() и локальное name() атрибута.

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

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

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

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

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

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

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

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

QXmlStreamReader::TokenType QXmlStreamReader::readNext()

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

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

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

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

bool QXmlStreamReader::readNextStartElement()

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

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

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

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

void QXmlStreamReader::setDevice(QIODevice *device)

Устанавливает текущий device в 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().

Анализатор потока не берёт на себя владение обработчиком. Пользователь отвечает за обеспечение корректности обработчика на протяжении всего жизненного цикла объекта анализатора потока или до установки другого обработчика или nullptr.

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

void QXmlStreamReader::skipCurrentElement()

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

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

QStringView QXmlStreamReader::text() const

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

QString QXmlStreamReader::tokenString() const

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

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

QXmlStreamReader::TokenType QXmlStreamReader::tokenType() const

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

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

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