//
// Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
// Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com)
//
// Distributed under the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
//
// Official repository: https://github.com/boostorg/url
//
#ifndef BOOST_URL_URL_BASE_HPP
#define BOOST_URL_URL_BASE_HPP
#include <boost/url/detail/config.hpp>
#include <boost/url/ipv4_address.hpp>
#include <boost/url/ipv6_address.hpp>
#include <boost/url/params_encoded_ref.hpp>
#include <boost/url/params_ref.hpp>
#include <boost/url/pct_string_view.hpp>
#include <boost/url/scheme.hpp>
#include <boost/url/segments_encoded_ref.hpp>
#include <boost/url/segments_ref.hpp>
#include <boost/url/url_view_base.hpp>
#include <cstdint>
#include <initializer_list>
#include <memory>
#include <string>
#include <utility>
namespace boost {
namespace urls {
#ifndef BOOST_URL_DOCS
namespace detail {
struct any_params_iter;
struct any_segments_iter;
struct params_iter_impl;
struct segments_iter_impl;
struct pattern;
}
#endif
/** Common functionality for containers
This base class is used by the library
to provide common member functions for
containers. This cannot be instantiated
directly; Instead, use one of the
containers or functions:
@par Containers
@li @ref url
@li @ref url_view
@li @ref static_url
@par Functions
@li @ref parse_absolute_uri
@li @ref parse_origin_form
@li @ref parse_relative_ref
@li @ref parse_uri
@li @ref parse_uri_reference
*/
class BOOST_URL_DECL
url_base
: public url_view_base
{
char* s_ = nullptr;
std::size_t cap_ = 0;
friend class url;
friend class static_url_base;
friend class params_ref;
friend class segments_ref;
friend class segments_encoded_ref;
friend class params_encoded_ref;
friend struct detail::pattern;
struct op_t
{
~op_t();
op_t(url_base&,
core::string_view* = nullptr,
core::string_view* = nullptr) noexcept;
void move(char*, char const*,
std::size_t) noexcept;
url_base& u;
core::string_view* s0 = nullptr;
core::string_view* s1 = nullptr;
char* old = nullptr;
};
virtual ~url_base() noexcept = default;
url_base() noexcept = default;
url_base(detail::url_impl const&) noexcept;
explicit url_base(core::string_view);
void reserve_impl(std::size_t n);
void copy(url_view_base const&);
virtual void clear_impl() noexcept = 0;
virtual void reserve_impl(
std::size_t, op_t&) = 0;
virtual void cleanup(op_t&) = 0;
public:
//--------------------------------------------
//
// Observers
//
//--------------------------------------------
/** Return the url as a null-terminated string
This function returns a pointer to a null
terminated string representing the url,
which may contain percent escapes.
@par Example
@code
assert( std::strlen( url( "http://www.example.com" ).c_str() ) == 22 );
@endcode
@par Complexity
Constant.
@par Exception Safety
Throws nothing.
*/
char const*
c_str() const noexcept
{
return pi_->cs_;
}
/** Return the number of characters that can be stored without reallocating
This does not include the null terminator,
which is always present.
@par Complexity
Constant.
@par Exception Safety
Throws nothing.
*/
std::size_t
capacity() const noexcept
{
return cap_;
}
/** Clear the contents while preserving the capacity
@par Postconditions
@code
this->empty() == true
@endcode
@par Complexity
Constant.
@par Exception Safety
No-throw guarantee.
*/
void
clear() noexcept
{
this->clear_impl();
}
/** Adjust the capacity without changing the size
This function adjusts the capacity
of the container in characters, without
affecting the current contents. Has
no effect if `n <= this->capacity()`.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@throw bad_alloc Allocation failure
@param n The capacity in characters,
excluding any null terminator.
*/
void
reserve(std::size_t n)
{
reserve_impl(n);
}
//--------------------------------------------
//
// Fluent API
//
//--------------------------------------------
//
// Scheme
//
//--------------------------------------------
/** Set the scheme
The scheme is set to the specified
string, which must contain a valid
scheme without any trailing colon
(':').
Note that schemes are case-insensitive,
and the canonical form is lowercased.
@par Example
@code
assert( url( "http://www.example.com" ).set_scheme( "https" ).scheme_id() == scheme::https );
@endcode
@par Complexity
Linear in `this->size() + s.size()`.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
Exceptions thrown on invalid input.
@throw system_error
`s` contains an invalid scheme.
@param s The scheme to set.
@par BNF
@code
scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.1">
3.1. Scheme (rfc3986)</a>
@see
@ref remove_scheme.
*/
url_base&
set_scheme(core::string_view s);
/** Set the scheme
This function sets the scheme to the specified
known @ref urls::scheme id, which may not be
@ref scheme::unknown or else an exception is
thrown. If the id is @ref scheme::none, this
function behaves as if @ref remove_scheme
were called.
@par Example
@code
assert( url( "http://example.com/echo.cgi" ).set_scheme_id( scheme::wss ).buffer() == "wss://example.com/echo.cgi" );
@endcode
@par Complexity
Linear in `this->size()`.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
Exceptions thrown on invalid input.
@throw system_error
The scheme is invalid.
@param id The scheme to set.
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.1">
3.1. Scheme (rfc3986)</a>
*/
url_base&
#ifndef BOOST_URL_DOCS
set_scheme_id(urls::scheme id);
#else
set_scheme_id(scheme id);
#endif
/** Remove the scheme
This function removes the scheme if it
is present.
@par Example
@code
assert( url("http://www.example.com/index.htm" ).remove_scheme().buffer() == "//www.example.com/index.htm" );
@endcode
@par Postconditions
@code
this->has_scheme() == false && this->scheme_id() == scheme::none
@endcode
@par Complexity
Linear in `this->size()`.
@par Exception Safety
Throws nothing.
@par BNF
@code
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.1">
3.1. Scheme (rfc3986)</a>
@see
@ref set_scheme.
*/
url_base&
remove_scheme();
//--------------------------------------------
//
// Authority
//
//--------------------------------------------
/** Set the authority
This function sets the authority
to the specified string.
The string may contain percent-escapes.
@par Example
@code
assert( url().set_encoded_authority( "My%20Computer" ).has_authority() );
@endcode
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
Exceptions thrown on invalid input.
@throw system_eror
The string contains an invalid percent-encoding.
@param s The authority string to set.
@par BNF
@code
authority = [ userinfo "@" ] host [ ":" port ]
userinfo = *( unreserved / pct-encoded / sub-delims / ":" )
host = IP-literal / IPv4address / reg-name
port = *DIGIT
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2">
3.2. Authority (rfc3986)</a>
@see
@ref remove_authority.
*/
url_base&
set_encoded_authority(
pct_string_view s);
/** Remove the authority
This function removes the authority,
which includes the userinfo, host, and
a port if present.
@par Example
@code
assert( url( "http://example.com/echo.cgi" ).remove_authority().buffer() == "http:/echo.cgi" );
@endcode
@par Postconditions
@code
this->has_authority() == false && this->has_userinfo() == false && this->has_port() == false
@endcode
@par Complexity
Linear in `this->size()`.
@par Exception Safety
Throws nothing.
@par BNF
@code
authority = [ userinfo "@" ] host [ ":" port ]
userinfo = *( unreserved / pct-encoded / sub-delims / ":" )
host = IP-literal / IPv4address / reg-name
port = *DIGIT
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2">
3.2. Authority (rfc3986)</a>
@see
@ref set_encoded_authority.
*/
url_base&
remove_authority();
//--------------------------------------------
//
// Userinfo
//
//--------------------------------------------
/** Set the userinfo
The userinfo is set to the given string,
which may contain percent-escapes.
Any special or reserved characters in the
string are automatically percent-encoded.
The effects on the user and password
depend on the presence of a colon (':')
in the string:
@li If an unescaped colon exists, the
characters up to the colon become
the user and the rest of the characters
after the colon become the password.
In this case @ref has_password returns
true. Otherwise,
@li If there is no colon, the user is
set to the string. The function
@ref has_password returns false.
@note
The interpretation of the userinfo as
individual user and password components
is scheme-dependent. Transmitting
passwords in URLs is deprecated.
@par Example
@code
assert( url( "http://example.com" ).set_userinfo( "user:pass" ).encoded_user() == "user" );
@endcode
@par Complexity
Linear in `this->size() + s.size()`.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@param s The string to set.
@par BNF
@code
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1">
3.2.1. User Information (rfc3986)</a>
@see
@ref remove_userinfo,
@ref set_encoded_userinfo.
*/
url_base&
set_userinfo(
core::string_view s);
/** Set the userinfo.
The userinfo is set to the given string,
which may contain percent-escapes.
Escapes in the string are preserved,
and reserved characters in the string
are percent-escaped in the result.
The effects on the user and password
depend on the presence of a colon (':')
in the string:
@li If an unescaped colon exists, the
characters up to the colon become
the user and the rest of the characters
after the colon become the password.
In this case @ref has_password returns
true. Otherwise,
@li If there is no colon, the user is
set to the string. The function
@ref has_password returns false.
@note
The interpretation of the userinfo as
individual user and password components
is scheme-dependent. Transmitting
passwords in URLs is deprecated.
@par Example
@code
assert( url( "http://example.com" ).set_encoded_userinfo( "john%20doe" ).user() == "john doe" );
@endcode
@par Complexity
Linear in `this->size() + s.size()`.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
Exceptions thrown on invalid input.
@throw system_error
`s` contains an invalid percent-encoding.
@param s The string to set.
@par BNF
@code
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1">
3.2.1. User Information (rfc3986)</a>
@see
@ref remove_userinfo,
@ref set_userinfo.
*/
url_base&
set_encoded_userinfo(
pct_string_view s);
/** Remove the userinfo
This function removes the userinfo if
present, without removing any authority.
@par Example
@code
assert( url( "http://user@example.com" ).remove_userinfo().has_userinfo() == false );
@endcode
@par Postconditions
@code
this->has_userinfo() == false && this->encoded_userinfo().empty == true
@endcode
@par Complexity
Linear in `this->size()`.
@par Exception Safety
Throws nothing.
@par BNF
@code
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1">
3.2.1. User Information (rfc3986)</a>
@see
@ref set_encoded_userinfo,
@ref set_userinfo.
*/
url_base&
remove_userinfo() noexcept;
//--------------------------------------------
/** Set the user
This function sets the user part of the
userinfo to the string.
Any special or reserved characters in the
string are automatically percent-encoded.
@par Example
@code
assert( url().set_user("john doe").encoded_userinfo() == "john%20doe" );
@endcode
@par Postconditions
@code
this->has_authority() == true && this->has_userinfo() == true
@endcode
@par Complexity
Linear in `this->size() + s.size()`.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@param s The string to set.
@par BNF
@code
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1">
3.2.1. User Information (rfc3986)</a>
@see
@ref remove_password,
@ref set_encoded_password,
@ref set_encoded_user,
@ref set_password.
*/
url_base&
set_user(
core::string_view s);
/** Set the user
This function sets the user part of the
userinfo the the string, which may
contain percent-escapes.
Escapes in the string are preserved,
and reserved characters in the string
are percent-escaped in the result.
@par Example
@code
assert( url().set_encoded_user("john%20doe").userinfo() == "john doe" );
@endcode
@par Postconditions
@code
this->has_authority() == true && this->has_userinfo() == true
@endcode
@par Complexity
Linear in `this->size() + s.size()`.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@throw system_error
`s` contains an invalid percent-encoding.
@param s The string to set.
@par BNF
@code
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1">
3.2.1. User Information (rfc3986)</a>
@see
@ref remove_password,
@ref set_encoded_password,
@ref set_password,
@ref set_user.
*/
url_base&
set_encoded_user(
pct_string_view s);
/** Set the password.
This function sets the password in
the userinfo to the string.
Reserved characters in the string are
percent-escaped in the result.
@note
The interpretation of the userinfo as
individual user and password components
is scheme-dependent. Transmitting
passwords in URLs is deprecated.
@par Example
@code
assert( url("http://user@example.com").set_password( "pass" ).encoded_userinfo() == "user:pass" );
@endcode
@par Postconditions
@code
this->has_password() == true && this->password() == s
@endcode
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@param s The string to set. This string may
contain any characters, including nulls.
@par BNF
@code
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1">
3.2.1. User Information (rfc3986)</a>
@see
@ref remove_password,
@ref set_encoded_password,
@ref set_encoded_user,
@ref set_user.
*/
url_base&
set_password(
core::string_view s);
/** Set the password.
This function sets the password in
the userinfo to the string, which
may contain percent-escapes.
Escapes in the string are preserved,
and reserved characters in the string
are percent-escaped in the result.
@note
The interpretation of the userinfo as
individual user and password components
is scheme-dependent. Transmitting
passwords in URLs is deprecated.
@par Example
@code
assert( url("http://user@example.com").set_encoded_password( "pass" ).encoded_userinfo() == "user:pass" );
@endcode
@par Postconditions
@code
this->has_password() == true
@endcode
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@throw system_error
`s` contains an invalid percent-encoding.
@param s The string to set. This string may
contain any characters, including nulls.
@par BNF
@code
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1">
3.2.1. User Information (rfc3986)</a>
@see
@ref remove_password,
@ref set_encoded_password,
@ref set_encoded_user,
@ref set_user.
*/
url_base&
set_encoded_password(
pct_string_view s);
/** Remove the password
This function removes the password from
the userinfo if a password exists. If
there is no userinfo or no authority,
the call has no effect.
@note
The interpretation of the userinfo as
individual user and password components
is scheme-dependent. Transmitting
passwords in URLs is deprecated.
@par Example
@code
assert( url( "http://user:pass@example.com" ).remove_password().authority().buffer() == "user@example.com" );
@endcode
@par Postconditions
@code
this->has_password() == false && this->encoded_password().empty() == true
@endcode
@par Complexity
Linear in `this->size()`.
@par Exception Safety
Throws nothing.
@par BNF
@code
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1">
3.2.1. User Information (rfc3986)</a>
@see
@ref set_encoded_password,
@ref set_encoded_user,
@ref set_password,
@ref set_user.
*/
url_base&
remove_password() noexcept;
//--------------------------------------------
//
// Host
//
//--------------------------------------------
/** Set the host
Depending on the contents of the passed
string, this function sets the host:
@li If the string is a valid IPv4 address,
then the host is set to the address.
The host type is @ref host_type::ipv4.
@li If the string is a valid IPv6 address
enclosed in square brackets, then the
host is set to that address.
The host type is @ref host_type::ipv6.
@li If the string is a valid IPvFuture
address enclosed in square brackets, then
the host is set to that address.
The host type is @ref host_type::ipvfuture.
@li Otherwise, the host name is set to
the string, which may be empty.
Reserved characters in the string are
percent-escaped in the result.
The host type is @ref host_type::name.
In all cases, when this function returns,
the URL contains an authority.
@par Example
@code
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );
@endcode
@par Postconditions
@code
this->has_authority() == true
@endcode
@par Complexity
Linear in `this->size() + s.size()`.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@param s The string to set.
@par BNF
@code
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")
@endcode
@par Specification
@li <a href="https://en.wikipedia.org/wiki/IPv4"
>IPv4 (Wikipedia)</a>
@li <a href="https://datatracker.ietf.org/doc/html/rfc4291"
>IP Version 6 Addressing Architecture (rfc4291)</a>
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">
3.2.2. Host (rfc3986)</a>
@see
@ref set_encoded_host,
@ref set_encoded_host_address,
@ref set_encoded_host_name,
@ref set_host_address,
@ref set_host_ipv4,
@ref set_host_ipv6,
@ref set_host_ipvfuture,
@ref set_host_name.
*/
url_base&
set_host(
core::string_view s);
/** Set the host
Depending on the contents of the passed
string, this function sets the host:
@li If the string is a valid IPv4 address,
then the host is set to the address.
The host type is @ref host_type::ipv4.
@li If the string is a valid IPv6 address
enclosed in square brackets, then the
host is set to that address.
The host type is @ref host_type::ipv6.
@li If the string is a valid IPvFuture
address enclosed in square brackets, then
the host is set to that address.
The host type is @ref host_type::ipvfuture.
@li Otherwise, the host name is set to
the string. This string can contain percent
escapes, or can be empty.
Escapes in the string are preserved,
and reserved characters in the string
are percent-escaped in the result.
The host type is @ref host_type::name.
In all cases, when this function returns,
the URL contains an authority.
@par Example
@code
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );
@endcode
@par Postconditions
@code
this->has_authority() == true
@endcode
@par Complexity
Linear in `this->size() + s.size()`.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
Exceptions thrown on invalid input.
@throw system_error
`s` contains an invalid percent-encoding.
@param s The string to set.
@par BNF
@code
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")
@endcode
@par Specification
@li <a href="https://en.wikipedia.org/wiki/IPv4"
>IPv4 (Wikipedia)</a>
@li <a href="https://datatracker.ietf.org/doc/html/rfc4291"
>IP Version 6 Addressing Architecture (rfc4291)</a>
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">
3.2.2. Host (rfc3986)</a>
@see
@ref set_encoded_host_address,
@ref set_encoded_host_name,
@ref set_host,
@ref set_host_address,
@ref set_host_ipv4,
@ref set_host_ipv6,
@ref set_host_ipvfuture,
@ref set_host_name.
*/
url_base&
set_encoded_host(pct_string_view s);
/** Set the host to an address
Depending on the contents of the passed
string, this function sets the host:
@li If the string is a valid IPv4 address,
then the host is set to the address.
The host type is @ref host_type::ipv4.
@li If the string is a valid IPv6 address,
then the host is set to that address.
The host type is @ref host_type::ipv6.
@li If the string is a valid IPvFuture,
then the host is set to that address.
The host type is @ref host_type::ipvfuture.
@li Otherwise, the host name is set to
the string, which may be empty.
Reserved characters in the string are
percent-escaped in the result.
The host type is @ref host_type::name.
In all cases, when this function returns,
the URL contains an authority.
@par Example
@code
assert( url( "http://www.example.com" ).set_host_address( "127.0.0.1" ).buffer() == "http://127.0.0.1" );
@endcode
@par Postconditions
@code
this->has_authority() == true
@endcode
@par Complexity
Linear in `s.size()`.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@param s The string to set.
@par BNF
@code
IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet
dec-octet = DIGIT ; 0-9
/ %x31-39 DIGIT ; 10-99
/ "1" 2DIGIT ; 100-199
/ "2" %x30-34 DIGIT ; 200-249
/ "25" %x30-35 ; 250-255
IPv6address = 6( h16 ":" ) ls32
/ "::" 5( h16 ":" ) ls32
/ [ h16 ] "::" 4( h16 ":" ) ls32
/ [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
/ [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
/ [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32
/ [ *4( h16 ":" ) h16 ] "::" ls32
/ [ *5( h16 ":" ) h16 ] "::" h16
/ [ *6( h16 ":" ) h16 ] "::"
ls32 = ( h16 ":" h16 ) / IPv4address
; least-significant 32 bits of address
h16 = 1*4HEXDIG
; 16 bits of address represented in hexadecimal
IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )
reg-name = *( unreserved / pct-encoded / "-" / ".")
@endcode
@par Specification
@li <a href="https://en.wikipedia.org/wiki/IPv4"
>IPv4 (Wikipedia)</a>
@li <a href="https://datatracker.ietf.org/doc/html/rfc4291"
>IP Version 6 Addressing Architecture (rfc4291)</a>
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">
3.2.2. Host (rfc3986)</a>
@see
@ref set_encoded_host,
@ref set_encoded_host_address,
@ref set_encoded_host_name,
@ref set_host,
@ref set_host_address,
@ref set_host_ipv4,
@ref set_host_ipv6,
@ref set_host_ipvfuture,
@ref set_host_name.
*/
url_base&
set_host_address(core::string_view s);
/** Set the host to an address
Depending on the contents of the passed
string, this function sets the host:
@li If the string is a valid IPv4 address,
then the host is set to the address.
The host type is @ref host_type::ipv4.
@li If the string is a valid IPv6 address,
then the host is set to that address.
The host type is @ref host_type::ipv6.
@li If the string is a valid IPvFuture,
then the host is set to that address.
The host type is @ref host_type::ipvfuture.
@li Otherwise, the host name is set to
the string. This string can contain percent
escapes, or can be empty.
Escapes in the string are preserved,
and reserved characters in the string
are percent-escaped in the result.
The host type is @ref host_type::name.
In all cases, when this function returns,
the URL contains an authority.
@par Example
@code
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );
@endcode
@par Postconditions
@code
this->has_authority() == true
@endcode
@par Complexity
Linear in `this->size() + s.size()`.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
Exceptions thrown on invalid input.
@throw system_error
`s` contains an invalid percent-encoding.
@param s The string to set.
@par BNF
@code
IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet
dec-octet = DIGIT ; 0-9
/ %x31-39 DIGIT ; 10-99
/ "1" 2DIGIT ; 100-199
/ "2" %x30-34 DIGIT ; 200-249
/ "25" %x30-35 ; 250-255
IPv6address = 6( h16 ":" ) ls32
/ "::" 5( h16 ":" ) ls32
/ [ h16 ] "::" 4( h16 ":" ) ls32
/ [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
/ [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
/ [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32
/ [ *4( h16 ":" ) h16 ] "::" ls32
/ [ *5( h16 ":" ) h16 ] "::" h16
/ [ *6( h16 ":" ) h16 ] "::"
ls32 = ( h16 ":" h16 ) / IPv4address
; least-significant 32 bits of address
h16 = 1*4HEXDIG
; 16 bits of address represented in hexadecimal
IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )
reg-name = *( unreserved / pct-encoded / "-" / ".")
@endcode
@par Specification
@li <a href="https://en.wikipedia.org/wiki/IPv4"
>IPv4 (Wikipedia)</a>
@li <a href="https://datatracker.ietf.org/doc/html/rfc4291"
>IP Version 6 Addressing Architecture (rfc4291)</a>
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">
3.2.2. Host (rfc3986)</a>
@see
@ref set_encoded_host,
@ref set_encoded_host_name,
@ref set_host,
@ref set_host_address,
@ref set_host_ipv4,
@ref set_host_ipv6,
@ref set_host_ipvfuture,
@ref set_host_name.
*/
url_base&
set_encoded_host_address(
pct_string_view s);
/** Set the host to an address
The host is set to the specified IPv4
address.
The host type is @ref host_type::ipv4.
@par Example
@code
assert( url("http://www.example.com").set_host_ipv4( ipv4_address( "127.0.0.1" ) ).buffer() == "http://127.0.0.1" );
@endcode
@par Complexity
Linear in `this->size()`.
@par Postconditions
@code
this->has_authority() == true && this->host_ipv4_address() == addr && this->host_type() == host_type::ipv4
@endcode
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@param addr The address to set.
@par BNF
@code
IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet
dec-octet = DIGIT ; 0-9
/ %x31-39 DIGIT ; 10-99
/ "1" 2DIGIT ; 100-199
/ "2" %x30-34 DIGIT ; 200-249
/ "25" %x30-35 ; 250-255
@endcode
@par Specification
@li <a href="https://en.wikipedia.org/wiki/IPv4"
>IPv4 (Wikipedia)</a>
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">
3.2.2. Host (rfc3986)</a>
@see
@ref set_encoded_host,
@ref set_encoded_host_address,
@ref set_encoded_host_name,
@ref set_host,
@ref set_host_address,
@ref set_host_ipv6,
@ref set_host_ipvfuture,
@ref set_host_name.
*/
url_base&
set_host_ipv4(
ipv4_address const& addr);
/** Set the host to an address
The host is set to the specified IPv6
address.
The host type is @ref host_type::ipv6.
@par Example
@code
assert( url().set_host_ipv6( ipv6_address( "1::6:c0a8:1" ) ).authority().buffer() == "[1::6:c0a8:1]" );
@endcode
@par Postconditions
@code
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::ipv6
@endcode
@par Complexity
Linear in `this->size()`.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@param addr The address to set.
@par BNF
@code
IPv6address = 6( h16 ":" ) ls32
/ "::" 5( h16 ":" ) ls32
/ [ h16 ] "::" 4( h16 ":" ) ls32
/ [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
/ [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
/ [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32
/ [ *4( h16 ":" ) h16 ] "::" ls32
/ [ *5( h16 ":" ) h16 ] "::" h16
/ [ *6( h16 ":" ) h16 ] "::"
ls32 = ( h16 ":" h16 ) / IPv4address
; least-significant 32 bits of address
h16 = 1*4HEXDIG
; 16 bits of address represented in hexadecimal
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc4291"
>IP Version 6 Addressing Architecture (rfc4291)</a>
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">
3.2.2. Host (rfc3986)</a>
@see
@ref set_encoded_host,
@ref set_encoded_host_address,
@ref set_encoded_host_name,
@ref set_host,
@ref set_host_address,
@ref set_host_ipv4,
@ref set_host_ipvfuture,
@ref set_host_name.
*/
url_base&
set_host_ipv6(
ipv6_address const& addr);
/** Set the host to an address
The host is set to the specified IPvFuture
string.
The host type is @ref host_type::ipvfuture.
@par Example
@code
assert( url().set_host_ipvfuture( "v42.bis" ).buffer() == "//[v42.bis]" );
@endcode
@par Complexity
Linear in `this->size() + s.size()`.
@par Postconditions
@code
this->has_authority() == true && this->host_ipvfuture) == s && this->host_type() == host_type::ipvfuture
@endcode
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
Exceptions thrown on invalid input.
@throw system_error
`s` contains an invalid percent-encoding.
@param s The string to set.
@par BNF
@code
IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">
3.2.2. Host (rfc3986)</a>
@see
@ref set_encoded_host,
@ref set_encoded_host_address,
@ref set_encoded_host_name,
@ref set_host,
@ref set_host_address,
@ref set_host_ipv4,
@ref set_host_ipv6,
@ref set_host_name.
*/
url_base&
set_host_ipvfuture(
core::string_view s);
/** Set the host to a name
The host is set to the specified string,
which may be empty.
Reserved characters in the string are
percent-escaped in the result.
The host type is @ref host_type::name.
@par Example
@code
assert( url( "http://www.example.com/index.htm").set_host_name( "localhost" ).host_address() == "localhost" );
@endcode
@par Postconditions
@code
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name
@endcode
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@param s The string to set.
@par BNF
@code
reg-name = *( unreserved / pct-encoded / "-" / ".")
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">
3.2.2. Host (rfc3986)</a>
@see
@ref set_encoded_host,
@ref set_encoded_host_address,
@ref set_encoded_host_name,
@ref set_host,
@ref set_host_address,
@ref set_host_ipv4,
@ref set_host_ipv6,
@ref set_host_ipvfuture.
*/
url_base&
set_host_name(
core::string_view s);
/** Set the host to a name
The host is set to the specified string,
which may contain percent-escapes and
can be empty.
Escapes in the string are preserved,
and reserved characters in the string
are percent-escaped in the result.
The host type is @ref host_type::name.
@par Example
@code
assert( url( "http://www.example.com/index.htm").set_encoded_host_name( "localhost" ).host_address() == "localhost" );
@endcode
@par Postconditions
@code
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name
@endcode
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
Exceptions thrown on invalid input.
@throw system_error
`s` contains an invalid percent-encoding.
@param s The string to set.
@par BNF
@code
reg-name = *( unreserved / pct-encoded / "-" / ".")
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">
3.2.2. Host (rfc3986)</a>
@see
@ref set_encoded_host,
@ref set_encoded_host_address,
@ref set_host,
@ref set_host_address,
@ref set_host_ipv4,
@ref set_host_ipv6,
@ref set_host_ipvfuture,
@ref set_host_name.
*/
url_base&
set_encoded_host_name(
pct_string_view s);
//--------------------------------------------
/** Set the port
The port is set to the specified integer.
@par Example
@code
assert( url( "http://www.example.com" ).set_port_number( 8080 ).authority().buffer() == "www.example.com:8080" );
@endcode
@par Postconditions
@code
this->has_authority() == true && this->has_port() == true && this->port_number() == n
@endcode
@par Complexity
Linear in `this->size()`.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@param n The port number to set.
@par BNF
@code
authority = [ userinfo "@" ] host [ ":" port ]
port = *DIGIT
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.3">
3.2.3. Port (rfc3986)</a>
@see
@ref remove_port,
@ref set_port.
*/
url_base&
set_port_number(std::uint16_t n);
/** Set the port
This port is set to the string, which
must contain only digits or be empty.
An empty port string is distinct from
having no port.
@par Example
@code
assert( url( "http://www.example.com" ).set_port( "8080" ).authority().buffer() == "www.example.com:8080" );
@endcode
@par Postconditions
@code
this->has_port() == true && this->port_number() == n && this->port() == std::to_string(n)
@endcode
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
Exceptions thrown on invalid input.
@throw system_error
`s` does not contain a valid port.
@param s The port string to set.
@par BNF
@code
port = *DIGIT
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.3">
3.2.3. Port (rfc3986)</a>
@see
@ref remove_port,
@ref set_port.
*/
url_base&
set_port(core::string_view s);
/** Remove the port
If a port exists, it is removed. The rest
of the authority is unchanged.
@par Example
@code
assert( url( "http://www.example.com:80" ).remove_port().authority().buffer() == "www.example.com" );
@endcode
@par Postconditions
@code
this->has_port() == false && this->port_number() == 0 && this->port() == ""
@endcode
@par Complexity
Linear in `this->size()`.
@par Exception Safety
Throws nothing.
@par BNF
@code
authority = [ userinfo "@" ] host [ ":" port ]
port = *DIGIT
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.3">
3.2.3. Port (rfc3986)</a>
@see
@ref set_port.
*/
url_base&
remove_port() noexcept;
//--------------------------------------------
//
// Path
//
//--------------------------------------------
/** Set if the path is absolute
This function adjusts the path to make
it absolute or not, depending on the
parameter.
@note
If an authority is present, the path
is always absolute. In this case, the
function has no effect.
@par Example
@code
url u( "path/to/file.txt" );
assert( u.set_path_absolute( true ) );
assert( u.buffer() == "/path/to/file.txt" );
@endcode
@par Postconditions
@code
this->is_path_absolute() == true && this->encoded_path().front() == '/'
@endcode
@return true on success.
@par Complexity
Linear in `this->size()`.
@par BNF
@code
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.3"
>3.3. Path (rfc3986)</a>
@see
@ref encoded_segments,
@ref segments,
@ref set_encoded_path,
@ref set_path.
*/
bool
set_path_absolute(bool absolute);
/** Set the path.
This function sets the path to the
string, which may be empty.
Reserved characters in the string are
percent-escaped in the result.
@note
The library may adjust the final result
to ensure that no other parts of the url
is semantically affected.
@note
This function does not encode '/' chars, which
are unreserved for paths but reserved for
path segments. If a path segment should include
encoded '/'s to differentiate it from path separators,
the functions @ref set_encoded_path or @ref segments
should be used instead.
@par Example
@code
url u( "http://www.example.com" );
u.set_path( "path/to/file.txt" );
assert( u.path() == "/path/to/file.txt" );
@endcode
@par Complexity
Linear in `this->size() + s.size()`.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@param s The string to set.
@par BNF
@code
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.3"
>3.3. Path (rfc3986)</a>
@see
@ref encoded_segments,
@ref segments,
@ref set_encoded_path,
@ref set_path_absolute.
*/
url_base&
set_path(
core::string_view s);
/** Set the path.
This function sets the path to the
string, which may contain percent-escapes
and can be empty.
Escapes in the string are preserved,
and reserved characters in the string
are percent-escaped in the result.
@note
The library may adjust the final result
to ensure that no other parts of the url
is semantically affected.
@par Example
@code
url u( "http://www.example.com" );
u.set_encoded_path( "path/to/file.txt" );
assert( u.encoded_path() == "/path/to/file.txt" );
@endcode
@par Complexity
Linear in `this->size() + s.size()`.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
Exceptions thrown on invalid input.
@throw system_error
`s` contains an invalid percent-encoding.
@param s The string to set.
@par BNF
@code
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.3"
>3.3. Path (rfc3986)</a>
@see
@ref encoded_segments,
@ref segments,
@ref set_path,
@ref set_path_absolute.
*/
url_base&
set_encoded_path(
pct_string_view s);
/** Return the path as a container of segments
This function returns a bidirectional
view of segments over the path.
The returned view references the same
underlying character buffer; ownership
is not transferred.
Any percent-escapes in strings returned
when iterating the view are decoded first.
The container is modifiable; changes
to the container are reflected in the
underlying URL.
@par Example
@code
url u( "http://example.com/path/to/file.txt" );
segments sv = u.segments();
@endcode
@par Complexity
Constant.
@par Exception Safety
Throws nothing.
@par BNF
@code
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.3"
>3.3. Path (rfc3986)</a>
@see
@ref encoded_segments,
@ref set_encoded_path,
@ref set_path,
@ref set_path_absolute.
*/
urls::segments_ref
segments() noexcept;
/// @copydoc url_view_base::segments
segments_view
segments() const noexcept
{
return url_view_base::segments();
}
/** Return the path as a container of segments
This function returns a bidirectional
view of segments over the path.
The returned view references the same
underlying character buffer; ownership
is not transferred.
Strings returned when iterating the
range may contain percent escapes.
The container is modifiable; changes
to the container are reflected in the
underlying URL.
@par Example
@code
url u( "http://example.com/path/to/file.txt" );
segments_encoded_ref sv = u.encoded_segments();
@endcode
@par Complexity
Constant.
@par Exception Safety
Throws nothing.
@par BNF
@code
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.3"
>3.3. Path (rfc3986)</a>
@see
@ref encoded_segments,
@ref set_encoded_path,
@ref set_path,
@ref set_path_absolute.
*/
segments_encoded_ref
encoded_segments() noexcept;
/// @copydoc url_view_base::encoded_segments
segments_encoded_view
encoded_segments() const noexcept
{
return url_view_base::encoded_segments();
}
//--------------------------------------------
//
// Query
//
//--------------------------------------------
/** Set the query
This sets the query to the string, which
can be empty.
An empty query is distinct from having
no query.
Reserved characters in the string are
percent-escaped in the result.
@par Example
@code
assert( url( "http://example.com" ).set_query( "id=42" ).query() == "id=42" );
@endcode
@par Postconditions
@code
this->has_query() == true && this->query() == s
@endcode
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@param s The string to set.
@par BNF
@code
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4"
>3.4. Query (rfc3986)</a>
@li <a href="https://en.wikipedia.org/wiki/Query_string"
>Query string (Wikipedia)</a>
@see
@ref encoded_params,
@ref params,
@ref remove_query,
@ref set_encoded_query.
*/
url_base&
set_query(
core::string_view s);
/** Set the query
This sets the query to the string, which
may contain percent-escapes and can be
empty.
An empty query is distinct from having
no query.
Escapes in the string are preserved,
and reserved characters in the string
are percent-escaped in the result.
@par Example
@code
assert( url( "http://example.com" ).set_encoded_query( "id=42" ).encoded_query() == "id=42" );
@endcode
@par Postconditions
@code
this->has_query() == true && this->query() == decode_view( s );
@endcode
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
Exceptions thrown on invalid input.
@param s The string to set.
@throws system_error
`s` contains an invalid percent-encoding.
@par BNF
@code
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4"
>3.4. Query (rfc3986)</a>
@li <a href="https://en.wikipedia.org/wiki/Query_string"
>Query string (Wikipedia)</a>
@see
@ref encoded_params,
@ref params,
@ref remove_query,
@ref set_query.
*/
url_base&
set_encoded_query(
pct_string_view s);
/** Return the query as a container of parameters
This function returns a bidirectional
view of key/value pairs over the query.
The returned view references the same
underlying character buffer; ownership
is not transferred.
Any percent-escapes in strings returned
when iterating the view are decoded first.
The container is modifiable; changes
to the container are reflected in the
underlying URL.
@par Example
@code
params_ref pv = url( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).params();
@endcode
@par Complexity
Constant.
@par Exception Safety
Throws nothing.
@par BNF
@code
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4"
>3.4. Query (rfc3986)</a>
@li <a href="https://en.wikipedia.org/wiki/Query_string"
>Query string (Wikipedia)</a>
@see
@ref encoded_params,
@ref remove_query,
@ref set_encoded_query,
@ref set_query.
*/
params_ref
params() noexcept;
/// @copydoc url_view_base::params
params_view
params() const noexcept
{
return url_view_base::params();
}
/** Return the query as a container of parameters
This function returns a bidirectional
view of key/value pairs over the query.
The returned view references the same
underlying character buffer; ownership
is not transferred.
Any percent-escapes in strings returned
when iterating the view are decoded first.
The container is modifiable; changes
to the container are reflected in the
underlying URL.
@par Example
@code
encoding_opts opt;
opt.space_as_plus = true;
params_ref pv = url( "/sql?id=42&name=jane+doe&page+size=20" ).params(opt);
@endcode
@par Complexity
Constant.
@par Exception Safety
Throws nothing.
@param opt The options for decoding. If
this parameter is omitted, the `space_as_plus`
is used.
@par BNF
@code
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4"
>3.4. Query (rfc3986)</a>
@li <a href="https://en.wikipedia.org/wiki/Query_string"
>Query string (Wikipedia)</a>
@see
@ref encoded_params,
@ref remove_query,
@ref set_encoded_query,
@ref set_query.
*/
params_ref
params(encoding_opts opt) noexcept;
/// @copydoc url_view_base::encoded_params
params_encoded_view
encoded_params() const noexcept
{
return url_view_base::encoded_params();
}
/** Return the query as a container of parameters
This function returns a bidirectional
view of key/value pairs over the query.
The returned view references the same
underlying character buffer; ownership
is not transferred.
Strings returned when iterating the
range may contain percent escapes.
The container is modifiable; changes
to the container are reflected in the
underlying URL.
@par Example
@code
params_encoded_ref pv = url( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_params();
@endcode
@par Complexity
Constant.
@par Exception Safety
Throws nothing.
@par BNF
@code
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4"
>3.4. Query (rfc3986)</a>
@li <a href="https://en.wikipedia.org/wiki/Query_string"
>Query string (Wikipedia)</a>
@see
@ref params,
@ref remove_query,
@ref set_encoded_query,
@ref set_query.
*/
params_encoded_ref
encoded_params() noexcept;
/** Set the query params
This sets the query params to the list
of param_view, which can be empty.
An empty list of params is distinct from
having no params.
Reserved characters in the string are
percent-escaped in the result.
@par Example
@code
assert( url( "http://example.com" ).set_params( {"id", "42"} ).query() == "id=42" );
@endcode
@par Postconditions
@code
this->has_query() == true
@endcode
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@par Complexity
Linear.
@param ps The params to set.
@par BNF
@code
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4
>3.4. Query (rfc3986)</a>
@li <a href="https://en.wikipedia.org/wiki/Query_string"
>Query string (Wikipedia)</a>
@see
@ref encoded_params,
@ref remove_query,
@ref set_encoded_query,
@ref set_query.
*/
url_base&
set_params( std::initializer_list<param_view> ps ) noexcept;
/** Set the query params
This sets the query params to the elements
in the list, which may contain
percent-escapes and can be empty.
An empty list of params is distinct from
having no query.
Escapes in the string are preserved,
and reserved characters in the string
are percent-escaped in the result.
@par Example
@code
assert( url( "http://example.com" ).set_encoded_params( {"id", "42"} ).encoded_query() == "id=42" );
@endcode
@par Postconditions
@code
this->has_query() == true
@endcode
@par Complexity
Linear.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
Exceptions thrown on invalid input.
@param ps The params to set.
@throws system_error
some element in `ps` contains an invalid percent-encoding.
@par BNF
@code
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4"
>3.4. Query (rfc3986)</a>
@li <a href="https://en.wikipedia.org/wiki/Query_string"
>Query string (Wikipedia)</a>
@see
@ref set_params,
@ref params,
@ref remove_query,
@ref set_encoded_query,
@ref set_query.
*/
url_base&
set_encoded_params( std::initializer_list< param_pct_view > ps ) noexcept;
/** Remove the query
If a query is present, it is removed.
An empty query is distinct from having
no query.
@par Example
@code
assert( url( "http://www.example.com?id=42" ).remove_query().buffer() == "http://www.example.com" );
@endcode
@par Postconditions
@code
this->has_query() == false && this->params().empty()
@endcode
@par Exception Safety
Throws nothing.
@par BNF
@code
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4"
>3.4. Query (rfc3986)</a>
@li <a href="https://en.wikipedia.org/wiki/Query_string"
>Query string (Wikipedia)</a>
@see
@ref encoded_params,
@ref params,
@ref set_encoded_query,
@ref set_query.
*/
url_base&
remove_query() noexcept;
//--------------------------------------------
//
// Fragment
//
//--------------------------------------------
/** Remove the fragment
This function removes the fragment.
An empty fragment is distinct from
having no fragment.
@par Example
@code
assert( url( "?first=john&last=doe#anchor" ).remove_fragment().buffer() == "?first=john&last=doe" );
@endcode
@par Postconditions
@code
this->has_fragment() == false && this->encoded_fragment() == ""
@endcode
@par Complexity
Constant.
@par Exception Safety
Throws nothing.
@par BNF
@code
fragment = *( pchar / "/" / "?" )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.5"
>3.5. Fragment</a>
@see
@ref remove_fragment,
@ref set_encoded_fragment,
@ref set_fragment.
*/
url_base&
remove_fragment() noexcept;
/** Set the fragment.
This function sets the fragment to the
specified string, which may be empty.
An empty fragment is distinct from
having no fragment.
Reserved characters in the string are
percent-escaped in the result.
@par Example
@code
assert( url("?first=john&last=doe" ).set_encoded_fragment( "john doe" ).encoded_fragment() == "john%20doe" );
@endcode
@par Postconditions
@code
this->has_fragment() == true && this->fragment() == s
@endcode
@par Complexity
Linear in `this->size() + s.size()`.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@param s The string to set.
@par BNF
@code
fragment = *( pchar / "/" / "?" )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.5"
>3.5. Fragment</a>
@see
@ref remove_fragment,
@ref set_encoded_fragment.
*/
url_base&
set_fragment(
core::string_view s);
/** Set the fragment.
This function sets the fragment to the
specified string, which may contain
percent-escapes and which may be empty.
An empty fragment is distinct from
having no fragment.
Escapes in the string are preserved,
and reserved characters in the string
are percent-escaped in the result.
@par Example
@code
assert( url("?first=john&last=doe" ).set_encoded_fragment( "john%2Ddoe" ).fragment() == "john-doe" );
@endcode
@par Postconditions
@code
this->has_fragment() == true && this->fragment() == decode_view( s )
@endcode
@par Complexity
Linear in `this->size() + s.size()`.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
Exceptions thrown on invalid input.
@throw system_error
`s` contains an invalid percent-encoding.
@param s The string to set.
@par BNF
@code
fragment = *( pchar / "/" / "?" )
@endcode
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.5"
>3.5. Fragment</a>
@see
@ref remove_fragment,
@ref set_fragment.
*/
url_base&
set_encoded_fragment(
pct_string_view s);
//--------------------------------------------
//
// Compound Fields
//
//--------------------------------------------
/** Remove the origin component
This function removes the origin, which
consists of the scheme and authority.
@par Example
@code
assert( url( "http://www.example.com/index.htm" ).remove_origin().buffer() == "/index.htm" );
@endcode
@par Postconditions
@code
this->scheme_id() == scheme::none && this->has_authority() == false
@endcode
@par Complexity
Linear in `this->size()`.
@par Exception Safety
Throws nothing.
*/
url_base&
remove_origin();
//--------------------------------------------
//
// Normalization
//
//--------------------------------------------
/** Normalize the URL components
Applies Syntax-based normalization to
all components of the URL.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2"
>6.2.2 Syntax-Based Normalization (rfc3986)</a>
*/
url_base&
normalize();
/** Normalize the URL scheme
Applies Syntax-based normalization to the
URL scheme.
The scheme is normalized to lowercase.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2"
>6.2.2 Syntax-Based Normalization (rfc3986)</a>
*/
url_base&
normalize_scheme();
/** Normalize the URL authority
Applies Syntax-based normalization to the
URL authority.
Percent-encoding triplets are normalized
to uppercase letters. Percent-encoded
octets that correspond to unreserved
characters are decoded.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2"
>6.2.2 Syntax-Based Normalization (rfc3986)</a>
*/
url_base&
normalize_authority();
/** Normalize the URL path
Applies Syntax-based normalization to the
URL path.
Percent-encoding triplets are normalized
to uppercase letters. Percent-encoded
octets that correspond to unreserved
characters are decoded. Redundant
path-segments are removed.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2"
>6.2.2 Syntax-Based Normalization (rfc3986)</a>
*/
url_base&
normalize_path();
/** Normalize the URL query
Applies Syntax-based normalization to the
URL query.
Percent-encoding triplets are normalized
to uppercase letters. Percent-encoded
octets that correspond to unreserved
characters are decoded.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2"
>6.2.2 Syntax-Based Normalization (rfc3986)</a>
*/
url_base&
normalize_query();
/** Normalize the URL fragment
Applies Syntax-based normalization to the
URL fragment.
Percent-encoding triplets are normalized
to uppercase letters. Percent-encoded
octets that correspond to unreserved
characters are decoded.
@par Exception Safety
Strong guarantee.
Calls to allocate may throw.
@par Specification
@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2"
>6.2.2 Syntax-Based Normalization (rfc3986)</a>
*/
url_base&
normalize_fragment();
//
// (end of fluent API)
//
//--------------------------------------------
//--------------------------------------------
//
// Resolution
//
//--------------------------------------------
/** Resolve a URL reference against this base URL
This function attempts to resolve a URL
reference `ref` against this base URL
in a manner similar to that of a web browser
resolving an anchor tag.
This URL must satisfy the <em>URI</em>
grammar. In other words, it must contain
a scheme.
Relative references are only usable when
in the context of a base absolute URI.
This process of resolving a relative
<em>reference</em> within the context of
a <em>base</em> URI is defined in detail
in rfc3986 (see below).
The resolution process works as if the
relative reference is appended to the base
URI and the result is normalized.
Given the input base URL, this function
resolves the relative reference
as if performing the following steps:
@li Ensure the base URI has at least a scheme
@li Normalizing the reference path
@li Merge base and reference paths
@li Normalize the merged path
This function places the result of the
resolution into this URL in place.
If an error occurs, the contents of
this URL are unspecified and a @ref result
with an `system::error_code` is returned.
@par Example
@code
url base1( "/one/two/three" );
base1.resolve("four");
assert( base1.buffer() == "/one/two/four" );
url base2( "http://example.com/" )
base2.resolve("/one");
assert( base2.buffer() == "http://example.com/one" );
url base3( "http://example.com/one" );
base3.resolve("/two");
assert( base3.buffer() == "http://example.com/two" );
url base4( "http://a/b/c/d;p?q" );
base4.resolve("g#s");
assert( base4.buffer() == "http://a/b/c/g#s" );
@endcode
@par BNF
@code
absolute-URI = scheme ":" hier-part [ "?" query ]
@endcode
@par Exception Safety
Basic guarantee.
Calls to allocate may throw.
@return An empty @ref result upon success,
otherwise an error code if `!base.has_scheme()`.
@param ref The URL reference to resolve.
@par Specification
<a href="https://datatracker.ietf.org/doc/html/rfc3986#section-5"
>5. Reference Resolution (rfc3986)</a>
@see
@ref url,
@ref url_view.
*/
system::result<void>
resolve(
url_view_base const& ref);
friend
system::result<void>
resolve(
url_view_base const& base,
url_view_base const& ref,
url_base& dest);
private:
//--------------------------------------------
//
// implementation
//
//--------------------------------------------
void check_invariants() const noexcept;
char* resize_impl(int, std::size_t, op_t&);
char* resize_impl(int, int, std::size_t, op_t&);
char* shrink_impl(int, std::size_t, op_t&);
char* shrink_impl(int, int, std::size_t, op_t&);
void set_scheme_impl(core::string_view, urls::scheme);
char* set_user_impl(std::size_t n, op_t& op);
char* set_password_impl(std::size_t n, op_t& op);
char* set_userinfo_impl(std::size_t n, op_t& op);
char* set_host_impl(std::size_t n, op_t& op);
char* set_port_impl(std::size_t n, op_t& op);
char* set_path_impl(std::size_t n, op_t& op);
core::string_view
first_segment() const noexcept;
detail::segments_iter_impl
edit_segments(
detail::segments_iter_impl const&,
detail::segments_iter_impl const&,
detail::any_segments_iter&& it0,
int absolute = -1);
auto
edit_params(
detail::params_iter_impl const&,
detail::params_iter_impl const&,
detail::any_params_iter&&) ->
detail::params_iter_impl;
system::result<void>
resolve_impl(
url_view_base const& base,
url_view_base const& ref);
template<class CharSet>
void normalize_octets_impl(int,
CharSet const& allowed, op_t&) noexcept;
void decoded_to_lower_impl(int id) noexcept;
void to_lower_impl(int id) noexcept;
};
//------------------------------------------------
/** Resolve a URL reference against a base URL
This function attempts to resolve a URL
reference `ref` against the base URL `base`
in a manner similar to that of a web browser
resolving an anchor tag.
The base URL must satisfy the <em>URI</em>
grammar. In other words, it must contain
a scheme.
Relative references are only usable when
in the context of a base absolute URI.
This process of resolving a relative
<em>reference</em> within the context of
a <em>base</em> URI is defined in detail
in rfc3986 (see below).
The resolution process works as if the
relative reference is appended to the base
URI and the result is normalized.
Given the input base URL, this function
resolves the relative reference
as if performing the following steps:
@li Ensure the base URI has at least a scheme
@li Normalizing the reference path
@li Merge base and reference paths
@li Normalize the merged path
This function places the result of the
resolution into `dest`, which can be
any of the url containers that inherit
from @ref url_base.
If an error occurs, the contents of
`dest` is unspecified and `ec` is set.
@par Example
@code
url dest;
system::error_code ec;
resolve("/one/two/three", "four", dest, ec);
assert( dest.str() == "/one/two/four" );
resolve("http://example.com/", "/one", dest, ec);
assert( dest.str() == "http://example.com/one" );
resolve("http://example.com/one", "/two", dest, ec);
assert( dest.str() == "http://example.com/two" );
resolve("http://a/b/c/d;p?q", "g#s", dest, ec);
assert( dest.str() == "http://a/b/c/g#s" );
@endcode
@par BNF
@code
absolute-URI = scheme ":" hier-part [ "?" query ]
@endcode
@par Exception Safety
Basic guarantee.
Calls to allocate may throw.
@return An empty @ref result upon success,
otherwise an error code if `!base.has_scheme()`.
@param base The base URL to resolve against.
@param ref The URL reference to resolve.
@param dest The container where the result
is written, upon success.
@par Specification
<a href="https://datatracker.ietf.org/doc/html/rfc3986#section-5"
>5. Reference Resolution (rfc3986)</a>
@see
@ref url,
@ref url_view.
*/
inline
system::result<void>
resolve(
url_view_base const& base,
url_view_base const& ref,
url_base& dest)
{
if (&dest != &base)
dest.copy(base);
return dest.resolve(ref);
}
} // urls
} // boost
// These are here because of circular references
#include <boost/url/impl/params_ref.hpp>
#include <boost/url/impl/params_encoded_ref.hpp>
#include <boost/url/impl/segments_ref.hpp>
#include <boost/url/impl/segments_encoded_ref.hpp>
#endif