Doc: update the documentation of QUrl about HTML Form encoding

HTML forms deviate slightly from URL encoding. They encode spaces as
plus signs (+) and the plus sign is encoded as %2b.

QUrl is a strict URL/URI tool, so it does not know about HTML form
encoding. Add a note to the methods that encode/decode queries about
this difference.

Task-number:   QTBUG-13403

1 files changed, 20 insertions, 0 deletions

diff --git a/src/corelib/io/qurl.cpp b/src/corelib/io/qurl.cpp
index f57a4022e2..56a03c9bfc 100644
--- a/src/corelib/io/qurl.cpp
+++ b/src/corelib/io/qurl.cpp
@@ -4958,6 +4958,10 @@ void QUrl::setEncodedQuery(const QByteArray &query)
     pairDelimiter(), and the key and value are delimited by
     valueDelimiter().
 
+    \note This method does not encode spaces (ASCII 0x20) as plus (+) signs,
+    like HTML forms do. If you need that kind of encoding, you must encode
+    the value yourself and use QUrl::setEncodedQueryItems.
+
     \sa setQueryDelimiters(), queryItems(), setEncodedQueryItems()
 */
 void QUrl::setQueryItems(const QList<QPair<QString, QString> > &query)
@@ -5028,6 +5032,10 @@ void QUrl::setEncodedQueryItems(const QList<QPair<QByteArray, QByteArray> > &que
     character returned by valueDelimiter(). Each key/value pair is 
     delimited by the character returned by pairDelimiter().
 
+    \note This method does not encode spaces (ASCII 0x20) as plus (+) signs,
+    like HTML forms do. If you need that kind of encoding, you must encode
+    the value yourself and use QUrl::addEncodedQueryItem.
+
     \sa addEncodedQueryItem()
 */
 void QUrl::addQueryItem(const QString &key, const QString &value)
@@ -5084,6 +5092,10 @@ void QUrl::addEncodedQueryItem(const QByteArray &key, const QByteArray &value)
 /*!
     Returns the query string of the URL, as a map of keys and values.
 
+    \note This method does not decode spaces plus (+) signs as spaces (ASCII
+    0x20), like HTML forms do. If you need that kind of decoding, you must
+    use QUrl::encodedQueryItems and decode the data yourself.
+
     \sa setQueryItems(), setEncodedQuery()
 */
 QList<QPair<QString, QString> > QUrl::queryItems() const
@@ -5188,6 +5200,10 @@ bool QUrl::hasEncodedQueryItem(const QByteArray &key) const
     Returns the first query string value whose key is equal to \a key
     from the URL.
 
+    \note This method does not decode spaces plus (+) signs as spaces (ASCII
+    0x20), like HTML forms do. If you need that kind of decoding, you must
+    use QUrl::encodedQueryItemValue and decode the data yourself.
+
     \sa allQueryItemValues()
 */
 QString QUrl::queryItemValue(const QString &key) const
@@ -5232,6 +5248,10 @@ QByteArray QUrl::encodedQueryItemValue(const QByteArray &key) const
     Returns the a list of query string values whose key is equal to
     \a key from the URL.
 
+    \note This method does not decode spaces plus (+) signs as spaces (ASCII
+    0x20), like HTML forms do. If you need that kind of decoding, you must
+    use QUrl::allEncodedQueryItemValues and decode the data yourself.
+
     \sa queryItemValue()
 */
 QStringList QUrl::allQueryItemValues(const QString &key) const