Namespaces
namespace	idna

Classes
class	url
	URL class. More...
class	host_output
class	host_parser
class	url_host
class	url_error
	URL exception class. More...
class	url_search_params
	URLSearchParams class. More...
class	code_point_set
	Represents code point set. More...
struct	urlpattern_init
	URLPatternInit struct. More...
struct	urlpattern_options
class	urlpattern_inputs
struct	urlpattern_component_result
	URLPatternComponentResult struct. More...
struct	urlpattern_result
	The result of executing the URL pattern when there is a match. More...
struct	urlpattern_result_and_inputs
	The result of executing the URL pattern when there is a match. More...
class	urlpattern
	URL pattern class template. More...
class	urlpattern_error
	urlpattern exception class More...
class	public_suffix_list
	The Public Suffix List class. More...
class	regex_engine_srell
	Regex engine class based on SRELL library. More...
class	regex_engine_std
	Regex engine class based on std::regex. More...

Typedefs
using	urlpattern_input

Enumerations
enum class	file_path_format { posix = 1 , windows , native = posix }
	File path format. More...
enum class	HostType { Empty = 0 , Opaque , Domain , IPv4 , IPv6 }
	Host representation. More...
enum class	validation_errc { ok = 0 , ignored , scheme_invalid_code_point , domain_to_unicode , ipv4_empty_part , ipv4_non_decimal_part , ipv4_out_of_range_part , invalid_url_unit , special_scheme_missing_following_solidus , invalid_reverse_solidus , invalid_credentials , file_invalid_windows_drive_letter , file_invalid_windows_drive_letter_host , domain_to_ascii , domain_invalid_code_point , host_invalid_code_point , ipv4_too_many_parts , ipv4_non_numeric_part , ipv6_unclosed , ipv6_invalid_compression , ipv6_too_many_pieces , ipv6_multiple_compression , ipv6_invalid_code_point , ipv6_too_few_pieces , ipv4_in_ipv6_too_many_pieces , ipv4_in_ipv6_invalid_code_point , ipv4_in_ipv6_out_of_range_part , ipv4_in_ipv6_too_few_parts , missing_scheme_non_relative_url , host_missing , port_out_of_range , port_invalid , overflow , invalid_base , file_empty_path , file_unsupported_path , not_file_url , file_url_cannot_have_host , file_url_unsupported_host , file_url_invalid_unc , file_url_not_windows_path , null_character }
	URL validation and other error codes. More...

Functions
bool	equals (const url &lhs, const url &rhs, bool exclude_fragments=false)
	URL equivalence.
bool	operator== (const url &lhs, const url &rhs)
	Lexicographically compares two URL's.
std::ostream &	operator<< (std::ostream &os, const url &url)
	Performs stream output on URL.
void	swap (url &lhs, url &rhs) noexcept
	Swaps the contents of two URLs.
template<class StrT, enable_if_str_arg_t< StrT > = 0>
url	url_from_file_path (const StrT &str, file_path_format format=file_path_format::native)
	Make URL from OS file path.
url	url_from_file_path (const std::filesystem::path &path)
	Make URL from OS file path.
std::string	path_from_file_url (const url &file_url, file_path_format format=file_path_format::native)
	Get OS path from file URL.
std::filesystem::path	fs_path_from_file_url (const url &file_url)
	Get OS path as std::filesystem::path from file URL.
UPA_API std::uint32_t	version_num ()
	Get library version encoded to one number.
bool	check_version ()
	Check used library version.
template<class StrT, enable_if_str_arg_t< StrT > = 0>
validation_errc	domain_parser (std::string &output, const StrT &input, bool be_strict)
	Implements the domain parser algorithm.
template<class CharT, class StrT, enable_if_str_arg_t< StrT > = 0>
bool	domain_to_unicode (std::basic_string< CharT > &output, const StrT &input, bool be_strict=false, bool is_input_ascii=false)
	Implements the domain to Unicode algorithm.
