Класс 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, который не включает внешние анализируемые сущности. Пока не произойдёт ошибка, код приложения может быть уверен, что данные, предоставляемые ридером потока, соответствуют критериям хорошо сформированного XML W3C. Например, вы можете быть уверены, что все теги действительно вложены и закрыты должным образом, что ссылки на внутренние сущности заменены правильным текстом замены и что атрибуты нормализованы или добавлены в соответствии с внутренним подмножеством DTD.

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

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

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

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

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

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

QXmlStreamReader::QXmlStreamReader(QIODevice *device)

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

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

QXmlStreamReader::QXmlStreamReader(const QByteArray &data)

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

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

QXmlStreamReader::QXmlStreamReader(const QString &data)

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

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

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

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

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

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-элементов. Пример с закладками XML в Qt использует эту функцию.

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

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

void QXmlStreamReader::setDevice(QIODevice *device)

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

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

void QXmlStreamReader::setEntityResolver(QXmlStreamEntityResolver *resolver)

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

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

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

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

void QXmlStreamReader::skipCurrentElement()

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

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

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

QStringRef 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().