Класс QXmlStreamReader

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

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

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

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

Свойства

• namespaceProcessing : bool

Открытые функции

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

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

QXmlStreamReader — это более быстрый и удобный аналог собственного SAX-парсера Qt (см. QXmlSimpleReader). В некоторых случаях он может быть также более быстрым и удобным альтернативом для использования в приложениях, которые в противном случае использовали бы дерево 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.

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

enum QXmlStreamReader::Error

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

enum QXmlStreamReader::ReadElementTextBehaviour

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

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

enum QXmlStreamReader::TokenType

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

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

QXmlStreamReader::QXmlStreamReader()

Создаёт ридер потока.

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

QXmlStreamReader::QXmlStreamReader(QIODevice *device)

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

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

QXmlStreamReader::QXmlStreamReader(const QByteArray &data)

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

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

QXmlStreamReader::QXmlStreamReader(const QString &data)

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

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

QXmlStreamReader::QXmlStreamReader(const char *data)

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

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

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-документа.

Функция была введена в 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(), 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, или 0, если устройство не назначено.

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

QXmlStreamEntityResolver *QXmlStreamReader::entityResolver() const

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

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

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

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(ReadElementTextBehaviour behaviour = ErrorOnUnexpectedElement)

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

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

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

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

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 широко использует эту функцию.

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

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

void QXmlStreamReader::setDevice(QIODevice *device)

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

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

void QXmlStreamReader::setEntityResolver(QXmlStreamEntityResolver *resolver)

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

Чтец потока XML не принимает на себя владение разрешителем. Ответственность за обеспечение корректности разрешителя в течение всего времени жизни объекта чтеца потока или до установки другого разрешителя или 0 возлагается на вызывающую сторону.

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

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

void QXmlStreamReader::skipCurrentElement()

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

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

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

QStringRef QXmlStreamReader::text() const

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

QString QXmlStreamReader::tokenString() const

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

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

TokenType QXmlStreamReader::tokenType() const

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

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

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