QUrl Class

The QUrl class parses, builds and resolves URLs. More…

List of all members, including inherited members

Public Types

Public Functions

Static Public Members

Detailed Description

Parse a URL from text, or build one a component at a time:

QUrl url("https://user@example.com:8080/a%20b?q=1#top");
url.host();                // "example.com"
url.port();                // 8080
url.path();                // "/a b"

QUrl built;
built.setScheme("http");
built.setHost("example.com");
built.setPath("/a b");
built.toString();          // "http://example.com/a b"
built.toEncoded();         // "http://example.com/a%20b"

Use resolved() to combine a base URL with a relative reference, following RFC 3986.

See also QUrlQuery.

Differences from Qt

Member Type Documentation

enum QUrl::AceProcessingOption

Options for toAce() and fromAce().

typedef QUrl::AceProcessingOptions

The AceProcessingOptions type is a typedef for QFlags<AceProcessingOption>. It stores an OR combination of AceProcessingOption values.

enum QUrl::ComponentFormattingOption

Selects how a component is returned.

typedef QUrl::ComponentFormattingOptions

The ComponentFormattingOptions type is a typedef for QFlags<ComponentFormattingOption>. It stores an OR combination of ComponentFormattingOption values.

typedef QUrl::FormattingOptions

The FormattingOptions type is a typedef for QFlags<UrlFormattingOption>. It stores an OR combination of UrlFormattingOption values.

enum QUrl::ParsingMode

Selects how input text is interpreted.

enum QUrl::UrlFormattingOption

Selects what toString() and adjusted() leave out or change.

enum QUrl::UserInputResolutionOption

Selects how fromUserInput() treats text that could be a file name.

typedef QUrl::UserInputResolutionOptions

The UserInputResolutionOptions type is a typedef for QFlags<UserInputResolutionOption>. It stores an OR combination of UserInputResolutionOption values.

Member Function Documentation

QUrl::QUrl()

Constructs an empty URL.

QUrl::QUrl(const QString &url, ParsingMode mode = TolerantMode)

Constructs a URL by parsing url using mode.

See also setUrl() and isValid().

QUrl QUrl::adjusted(FormattingOptions options) const

Returns a copy of the URL with options applied to its components.

See also toString().

QString QUrl::authority(ComponentFormattingOptions options = PrettyDecoded) const

Returns the authority, formatted according to options.

See also setAuthority().

void QUrl::clear()

Resets the URL to the empty state.

See also isEmpty().

QString QUrl::errorString() const

Returns a description of the first parsing error, or an empty string if there is none.

See also isValid().

QString QUrl::fileName(ComponentFormattingOptions options = FullyDecoded) const

Returns the last segment of the path, formatted according to options. It is empty if the path ends with a slash.

See also path().

QString QUrl::fragment(ComponentFormattingOptions options = PrettyDecoded) const

Returns the fragment, formatted according to options.

See also setFragment() and hasFragment().

[static] QString QUrl::fromAce(const QByteArray &domain, AceProcessingOptions options = {})

Returns the Unicode form of the ACE-encoded domain: each label that starts with xn-- and is valid Punycode is decoded, and every other label is kept, in lower case. options is accepted for compatibility.

QUrl::fromAce("xn--bcher-kva.example");   // "bücher.example"

This function was introduced in 4.2.

See also toAce().

[static] QUrl QUrl::fromEncoded(const QByteArray &input, ParsingMode mode = TolerantMode)

Returns a URL parsed from the percent-encoded input using mode.

See also toEncoded().

[static] QUrl QUrl::fromLocalFile(const QString &localFile)

Returns a file: URL for the path localFile.

See also toLocalFile().

[static] QString QUrl::fromPercentEncoding(const QByteArray &input)

Returns the text of the percent-encoded input, decoded as UTF-8.

See also toPercentEncoding().

[static] QList<QUrl> QUrl::fromStringList(const QStringList &urls, ParsingMode mode = TolerantMode)