constexpr bool	success (validation_errc res) noexcept
	Check validation error code indicates success.
std::ostream &	operator<< (std::ostream &os, const url_search_params &usp)
	Performs stream output on URL search parameters.
void	swap (url_search_params &lhs, url_search_params &rhs) noexcept
	Swaps the contents of two url_search_params.
template<class StrT, enable_if_str_arg_t< StrT > = 0>
std::string	percent_decode (StrT &&str)
	Percent decode input string.
template<class StrT, enable_if_str_arg_t< StrT > = 0>
std::string	percent_encode (StrT &&str, const code_point_set &no_encode_set)
	UTF-8 percent encode input string using specified percent encode set.
template<class StrT, enable_if_str_arg_t< StrT > = 0>
std::string	encode_url_component (StrT &&str)
	UTF-8 percent encode input string using component percent encode set.
template<class StrT, enable_if_str_arg_t< StrT > = 0>
constexpr std::size_t	get_label_pos_by_index (const StrT &str_host, std::size_t index)
	Get label position in hostname by it's index.

Variables
constexpr code_point_set	fragment_no_encode_set
constexpr code_point_set	query_no_encode_set
constexpr code_point_set	special_query_no_encode_set
constexpr code_point_set	path_no_encode_set
constexpr code_point_set	raw_path_no_encode_set
constexpr code_point_set	posix_path_no_encode_set
constexpr code_point_set	userinfo_no_encode_set
constexpr code_point_set	component_no_encode_set
template<class T>
constexpr bool	is_regex_engine_v

Typedef Documentation

◆ urlpattern_input

using upa::urlpattern_input

Initial value:

std::variant<
   std::monostate,
   std::string_view,
 
 
 
   std::u16string_view,
   std::u32string_view,
   std::wstring_view,
   const urlpattern_init*>

Definition at line 462 of file urlpattern.h.

Enumeration Type Documentation

◆ file_path_format

enum class upa::file_path_format

strong

File path format.

Enumerator
posix	POSIX file path format.
windows	Windows file path format.
native	The file path format corresponds to the OS on which the code was compiled.

Definition at line 3167 of file url.h.

◆ HostType

enum class upa::HostType

strong

Host representation.

See: https://url.spec.whatwg.org/#host-representation

Enumerator
Empty	empty host is the empty string
Opaque	opaque host is a non-empty ASCII string used in a not special URL
Domain	domain is a non-empty ASCII string that identifies a realm within a network (it is usually the host of a special URL)
IPv4	host is an IPv4 address
IPv6	host is an IPv6 address

Definition at line 33 of file url_host.h.

◆ validation_errc

enum class upa::validation_errc

strong

URL validation and other error codes.

See: https://url.spec.whatwg.org/#validation-error

