diff options
Diffstat (limited to 'src/corelib/io/qurl.cpp')
| -rw-r--r-- | src/corelib/io/qurl.cpp | 110 |
1 files changed, 105 insertions, 5 deletions
diff --git a/src/corelib/io/qurl.cpp b/src/corelib/io/qurl.cpp index cf7ed130ba..4587b9fcd6 100644 --- a/src/corelib/io/qurl.cpp +++ b/src/corelib/io/qurl.cpp @@ -90,11 +90,6 @@ fromPercentEncoding() and toPercentEncoding() which deal with percent encoding and decoding of QString objects. - Calling isRelative() will tell whether or not the URL is - relative. A relative URL can be resolved by passing it as argument - to resolved(), which returns an absolute URL. isParentOf() is used - for determining whether one URL is a parent of another. - fromLocalFile() constructs a QUrl by parsing a local file path. toLocalFile() converts a URL to a local file path. @@ -116,6 +111,37 @@ from freedesktop.org, provided that the locale encodes file names using UTF-8 (required by IDN). + \section2 Relative URLs vs Relative Paths + + Calling isRelative() will return whether or not the URL is relative. + A relative URL has no \l {scheme}. For example: + + \code + qDebug() << QUrl("main.qml").isRelative(); // true: no scheme + qDebug() << QUrl("qml/main.qml").isRelative(); // true: no scheme + qDebug() << QUrl("file:main.qml").isRelative(); // false: has "file" scheme + qDebug() << QUrl("file:qml/main.qml").isRelative(); // false: has "file" scheme + \endcode + + Notice that a URL can be absolute while containing a relative path, and + vice versa: + + \code + // Absolute URL, relative path + QUrl url("file:file.txt"); + qDebug() << url.isRelative(); // false: has "file" scheme + qDebug() << QDir::isAbsolutePath(url.path()); // false: relative path + + // Relative URL, absolute path + url = QUrl("/home/user/file.txt"); + qDebug() << url.isRelative(); // true: has no scheme + qDebug() << QDir::isAbsolutePath(url.path()); // true: absolute path + \endcode + + A relative URL can be resolved by passing it as an argument to resolved(), + which returns an absolute URL. isParentOf() is used for determining whether + one URL is a parent of another. + \section2 Error checking QUrl is capable of detecting many errors in URLs while parsing it or when @@ -2539,6 +2565,12 @@ void QUrl::setPath(const QString &path, ParsingMode mode) /*! Returns the path of the URL. + \code + qDebug() << QUrl("file:file.txt").path(); // "file.txt" + qDebug() << QUrl("/home/user/file.txt").path(); // "/home/user/file.txt" + qDebug() << QUrl("http://www.example.com/test/123").path(); // "/test/123" + \endcode + The \a options argument controls how to format the path component. All values produce an unambiguous result. With QUrl::FullyDecoded, all percent-encoded sequences are decoded; otherwise, the returned value may @@ -2549,6 +2581,31 @@ void QUrl::setPath(const QString &path, ParsingMode mode) sequences are present. It is recommended to use that value when the result will be used in a non-URL context, such as sending to an FTP server. + An example of data loss is when you have non-Unicode percent-encoded sequences + and use FullyDecoded (the default): + + \code + qDebug() << QUrl("/foo%FFbar").path(); + \endcode + + In this example, there will be some level of data loss because the \c %FF cannot + be converted. + + Data loss can also occur when the path contains sub-delimiters (such as \c +): + + \code + qDebug() << QUrl("/foo+bar%2B").path(); // "/foo+bar+" + \endcode + + Other decoding examples: + + \code + const QUrl url("/tmp/Mambo %235%3F.mp3"); + qDebug() << url.path(QUrl::FullyDecoded); // "/tmp/Mambo #5?.mp3" + qDebug() << url.path(QUrl::PrettyDecoded); // "/tmp/Mambo #5?.mp3" + qDebug() << url.path(QUrl::FullyEncoded); // "/tmp/Mambo%20%235%3F.mp3" + \endcode + \sa setPath() */ QString QUrl::path(ComponentFormattingOptions options) const @@ -3257,6 +3314,8 @@ QUrl QUrl::resolved(const QUrl &relative) const equivalent to calling scheme().isEmpty(). Relative references are defined in RFC 3986 section 4.2. + + \sa {Relative URLs vs Relative Paths} */ bool QUrl::isRelative() const { @@ -3796,6 +3855,41 @@ bool QUrl::isDetached() const An empty \a localFile leads to an empty URL (since Qt 5.4). + \code + qDebug() << QUrl::fromLocalFile("file.txt"); // QUrl("file:file.txt") + qDebug() << QUrl::fromLocalFile("/home/user/file.txt"); // QUrl("file:///home/user/file.txt") + qDebug() << QUrl::fromLocalFile("file:file.txt"); // doesn't make sense; expects path, not url with scheme + \endcode + + In the first line in snippet above, a file URL is constructed from a + local, relative path. A file URL with a relative path only makes sense + if there is a base URL to resolve it against. For example: + + \code + QUrl url = QUrl::fromLocalFile("file.txt"); + QUrl baseUrl = QUrl("file:/home/user/"); + // wrong: prints QUrl("file:file.txt"), as url already has a scheme + qDebug() << baseUrl.resolved(url); + \endcode + + To resolve such a URL, it's necessary to remove the scheme beforehand: + + \code + // correct: prints QUrl("file:///home/user/file.txt") + url.setScheme(QString()); + qDebug() << baseUrl.resolved(url); + \endcode + + For this reason, it is better to use a relative URL (that is, no scheme) + for relative file paths: + + \code + QUrl url = QUrl("file.txt"); + QUrl baseUrl = QUrl("file:/home/user/"); + // prints QUrl("file:///home/user/file.txt") + qDebug() << baseUrl.resolved(url); + \endcode + \sa toLocalFile(), isLocalFile(), QDir::toNativeSeparators() */ QUrl QUrl::fromLocalFile(const QString &localFile) @@ -3840,6 +3934,12 @@ QUrl QUrl::fromLocalFile(const QString &localFile) returned value in the form found on SMB networks (for example, "//servername/path/to/file.txt"). + \code + qDebug() << QUrl("file:file.txt").toLocalFile(); // "file:file.txt" + qDebug() << QUrl("file:/home/user/file.txt").toLocalFile(); // "file:///home/user/file.txt" + qDebug() << QUrl("file.txt").toLocalFile(); // ""; wasn't a local file as it had no scheme + \endcode + Note: if the path component of this URL contains a non-UTF-8 binary sequence (such as %80), the behaviour of this function is undefined. |