Returns the strings in urls as URLs, each parsed using mode.

This function was introduced in 5.1.

See also toStringList().

[static] QUrl QUrl::fromUserInput(const QString &userInput, const QString &workingDirectory = QString(), UserInputResolutionOptions options = DefaultResolution)

Returns a URL for text that a person typed, such as the contents of an address bar. The text userInput is trimmed, and then:

• an absolute path, or the name of a file that exists in workingDirectory, gives a file: URL;

• text that is a URL with a scheme is parsed as it is;

• anything else is taken as a host name, with an optional port and path, and gets the scheme http, or ftp if the host name starts with ftp..

With AssumeLocalFile in options, text without a scheme is resolved against workingDirectory even if no such file exists. Returns an invalid URL if nothing can be made of the text.

QUrl::fromUserInput("example.com/index.html");   // http://example.com/index.html
QUrl::fromUserInput("localhost:8080");            // http://localhost:8080
QUrl::fromUserInput("/etc/hosts");                // file:///etc/hosts

This function was introduced in 5.4.

See also fromLocalFile().

bool QUrl::hasFragment() const

Returns true if the URL has a fragment, even an empty one.

See also fragment().

bool QUrl::hasQuery() const

Returns true if the URL has a query, even an empty one.

See also query().

QString QUrl::host(ComponentFormattingOptions options = FullyDecoded) const

Returns the host. An IPv6 address is returned in brackets, unless options is FullyDecoded. With FullyEncoded, an internationalized host name is returned in its ACE form, as it is used in DNS.

See also setHost() and toAce().

bool QUrl::isEmpty() const

Returns true if the URL has no components.

See also clear() and isValid().

bool QUrl::isLocalFile() const

Returns true if the URL has the file scheme.

See also toLocalFile().

bool QUrl::isParentOf(const QUrl &url) const

Returns true if this URL is a parent of url: the same scheme and authority, and a path that the path of url extends.

bool QUrl::isRelative() const

Returns true if the URL has no scheme.

See also resolved().

bool QUrl::isValid() const

Returns true if the URL is not empty and parsed without an error.

See also errorString() and isEmpty().

bool QUrl::matches(const QUrl &url, FormattingOptions options) const

Returns true if this URL and url are the same once options have been applied to both; otherwise returns false. This compares two URLs while ignoring, for example, the fragment or a trailing slash:

QUrl a("http://example.com/docs/#intro");
QUrl b("http://example.com/docs");
a.matches(b, QUrl::RemoveFragment | QUrl::StripTrailingSlash);   // true

This function was introduced in 5.2.

See also adjusted().

QUrl & QUrl::operator=(const QString &url)

Sets this URL to the one parsed from url, as setUrl() does in tolerant mode, and returns a reference to this URL.

QString QUrl::password(ComponentFormattingOptions options = FullyDecoded) const

Returns the password, formatted according to options.

See also setPassword().

QString QUrl::path(ComponentFormattingOptions options = FullyDecoded) const

Returns the path, formatted according to options.

See also setPath() and fileName().

int QUrl::port(int defaultPort = -1) const

Returns the port, or defaultPort if none is set.

See also setPort().

QString QUrl::query(ComponentFormattingOptions options = PrettyDecoded) const

Returns the query, formatted according to options.

See also setQuery() and hasQuery().

QUrl QUrl::resolved(const QUrl &relative) const

Returns relative resolved against this URL, following RFC 3986.

QUrl base("http://a/b/c/d");
base.resolved(QUrl("../e"));    // "http://a/b/e"

QString QUrl::scheme() const

Returns the scheme in lower case, or an empty string if there is none.

See also setScheme().

void QUrl::setAuthority(const QString &authority, ParsingMode mode = TolerantMode)

Parses authority, which has the form [user[:password]@]host[:port], using mode.

See also authority().

void QUrl::setFragment(const QString &fragment, ParsingMode mode = TolerantMode)

Sets the fragment to fragment, interpreted using mode. A null string removes it.

