Класс QUrlQuery

Класс QUrlQuery предоставляет способ манипулирования парами «ключ-значение» в запросе URL. Подробнее...

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

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

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

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

Статические открытые члены

Связанные нечлены

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

Используется для разбора строк запроса, найденных в URL, таких как следующая:

Строки запроса, подобные приведенным выше, используются для передачи параметров в URL и обычно декодируются в несколько пар «ключ-значение». Приведенный выше пример содержал бы две записи в своем списке с ключами «тип» и «цвет». QUrlQuery также может использоваться для создания строки запроса, подходящей для использования в QUrl::setQuery() из отдельных компонентов запроса.

Наиболее распространенный способ разбора строки запроса — инициализация его в конструкторе, передав ему строку запроса. В противном случае метод setQuery() может использоваться для установки анализируемого запроса. Этот метод также может использоваться для разбора запроса с нестандартными разделителями после установки их с помощью функции setQueryDelimiters().

Закодированная строка запроса может быть получена повторно с помощью query(). Это возьмет все хранящиеся внутри элементы и закодирует строку с помощью разделителей.

Кодирование

Все методы-получатели в QUrlQuery поддерживают необязательный параметр типа QUrl::ComponentFormattingOptions, включая query(), который определяет, как закодировать данные в вопрос. За исключением QUrl::FullyDecoded, возвращаемое значение все равно должно считаться процентно-закодированной строкой, так как существуют определенные значения, которые нельзя выразить в декодированном виде (например, управляющие символы, последовательности байтов, не поддающиеся декодированию в UTF-8). По этой причине процентный символ всегда представляется строкой «%25».

Обработка пробелов и плюсов («+»)

Веб-браузеры обычно кодируют пробелы, найденные в элементах HTML FORM, в знак «плюс» («+»), а знаки «плюс» — в их процентно-закодированном виде (%2B). Однако спецификации Интернета, регулирующие URL, не считают пробелы и знак «плюс» эквивалентными.

Поэтому QUrlQuery никогда не кодирует пробел в «+» и никогда не декодирует «+» в пробел. Вместо этого пробелы будут отображаться как «%20» в закодированном виде.

Для поддержки кодирования, подобного кодированию форм HTML, QUrlQuery также никогда не декодирует последовательность «%2B» в знак «плюс», а также никогда не кодирует знак «плюс». Фактически, все последовательности «%2B» или «+», найденные в ключах, значениях или строке запроса, остаются в точности такими, как написаны (за исключением преобразования "%2b" в "%2B" в верхний регистр).

Полное декодирование

С форматированием QUrl::FullyDecoded все процентно-закодированные последовательности будут полностью декодированы, а символ «%» будет использоваться для представления самого себя. QUrl::FullyDecoded следует использовать с осторожностью, так как это может привести к потере данных. См. документацию QUrl::FullyDecoded для получения информации о том, какие данные могут быть потеряны.

Этот режим форматирования следует использовать только при работе с текстом, представленным пользователю в контекстах, где процентное кодирование нежелательно. Обратите внимание, что установщики QUrlQuery и методы запроса не поддерживают эквивалентный парсер QUrl::DecodedMode, поэтому использование QUrl::FullyDecoded для получения списка ключей может привести к тому, что ключи не будут найдены в объекте.

Нестандартные разделители

По умолчанию QUrlQuery использует знак равенства («=») для разделения ключа и значения и амперсанд («&») для разделения пар «ключ-значение» друг от друга. Можно изменить разделители, используемые QUrlQuery для анализа и реконструирования запроса, вызвав setQueryDelimiters().

Нестандартные разделители должны быть выбраны из тех, что RFC 3986 называет «подразделителями». Это:

sub-delims    = "!" / "$" / "&" / "'" / "(" / ")"
              / "*" / "+" / "," / ";" / "="

Использование других символов не поддерживается и может привести к неожиданному поведению. QUrlQuery не проверяет, что вы передали допустимый разделитель.

См. также QUrl.

Документация по функциям-членам

QUrlQuery::QUrlQuery(const QUrlQuery &other)

Копирует содержимое объекта QUrlQuery other, включая разделители запроса.

QUrlQuery::QUrlQuery(std::initializer_list<QPair<QString, QString> > list)

Создает объект QUrlQuery из списка пар ключ/значение list.

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

