urlparser::hostname Class Reference

A domain name used as a URL's host, e.g. "www.example.com". More...

#include <urlparser.h>

Collaboration diagram for urlparser::hostname:

Public Member Functions
	hostname () noexcept=default
	Default constructor for the hostname class. Creates an empty hostname object.
	hostname (std::string host, const bool ignore_www=DEFAULT_IGNORE_WWW)
	Construct a hostname object from a hostname string.
const std::string &	domain () const noexcept
	The domain of the host (e.g., "example" in "www.example.com").
std::string	domain_name () const noexcept
	The domain name, i.e. "<domain>.<suffix>".
const std::string &	full_domain () const noexcept
	The full domain of the host (e.g., "example.com").
std::string	normalized_ascii () const
	The IDNA/Punycode-normalized, all-ASCII form of str(). Unlike str(), which keeps whatever the input looked like (Unicode included), this always returns the canonical ASCII form - so two hostnames that denote the same domain (e.g. "café.com" and "xn--caf-dma.com") normalize to the same string here even though str() differs. See urlparser::idna::to_ascii() in idna.h.
bool	operator== (const hostname &other) const noexcept
	Equality operator for comparing two hostname objects.
bool	operator== (const std::string &other) const noexcept
	Equality operator for comparing a hostname object with a string.
const std::string &	str () const noexcept
	The complete host string (same as full_domain()).
const std::string &	subdomain () const noexcept
	The subdomain of the host (e.g., "www" in "www.example.com").
const std::string &	suffix () const noexcept
	The suffix of the host (e.g., "com" in "example.com").

Static Public Member Functions
static hostname	from_url (const char *url, const bool ignore_www=DEFAULT_IGNORE_WWW)
	Create a hostname from a URL string literal. Disambiguation overload: without this, from_url("literal") would be an ambiguous call between the string_view and string&& overloads (a const char* converts equally well to either).
static hostname	from_url (const std::string &url, const bool ignore_www=DEFAULT_IGNORE_WWW)
	Create a hostname from a URL string.
static hostname	from_url (std::string &&url, const bool ignore_www=DEFAULT_IGNORE_WWW)
	Create a hostname from a URL string, taking ownership of it. Prefer this overload when you already have an owned/temporary std::string you don't need afterward (e.g. a std::move'd variable): it reuses that string's existing allocation to build the hostname in place, instead of copying the host substring into a brand new one.
static hostname	from_url (std::string_view url, const bool ignore_www=DEFAULT_IGNORE_WWW)
	Create a hostname from a URL string, without taking ownership. Prefer this overload when the caller only has a borrowed view of the URL (e.g. a buffer owned by something else, like a Python string) - it never allocates anything beyond the final hostname string itself.
static std::string_view	remove_www (const std::string_view &host) noexcept
	Remove "www." from the beginning of a hostname string.

Detailed Description

A domain name used as a URL's host, e.g. "www.example.com".

hostname encapsulates the domain-specific details of a host: suffix, domain, subdomain, and the full (possibly www-stripped) domain. For an IP address host, use ipv4/ipv6 instead - see the file-level docs.

A hostname is a plain value type: constructing one is just a string copy. The Public-Suffix-List lookup that domain()/subdomain()/suffix()/ domain_name() need is deferred until one of them is first called, and cached from then on.

Constructor & Destructor Documentation

hostname() [1/2]

urlparser::hostname::hostname	(	std::string	host,
		const bool	ignore_www = DEFAULT_IGNORE_WWW
	)

Construct a hostname object from a hostname string.

Parameters

host	The hostname to parse.
ignore_www	Whether to ignore the "www" subdomain. Default is false.

hostname() [2/2]

urlparser::hostname::hostname ( )

defaultnoexcept

Default constructor for the hostname class. Creates an empty hostname object.

Member Function Documentation

domain()

const std::string & urlparser::hostname::domain ( ) const

noexcept

The domain of the host (e.g., "example" in "www.example.com").

domain_name()

std::string urlparser::hostname::domain_name ( ) const

noexcept

The domain name, i.e. "<domain>.<suffix>".

from_url() [1/4]

static hostname urlparser::hostname::from_url ( const char *  url, const bool  ignore_www = DEFAULT_IGNORE_WWW  )

static

Create a hostname from a URL string literal. Disambiguation overload: without this, from_url("literal") would be an ambiguous call between the string_view and string&& overloads (a const char* converts equally well to either).

from_url() [2/4]

static hostname urlparser::hostname::from_url ( const std::string &  url, const bool  ignore_www = DEFAULT_IGNORE_WWW  )

static

Create a hostname from a URL string.

Parameters

url	The URL string to parse.
ignore_www	Whether to ignore the "www" subdomain. Default is false.

Returns

A hostname object representing the host part of the URL.

from_url() [3/4]

static hostname urlparser::hostname::from_url ( std::string &&  url, const bool  ignore_www = DEFAULT_IGNORE_WWW  )

static

Create a hostname from a URL string, taking ownership of it. Prefer this overload when you already have an owned/temporary std::string you don't need afterward (e.g. a std::move'd variable): it reuses that string's existing allocation to build the hostname in place, instead of copying the host substring into a brand new one.

Parameters

url	The URL string to parse. Left in a valid but unspecified state after the call.
ignore_www	Whether to ignore the "www" subdomain. Default is false.

Returns

A hostname object representing the host part of the URL.

from_url() [4/4]

static hostname urlparser::hostname::from_url ( std::string_view  url, const bool  ignore_www = DEFAULT_IGNORE_WWW  )

static

Create a hostname from a URL string, without taking ownership. Prefer this overload when the caller only has a borrowed view of the URL (e.g. a buffer owned by something else, like a Python string) - it never allocates anything beyond the final hostname string itself.

Parameters

url	The URL string to parse.
ignore_www	Whether to ignore the "www" subdomain. Default is false.

Returns

A hostname object representing the host part of the URL.

full_domain()

const std::string & urlparser::hostname::full_domain ( ) const

noexcept

The full domain of the host (e.g., "example.com").

normalized_ascii()

std::string urlparser::hostname::normalized_ascii

(

)

const

The IDNA/Punycode-normalized, all-ASCII form of str(). Unlike str(), which keeps whatever the input looked like (Unicode included), this always returns the canonical ASCII form - so two hostnames that denote the same domain (e.g. "café.com" and "xn--caf-dma.com") normalize to the same string here even though str() differs. See urlparser::idna::to_ascii() in idna.h.

operator==() [1/2]

bool urlparser::hostname::operator== ( const hostname &  other ) const

noexcept

Equality operator for comparing two hostname objects.

operator==() [2/2]

bool urlparser::hostname::operator== ( const std::string &  other ) const

noexcept

Equality operator for comparing a hostname object with a string.

remove_www()

static std::string_view urlparser::hostname::remove_www ( const std::string_view &  host )

staticnoexcept

Remove "www." from the beginning of a hostname string.

Parameters

host	The hostname text to process.

Returns

The text without a leading "www." if it was present.

str()

const std::string & urlparser::hostname::str ( ) const

noexcept

The complete host string (same as full_domain()).

subdomain()

const std::string & urlparser::hostname::subdomain ( ) const

noexcept

The subdomain of the host (e.g., "www" in "www.example.com").

suffix()

const std::string & urlparser::hostname::suffix ( ) const

noexcept

The suffix of the host (e.g., "com" in "example.com").

---

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

• /home/runner/work/liburlparser/liburlparser/include/urlparser.h