Класс 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 иллюстрирует, как использовать технику рекурсивного спуска для чтения файла закладок 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.

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

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

За одним исключением, как только функция error() возвращает ошибку при вызове 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 широко использует эту функцию.

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

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

void QXmlStreamReader::setDevice(QIODevice *device)

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

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

void QXmlStreamReader::setEntityResolver(QXmlStreamEntityResolver *resolver)

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

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