QUrlQuery::QUrlQuery(const QString &queryString)

Создает объект QUrlQuery и анализирует строку запроса queryString, используя стандартные разделители запроса. Чтобы проанализировать строку запроса с другими разделителями, необходимо сначала установить их с помощью setQueryDelimiters(), а затем установить запрос с помощью setQuery().

QUrlQuery::QUrlQuery(const QUrl &url)

Создает объект QUrlQuery и анализирует строку запроса, найденную в URL url, используя стандартные разделители запроса. Чтобы проанализировать строку запроса с другими разделителями, необходимо сначала установить их с помощью setQueryDelimiters(), а затем установить запрос с помощью setQuery().

См. также QUrl::query().

QUrlQuery::QUrlQuery()

Создает пустой объект QUrlQuery. Запрос может быть задан позже вызовом setQuery(), или элементы могут быть добавлены с помощью addQueryItem().

См. также setQuery() и addQueryItem().

QUrlQuery &QUrlQuery::operator=(QUrlQuery &&other)

Перемещает содержимое other в этот экземпляр QUrlQuery.

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

QUrlQuery &QUrlQuery::operator=(const QUrlQuery &other)

Копирует содержимое объекта other QUrlQuery, включая разделители запроса.

QUrlQuery::~QUrlQuery()

Уничтожает этот объект QUrlQuery.

void QUrlQuery::addQueryItem(const QString &key, const QString &value)

Добавляет пару key = value в конец строки запроса URL. Этот метод не перезаписывает существующие элементы с тем же ключом.

Примечание: Этот метод не рассматривает пробелы (ASCII 0x20) и знаки плюс ("+") как одинаковые, как это делают HTML-формы. Если вам нужно, чтобы пробелы представлялись как знаки плюс, используйте знаки плюс.

См. также hasQueryItem() и queryItemValue().

