QUrlQuery Class
The QUrlQuery class provides a way to manipulate a key-value pairs in a URL's query. More...
| Header: | #include <QUrlQuery> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
- List of all members, including inherited members
- QUrlQuery is part of Input/Output and Networking, Network Programming API, and Implicitly Shared Classes.
This class is equality-comparable.
Note: All functions in this class are reentrant.
Public Functions
| QUrlQuery() | |
| QUrlQuery(const QString &queryString) | |
| QUrlQuery(const QUrl &url) | |
| QUrlQuery(std::initializer_list<std::pair<QString, QString>> list) | |
| QUrlQuery(const QUrlQuery &other) | |
(since 6.5) | QUrlQuery(QUrlQuery &&other) |
| ~QUrlQuery() | |
| void | addQueryItem(const QString &key, const QString &value) |
| QStringList | allQueryItemValues(const QString &key, QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const |
| void | clear() |
| bool | hasQueryItem(const QString &key) const |
| bool | isEmpty() const |
| QString | query(QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const |
| QString | queryItemValue(const QString &key, QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const |
| QList<std::pair<QString, QString>> | queryItems(QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const |
| QChar | queryPairDelimiter() const |
| QChar | queryValueDelimiter() const |
| void | removeAllQueryItems(const QString &key) |
| void | removeQueryItem(const QString &key) |
| void | setQuery(const QString &queryString) |
| void | setQueryDelimiters(QChar valueDelimiter, QChar pairDelimiter) |
| void | setQueryItems(const QList<std::pair<QString, QString>> &query) |
| void | swap(QUrlQuery &other) |
| QString | toString(QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const |
| QUrlQuery & | operator=(QUrlQuery &&other) |
| QUrlQuery & | operator=(const QUrlQuery &other) |
Static Public Members
| char16_t | defaultQueryPairDelimiter() |
| char16_t | defaultQueryValueDelimiter() |
Related Non-Members
| size_t | qHash(const QUrlQuery &key, size_t seed = 0) |
| bool | operator!=(const QUrlQuery &lhs, const QUrlQuery &rhs) |
| bool | operator==(const QUrlQuery &lhs, const QUrlQuery &rhs) |
Detailed Description
It is used to parse the query strings found in URLs like the following:
Query strings like the above are used to transmit options in the URL and are usually decoded into multiple key-value pairs. The one above would contain two entries in its list, with keys "type" and "color". QUrlQuery can also be used to create a query string suitable for use in QUrl::setQuery() from the individual components of the query.
The most common way of parsing a query string is to initialize it in the constructor by passing it the query string. Otherwise, the setQuery() method can be used to set the query to be parsed. That method can also be used to parse a query with non-standard delimiters, after having set them using the setQueryDelimiters() function.
The encoded query string can be obtained again using query(). This will take all the internally-stored items and encode the string using the delimiters.
Encoding
All of the getter methods in QUrlQuery support an optional parameter of type QUrl::ComponentFormattingOptions, including query(), which dictate how to encode the data in question. Except for QUrl::FullyDecoded, the returned value must still be considered a percent-encoded string, as there are certain values which cannot be expressed in decoded form (like control characters, byte sequences not decodable to UTF-8). For that reason, the percent character is always represented by the string "%25".
All of the setter methods and the query methods like hasQueryItem() in QUrlQuery take encoded forms only. Unlike in QUrl, there's no optional parameter to specify that the strings being passed are decoded. If improperly-encoded strings are passed to the setter or query methods, QUrlQuery will attempt to recover instead of failing. That is to say, all functions in this class parse their string arguments as if the QUrl::TolerantMode decoding mode was specified.
Application code should strive to always ensure proper encoding and not rely on TolerantMode parsing fixing the strings. Notably, all user input must be first percent-encoded using QUrl::toPercentEncoding() or similar functions before being passed to the functions in this class.
Handling of spaces and plus ("+")
Web browsers usually encode spaces found in HTML FORM elements to a plus sign ("+") and plus signs to its percent-encoded form (%2B). However, the Internet specifications governing URLs do not consider spaces and the plus character equivalent.
For that reason, QUrlQuery never encodes the space character to "+" and will never decode "+" to a space character. Instead, space characters will be rendered "%20" in encoded form.
To support encoding like that of HTML forms, QUrlQuery also never decodes the "%2B" sequence to a plus sign nor encode a plus sign. In fact, any "%2B" or "+" sequences found in the keys, values, or query string are left exactly like written (except for the uppercasing of "%2b" to "%2B").
Full decoding
With QUrl::FullyDecoded formatting, all percent-encoded sequences will be decoded fully and the '%' character is used to represent itself. QUrl::FullyDecoded should be used with care, since it may cause data loss. See the documentation of QUrl::FullyDecoded for information on what data may be lost.
This formatting mode should be used only when dealing with text presented to the user in contexts where percent-encoding is not desired. Note that QUrlQuery setters and query methods do not support the counterpart QUrl::DecodedMode parsing, so using QUrl::FullyDecoded to obtain a listing of keys may result in keys not found in the object.
Non-standard delimiters
By default, QUrlQuery uses an equal sign ("=") to separate a key from its value, and an ampersand ("&") to separate key-value pairs from each other. It is possible to change the delimiters that QUrlQuery uses for parsing and for reconstructing the query by calling setQueryDelimiters().
Non-standard delimiters should be chosen from among what RFC 3986 calls "sub-delimiters". They are:
sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="
Use of other characters is not supported and may result in unexpected behaviour. QUrlQuery does not verify that you passed a valid delimiter.
See also QUrl.
Member Function Documentation
QUrlQuery::QUrlQuery()
Constructs an empty QUrlQuery object. A query can be set afterwards by calling setQuery() or items can be added by using addQueryItem().
See also setQuery() and addQueryItem().
[explicit] QUrlQuery::QUrlQuery(const QString &queryString)
Constructs a QUrlQuery object and parses the queryString query string, using the default query delimiters. To parse a query string using other delimiters, you should first set them using setQueryDelimiters() and then set the query with setQuery().
[explicit] QUrlQuery::QUrlQuery(const QUrl &url)
Constructs a QUrlQuery object and parses the query string found in the url URL, using the default query delimiters. To parse a query string using other delimiters, you should first set them using setQueryDelimiters() and then set the query with setQuery().
See also QUrl::query().
QUrlQuery::QUrlQuery(std::initializer_list<std::pair<QString, QString>> list)
Constructs a QUrlQuery object from the list of key/value pair.
QUrlQuery::QUrlQuery(const QUrlQuery &other)
Copies the contents of the other QUrlQuery object, including the query delimiters.
[noexcept, since 6.5] QUrlQuery::QUrlQuery(QUrlQuery &&other)
Moves the contents of the other QUrlQuery object, including the query delimiters.
This function was introduced in Qt 6.5.
[noexcept] QUrlQuery::~QUrlQuery()
Destroys this QUrlQuery object.
void QUrlQuery::addQueryItem(const QString &key, const QString &value)
Appends the pair key = value to the end of the query string of the URL. This method does not overwrite existing items that might exist with the same key.
Note: This method does not treat spaces (ASCII 0x20) and plus ("+") signs as the same, like HTML forms do. If you need spaces to be represented as plus signs, use actual plus signs.
Note: The key and value strings are expected to be in percent-encoded form.
See also hasQueryItem() and queryItemValue().
QStringList QUrlQuery::allQueryItemValues(const QString &key, QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const
Returns the a list of query string values whose key is equal to key from the URL, using the options specified in encoding to encode the return value. If the key key is not found, this function returns an empty list.
Note: The key is expected to be in percent-encoded form.
See also queryItemValue() and addQueryItem().
void QUrlQuery::clear()
Clears this QUrlQuery object by removing all of the key-value pairs currently stored. If the query delimiters have been changed, this function will leave them with their changed values.
See also isEmpty() and setQueryDelimiters().
[static constexpr noexcept] char16_t QUrlQuery::defaultQueryPairDelimiter()
Returns the default character for separating keys-value pairs from each other, an ampersand ("&").
Note: Prior to Qt 6, this function returned QChar.
See also setQueryDelimiters(), queryPairDelimiter(), and defaultQueryValueDelimiter().
[static constexpr noexcept] char16_t QUrlQuery::defaultQueryValueDelimiter()
Returns the default character for separating keys from values in the query, an equal sign ("=").
Note: Prior to Qt 6, this function returned QChar.
See also setQueryDelimiters(), queryValueDelimiter(), and defaultQueryPairDelimiter().
bool QUrlQuery::hasQueryItem(const QString &key) const
Returns true if there is a query string pair whose key is equal to key from the URL.
Note: The key expected to be in percent-encoded form.
See also addQueryItem() and queryItemValue().
bool QUrlQuery::isEmpty() const
Returns true if this QUrlQuery object contains no key-value pairs, such as after being default-constructed or after parsing an empty query string.
See also setQuery() and clear().
QString QUrlQuery::query(QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const
Returns the reconstructed query string, formed from the key-value pairs currently stored in this QUrlQuery object and separated by the query delimiters chosen for this object. The keys and values are encoded using the options given by the encoding parameter.
For this function, the only ambiguous delimiter is the hash ("#"), as in URLs it is used to separate the query string from the fragment that may follow.
The order of the key-value pairs in the returned string is exactly the same as in the original query.
See also setQuery(), QUrl::setQuery(), QUrl::fragment(), and Encoding.
QString QUrlQuery::queryItemValue(const QString &key, QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const
Returns the query value associated with key key from the URL, using the options specified in encoding to encode the return value. If the key key is not found, this function returns an empty string. If you need to distinguish between an empty value and a non-existent key, you should check for the key's presence first using hasQueryItem().
If the key key is multiply defined, this function will return the first one found, in the order they were present in the query string or added using addQueryItem().
Note: The key is expected to be in percent-encoded form.
See also addQueryItem(), allQueryItemValues(), and Encoding.
QList<std::pair<QString, QString>> QUrlQuery::queryItems(QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const
Returns the query string of the URL, as a map of keys and values, using the options specified in encoding to encode the items. The order of the elements is the same as the one found in the query string or set with setQueryItems().
See also setQueryItems() and Encoding.
QChar QUrlQuery::queryPairDelimiter() const
Returns the character used to delimit between keys-value pairs when reconstructing the query string in query() or when parsing in setQuery().
See also setQueryDelimiters() and queryValueDelimiter().
QChar QUrlQuery::queryValueDelimiter() const
Returns the character used to delimit between keys and values when reconstructing the query string in query() or when parsing in setQuery().
See also setQueryDelimiters() and queryPairDelimiter().
void QUrlQuery::removeAllQueryItems(const QString &key)
Removes all the query string pairs whose key is equal to key from the URL.
Note: The key is expected to be in percent-encoded form.
See also removeQueryItem().
void QUrlQuery::removeQueryItem(const QString &key)
Removes the query string pair whose key is equal to key from the URL. If there are multiple items with a key equal to key, it removes the first item in the order they were present in the query string or added with addQueryItem().
Note: The key is expected to be in percent-encoded form.
See also removeAllQueryItems().
void QUrlQuery::setQuery(const QString &queryString)
Parses the query string in queryString and sets the internal items to the values found there. If any delimiters have been specified with setQueryDelimiters(), this function will use them instead of the default delimiters to parse the string.
See also query().
void QUrlQuery::setQueryDelimiters(QChar valueDelimiter, QChar pairDelimiter)
Sets the characters used for delimiting between keys and values, and between key-value pairs in the URL's query string. The default value delimiter is '=' and the default pair delimiter is '&'.
valueDelimiter will be used for separating keys from values, and pairDelimiter will be used to separate key-value pairs. Any occurrences of these delimiting characters in the encoded representation of the keys and values of the query string are percent encoded when returned in query().
If valueDelimiter is set to ',' and pairDelimiter is ';', the above query string would instead be represented like this:
http://www.example.com/cgi-bin/drawgraph.cgi?type,pie;color,greenNote: Non-standard delimiters should be chosen from among what RFC 3986 calls "sub-delimiters". They are:
sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="
Use of other characters is not supported and may result in unexpected behavior. This method does not verify that you passed a valid delimiter.
See also queryValueDelimiter() and queryPairDelimiter().
void QUrlQuery::setQueryItems(const QList<std::pair<QString, QString>> &query)
Sets the items in this QUrlQuery object to query. The order of the elements in query is preserved.
Note: This method does not treat spaces (ASCII 0x20) and plus ("+") signs as the same, like HTML forms do. If you need spaces to be represented as plus signs, use actual plus signs.
Note: The keys and values are expected to be in percent-encoded form.
See also queryItems() and isEmpty().
[noexcept] void QUrlQuery::swap(QUrlQuery &other)
Swaps this URL query instance with other. This function is very fast and never fails.
QString QUrlQuery::toString(QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const
Returns this QUrlQuery as a QString. encoding can be used to specify the URL string encoding of the return value.
[noexcept] QUrlQuery &QUrlQuery::operator=(QUrlQuery &&other)
Move-assigns other to this QUrlQuery instance.
QUrlQuery &QUrlQuery::operator=(const QUrlQuery &other)
Copies the contents of the other QUrlQuery object, including the query delimiters.
Related Non-Members
[noexcept] size_t qHash(const QUrlQuery &key, size_t seed = 0)
Returns the hash value for key, using seed to seed the calculation.
[noexcept] bool operator!=(const QUrlQuery &lhs, const QUrlQuery &rhs)
Returns true if the QUrlQuery object rhs is not equal to lhs. Otherwise, returns false.
See also operator==().
[noexcept] bool operator==(const QUrlQuery &lhs, const QUrlQuery &rhs)
Returns true if QUrlQuery objects lhs and rhs contain the same contents, in the same order, and use the same query delimiters.
© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
