Класс QXmlStreamReader

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

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

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

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

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

Свойства

• namespaceProcessing : bool

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

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

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

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

Добавляет дополнительные данные для чтения ридером. Эта функция ничего не делает, если у ридера есть 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, или 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.

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(), а следует использовать 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() сообщит об 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().

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

Эта функция была добавлена в 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().