QStringList QUrlQuery::allQueryItemValues(const QString &key, QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const

Возвращает список значений строки запроса, чьей ключ равен key из URL, используя опции, указанные в encoding для кодирования возвращаемого значения. Если ключ key не найден, эта функция возвращает пустой список.

См. также queryItemValue() и addQueryItem().

void QUrlQuery::clear()

Очищает этот объект QUrlQuery, удаляя все пары ключ-значение, хранящиеся в данный момент. Если разделители запроса были изменены, эта функция оставит их с их измененными значениями.

См. также isEmpty() и setQueryDelimiters().

QChar QUrlQuery::defaultQueryPairDelimiter()

Возвращает символ, используемый по умолчанию для разделения пар ключ-значение друг от друга: амперсанд ("&").

См. также setQueryDelimiters(), queryPairDelimiter(), и defaultQueryValueDelimiter().

QChar QUrlQuery::defaultQueryValueDelimiter()

Возвращает символ, используемый по умолчанию для разделения ключей и значений в запросе: знак равенства ("=").

См. также setQueryDelimiters(), queryValueDelimiter(), и defaultQueryPairDelimiter().

bool QUrlQuery::hasQueryItem(const QString &key) const

Возвращает true, если существует пара строки запроса, чьей ключ равен key в URL.

См. также addQueryItem() и queryItemValue().

bool QUrlQuery::isEmpty() const

Возвращает true, если этот объект QUrlQuery не содержит пар ключ-значение, например, после создания по умолчанию или после анализа пустой строки запроса.

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

QString QUrlQuery::query(QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const

Возвращает воссозданную строку запроса, сформированную из пар ключ-значение, хранящихся в этом объекте QUrlQuery, разделённых разделителями запроса, выбранными для этого объекта. Ключи и значения кодируются с использованием опций, заданных параметром encoding.

Для этой функции единственный неоднозначный разделитель — символ решётки ("#"), так как в URL он используется для разделения строки запроса и фрагмента, который может следовать за ней.

Порядок пар ключ-значение в возвращаемой строке точно такой же, как в исходном запросе.

См. также setQuery(), QUrl::setQuery(), QUrl::fragment(), и Кодирование.

QString QUrlQuery::queryItemValue(const QString &key, QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const

Возвращает значение запроса, связанное с ключом key из URL, используя опции, указанные в encoding для кодирования возвращаемого значения. Если ключ key не найден, эта функция возвращает пустую строку. Если вам нужно отличить пустое значение от несуществующего ключа, сначала проверьте наличие ключа с помощью hasQueryItem().

Если ключ key определён несколько раз, эта функция вернёт первый найденный в порядке их появления в строке запроса или добавленный с помощью addQueryItem().

См. также addQueryItem(), allQueryItemValues(), и Кодирование.

QList<QPair<QString, QString> > QUrlQuery::queryItems(QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const

Возвращает строку запроса URL в виде карты ключей и значений, используя опции, указанные в encoding для кодирования элементов. Порядок элементов такой же, как и в строке запроса или установленный с помощью setQueryItems().

См. также setQueryItems() и Кодирование.

QChar QUrlQuery::queryPairDelimiter() const

Возвращает символ, используемый для разделения пар ключ-значение при реконструировании строки запроса в query() или при анализе в setQuery().

См. также setQueryDelimiters() и queryValueDelimiter().

QChar QUrlQuery::queryValueDelimiter() const

Возвращает символ, используемый для разделения ключей и значений при реконструировании строки запроса в query() или при анализе в setQuery().

См. также setQueryDelimiters() и queryPairDelimiter().

void QUrlQuery::removeAllQueryItems(const QString &key)

Удаляет все пары строки запроса, чьей ключ равен key из URL.

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

void QUrlQuery::removeQueryItem(const QString &key)

Удаляет пару строки запроса, чьей ключ равен key из URL. Если существует несколько элементов с ключом, равным key, удаляется первый элемент в порядке их присутствия в строке запроса или добавленные с помощью addQueryItem().

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

void QUrlQuery::setQuery(const QString &queryString)

Разбирает строку запроса в queryString и устанавливает внутренние элементы в значения, найденные там. Если какие-либо разделители были заданы с помощью setQueryDelimiters(), эта функция будет использовать их вместо стандартных разделителей для разбора строки.

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

void QUrlQuery::setQueryDelimiters(QChar valueDelimiter, QChar pairDelimiter)

Устанавливает символы, используемые для разграничения между ключами и значениями, а также между парами ключ-значение в строке запроса URL. По умолчанию разделитель значений равен '=', а разделитель пар — '&'.

valueDelimiter будет использоваться для разделения ключей и значений, а pairDelimiter — для разделения пар ключ-значение. Любые вхождения этих разделителей в закодированном представлении ключей и значений строки запроса будут закодированы по процентам, когда они возвращаются в query().

Если valueDelimiter установлено в '(' и pairDelimiter в ')', вышеупомянутая строка запроса будет представлена так:

http://www.example.com/cgi-bin/drawgraph.cgi?type(pie)color(green)

Примечание: Нестандартные разделители следует выбирать из тех, что RFC 3986 называет «подразделителями». Это:

sub-delims    = "!" / "$" / "&" / "'" / "(" / ")"
              / "*" / "+" / "," / ";" / "="

Использование других символов не поддерживается и может привести к неожиданному поведению. Этот метод не проверяет, что вы передали допустимый разделитель.

См. также queryValueDelimiter() и queryPairDelimiter().

void QUrlQuery::setQueryItems(const QList<QPair<QString, QString> > &query)

Устанавливает элементы в этом объекте QUrlQuery в query. Порядок элементов в query сохраняется.

Примечание: Этот метод не обрабатывает пробелы (ASCII 0x20) и знаки плюс («+») как одинаковые, как это делают HTML-формы. Если вам нужны пробелы, представленные как знаки плюс, используйте фактические знаки плюс.

См. также queryItems() и isEmpty().

void QUrlQuery::swap(QUrlQuery &other)

Меняет местами эту экземпляр URL-запроса с other. Эта функция очень быстрая и никогда не терпит неудачу.

QString QUrlQuery::toString(QUrl::ComponentFormattingOptions encoding = ...) const

Возвращает этот объект QUrlQuery как QString. encoding можно использовать для указания кодировки строки URL возвращаемого значения.

bool QUrlQuery::operator!=(const QUrlQuery &other) const

Возвращает true если other не равно этому объекту QUrlQuery. В противном случае возвращает false.

См. также operator==().

bool QUrlQuery::operator==(const QUrlQuery &other) const

Возвращает true если этот объект и объект other содержат одинаковое содержимое в том же порядке и используют те же разделители запроса.