Enumerator
ok	Success.
ignored	Setter ignored the value (internal).
scheme_invalid_code_point	The scheme contains invalid code point (internal, relevant to the protocol setter)
domain_to_unicode	Unicode ToUnicode records an error.
ipv4_empty_part	An IPv4 address ends with a U+002E (.).
ipv4_non_decimal_part	The IPv4 address contains numbers expressed using hexadecimal or octal digits.
ipv4_out_of_range_part	An IPv4 address part exceeds 255.
invalid_url_unit	A code point is found that is not a URL unit.
special_scheme_missing_following_solidus	The input’s scheme is not followed by "//".
invalid_reverse_solidus	The URL has a special scheme and it uses U+005C () instead of U+002F (/).
invalid_credentials	The input includes credentials.
file_invalid_windows_drive_letter	The input is a relative-URL string that starts with a Windows drive letter and the base URL’s scheme is "file"
file_invalid_windows_drive_letter_host	A file: URL’s host is a Windows drive letter.
domain_to_ascii	Unicode ToASCII records an error or returns the empty string.
domain_invalid_code_point	Unused, use domain_to_ascii instead.
host_invalid_code_point	An opaque host contains a forbidden host code point.
ipv4_too_many_parts	An IPv4 address does not consist of exactly 4 parts.
ipv4_non_numeric_part	An IPv4 address part is not numeric.
ipv6_unclosed	An IPv6 address is missing the closing U+005D (]).
ipv6_invalid_compression	An IPv6 address begins with improper compression.
ipv6_too_many_pieces	An IPv6 address contains more than 8 pieces.
ipv6_multiple_compression	An IPv6 address is compressed in more than one spot.
ipv6_invalid_code_point	An IPv6 address contains a code point that is neither an ASCII hex digit nor a U+003A (:). Or it unexpectedly ends
ipv6_too_few_pieces	An uncompressed IPv6 address contains fewer than 8 pieces.
ipv4_in_ipv6_too_many_pieces	An IPv6 address with IPv4 address syntax: the IPv6 address has more than 6 pieces.
ipv4_in_ipv6_invalid_code_point	An IPv6 address with IPv4 address syntax: An IPv4 part is empty or contains a non-ASCII digit An IPv4 part contains a leading 0 There are too many IPv4 parts
ipv4_in_ipv6_out_of_range_part	An IPv6 address with IPv4 address syntax: an IPv4 part exceeds 255.
ipv4_in_ipv6_too_few_parts	An IPv6 address with IPv4 address syntax: an IPv4 address contains too few parts.
missing_scheme_non_relative_url	The input is missing a scheme, because it does not begin with an ASCII alpha, and either no base URL was provided or the base URL cannot be used as a base URL because it has an opaque path
host_missing	The input has a special scheme, but does not contain a host.
port_out_of_range	The input’s port is too big.
port_invalid	The input’s port is invalid.
overflow	URL is too long.
invalid_base	Invalid base.
file_empty_path	Path cannot be empty.
file_unsupported_path	Unsupported file path (e.g. non-absolute).
not_file_url	Not a file URL.
file_url_cannot_have_host	POSIX path cannot have host.
file_url_unsupported_host	UNC path cannot have "." hostname.
file_url_invalid_unc	Invalid UNC path in file URL.
file_url_not_windows_path	Not a Windows path in file URL.
null_character	Path contains null character.

Definition at line 22 of file url_result.h.

Function Documentation

◆ check_version()

bool upa::check_version ( )

inline

Check used library version.

Check that the Upa URL library used is compatible with the header files. This makes sense when using the shared Upa URL library.

Returns: true if they are compatible

Definition at line 3406 of file url.h.

◆ domain_parser()

template<class StrT, enable_if_str_arg_t< StrT > = 0>

validation_errc upa::domain_parser	(	std::string &	output,
		const StrT &	input,
		bool	be_strict )

inline

Implements the domain parser algorithm.

See: https://url.spec.whatwg.org/#concept-domain-to-ascii The output is valid only if the function returns upa::validation_errc::ok.

Parameters

[out]	output	string to store result
[in]	input	source domain string
[in]	be_strict	whether to enforce strict parsing rules

Returns: upa::validation_errc::ok on success, or upa::validation_errc::domain_to_ascii on failure

Definition at line 189 of file url_host.h.

◆ domain_to_unicode()

template<class CharT, class StrT, enable_if_str_arg_t< StrT > = 0>

bool upa::domain_to_unicode	(	std::basic_string< CharT > &	output,
		const StrT &	input,
		bool	be_strict = false,
		bool	is_input_ascii = false )

inline

Implements the domain to Unicode algorithm.

It runs the Unicode ToUnicode algorithm on the input string. The result is appended to the output, and the function returns true if ToUnicode records no errors. Otherwise, the input is appended to the output, and the function returns false.

See: https://url.spec.whatwg.org/#concept-domain-to-unicode

Parameters

[out]	output	string to store result
[in]	input	source domain string
[in]	be_strict	whether to enforce strict parsing rules
[in]	is_input_ascii	whether the input is ASCII

