upa::public_suffix_list Class Reference

The Public Suffix List class. More...

#include <upa/public_suffix_list.h>

Classes
struct	result
	Return value type of the public_suffix_list::get_suffix_info function. More...
struct	push_context
	Push context for public_suffix_list::push_line, public_suffix_list::push and public_suffix_list::finalize functions. More...

Public Types
enum class	option { public_suffix = 0 , registrable_domain = 1 , allow_trailing_dot = 2 }
	Options for public_suffix_list::get_suffix, public_suffix_list::get_suffix_info and public_suffix_list::get_suffix_view functions. More...

Public Member Functions
bool	load (const std::filesystem::path &filename)
	Load Public Suffix List from file.
UPA_API bool	load (std::istream &input_stream)
	Load Public Suffix List from stream.
UPA_API void	push_line (push_context &ctx, std::string_view line)
	Push a line of the Public Suffix List file.
UPA_API void	push (push_context &ctx, std::string_view buff)
	Push a chunk of the Public Suffix List file.
UPA_API bool	finalize (push_context &ctx)
	Finalizes when all chunks are processed.
template<class StrT, enable_if_str_arg_t< StrT > = 0>
std::string	get_suffix (const StrT &str_host, option opt=option::public_suffix) const
	Get public suffix or registrable domain.
result	get_suffix_info (const url &url, option opt=option::public_suffix) const
	Get public suffix or registrable domain information.
result	get_suffix_info (const url_host &host, option opt=option::public_suffix) const
	Get public suffix or registrable domain information.
template<class StrT, enable_if_str_arg_t< StrT > = 0>
result	get_suffix_info (const StrT &str_host, option opt=option::public_suffix) const
	Get public suffix or registrable domain information.
std::string_view	get_suffix_view (const url &url, option opt=option::public_suffix) const
	Get public suffix or registrable domain as string view.
std::string_view	get_suffix_view (const url_host &host, option opt=option::public_suffix) const
	Get public suffix or registrable domain as string view.
template<class StrT, enable_if_str_arg_t< StrT > = 0>
auto	get_suffix_view (const StrT &str_host, option opt=option::public_suffix) const -> std::basic_string_view< typename str_arg< str_arg_char_t< StrT > >::value_type >
	Get public suffix or registrable domain as string view.
UPA_API bool	operator== (const public_suffix_list &other) const
	Compares *this with other.
UPA_API	public_suffix_list ()
UPA_API	~public_suffix_list ()
UPA_API	public_suffix_list (public_suffix_list &&) noexcept
	public_suffix_list (const public_suffix_list &)=delete
UPA_API public_suffix_list &	operator= (public_suffix_list &&) noexcept
public_suffix_list &	operator= (const public_suffix_list &)=delete

Detailed Description

The Public Suffix List class.

It contains functions for loading Public Suffix List, getting public suffix or registrable domain of hostname or getting information about them.

It implements the Public Suffix List algorithm defined here: https://github.com/publicsuffix/list/wiki/Format#formal-algorithm. It also implements the URL standard public suffix and registrable domain algorithms.

The Public Suffix List file public_suffix_list.dat is required and can be obtained from https://publicsuffix.org/list/ or https://github.com/publicsuffix/list.

Example

#include "upa/public_suffix_list.h"
#include <iostream>
 
int main() {
    upa::public_suffix_list psl;
    if (psl.load("public_suffix_list.dat")) {
        auto input = "upa-url.github.io";
        auto suffix = psl.get_suffix_view(input);
        std::cout << "Public suffix of " << input << " is " << suffix << '\n';
    }
}

Definition at line 91 of file public_suffix_list.h.

Member Enumeration Documentation

option

enum class upa::public_suffix_list::option

strong

Options for public_suffix_list::get_suffix, public_suffix_list::get_suffix_info and public_suffix_list::get_suffix_view functions.

Enumerator
public_suffix	to get public suffix
registrable_domain	to get registrable domain
allow_trailing_dot	this option has no effect because trailing dot in hostname is always allowed

Definition at line 100 of file public_suffix_list.h.

Constructor & Destructor Documentation

public_suffix_list() [1/3]

UPA_API upa::public_suffix_list::public_suffix_list

(

)

~public_suffix_list()

UPA_API upa::public_suffix_list::~public_suffix_list

(

)

public_suffix_list() [2/3]

UPA_API upa::public_suffix_list::public_suffix_list ( public_suffix_list && )

noexcept

public_suffix_list() [3/3]

upa::public_suffix_list::public_suffix_list ( const public_suffix_list & )

delete

Member Function Documentation

finalize()

UPA_API bool upa::public_suffix_list::finalize

(

push_context &

ctx

)

Finalizes when all chunks are processed.

Must be called after all chunks have been processed by the public_suffix_list::push function

Parameters

[in]

ctx

push context

Returns

true if the Public Suffix List was loaded successfully

get_suffix()

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

std::string upa::public_suffix_list::get_suffix ( const StrT & str_host, option opt = option::public_suffix ) const

inlinenodiscard

Get public suffix or registrable domain.

Returns public suffix if opt has default or option::public_suffix value; and returns registrable domain if opt is option::registrable_domain.

In case of error or if there is no public suffix or registrable domain, it returns an empty string.

Parameters

[in]	str_host	hostname string
[in]	opt	options

Returns

public suffix or registrable domain (depends on opt value)

