Url Class Reference

#include <ImFusion/Core/Filesystem/Url.h>

Entity representing a URL (Uniform Resource Locator). More...

Detailed Description

Entity representing a URL (Uniform Resource Locator).

Such an object is concerned only with the lexical and syntactic aspects of a URL. The URL does not necessarily point to an existing resource, and is not necessarily valid for the current environment. It can be converted from and to a Path, in which case either the path is absolute and the "file" scheme is used, or the path is relative and the scheme is missing.

Technically, a URI with the "file" scheme is not a URL, but it does not matter for the purposes of this class.

A URL consists of a sequence of five components which in turn consist of subcomponents separated by various tokens, called sigils (':', '//', '@', '/', '?', and '#'): scheme://authority/path?query#fragment

The authority's syntax is as follows: [userinfo@]host[:port] where both the userinfo and port are optional. If the host is empty, it resolves to "localhost".

The query and fragment components are always optional.

For an absolute URL, both the scheme and the authority must be present. If the scheme or the authority are absent, the URL is relative, the scheme is "file" by default, and the authority is "localhost" by default. If the authority is present, the path must either be empty or start with a slash '/'. Setting the scheme, the authority, or parts of it may result in an invalid URL if it previously was relative and becomes absolute, or vice versa.

Here is an example of the generic syntax (from https://en.wikipedia.org/wiki/Uniform_Resource_Identifier#Examples):

        userinfo       host      port
        ┌──┴───┐ ┌──────┴──────┐ ┌┴┐
https://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top
└─┬─┘   └───────────┬──────────────┘└───────┬───────┘ └───────────┬─────────────┘ └┬┘
scheme          authority                  path                 query           fragment

The characters ';', '/', '?', ':', '@', '=' and '&' are reserved for special meaning within a scheme. The character '#' is unsafe and the Url class treats it as reserved as well.

If the URL becomes invalid (by setting part of it, or from the parsing constructor), no exception is thrown and no error is returned. Instead, isValid() would return false.

Here is an example of what each getter returns with a sample URL:

Url("https://john.doe:123456@www.example.com:80/forum/questions/?tag=networking&order=newest#top")
.scheme() == "https"
.authority() == "john.doe:123456@www.example.com:80"
.userinfo() == "john.doe:123456"
.username() == "john.doe"
.password() == "123456"
.host() == "www.example.com"
.port() == "80"
.path() == "/forum/questions/"
.query() == "tag=networking&order=newest"
.fragment() == "top"

The path of a URL may be percent-encoded. For example, hashtags '#' in URL paths are replaced with "%23" (23 being the hexadecimal value of '#' in ASCII). The constructors of Url that take in a path separately do encode it. The Url::setPath method encodes its argument as well. The Url::path method decodes it, while the Url::string method does not.

Examples

PacsExample.cpp.

Classes
struct	RelativeTag
struct	Subquery
	A Subquery represents part of a query delimited by '&' or ';'. More...

Public Types
enum	FormattingOption : unsigned int {   None = 0x0 , NoScheme = 0x1 , NoPassword = 0x2 , NoUserinfo = 0x4 | NoPassword ,   NoPort = 0x8 , NoAuthority = 0x10 | NoUserinfo | NoPort , NoPath = 0x20 , NoQuery = 0x40 ,   NoFragment = 0x80 , DecodePath = 0x100 }
using	FormattingOptions = Flags<FormattingOption>

Public Member Functions
	Url ()=default
	Instantiates an empty URL.
	Url (const std::string &url)
	Instantiates a URL by parsing a string. The string should include all necessary sigils.
	Url (const char *url)
	Url (const std::string &scheme, const std::string &authority, const std::string &path, const std::string &query={}, const std::string &fragment={})
	Instantiates a URL from its components for convenience.
	Url (RelativeTag, const std::string &scheme, const std::string &path, const std::string &query={}, const std::string &fragment={})
	Instantiates a URL from its components for convenience, without authority.
	Url (const Url &other)=default
Url &	operator= (const Url &other)=default
bool	operator== (const Url &other) const
	Two URLs are equal when their representing strings are lexically equal.
bool	operator== (const std::string &other) const
bool	operator!= (const Url &other) const
bool	operator!= (const std::string &other) const
std::string	string (FormattingOptions formattingOptions=None) const
	Returns the URL as a string in a generic format.
void	clear ()
	Makes the URL empty.
Filesystem::Path	toLocalFile () const
	Returns the path as a Filesystem::Path if the scheme is "file". Otherwise, returns an empty path.
void	normalizePath ()
	Normalizes the URL path: change all occurrences of '\' in the path to '/', and remove redundant '/' (when there are multiple in a row)

Static Public Member Functions
static Url	fromLocalFile (const std::string &path)
	Constructs a file URL from the path.
static Url	relativeTo (const std::string &url, const std::string &basePath)
	Constructs a URL where the path is meant to be relative to basePath.
static std::string	percentEncoded (const std::string &str, const std::string &encodedChars="!#$%&*+,;=?@[]")
	Returns str with percent-encoded reserved characters.
static std::string	percentDecoded (const std::string &str)
	Returns str with reserved characters decoded from percent-encoding.

Static Public Attributes
static constexpr RelativeTag	makeRelative {}

Url decomposition into components
std::string	scheme () const
	Returns the scheme of the URL.
void	setScheme (const std::string &scheme)
	Changes the scheme of the URL or adds one to it.
std::string	authority () const
	Returns the authority of the URL.
void	setAuthority (const std::string &authority)
	Changes the authority of the URL or adds one to it.
std::string	userinfo () const
	Returns the userinfo of the URL (part of the authority).
void	setUserinfo (const std::string &userinfo)
	Changes the userinfo of the authority or adds a default authority to the URL with that userinfo.
std::string	username () const
	Returns the username of the URL (part of the userinfo).
void	setUsername (const std::string &username)
	Changes the username of the userinfo or adds a default userinfo to the URL with that username.
std::string	password () const
	Returns the password of the URL (part of the userinfo).
void	setPassword (const std::string &password)
	Changes the password of the userinfo or adds a default userinfo to the URL with that password.
std::string	host () const
	Returns the host of the URL (part of the authority).
void	setHost (const std::string &host)
	Changes the host of the authority or adds a default authority to the URL with that host.
std::string	port () const
	Returns the port of the URL (part of the authority).
void	setPort (const std::string &port)
	Changes the port of the authority or adds a default authority to the URL with that port.
int	portNumber () const
	Returns the port as an integer, or -1 if it isn't set.
void	setPort (int port)
	Sets the port from an integer.
std::string	path () const
	Returns the path of the URL, including both leading and trailing slashes if they exist.
void	setPath (const std::string &path)
	Changes the path of the URL or add one to it.
std::string	query () const
	Returns the query of the URL.
void	setQuery (const std::string &query)
	Changes the query of the URL or add one to it.
std::size_t	subqueryCount () const
	Returns the number of subqueries in the URL.
std::vector< Subquery >	subqueries () const
	Returns all subqueries as a vector.
std::optional< Subquery >	subquery (std::size_t index) const
	Returns the subquery corresponding to index (0-based), or nullopt if it doesn't exist.
std::optional< Subquery >	findSubquery (const std::string &key) const
	Returns the subquery with the key key, or nullopt if it doesn't exist.
void	replaceSubquery (std::size_t index, const Subquery &subquery)
	Changes the subquery corresponding to index (0-based).
void	appendSubquery (const Subquery &subquery)
	Adds the subquery at the end of the query string.
std::string	fragment () const
	Returns the fragment of the URL.
void	setFragment (const std::string &fragment)
	Changes the fragment of the URL or add one to it.

Query URL properties
bool	isRelative () const
bool	isAbsolute () const
bool	hasAuthority () const
	Checks if the URL has an authority component (potentially empty: the URL can contain "///").
bool	isEmpty () const
bool	isValid () const
	Checks if the URL can be interpreted as valid.

Constructor & Destructor Documentation

Url() [1/2]

Url	(	const std::string &	scheme,
		const std::string &	authority,
		const std::string &	path,
		const std::string &	query = {},
		const std::string &	fragment = {} )

Instantiates a URL from its components for convenience.

In principle, the parameters should not contain the various sigils that separate each component. Encodes reserved characters from the path.

Url() [2/2]

Url	(	RelativeTag	,
		const std::string &	scheme,
		const std::string &	path,
		const std::string &	query = {},
		const std::string &	fragment = {} )

Instantiates a URL from its components for convenience, without authority.

Use Url::makeRelative as the first argument. In principle, the parameters should not contain the various sigils that separate each component. Encodes reserved characters from the path.

Member Function Documentation

operator==()

bool operator== ( const Url & other ) const

inline

Two URLs are equal when their representing strings are lexically equal.

To determine if two URLs resolve to the same entity use makeCanonical().

string()

std::string string

(

FormattingOptions

formattingOptions = None

)

const

Returns the URL as a string in a generic format.

If absolute, the path always starts with a slash (even for Windows-style paths). Reserved characters in the path are not decoded.

scheme()

std::string scheme

(

)

const

Returns the scheme of the URL.

If this is empty, then the URL is relative (see isRelative()). Example: "https://www.example.com/" -> "https".

authority()

std::string authority

(

)

const

Returns the authority of the URL.

If this is empty, then the authority is either empty or nonexistent (see hasAuthority()). Example: "https://john.doe:123456@www.example.com:80" -> john.doe:12345.nosp@m.6@ww.nosp@m.w.exa.nosp@m.mple.nosp@m..com:80".

userinfo()

std::string userinfo

(

)

const

Returns the userinfo of the URL (part of the authority).

Example: "//john.doe:123456@www.example.com" -> "john.doe:123456".

username()

std::string username

(

)

const

Returns the username of the URL (part of the userinfo).

Example: "//john.doe:123456@www.example.com" -> "john.doe".

password()

std::string password

(

)

const

Returns the password of the URL (part of the userinfo).

Example: "//john.doe:123456@www.example.com" -> "123456".

host()

std::string host

(

)

const

Returns the host of the URL (part of the authority).

Example: "//john.doe:123456@www.example.com:80" -> "www.example.com".

Examples

PacsExample.cpp.

port()

std::string port

(

)

const

Returns the port of the URL (part of the authority).

Example: "//www.example.com:80" -> "80".

Examples

PacsExample.cpp.

portNumber()

int portNumber

(

)

const

Returns the port as an integer, or -1 if it isn't set.

Note: ports are technically unsigned 16-bit integers, but using an int is more consistant with the rest of the codebase.

path()

std::string path

(

)

const

Returns the path of the URL, including both leading and trailing slashes if they exist.

Reserved characters are decoded (unlike Url::string). Example: "https:///forum/questions/?tag=networking" -> "/forum/questions/".

setPath()

void setPath

(

const std::string &

path

)

Changes the path of the URL or add one to it.

Encodes reserved characters internally.

query()

std::string query

(

)

const

Returns the query of the URL.

Example: "https:/forum/questions/?tag=networking&order=newest#top" -> "tag=networking&order=newest".

fragment()

std::string fragment

(

)

const

Returns the fragment of the URL.

Example: "https:/forum/questions/?tag=networking&order=newest#top" -> "top".

fromLocalFile()

static Url fromLocalFile ( const std::string & path )

static

Constructs a file URL from the path.

The input path is expected to be a regular filesystem path that can be either relative or absolute. Reserved characters (such as query or fragment sigils) are considered to be part of the path and will be percent-encoded. Do not pass any scheme (such as file:) as this does not make sense and will yield an invalid URL as result.

relativeTo()

static Url relativeTo ( const std::string & url, const std::string & basePath )

static

Constructs a URL where the path is meant to be relative to basePath.

This is useful when working with a relative file URL and a working directory.

percentEncoded()

static std::string percentEncoded ( const std::string & str, const std::string & encodedChars = "!#$%&*+,;=?@[]" )

static

Returns str with percent-encoded reserved characters.

Not encoding colons ':' because of Windows-style paths. Add/Remove characters from the encodedChars parameter to Add/Remove them from encoding.

---

The documentation for this class was generated from the following file:

• ImFusion/Core/Filesystem/Url.h