Returns: true on success, or false on errors

Definition at line 228 of file url_host.h.

◆ encode_url_component()

template<class StrT, enable_if_str_arg_t< StrT > = 0>

std::string upa::encode_url_component ( StrT && str )

inlinenodiscard

UTF-8 percent encode input string using component percent encode set.

Invalid code points are replaced with UTF-8 percent encoded U+FFFD characters.

More info:

Parameters

[in] str string input

Returns: percent encoded string

Definition at line 563 of file url_percent_encode.h.

◆ equals()

bool upa::equals	(	const url &	lhs,
		const url &	rhs,
		bool	exclude_fragments = false )

inlinenodiscard

URL equivalence.

Determines if lhs equals to rhs, optionally with an exclude_fragments flag. More info: https://url.spec.whatwg.org/#concept-url-equals

Parameters

[in]	lhs,rhs	URLs to compare
[in]	exclude_fragments	exclude fragments when comparing

Definition at line 3135 of file url.h.

◆ fs_path_from_file_url()

std::filesystem::path upa::fs_path_from_file_url ( const url & file_url )

inlinenodiscard

Get OS path as std::filesystem::path from file URL.

Throws url_error exception on error.

Parameters

[in] file_url file URL

Returns: OS path as std::filesystem::path

Definition at line 3379 of file url.h.

◆ get_label_pos_by_index()

template<class StrT, enable_if_str_arg_t< StrT > = 0>

std::size_t upa::get_label_pos_by_index	(	const StrT &	str_host,
		std::size_t	index )

nodiscardconstexpr

Get label position in hostname by it's index.

The label separator can be any of the following characters: U+002E (.), U+3002, U+FF0E, U+FF61 (they are mapped to U+002E (.) by IDNA).

Parameters

[in]	str_host	hostname string
[in]	index	zero-based label index starting from the leftmost label

Returns: label position in the str_host string

Definition at line 37 of file public_suffix_list.h.

◆ operator<<() [1/2]

std::ostream & upa::operator<<	(	std::ostream &	os,
		const url &	url )

inline

Performs stream output on URL.

Outputs URL serialized to ASCII string

Parameters

[in]	os	the output stream to write to
[in]	url	the url object to serialize and output

Returns: a reference to the output stream

See also: https://url.spec.whatwg.org/#url-serializing

Definition at line 3152 of file url.h.

◆ operator<<() [2/2]

std::ostream & upa::operator<<	(	std::ostream &	os,
		const url_search_params &	usp )

inline

Performs stream output on URL search parameters.

Outputs URL search parameters serialized to application/x-www-form-urlencoded

Parameters

[in]	os	the output stream to write to
[in]	usp	the url_search_params object to serialize and output

Returns: a reference to the output stream

See also: https://url.spec.whatwg.org/#urlencoded-serializing

Definition at line 771 of file url_search_params.h.

◆ operator==()

bool upa::operator==	(	const url &	lhs,
		const url &	rhs )

inlinenodiscardnoexcept

Lexicographically compares two URL's.

Definition at line 3140 of file url.h.

◆ path_from_file_url()

std::string upa::path_from_file_url	(	const url &	file_url,
		file_path_format	format = file_path_format::native )

inlinenodiscard

Get OS path from file URL.

Throws url_error exception on error.

Parameters

[in]	file_url	file URL
[in]	format	file path format, one of upa::file_path_format::posix, upa::file_path_format::windows, upa::file_path_format::native

Returns: OS path encoded in UTF-8

Definition at line 3299 of file url.h.

◆ percent_decode()

template<class StrT, enable_if_str_arg_t< StrT > = 0>

std::string upa::percent_decode ( StrT && str )

inlinenodiscard

Percent decode input string.

Invalid code points are replaced with U+FFFD characters.

More info: https://url.spec.whatwg.org/#string-percent-decode

