From ce8fc1e88eef63308781d601dd10f694622abf95 Mon Sep 17 00:00:00 2001 From: Thiago Macieira Date: Thu, 5 Jan 2023 17:31:47 -0300 Subject: QUrl/doc: explain that the scheme-less URL is probably not intended It is a valid URL reference, which is not what people may want. Fixes: QTBUG-109855 Pick-to: 6.4 6.5 Change-Id: I69ecc04064514f939896fffd173783ce2228c1d2 Reviewed-by: Paul Wicking --- src/corelib/io/qurl.cpp | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) (limited to 'src/corelib/io') diff --git a/src/corelib/io/qurl.cpp b/src/corelib/io/qurl.cpp index d9137f439d..f925b2c901 100644 --- a/src/corelib/io/qurl.cpp +++ b/src/corelib/io/qurl.cpp @@ -14,14 +14,16 @@ \ingroup network \ingroup shared - It can parse and construct URLs in both encoded and unencoded form. QUrl also has support for internationalized domain names (IDNs). - The most common way to use QUrl is to initialize it via the - constructor by passing a QString. Otherwise, setUrl() can also - be used. + The most common way to use QUrl is to initialize it via the constructor by + passing a QString containing a full URL. QUrl objects can also be created + from a QByteArray containing a full URL using QUrl::fromEncoded(), or + heuristically from incomplete URLs using QUrl::fromUserInput(). The URL + representation can be obtained from a QUrl using either QUrl::toString() or + QUrl::toEncoded(). URLs can be represented in two forms: encoded or unencoded. The unencoded representation is suitable for showing to users, but @@ -1789,7 +1791,20 @@ inline void QUrlPrivate::validate() const /*! - Constructs a URL by parsing \a url. QUrl will automatically percent encode + Constructs a URL by parsing \a url. Note this constructor expects a proper + URL or URL-Reference and will not attempt to guess intent. For example, the + following declaration: + + \snippet code/src_corelib_io_qurl.cpp constructor-url-reference + + Will construct a valid URL but it may not be what one expects, as the + scheme() part of the input is missing. For a string like the above, + applications may want to use fromUserInput(). For this constructor or + setUrl(), the following is probably what was intended: + + \snippet code/src_corelib_io_qurl.cpp constructor-url + + QUrl will automatically percent encode all characters that are not allowed in a URL and decode the percent-encoded sequences that represent an unreserved character (letters, digits, hyphens, underscores, dots and tildes). All other characters are left in their -- cgit v1.2.3