See also fragment().

void QUrl::setHost(const QString &host, ParsingMode mode = DecodedMode)

Sets the host to host, which is stored in lower case. IPv6 addresses may be given with or without brackets. mode is accepted for compatibility: a host is checked the same way in every mode.

See also host().

void QUrl::setPassword(const QString &password, ParsingMode mode = DecodedMode)

Sets the password to password, interpreted using mode.

See also password().

void QUrl::setPath(const QString &path, ParsingMode mode = DecodedMode)

Sets the path to path, interpreted using mode. By default % is literal; use TolerantMode to pass an already encoded path.

See also path().

void QUrl::setPort(int port)

Sets the port to port; -1 unsets it. A value outside 0 to 65535 makes the URL invalid.

See also port().

void QUrl::setQuery(const QString &query, ParsingMode mode = TolerantMode)

Sets the query to query, interpreted using mode. A null string removes the query; an empty one keeps a bare ?.

See also query() and QUrlQuery.

void QUrl::setScheme(const QString &scheme)

Sets the scheme to scheme, which is stored in lower case. An invalid scheme makes the URL invalid.

See also scheme().

void QUrl::setUrl(const QString &url, ParsingMode mode = TolerantMode)

Parses url using mode, replacing the current contents.

See also isValid() and errorString().

void QUrl::setUserInfo(const QString &userInfo, ParsingMode mode = TolerantMode)

Sets the user name and password from userInfo, which has the form user[:password], interpreted using mode.

See also userInfo().

void QUrl::setUserName(const QString &userName, ParsingMode mode = DecodedMode)

Sets the user name to userName, interpreted using mode.

See also userName().

void QUrl::swap(QUrl &other)

Swaps this URL with other.

This function was introduced in 5.0.

[static] QByteArray QUrl::toAce(const QString &domain, AceProcessingOptions options = {})

Returns the ASCII Compatible Encoding of domain: each label that has characters outside ASCII is lower-cased and replaced by xn-- followed by its Punycode form (RFC 3492). This is the form of an internationalized domain name that DNS uses. options adjusts the mapping. Returns an empty byte array if a label cannot be encoded or is longer than 63 characters.

QUrl::toAce("bücher.example");   // "xn--bcher-kva.example"

This function was introduced in 4.2.

See also fromAce().

QString QUrl::toDisplayString(FormattingOptions options = RemovePassword) const

Returns the URL as text for showing to a person, with options applied. The password is left out by default.

See also toString().

QByteArray QUrl::toEncoded(FormattingOptions options = None) const

Returns the URL percent-encoded, with options applied.

See also fromEncoded() and toString().

QString QUrl::toLocalFile() const

Returns the local file path of a file: URL, or an empty string for any other URL.

See also fromLocalFile() and isLocalFile().

[static] QByteArray QUrl::toPercentEncoding(const QString &input, const QByteArray &exclude = QByteArray(), const QByteArray &include = QByteArray())

Returns input as percent-encoded UTF-8. Unreserved characters stay as they are, as do bytes listed in exclude. Bytes listed in include are encoded even if they are unreserved.

See also fromPercentEncoding().

QString QUrl::toString(FormattingOptions options = None) const

Returns the URL as text, with options applied. Characters are shown readably where that does not change the meaning.

See also toEncoded().

[static] QStringList QUrl::toStringList(const QList<QUrl> &urls, FormattingOptions options = None)

Returns the URLs in urls as strings, each formatted with options as toString() does.

This function was introduced in 5.1.

See also fromStringList() and toString().

QString QUrl::url(FormattingOptions options = None) const

Returns the URL as text, with options applied. This is the same as toString().

QString QUrl::userInfo(ComponentFormattingOptions options = PrettyDecoded) const

Returns the user name and password, formatted according to options.

See also setUserInfo().

QString QUrl::userName(ComponentFormattingOptions options = FullyDecoded) const

Returns the user name, formatted according to options.

See also setUserName().