Класс QXmlStreamReader

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

Этот класс был представлен в Qt 4.3.

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

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

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

Свойства

• 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 демонстрирует, как использовать технику рекурсивного спуска для чтения файла закладок 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. Это делается путём передачи всех данных строк как QStringRef вместо реальных объектов QString. QStringRef — это тонкая оболочка вокруг подстрок QString, которая предоставляет подмножество API QString без выделения памяти и накладных расходов на подсчёт ссылок. Вызов toString() для любого из этих объектов возвращает эквивалентный реальный объект QString.

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

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

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

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

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

Это перечисление было введено или изменено в Qt 4.6.

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

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

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

QXmlStreamReader::QXmlStreamReader(const char *data)

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

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

QXmlStreamReader::QXmlStreamReader(const QString &data)

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

Этот метод следует использовать только если заголовок XML указывает кодировку "UTF-8" или отсутствует информация о кодировке (последнее верно для QXmlStreamWriter, записывающего в QString). Любая другая кодировка, скорее всего, приведёт к повреждению данных ("mojibake").

См. также 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)

Добавляет дополнительные данные для чтения читателем. Этот метод ничего не делает, если у читателя есть устройство.

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

void QXmlStreamReader::addData(const QString &data)

Добавляет дополнительные данные для чтения читателем. Этот метод ничего не делает, если у читателя есть устройство.

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

void QXmlStreamReader::addData(const char *data)

Добавляет дополнительные данные для чтения читателем. Этот метод ничего не делает, если у читателя есть устройство.

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

void QXmlStreamReader::addExtraNamespaceDeclaration(const QXmlStreamNamespaceDeclaration &extraNamespaceDeclaration)

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

Этот метод был добавлен в Qt 4.4.

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

void QXmlStreamReader::addExtraNamespaceDeclarations(const QXmlStreamNamespaceDeclarations &extraNamespaceDeclarations)

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

Этот метод был добавлен в Qt 4.4.

См. также 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(), ошибка(), устройство(), и QIODevice::atEnd().

QXmlStreamAttributes QXmlStreamReader::attributes() const

Возвращает атрибуты элемента StartElement.

qint64 QXmlStreamReader::characterOffset() const

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

См. также номерСтроки() и номерСтолбца().

void QXmlStreamReader::clear()

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

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

qint64 QXmlStreamReader::columnNumber() const

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

См. также номерСтроки() и смещениеСимвола().

QIODevice *QXmlStreamReader::device() const

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

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

QStringRef QXmlStreamReader::documentEncoding() const

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

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

QStringRef QXmlStreamReader::documentVersion() const

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

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

QStringRef QXmlStreamReader::dtdName() const

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

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

QStringRef QXmlStreamReader::dtdPublicId() const

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

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

QStringRef QXmlStreamReader::dtdSystemId() const

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

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

QXmlStreamEntityDeclarations QXmlStreamReader::entityDeclarations() const

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

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

int QXmlStreamReader::entityExpansionLimit() const

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

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

См. также setEntityExpansionLimit.

QXmlStreamEntityResolver *QXmlStreamReader::entityResolver() const

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

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

См. также 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().

QStringRef QXmlStreamReader::name() const

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

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

QXmlStreamNamespaceDeclarations QXmlStreamReader::namespaceDeclarations() const

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

Класс QXmlStreamNamespaceDeclarations определён как QVector объектов QXmlStreamNamespaceDeclaration.

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

QStringRef QXmlStreamReader::namespaceUri() const

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

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

QXmlStreamNotationDeclarations QXmlStreamReader::notationDeclarations() const

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

Класс QXmlStreamNotationDeclarations определён как QVector объектов QXmlStreamNotationDeclaration.

QStringRef QXmlStreamReader::prefix() const

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

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

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

QStringRef QXmlStreamReader::processingInstructionData() const

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

QStringRef QXmlStreamReader::processingInstructionTarget() const

Возвращает целевой элемент ProcessingInstruction.

QStringRef 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 и возвращает весь текст между ними. В случае отсутствия ошибок текущий токен (см. tokenType()) после вызова этой функции будет EndElement.

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

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

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

QXmlStreamReader::TokenType QXmlStreamReader::readNext()

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

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

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

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

bool QXmlStreamReader::readNextStartElement()

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

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

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

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

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

void QXmlStreamReader::setDevice(QIODevice *device)

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

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

void QXmlStreamReader::setEntityExpansionLimit(int limit)

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

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

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

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

См. также entityExpansionLimit.

void QXmlStreamReader::setEntityResolver(QXmlStreamEntityResolver *resolver)

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

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

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

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

void QXmlStreamReader::skipCurrentElement()

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

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

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

QStringRef QXmlStreamReader::text() const

Возвращает текст символов, комментария, DTD или ссылка на сущность.

QString QXmlStreamReader::tokenString() const

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

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

QXmlStreamReader::TokenType QXmlStreamReader::tokenType() const

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

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

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