Definition at line 203 of file public_suffix_list.h.

get_suffix_info() [1/3]

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

result upa::public_suffix_list::get_suffix_info ( const StrT & str_host, option opt = option::public_suffix ) const

inlinenodiscard

Get public suffix or registrable domain information.

Returns information about the public suffix or registrable domain of the str_host string.

Parameters

[in]	str_host	hostname string
[in]	opt	options

Returns

information in the public_suffix_list::result type struct

Definition at line 254 of file public_suffix_list.h.

get_suffix_info() [2/3]

result upa::public_suffix_list::get_suffix_info ( const url & url, option opt = option::public_suffix ) const

inlinenodiscard

Get public suffix or registrable domain information.

Returns information about the public suffix or registrable domain in a hostname returned by url::hostname() const.

Parameters

[in]	url	the url object
[in]	opt	options

Returns

information in the public_suffix_list::result type struct

Definition at line 223 of file public_suffix_list.h.

get_suffix_info() [3/3]

result upa::public_suffix_list::get_suffix_info ( const url_host & host, option opt = option::public_suffix ) const

inlinenodiscard

Get public suffix or registrable domain information.

Returns information about the public suffix or registrable domain of the host.

Parameters

[in]	host	the url_host object
[in]	opt	options

Returns

information in the public_suffix_list::result type struct

Definition at line 238 of file public_suffix_list.h.

get_suffix_view() [1/3]

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

auto upa::public_suffix_list::get_suffix_view ( const StrT & str_host, option opt = option::public_suffix ) const -> std::basic_string_view< typename str_arg< str_arg_char_t< StrT > >::value_type >

inlinenodiscard

Get public suffix or registrable domain as string view.

Returns the public suffix or registrable domain of the str_host string. To get the public suffix, use the default opt value; to get the registrable domain, set opt to option::registrable_domain.

The returned view is only valid as long as the str_host exists and has not been modified.

In case of error or if there is no public suffix or registrable domain, it returns an empty string view.

Parameters

[in]	str_host	hostname string
[in]	opt	options

Returns

public suffix or registrable domain (depends on opt value)

Definition at line 326 of file public_suffix_list.h.

get_suffix_view() [2/3]

std::string_view upa::public_suffix_list::get_suffix_view ( const url & url, option opt = option::public_suffix ) const

inlinenodiscard

Get public suffix or registrable domain as string view.

Returns the public suffix or registrable domain of a hostname returned by url::hostname() const. To get the public suffix, use the default opt value; to get the registrable domain, set opt to option::registrable_domain.

The returned view is only valid as long as the url exists and has not been modified.

In case of error or if there is no public suffix or registrable domain, it returns an empty string view.

Parameters

[in]	url	the url object
[in]	opt	options

Returns

public suffix or registrable domain (depends on opt value)

Definition at line 281 of file public_suffix_list.h.

get_suffix_view() [3/3]

std::string_view upa::public_suffix_list::get_suffix_view ( const url_host & host, option opt = option::public_suffix ) const

inlinenodiscard

Get public suffix or registrable domain as string view.

Returns the public suffix or registrable domain of the host. To get the public suffix, use the default opt value; to get the registrable domain, set opt to option::registrable_domain.

The returned view is only valid as long as the host exists and has not been modified.

In case of error or if there is no public suffix or registrable domain, it returns an empty string view.

Parameters

[in]	host	the url_host object
[in]	opt	options

Returns

public suffix or registrable domain (depends on opt value)

Definition at line 303 of file public_suffix_list.h.

load() [1/2]

bool upa::public_suffix_list::load ( const std::filesystem::path & filename )

inline

Load Public Suffix List from file.

The Public Suffix List file public_suffix_list.dat can be obtained from https://publicsuffix.org/list/ or https://github.com/publicsuffix/list

Parameters

[in]

filename

the path to the Public Suffix List file

Returns

true if the Public Suffix List was loaded successfully

Definition at line 143 of file public_suffix_list.h.

load() [2/2]

UPA_API bool upa::public_suffix_list::load

(

std::istream &

input_stream

)

Load Public Suffix List from stream.

Parameters

[in]

input_stream

input stream of the Public Suffix List file

Returns

true if the Public Suffix List was loaded successfully

operator=() [1/2]

public_suffix_list & upa::public_suffix_list::operator= ( const public_suffix_list & )

delete

operator=() [2/2]

UPA_API public_suffix_list & upa::public_suffix_list::operator= ( public_suffix_list && )

noexcept

operator==()

UPA_API bool upa::public_suffix_list::operator== ( const public_suffix_list & other ) const

nodiscard

Compares *this with other.

Parameters

[in]

other

the public_suffix_list to compare with

Returns

true if both lists are equal

push()

UPA_API void upa::public_suffix_list::push	(	push_context &	ctx,
		std::string_view	buff )

Push a chunk of the Public Suffix List file.

Useful when the Public Suffix List is downloaded chunk by chunk over the network. public_suffix_list::finalize must be called after all chunks have been processed.

Parameters

[in]	ctx	push context
[in]	buff	chunk content

push_line()

UPA_API void upa::public_suffix_list::push_line	(	push_context &	ctx,
		std::string_view	line )

Push a line of the Public Suffix List file.

There is no need to call public_suffix_list::finalize after pushing all lines.

Parameters

[in]	ctx	push context
[in]	line	text line to push

---

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

• include/upa/public_suffix_list.h