Класс 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(), где ридер читает из входного потока до тех пор, пока не завершит следующий токен, после чего возвращает тип_токенa(). Затем можно использовать набор удобных функций, включая 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(), номер_строки(), номер_столбца() и смещение_символа() предназначены для создания соответствующего сообщения об ошибке или предупреждении. Для упрощения кода приложения 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(), либо из-за того, что больше данных доступно по сетевому устройству(), ридер восстанавливается после ошибки 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()

Удаляет любой 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() сообщит об ошибке (error()), дальнейшее чтение 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() и clear().

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

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

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

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

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

См. также entityExpansionLimit.

void QXmlStreamReader::setEntityResolver(QXmlStreamEntityResolver *resolver)

Устанавливает resolver как новый entityResolver().

Поток чтения не берёт на себя ответственность за resolver. Ответственность за обеспечение работоспособности resolver на протяжении всего жизненного цикла объекта потока чтения или до установки другого resolver или 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().