kvikio::detail::UrlBuilder Class Reference

URL builder utility using libcurl's URL API. More...

#include <url.hpp>

Public Member Functions
	UrlBuilder ()
	Construct an empty URL builder. More...
	UrlBuilder (std::string const &url, std::optional< unsigned int > bitmask_url_flags=std::nullopt)
	Construct a URL builder from an existing URL string. More...
	UrlBuilder (UrlParser::UrlComponents const &components, std::optional< unsigned int > bitmask_url_flags=std::nullopt)
	Construct a URL builder from parsed URL components. More...
UrlBuilder &	set_scheme (std::optional< std::string > const &scheme)
	Set the URL scheme (e.g., "http", "https", "ftp") More...
UrlBuilder &	set_host (std::optional< std::string > const &host)
	Set the hostname or IP address. More...
UrlBuilder &	set_port (std::optional< std::string > const &port)
	Set the port number. More...
UrlBuilder &	set_path (std::optional< std::string > const &path)
	Set the path component. More...
UrlBuilder &	set_query (std::optional< std::string > const &query)
	Set the entire query string. More...
UrlBuilder &	set_fragment (std::optional< std::string > const &fragment)
	Set the fragment identifier. More...
std::string	build (std::optional< unsigned int > bitmask_component_flags=std::nullopt) const
	Build the final URL string. More...

Static Public Member Functions
static std::string	build_manually (UrlParser::UrlComponents const &components)

Detailed Description

URL builder utility using libcurl's URL API.

This class provides methods for constructing and modifying URLs by setting individual components (scheme, host, port, path, query, fragment).

Note

This class uses libcurl's URL parsing which follows RFC 3986 plus. See https://curl.se/docs/url-syntax.html

Example:

// Build from scratch
auto url = UrlBuilder()
    .set_scheme("https")
    .set_host("witcher4.com")
    .set_path("/ciri")
    .set_query("occupation", "witcher")
    .build();
 
// Modify existing URL
auto modified = UrlBuilder("https://witcher4.com/old/path/to/bestiary")
    .set_path("/new/path/to/bestiary")
    .set_port("8080")
    .build();

Definition at line 216 of file url.hpp.

Constructor & Destructor Documentation

UrlBuilder() [1/3]

kvikio::detail::UrlBuilder::UrlBuilder ( )

explicit

Construct an empty URL builder.

Exceptions

std::runtime_error

if initialization fails

UrlBuilder() [2/3]

kvikio::detail::UrlBuilder::UrlBuilder ( std::string const &  url, std::optional< unsigned int >  bitmask_url_flags = std::nullopt  )

explicit

Construct a URL builder from an existing URL string.

Parameters

url	The URL string to start with
bitmask_url_flags	Optional flags for URL parsing. Common flags include: CURLU_DEFAULT_SCHEME: Allows URLs without schemes CURLU_NON_SUPPORT_SCHEME: Accept non-supported schemes CURLU_URLENCODE: URL encode the path

Exceptions

std::runtime_error

if the URL cannot be parsed

UrlBuilder() [3/3]

kvikio::detail::UrlBuilder::UrlBuilder ( UrlParser::UrlComponents const &  components, std::optional< unsigned int >  bitmask_url_flags = std::nullopt  )

explicit

Construct a URL builder from parsed URL components.

Parameters

components	The parsed URL components to start with
bitmask_url_flags	Optional flags for URL handling

Exceptions

std::runtime_error

if the components cannot be set

Member Function Documentation

build()

std::string kvikio::detail::UrlBuilder::build

(

std::optional< unsigned int >

bitmask_component_flags = std::nullopt

)

const

Build the final URL string.

Parameters

bitmask_component_flags

Optional flags for URL formatting. Common flags: CURLU_PUNYCODE: Convert host to punycode if needed CURLU_NO_DEFAULT_PORT: Include port even if it's the default for the scheme

Returns

The complete URL string

Exceptions

std::runtime_error

if the URL cannot be built

Example:

std::string url = builder.build();

set_fragment()

UrlBuilder& kvikio::detail::UrlBuilder::set_fragment

(

std::optional< std::string > const &

fragment

)

Set the fragment identifier.

Parameters

fragment

The fragment (without leading "#"). Use std::nullopt to clear

Returns

Reference to this builder for chaining

Exceptions

std::runtime_error

if the fragment is invalid

Example:

builder.set_fragment("section-2");

set_host()

UrlBuilder& kvikio::detail::UrlBuilder::set_host

(

std::optional< std::string > const &

host

)

Set the hostname or IP address.

Parameters

host	The host to set. Use std::nullopt to clear

Returns

Reference to this builder for chaining

Exceptions

std::runtime_error

if the host is invalid

Example:

builder.set_host("api.example.com");

set_path()

UrlBuilder& kvikio::detail::UrlBuilder::set_path

(

std::optional< std::string > const &

path

)

Set the path component.

Parameters

path	The path to set (should start with "/" for absolute paths). Use std::nullopt to clear

Returns

Reference to this builder for chaining

Exceptions

std::runtime_error

if the path is invalid

Example:

builder.set_path("/api/v1/users");

set_port()

UrlBuilder& kvikio::detail::UrlBuilder::set_port

(

std::optional< std::string > const &

port

)

Set the port number.

Parameters

port	The port to set as string. Use std::nullopt to clear

Returns

Reference to this builder for chaining

Exceptions

std::runtime_error

if the port is invalid

Example:

builder.set_port("8080");

set_query()

UrlBuilder& kvikio::detail::UrlBuilder::set_query

(

std::optional< std::string > const &

query

)

Set the entire query string.

Parameters

query

The query string (without leading "?"). Use std::nullopt to clear

Returns

Reference to this builder for chaining

Exceptions

std::runtime_error

if the query is invalid

Example:

builder.set_query("page=1&limit=10");

set_scheme()

UrlBuilder& kvikio::detail::UrlBuilder::set_scheme

(

std::optional< std::string > const &

scheme

)

Set the URL scheme (e.g., "http", "https", "ftp")

Parameters

scheme

The scheme to set. Use std::nullopt to clear

Returns

Reference to this builder for chaining

Exceptions

std::runtime_error

if the scheme is invalid

Example:

builder.set_scheme("https");

---

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

• url.hpp