Parameters

[in] str string input

Returns: percent decoded string

Definition at line 526 of file url_percent_encode.h.

◆ percent_encode()

template<class StrT, enable_if_str_arg_t< StrT > = 0>

std::string upa::percent_encode	(	StrT &&	str,
		const code_point_set &	no_encode_set )

inlinenodiscard

UTF-8 percent encode input string using specified percent encode set.

Invalid code points are replaced with UTF-8 percent encoded U+FFFD characters.

More info: https://url.spec.whatwg.org/#string-utf-8-percent-encode

Parameters

[in]	str	string input
[in]	no_encode_set	percent no encode set, contains code points which must not be percent encoded

Returns: percent encoded string

Definition at line 544 of file url_percent_encode.h.

◆ success()

bool upa::success ( validation_errc res )

nodiscardconstexprnoexcept

Check validation error code indicates success.

Returns: true if validation error code is validation_errc::ok, false otherwise

Definition at line 98 of file url_result.h.

◆ swap() [1/2]

void upa::swap	(	url &	lhs,
		url &	rhs )

inlinenoexcept

Swaps the contents of two URLs.

Swaps the contents of the lhs and rhs URLs

Parameters

[in,out]	lhs
[in,out]	rhs

Definition at line 3162 of file url.h.

◆ swap() [2/2]

void upa::swap	(	url_search_params &	lhs,
		url_search_params &	rhs )

inlinenoexcept

Swaps the contents of two url_search_params.

Swaps the contents of the lhs and rhs url_search_params

NOTE: It is undefined behavior to use this function to swap the contents of references returned by url::search_params().

Parameters

[in,out]	lhs
[in,out]	rhs

Definition at line 784 of file url_search_params.h.

◆ url_from_file_path() [1/2]

url upa::url_from_file_path ( const std::filesystem::path & path )

inlinenodiscard

Make URL from OS file path.

Throws url_error exception on error.

Parameters

[in] path absolute file path

Returns: file URL

Definition at line 3281 of file url.h.

◆ url_from_file_path() [2/2]

template<class StrT, enable_if_str_arg_t< StrT > = 0>

url upa::url_from_file_path	(	const StrT &	str,
		file_path_format	format = file_path_format::native )

inlinenodiscard

Make URL from OS file path.

The file path must be absolute and must not contain any dot-dot (..) segments.

There is a difference in how paths with dot-dot segments are normalized in the OS and in the WHATWG URL standard. For example, in POSIX the path /a//../b is normalized to /b, while the URL parser normalizes this path to /a/b. This library does not implement OS specific path normalization, which is the main reason why it does not accept paths with dot-dot segments. Therefore, if there are such segments in the path, it should be normalized by OS tools before being submitted to this function. Normalization can be done using the POSIX realpath function, the Windows GetFullPathName function, or, if you are using C++17, the std::filesystem::canonical function.

Throws url_error exception on error.

Parameters

[in]	str	absolute file path string
[in]	format	file path format, one of upa::file_path_format::posix, upa::file_path_format::windows, upa::file_path_format::native

Returns: file URL

See also: Pathname (POSIX), realpath, GetFullPathName, std::filesystem::canonical

Definition at line 3202 of file url.h.

◆ version_num()

UPA_API std::uint32_t upa::version_num ( )

Get library version encoded to one number.

For example, for the 2.1.0 version, it returns 0x00020100.

Returns: encoded version

Variable Documentation

◆ component_no_encode_set

code_point_set upa::component_no_encode_set

inlineconstexpr

Initial value:

{ [](code_point_set& self) constexpr {
    self.copy(userinfo_no_encode_set);
    self.exclude({ 0x24, 0x25, 0x26, 0x2B, 0x2C });
    } }

Definition at line 165 of file url_percent_encode.h.

◆ fragment_no_encode_set

code_point_set upa::fragment_no_encode_set

inlineconstexpr

Initial value:

