URL

#include <Ultralight/URL.h>

Overview

Parsed web address.

URL represents a parsed web address conforming to the WHATWG specification. You'll use it to inspect address components and resolve relative paths when loading pages into a View.

The object converts to String automatically, so you can pass it directly to View::LoadURL().

Construct a URL from a string and verify that parsing succeeded before loading the address:

URL link(input);  // eg, "https://example.com/docs"
if (link)
  view->LoadURL(link);

Parsing Addresses

Testing a URL in a conditional evaluates to true when parsing succeeds and false when parsing fails.

The library stores addresses in canonical form– str() returns the lowercased scheme and host rather than the raw input text.

Reading Components

Inspect individual parts of an address with component accessors:

URL link("https://example.com/search?q=maps#top");
 
String site = link.host();                 // "example.com"
String route = link.path();                // "/search"
String terms = link.query_parameter("q");  // "maps"

Accessors return an empty String when a component is absent.

Call query_parameter() with a key name to read a single parameter– it returns the form-decoded value, or an empty String when the key isn't present.

Resolving Relative References

Resolve a relative path against an existing base URL using Resolve():

URL base(view->url());
URL logo = base.Resolve("../images/logo.png");

Resolve() resolves references using the same rules a web browser applies to page links.

Building Query Strings

Append key-value pairs to an address using AppendQueryParameter():

URL search("https://www.google.com/search");
search.AppendQueryParameter("q", "C++ URL & more");
// https://www.google.com/search?q=C%2B%2B+URL+%26+more

You can add parameters individually or replace the entire query at once:

• AppendQueryParameter() encodes both keys and values automatically. This makes it safe to build addresses from user input.
• set_query() applies raw query text as-is. You'll need to encode the string beforehand.

Converting File Paths

Convert a local file path to a file: URL with FromFilePath():

URL menu_url = URL::FromFilePath("C:\\Games\\ui\\menu.html");  // a Windows path
String native_path = menu_url.ToFilePath();  // back to the native path

Both methods use the host OS's native path format, converting conventions such as Windows drive letters and backslashes automatically.

Note

Parsing requires an absolute address with a scheme (input like "example.com" fails to parse).

Note

You must initialize the object directly because copy initialization from a string doesn't compile.

See also

View::LoadURL(), View::url()

Static Public Member Functions
static URL	FromFilePath (const String &file_path)
	Create a file: URL from a native file-system path.
static String	EncodeComponent (const String &component)
	Percent-encode a string for safe embedding inside a URL component.
static String	DecodeComponent (const String &encoded)
	Decode a percent-encoded URL component.

Public Member Functions
	URL ()
	Create an empty, invalid URL.
	URL (const String &url_string)
	Parse a string as an absolute URL (WHATWG-standard parsing).
	URL (const URL &base, const String &relative)
	Resolve a (possibly relative) reference against a base URL.
	URL (const URL &other)
	Copy constructor.
	URL (URL &&other)
	Move constructor.
	~URL ()
	Destructor.
URL &	operator= (const URL &other)
	Assignment operator.
URL &	operator= (URL &&other)
	Move assignment operator.
bool	is_valid () const
	Whether or not this URL parsed successfully.
	operator bool () const
	Whether or not this URL parsed successfully (same as is_valid()).
bool	empty () const
	Whether or not this URL is empty (equivalent to !is_valid()).
String	str () const
	Get the canonical serialization of the whole URL ("" if invalid).
	operator String () const
	Implicit conversion to the canonical serialization.
URL	Resolve (const String &relative) const
	Resolve a relative or absolute reference against this URL (same as the two-argument constructor).
String	origin () const
	Get the origin serialization, like JavaScript's URL.origin.
String	scheme () const
	Get the scheme, lowercased, without the trailing colon (eg, "https"; "" if invalid).
String	host () const
	Get the host, without the port (eg, "example.com"; "" if invalid or hostless).
String	host_with_port () const
	Get the host with the explicit port appended, if one is present (eg, "example.com:8080").
bool	has_port () const
	Whether or not the URL carries an explicit port.
unsigned short	port () const
	Get the explicit port number (0 when has_port() is false).
String	username () const
	Get the username portion of the URL's credentials, percent-decoded ("" if none).
String	password () const
	Get the password portion of the URL's credentials, percent-decoded ("" if none).
String	path () const
	Get the path (eg, "/a/b"; "" if invalid).
String	query () const
	Get the query string, without the leading '?
String	fragment () const
	Get the fragment, without the leading '#' ("" if none).
bool	set_scheme (const String &scheme)
	Set the scheme.
void	set_host (const String &host)
	Set the host (without port).
void	set_port (unsigned short port)
	Set an explicit port.
void	clear_port ()
	Remove the explicit port, if any.
void	set_username (const String &username)
	Set the username portion of the URL's credentials (percent-encoded as needed).
