Класс QXmlStreamReader

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

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

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

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

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

Свойства

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

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

Пример QXmlStream Bookmarks Example иллюстрирует, как использовать технику рекурсивного спуска для чтения файла закладок 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(), а вместо этого используйте полученное 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 на протяжении всего жизненного цикла объекта stream reader или до установки другого 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().