{ [](code_point_set& self) constexpr {
    self.include(0x20, 0x7E); 
    self.exclude({ 0x20, 0x22, 0x3C, 0x3E, 0x60 });
    } }

Definition at line 116 of file url_percent_encode.h.

◆ is_regex_engine_v

template<class T>

bool upa::is_regex_engine_v

constexpr

Initial value:

                             =
std::is_default_constructible_v<T>
&& std::is_copy_constructible_v<T>
&& std::is_move_constructible_v<T>
&& std::is_copy_assignable_v<T>
&& std::is_move_assignable_v<T>
&& pattern::has_regex_engine_members<T>::value

Definition at line 140 of file urlpattern.h.

◆ path_no_encode_set

code_point_set upa::path_no_encode_set

inlineconstexpr

Initial value:

{ [](code_point_set& self) constexpr {
    self.copy(query_no_encode_set);
    self.exclude({ 0x3F, 0x5E, 0x60, 0x7B, 0x7D });
    } }

Definition at line 137 of file url_percent_encode.h.

◆ posix_path_no_encode_set

code_point_set upa::posix_path_no_encode_set

inlineconstexpr

Initial value:

{ [](code_point_set& self) constexpr {
    self.copy(raw_path_no_encode_set);
    self.exclude({ 0x3A, 0x5C, 0x7C }); 
    } }

Definition at line 151 of file url_percent_encode.h.

◆ query_no_encode_set

code_point_set upa::query_no_encode_set

inlineconstexpr

Initial value:

{ [](code_point_set& self) constexpr {
    self.include(0x20, 0x7E); 
    self.exclude({ 0x20, 0x22, 0x23, 0x3C, 0x3E });
    } }

Definition at line 123 of file url_percent_encode.h.

◆ raw_path_no_encode_set

code_point_set upa::raw_path_no_encode_set

inlineconstexpr

Initial value:

{ [](code_point_set& self) constexpr {
    self.copy(path_no_encode_set);
    self.exclude(0x25);
    } }

Definition at line 143 of file url_percent_encode.h.

◆ special_query_no_encode_set

code_point_set upa::special_query_no_encode_set

inlineconstexpr

Initial value:

{ [](code_point_set& self) constexpr {
    self.copy(query_no_encode_set);
    self.exclude(0x27);
    } }

Definition at line 130 of file url_percent_encode.h.

◆ userinfo_no_encode_set

code_point_set upa::userinfo_no_encode_set

inlineconstexpr

Initial value:

{ [](code_point_set& self) constexpr {
    self.copy(path_no_encode_set);
    self.exclude({ 0x2F, 0x3A, 0x3B, 0x3D, 0x40, 0x5B, 0x5C, 0x5D, 0x7C });
    } }

Definition at line 158 of file url_percent_encode.h.

Namespaces

Classes

Typedefs

Enumerations

Functions

Variables

Typedef Documentation

◆ urlpattern_input

Enumeration Type Documentation

◆ file_path_format

◆ HostType

◆ validation_errc

Function Documentation

◆ check_version()

◆ domain_parser()

◆ domain_to_unicode()

◆ encode_url_component()

◆ equals()

◆ fs_path_from_file_url()

◆ get_label_pos_by_index()

◆ operator<<() [1/2]

◆ operator<<() [2/2]

◆ operator==()

◆ path_from_file_url()

◆ percent_decode()

◆ percent_encode()

◆ success()

◆ swap() [1/2]

◆ swap() [2/2]

◆ url_from_file_path() [1/2]

◆ url_from_file_path() [2/2]

◆ version_num()

Variable Documentation

◆ component_no_encode_set

◆ fragment_no_encode_set

◆ is_regex_engine_v

◆ path_no_encode_set

◆ posix_path_no_encode_set

◆ query_no_encode_set

◆ raw_path_no_encode_set

◆ special_query_no_encode_set

◆ userinfo_no_encode_set