void	set_password (const String &password)
	Set the password portion of the URL's credentials (percent-encoded as needed).
void	set_path (const String &path)
	Set the path.
void	set_query (const String &query)
	Set the raw query string (without the leading '?
void	set_fragment (const String &fragment)
	Set the fragment (without the leading '#').
bool	has_query_parameter (const String &key) const
	Whether or not the query contains a parameter with the given key (form-decoded match).
String	query_parameter (const String &key) const
	Get the first query-parameter value for the given key, form-decoded ("" if absent).
void	AppendQueryParameter (const String &key, const String &value)
	Append a key-value pair to the query, form-encoding both.
String	ToFilePath () const
	Get the native file-system path for a file: URL.
bool	operator== (const URL &other) const
	Equality over the canonical serialization.
bool	operator!= (const URL &other) const
	Inequality over the canonical serialization.
bool	operator< (const URL &other) const
	Lexicographic ordering over the canonical serialization (for ordered containers).
bool	operator== (const String &other) const
	Compare the canonical serialization against a raw string.
bool	operator!= (const String &other) const
	Inequality against a raw string (see the equality operator taking a String).

Friends
bool	operator== (const String &lhs, const URL &rhs)
	Equality with the string on the left-hand side.
bool	operator!= (const String &lhs, const URL &rhs)
	Inequality with the string on the left-hand side.

Constructor & Destructor Documentation

URL() [1/5]

URL

(

)

Create an empty, invalid URL.

URL() [2/5]

URL ( const String & url_string )

explicit

Parse a string as an absolute URL (WHATWG-standard parsing).

Input without a scheme (eg, "example.com") does not parse; the result is invalid. To resolve a relative reference, use the two-argument constructor taking a base URL.

Parameters

url_string

The string to parse.

Warning

A host with non-ASCII characters (an international domain name) needs the library's Unicode data, which the Renderer loads. Parse such a URL only after you've called Renderer::Create() or App::Create().

URL() [3/5]

URL	(	const URL &	base,
		const String &	relative )

Resolve a (possibly relative) reference against a base URL.

This follows the same rules a browser uses to resolve links on a page. An invalid base yields an invalid result unless relative is itself an absolute URL.

Parameters

base	The base URL to resolve against.
relative	The reference to resolve. This may be a path ("../images/logo.png"), an absolute path ("/index.html"), a fragment ("#top"), or a full absolute URL (which ignores the base).

URL() [4/5]

URL

(

const URL &

other

)

Copy constructor.

URL() [5/5]

URL

(

URL &&

other

)

Move constructor.

~URL()

~URL

(

)

Destructor.

Member Function Documentation

AppendQueryParameter()

void AppendQueryParameter	(	const String &	key,
		const String &	value )

Append a key-value pair to the query, form-encoding both.

Spaces become + and reserved characters are percent-encoded.

Parameters

key	The parameter name (unencoded).
value	The parameter value (unencoded).

clear_port()

void clear_port

(

)

Remove the explicit port, if any.

DecodeComponent()

String DecodeComponent ( const String & encoded )

static

Decode a percent-encoded URL component.

This matches JavaScript's decodeURIComponent for well-formed input: XX escapes (case-insensitive hex) are decoded as UTF-8 bytes.

Unlike its JavaScript counterpart this function never fails. A malformed escape (truncated, or with non-hex digits) is passed through unchanged.

Parameters

encoded

The text to decode.

Returns

Returns the decoded text.

empty()

bool empty

(

)

const

Whether or not this URL is empty (equivalent to !is_valid()).

EncodeComponent()

String EncodeComponent ( const String & component )

static

Percent-encode a string for safe embedding inside a URL component.

This matches JavaScript's encodeURIComponent: every character except letters, digits, and - _ . ! ~ * ' ( ) is replaced by the percent-encoding of its UTF-8 bytes.

Parameters

component

The text to encode.

Returns

Returns the encoded text.

fragment()

String fragment

(

)

const

Get the fragment, without the leading '#' ("" if none).

FromFilePath()

URL FromFilePath ( const String & file_path )

static

Create a file: URL from a native file-system path.

Platform path conventions are handled for you (eg, Windows drive letters and backslashes). Use ToFilePath() for the reverse conversion.

Parameters

file_path

An absolute native file-system path.

Returns

Returns a file: URL, or an invalid URL if the path cannot be represented.

has_port()

bool has_port

(

)

const

Whether or not the URL carries an explicit port.

A default port (eg, 443 for https) is elided during canonicalization and does not count as explicit.

has_query_parameter()

bool has_query_parameter

(

const String &

key

)

const

Whether or not the query contains a parameter with the given key (form-decoded match).

host()

String host

(

)

const

Get the host, without the port (eg, "example.com"; "" if invalid or hostless).

host_with_port()

String host_with_port

(

)

const

Get the host with the explicit port appended, if one is present (eg, "example.com:8080").

is_valid()

bool is_valid

(

)

const

Whether or not this URL parsed successfully.

operator bool()

operator bool ( ) const

inlineexplicit

Whether or not this URL parsed successfully (same as is_valid()).

operator String()

operator String

(

)

const

Implicit conversion to the canonical serialization.

operator!=() [1/2]

bool operator!=

(

const String &

other

)

const

Inequality against a raw string (see the equality operator taking a String).

operator!=() [2/2]

bool operator!=

(

const URL &

other

)

const

Inequality over the canonical serialization.

operator<()

bool operator<

(

const URL &

other

)

const

Lexicographic ordering over the canonical serialization (for ordered containers).

operator=() [1/2]

URL & operator=

(

const URL &

other

)

Assignment operator.

operator=() [2/2]

URL & operator=

(

URL &&

other

)

Move assignment operator.

operator==() [1/2]

bool operator==

(

const String &

other

)

const

Compare the canonical serialization against a raw string.

Note

The comparison is textual, so the string must already be in canonical form to match (eg, URL("HTTP://example.com") == "http://example.com/").

operator==() [2/2]

bool operator==

(

const URL &

other

)

const

Equality over the canonical serialization.

origin()

String origin

(

)

const

Get the origin serialization, like JavaScript's URL.origin.

For hierarchical schemes this is "scheme://host" plus the port when one is explicitly present (eg, "https://example.com:8080").

Note

Opaque origins (eg, data: URLs) serialize as "null".

password()

String password

(

)

const

Get the password portion of the URL's credentials, percent-decoded ("" if none).

path()

String path

(

)

const

Get the path (eg, "/a/b"; "" if invalid).

port()

unsigned short port

(

)

const

Get the explicit port number (0 when has_port() is false).

query()

String query

(

)

const

Get the query string, without the leading '?

' ("" if none).

Values inside the query are stored encoded. Use query_parameter() to read a decoded value.

query_parameter()

String query_parameter

(

const String &

key

)

const

Get the first query-parameter value for the given key, form-decoded ("" if absent).

Resolve()

URL Resolve

(

const String &

relative

)

const

Resolve a relative or absolute reference against this URL (same as the two-argument constructor).

Parameters

relative

The reference to resolve.

Returns

Returns the resolved URL. The result is invalid when this URL is invalid, unless relative is itself an absolute URL.

scheme()

String scheme

(

)

const

Get the scheme, lowercased, without the trailing colon (eg, "https"; "" if invalid).

set_fragment()

void set_fragment

(

const String &

fragment

)

Set the fragment (without the leading '#').

Pass an empty string to remove the fragment entirely.

set_host()

void set_host

(

const String &

host

)

Set the host (without port).

Invalid input (eg, a stray colon) and empty input are ignored, leaving the URL unchanged. This matches the JavaScript URL.host setter, which reports no acceptance signal either.

Note

This has no effect on non-hierarchical URLs (eg, data:).

set_password()

void set_password

(

const String &

password

)

Set the password portion of the URL's credentials (percent-encoded as needed).

Pass an empty string to remove it.

Note

This has no effect on non-hierarchical URLs.

set_path()

void set_path

(

const String &

path

)

Set the path.

The path is encoded as needed. On http(s) URLs an empty path becomes "/".

set_port()

void set_port

(

unsigned short

port

)

Set an explicit port.

A scheme-default port (eg, 443 for https) is elided from the serialization.

Note

This has no effect on non-hierarchical URLs.

set_query()

void set_query

(

const String &

query

)

Set the raw query string (without the leading '?

').

Pass an empty string to remove the query entirely.

The value is used as-is, so you are responsible for encoding it. To build a query from arbitrary text safely, use AppendQueryParameter() instead.

set_scheme()

bool set_scheme

(

const String &

scheme

)

Set the scheme.

The new scheme is validated and canonicalized (lowercased).

Parameters

scheme

The new scheme, with or without the trailing colon.

Returns

Returns whether or not the scheme was accepted. On failure the URL is unchanged.

set_username()

void set_username

(

const String &

username

)

Set the username portion of the URL's credentials (percent-encoded as needed).

Pass an empty string to remove it.

Note

This has no effect on non-hierarchical URLs.

str()

String str

(

)

const

Get the canonical serialization of the whole URL ("" if invalid).

ToFilePath()

String ToFilePath

(

)

const

Get the native file-system path for a file: URL.

Returns

Returns the native path, or "" for any other scheme or if this URL is invalid.

See also

FromFilePath()

username()

String username

(

)

const

Get the username portion of the URL's credentials, percent-decoded ("" if none).

Friends And Related Symbol Documentation

operator!=

bool operator!= ( const String & lhs, const URL & rhs )

friend

Inequality with the string on the left-hand side.

operator==

bool operator== ( const String & lhs, const URL & rhs )

friend

Equality with the string on the left-hand side.

---

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

• Ultralight/URL.h