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

Пример закладок XML-потока демонстрирует, как использовать технику рекурсивного спуска для чтения файла закладок 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()

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

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

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

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

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

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

void QXmlStreamReader::setDevice(QIODevice *device)

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

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

void QXmlStreamReader::setEntityResolver(QXmlStreamEntityResolver *resolver)

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

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