Класс 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)

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

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, если в URL есть пара ключ-значение с ключом, равным key.

См. также 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 содержат одинаковое содержимое в том же порядке и используют те же разделители запроса.