| Name | Description |
|---|---|
| boost |
| Name | Description |
|---|---|
| urls |
| Name | Description |
|---|---|
| error_types | |
| grammar | |
| implementation_defined | |
| see_below | |
| string_token |
| Name | Description |
|---|---|
| authority_view |
A non-owning reference to a valid authority |
| decode_view |
A reference to a valid, percent-encoded string |
| encoding_opts |
Percent-encoding options |
| ignore_case_param |
An optional parameter to determine case-sensitivity |
| ipv4_address |
An IP version 4 style address. |
| ipv6_address |
An IP version 6 style address. |
| no_value_t |
The type of no_value |
| optional |
The type of optional used by the library |
| param |
A query parameter |
| param_pct_view |
A query parameter |
| param_view |
A query parameter |
| params_base |
Common functionality for containers |
| params_encoded_base |
Common functionality for containers |
| params_encoded_ref |
A view representing query parameters in a URL |
| params_encoded_view |
A view representing query parameters in a URL |
| params_ref |
A view representing query parameters in a URL |
| params_view |
A view representing query parameters in a URL |
| pct_string_view |
A reference to a valid percent-encoded string |
| segments_base |
Common functionality for containers |
| segments_encoded_base |
Common functionality for containers |
| segments_encoded_ref |
A view representing path segments in a URL |
| segments_encoded_view |
A view representing path segments in a URL |
| segments_ref |
A view representing path segments in a URL |
| segments_view |
A view representing path segments in a URL |
| static_url |
A modifiable container for a URL. |
| static_url_base |
Common implementation for all static URLs |
| string_view |
The type of string_view used by the library |
| url |
A modifiable container for a URL. |
| url_base |
Common functionality for containers |
| url_view |
A non-owning reference to a valid URL |
| url_view_base |
Common functionality for containers |
| variant |
The type of variant used by the library |
| Name | Description |
|---|---|
| error |
Error codes returned the library |
| host_type |
Identifies the type of host in a URL. |
| scheme |
Identifies a known URL scheme |
| Name | Description |
|---|---|
| arg |
Designate a named argument for a replacement field |
| default_port |
Return the default port for a known scheme |
| encode |
Apply percent-encoding to a string Return a percent-encoded string |
| encoded_size |
Return the buffer size needed for percent-encoding |
| format |
Format arguments into a URL |
| format_to |
Format arguments into a URL |
| make_pct_string_view |
Return a valid percent-encoded string |
| operator!= |
Compare two decode views for inequality Return the result of comparing two URLs Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized. Return true if two addresses are not equal |
| operator< |
Compare two decode views for less than Return the result of comparing two URLs Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized. |
| operator<< |
Format the address to an output stream. Format the address to an output stream Format the encoded authority to the output stream Format the string with percent-decoding applied to the output stream Format the url to the output stream Format to an output stream |
| operator<= |
Compare two decode views for less than or equal Return the result of comparing two URLs Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized. |
| operator== |
Compare two decode views for equality Return the result of comparing two URLs Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized. Return true if two addresses are equal |
| operator> |
Compare two decode views for greater than Return the result of comparing two URLs Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized. |
| operator>= |
Compare two decode views for greater than or equal Return the result of comparing two URLs Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized. |
| parse_absolute_uri |
Return a reference to a parsed URL string |
| parse_authority |
Parse an authority |
| parse_ipv4_address |
Return an IPv4 address from an IP address string in dotted decimal form |
| parse_ipv6_address |
Parse a string containing an IPv6 address. |
| parse_origin_form |
Return a reference to a parsed URL string |
| parse_path |
Parse a string and return an encoded segment view |
| parse_query |
Parse a string and return an encoded params view |
| parse_relative_ref |
Return a reference to a parsed URL string |
| parse_uri |
Return a reference to a parsed URL string |
| parse_uri_reference |
Return a reference to a parsed URL string |
| pct_encoded_rule |
Rule for a string with percent-encoded escapes |
| resolve |
Resolve a URL reference against a base URL |
| string_to_scheme |
Return the known scheme for a non-normalized string, if known |
| swap |
Swap |
| to_string |
Return the normalized string for a known scheme |
| Name | Description |
|---|---|
| absolute_uri_rule |
Rule for absolute-URI |
| authority_rule |
Rule for authority |
| gen_delim_chars |
The gen-delims character set |
| ignore_case |
Ignore case when comparing |
| ipv4_address_rule |
Rule for an IP version 4 style address |
| ipv6_address_rule |
Rule for An IP version 6 style address |
| no_value |
Constant indicating no value in a param |
| origin_form_rule |
Rule for origin-form |
| pchars |
The path character set |
| query_rule |
Rule for query |
| relative_ref_rule |
Rule for relative-ref |
| reserved_chars |
The reserved character set |
| sub_delim_chars |
The sub-delims character set |
| unreserved_chars |
The unreserved character set |
| uri_reference_rule |
Rule for URI-reference |
| uri_rule |
Rule for URI |
| Name | Description |
|---|---|
| implementation_defined | |
| see_below |
| Name | Description |
|---|---|
| aligned_storage |
Provides an aligned storage buffer aligned for T |
| ci_equal |
A case-insensitive equals predicate for strings |
| ci_hash |
A case-insensitive hash function object for strings |
| ci_less |
A case-insensitive less predicate for strings |
| is_charset |
Alias for `std::true_type` if T satisfies CharSet . |
| is_rule |
Determine if T meets the requirements of Rule |
| literal_rule | |
| lut_chars |
A set of characters |
| range |
A forward range of parsed elements |
| recycled |
A thread-safe collection of instances of T |
| recycled_ptr |
A pointer to a shared instance of T |
| string_view_base |
Common functionality for string views |
| unsigned_rule |
Match an unsigned decimal |
| Name | Description |
|---|---|
| condition |
Error conditions for errors received from rules |
| error |
Error codes returned when using rules |
| Name | Description |
|---|---|
| ci_compare |
Return the case-insensitive comparison of s0 and s1 |
| ci_digest |
Return the case-insensitive digest of a string |
| ci_is_equal |
Return true if s0 equals s1 using case-insensitive comparison |
| ci_is_less |
Return true if s0 is less than s1 using case-insensitive comparison |
| delim_rule |
Match a character literal Match a single character from a character set |
| find_if |
Find the first character in the string that is in the set. |
| find_if_not |
Find the first character in the string that is not in CharSet |
| hexdig_value |
Return the decimal value of a hex character |
| not_empty_rule |
Match another rule, if the result is not empty |
| operator!= |
Compare two string views for inequality |
| operator+ |
Return the union of two character sets. |
| operator- |
Return a new character set by subtracting |
| operator< |
Compare two string views for less than |
| operator<< |
Format a string to an output stream |
| operator<= |
Compare two string views for less than or equal |
| operator== |
Compare two string views for equality |
| operator> |
Compare two string views for greater than |
| operator>= |
Compare two string views for greater than or equal |
| optional_rule |
Match a rule, or the empty string |
| parse |
Parse a character buffer using a rule |
| range_rule |
Match a repeating number of elements |
| ref |
Return a reference to a character set Return a reference to a rule |
| squelch |
Squelch the value of a rule |
| to_lower |
Return c converted to lowercase |
| to_upper |
Return c converted to uppercase |
| token_rule |
Match a non-empty string of characters from a set |
| tuple_rule |
Match a series of rules in order |
| variant_rule |
Match one of a set of rules |
| Name | Description |
|---|---|
| all_chars |
The set of all characters |
| alnum_chars |
The set of letters and digits |
| alpha_chars |
The set of all letters |
| dec_octet_rule |
Match a decimal octet |
| digit_chars |
The set of decimal digits |
| hexdig_chars |
The set of hexadecimal digits |
| vchars |
The set of visible characters |
| Name | Description |
|---|---|
| operator() |
Declared in <boost/url/grammar/alnum_chars.hpp>
constexpr
bool
operator()(char c) const noexcept;
| Name | Description |
|---|---|
| alpha_chars_t [constructor] | |
| operator() |
Declared in <boost/url/grammar/alpha_chars.hpp>
constexpr
alpha_chars_t() noexcept = default;
Declared in <boost/url/grammar/alpha_chars.hpp>
constexpr
bool
operator()(char c) const noexcept;
| Name | Description |
|---|---|
| find_if | |
| find_if_not | |
| operator() |
| Name | Description |
|---|---|
| cs_ |
Declared in <boost/url/grammar/charset.hpp>
constexpr
bool
operator()(char ch) const noexcept;
Declared in <boost/url/grammar/charset.hpp>
char const*
find_if(
char const* first,
char const* last) const noexcept;
Declared in <boost/url/grammar/charset.hpp>
char const*
find_if_not(
char const* first,
char const* last) const noexcept;
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| parse |
Declared in <boost/url/grammar/dec_octet_rule.hpp>
system::result<_implementation-defined_>
parse(
char const*& it,
char const* end) const noexcept;
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| ch_delim_rule [constructor] | |
| parse |
Declared in <boost/url/grammar/delim_rule.hpp>
system::result<_implementation-defined_>
parse(
char const*& it,
char const* end) const noexcept;
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| cs_delim_rule [constructor] | |
| parse |
Declared in <boost/url/grammar/delim_rule.hpp>
constexpr
cs_delim_rule(CharSet const& cs) noexcept;
Declared in <boost/url/grammar/delim_rule.hpp>
system::result<_implementation-defined_>
parse(
char const*& it,
char const* end) const noexcept;
| Name | Description |
|---|---|
| operator() |
Declared in <boost/url/grammar/digit_chars.hpp>
constexpr
bool
operator()(char c) const noexcept;
| Name | Description |
|---|---|
| operator() |
Return true if c is in the character set. |
Return true if c is in the character set.
Declared in <boost/url/grammar/hexdig_chars.hpp>
constexpr
bool
operator()(char c) const noexcept;
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| not_empty_rule_t [constructor] | |
| parse |
Declared in <boost/url/grammar/not_empty_rule.hpp>
system::result<_implementation-defined_>
parse(
char const*& it,
char const* end) const;
Declared in <boost/url/grammar/not_empty_rule.hpp>
constexpr
not_empty_rule_t(R const& r) noexcept;
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| parse |
| Name | Description |
|---|---|
| r_ |
Declared in <boost/url/grammar/parse.hpp>
system::result<_implementation-defined_>
parse(
char const*& it,
char const* end) const;
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| optional_rule_t [constructor] | |
| parse |
Declared in <boost/url/grammar/optional_rule.hpp>
system::result<_implementation-defined_>
parse(
char const*& it,
char const* end) const;
Declared in <boost/url/grammar/optional_rule.hpp>
constexpr
optional_rule_t(Rule const& r) noexcept;
Declared in <boost/url/grammar/range_rule.hpp>
template<
class R0,
class R1 = void>
struct range_rule_t;
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| parse | |
| range_rule_t [constructor] |
Declared in <boost/url/grammar/range_rule.hpp>
system::result<_implementation-defined_>
parse(
char const*& it,
char const* end) const;
Declared in <boost/url/grammar/range_rule.hpp>
constexpr
range_rule_t(
R0 const& first,
R1 const& next,
std::size_t N,
std::size_t M) noexcept;
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| parse | |
| range_rule_t [constructor] |
Declared in <boost/url/grammar/range_rule.hpp>
system::result<_implementation-defined_>
parse(
char const*& it,
char const* end) const;
Declared in <boost/url/grammar/range_rule.hpp>
constexpr
range_rule_t(
R const& next,
std::size_t N,
std::size_t M) noexcept;
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| parse | |
| token_rule_t [constructor] |
Declared in <boost/url/grammar/token_rule.hpp>
system::result<_implementation-defined_>
parse(
char const*& it,
char const* end) const noexcept;
Declared in <boost/url/grammar/token_rule.hpp>
constexpr
token_rule_t(CharSet const& cs) noexcept;
Declared in <boost/url/grammar/tuple_rule.hpp>
template<
class R0,
class... Rn>
class tuple_rule_t;
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| parse | |
| tuple_rule_t [constructor] |
Declared in <boost/url/grammar/tuple_rule.hpp>
constexpr
tuple_rule_t(
R0 const& r0,
Rn const&... rn) noexcept;
Declared in <boost/url/grammar/tuple_rule.hpp>
system::result<_implementation-defined_>
parse(
char const*& it,
char const* end) const;
Declared in <boost/url/grammar/tuple_rule.hpp>
template
struct squelch_rule_t
: empty_value;
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| parse | |
| squelch_rule_t [constructor] |
Declared in <boost/url/grammar/tuple_rule.hpp>
constexpr
squelch_rule_t(Rule const& r) noexcept;
Declared in <boost/url/grammar/tuple_rule.hpp>
system::result<_implementation-defined_>
parse(
char const*& it,
char const* end) const;
Declared in <boost/url/grammar/variant_rule.hpp>
template<
class R0,
class... Rn>
class variant_rule_t;
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| parse | |
| variant_rule_t [constructor] |
Declared in <boost/url/grammar/variant_rule.hpp>
system::result<_implementation-defined_>
parse(
char const*& it,
char const* end) const;
Declared in <boost/url/grammar/variant_rule.hpp>
constexpr
variant_rule_t(
R0 const& r0,
Rn const&... rn) noexcept;
| Name | Description |
|---|---|
| operator() |
Declared in <boost/url/grammar/vchars.hpp>
constexpr
bool
operator()(char c) const noexcept;
| Name | Description |
|---|---|
| all_chars_t [constructor] | |
| operator() |
Declared in <boost/url/grammar/all_chars.hpp>
constexpr
bool
operator()(char) const noexcept;
The set of letters and digits
Declared in <boost/url/grammar/alnum_chars.hpp>
constexpr
_implementation-defined_ alnum_chars = {};
functions find_if and find_if_not .
system::result< core::string_view > = parse( "Johnny42", token_rule( alnumchars ) );
ALNUM = ALPHA / DIGIT
ALPHA = %x41-5A / %x61-7A
; A-Z / a-z
DIGIT = %x30-39
; 0-9
The set of all letters
Declared in <boost/url/grammar/alpha_chars.hpp>
constexpr
_implementation-defined_ alpha_chars = alpha_chars{};
functions find_if and find_if_not .
system::result< core::string_view > rv = parse( "JohnDoe", token_rule( alpha_chars ) );
ALPHA = %x41-5A / %x61-7A
; A-Z / a-z
| Name | Description |
|---|---|
| nearest_pow2 | |
| recycled_add | |
| recycled_add_impl | |
| recycled_remove | |
| recycled_remove_impl |
Declared in <boost/url/grammar/charset.hpp>
template<
class T,
class = void>
struct is_charset
: std::false_type;
Declared in <boost/url/grammar/charset.hpp>
template
struct is_charset() =
std::declval().operator()(
std::declval()))>>
: std::true_type;
| Name | Description |
|---|---|
| is_transparent |
| Name | Description |
|---|---|
| operator() |
Declared in <boost/url/grammar/ci_string.hpp>
std::size_t
operator()(core::string_view s) const noexcept;
| Name | Description |
|---|---|
| is_transparent |
| Name | Description |
|---|---|
| operator() |
Declared in <boost/url/grammar/ci_string.hpp>
template<
class String0,
class String1>
bool
operator()(
String0 s0,
String1 s1) const noexcept;
| Name | Description |
|---|---|
| is_transparent |
| Name | Description |
|---|---|
| operator() |
Declared in <boost/url/grammar/ci_string.hpp>
std::size_t
operator()(
core::string_view s0,
core::string_view s1) const noexcept;
Declared in <boost/url/grammar/type_traits.hpp>
template<
class T,
class = void>
struct is_rule
: std::false_type;
Declared in <boost/url/grammar/type_traits.hpp>
template
struct is_rule&>() =
std::declval().parse(
std::declval(),
std::declval()))>>
: std::is_nothrow_copy_constructible;
Declared in <boost/url/grammar/detail/recycled.hpp>
template<
std::size_t Size,
std::size_t Align>
struct aligned_storage_impl;
| Name | Description |
|---|---|
| addr |
void*
addr() noexcept;void const*
addr() const noexcept;
Declared in <boost/url/grammar/detail/recycled.hpp>
constexpr
std::size_t
nearest_pow2(
std::size_t x,
std::size_t f = 0) noexcept;
Declared in <boost/url/grammar/detail/recycled.hpp>
void
recycled_add_impl(std::size_t) noexcept;
Declared in <boost/url/grammar/detail/recycled.hpp>
void
recycled_remove_impl(std::size_t) noexcept;
Declared in <boost/url/grammar/detail/recycled.hpp>
void
recycled_add(std::size_t) noexcept;
Declared in <boost/url/grammar/detail/recycled.hpp>
void
recycled_remove(std::size_t) noexcept;
Alias for `std::true_type` if T satisfies CharSet .
This metafunction determines if the type `T` meets these requirements of CharSet :
bool T::operator()( char ) const noexcept;
template< class CharSet >
typename std::enable_if< is_charset::value >::type
func( CharSet const& cs );
Find the first character in the string that is in the set.
Declared in <boost/url/grammar/charset.hpp>
template
char const*
find_if(
char const const* first,
char const const* last,
CharSet const& cs) noexcept;
| Name | Description |
|---|---|
| first | |
| last | |
| cs |
Find the first character in the string that is not in CharSet
Declared in <boost/url/grammar/charset.hpp>
template
char const*
find_if_not(
char const const* first,
char const const* last,
CharSet const& cs) noexcept;
| Name | Description |
|---|---|
| first | |
| last | |
| cs |
Return a reference to a character set
template
constexpr
_implementation-defined_
ref(CharSet const& cs) noexcept; Return a reference to a rule
template
constexpr
_implementation-defined_
ref(Rule const& r) noexcept; Return c converted to lowercase
This function returns the character, converting it to lowercase if it is uppercase. The function is defined only for low-ASCII characters.
assert( to_lower( 'A' ) == 'a' );
| Name | Description |
|---|---|
| c |
Return c converted to uppercase
This function returns the character, converting it to uppercase if it is lowercase. The function is defined only for low-ASCII characters.
assert( to_upper( 'a' ) == 'A' );
| Name | Description |
|---|---|
| c |
Return the case-insensitive comparison of s0 and s1
Declared in <boost/url/grammar/ci_string.hpp>
int
ci_compare(
core::string_view s0,
core::string_view s1) noexcept;
This returns the lexicographical comparison of two strings, ignoring case. The function is defined only for strings containing low-ASCII characters.
assert( ci_compare( "boost", "Boost" ) == 0 );
| Name | Description |
|---|---|
| s0 | |
| s1 |
Return the case-insensitive digest of a string
Declared in <boost/url/grammar/ci_string.hpp>
std::size_t
ci_digest(core::string_view s) noexcept;
The hash function is non-cryptographic and not hardened against algorithmic complexity attacks. Returned digests are suitable for usage in unordered containers. The function is defined only for strings containing low-ASCII characters.
| Name | Description |
|---|---|
| s |
Return true if s0 equals s1 using case-insensitive comparison
template<
class String0,
class String1>
bool
ci_is_equal(
String0 const& s0,
String1 const& s1);Return true if s0 equals s1 using case-insensitive comparison
bool
ci_is_equal(
core::string_view s0,
core::string_view s1) noexcept;Return true if s0 is less than s1 using case-insensitive comparison
Declared in <boost/url/grammar/ci_string.hpp>
bool
ci_is_less(
core::string_view s0,
core::string_view s1) noexcept;
The comparison algorithm implements a case-insensitive total order on the set of all strings; however, it is not a lexicographical comparison. The function is defined only for strings containing low-ASCII characters.
assert( ! ci_is_less( "Boost", "boost" ) );
A case-insensitive hash function object for strings
The hash function is non-cryptographic and not hardened against algorithmic complexity attacks. This is a suitable hash function for unordered containers. The function is defined only for strings containing low-ASCII characters.
boost::unordered_map< std::string, std::string, ci_hash, ci_equal > m1;
std::unordered_map < std::string, std::string, ci_hash, ci_equal > m2; // (since C++20)
A case-insensitive equals predicate for strings
The function object returns `true` when two strings are equal, ignoring case. This is a suitable equality predicate for unordered containers. The function is defined only for strings containing low-ASCII characters.
boost::unordered_map< std::string, std::string, ci_hash, ci_equal > m1;
std::unordered_map < std::string, std::string, ci_hash, ci_equal > m2; // (since C++20)
A case-insensitive less predicate for strings
The comparison algorithm implements a case-insensitive total order on the set of all ASCII strings; however, it is not a lexicographical comparison. This is a suitable predicate for ordered containers. The function is defined only for strings containing low-ASCII characters.
boost::container::map< std::string, std::string, ci_less > m1;
std::map< std::string, std::string, ci_less > m2; // (since C++14)
Match a decimal octet
Declared in <boost/url/grammar/dec_octet_rule.hpp>
constexpr
_implementation-defined_ dec_octet_rule = {};
A decimal octet is precise way of saying a number from 0 to 255. These are commonly used in IPv4 addresses.
using value_type = unsigned char;
parse .
system::result< unsigned char > rv = parse( "255", dec_octet_rule );
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
Error codes returned when using rules
| Name | Description |
|---|---|
| need_more | More input is needed to match the rule |
| mismatch | The rule did not match the input. |
| end_of_range | A rule reached the end of a range |
| leftover | Leftover input remaining after match. |
| invalid | A rule encountered unrecoverable invalid input. |
| out_of_range | An integer overflowed during parsing. |
| syntax | An unspecified syntax error was found. |
More input is needed to match the rule
A rule reached the end of the input, resulting in a partial match. The error is recoverable; the caller may obtain more input if possible and attempt to parse the character buffer again. Custom rules should only return this error if it is completely unambiguous that the rule cannot be matched without more input.
The rule did not match the input.
This error is returned when a rule fails to match the input. The error is recoverable; the caller may rewind the input pointer and attempt to parse again using a different rule.
A rule reached the end of a range
This indicates that the input was consumed when parsing a range . The range_rule avoids rewinding the input buffer when this error is returned. Thus the consumed characters are be considered part of the range without contributing additional elements.
Leftover input remaining after match.
A rule encountered unrecoverable invalid input.
This error is returned when input is matching but one of the requirements is violated. For example if a percent escape is found, but one or both characters that follow are not valid hexadecimal digits. This is usually an unrecoverable error.
An integer overflowed during parsing.
An unspecified syntax error was found.
Error conditions for errors received from rules
| Name | Description |
|---|---|
| fatal | A fatal error in syntax was encountered. |
A fatal error in syntax was encountered.
This indicates that parsing cannot continue.
Determine if T meets the requirements of Rule
This is an alias for `std::true_type` if `T` meets the requirements, otherwise it is an alias for `std::false_type`.
struct U
{
struct value_type;
auto
parse(
char const*& it,
char const* end) const ->
system::result
};
static_assert( is_rule::value, "Requirements not met" );
Match a character literal
constexpr
_implementation-defined_
delim_rule(char ch) noexcept;Match a single character from a character set
template
constexpr
_implementation-defined_
delim_rule(CharSet const& cs) noexcept; The set of decimal digits
Declared in <boost/url/grammar/digit_chars.hpp>
constexpr
_implementation-defined_ digit_chars = {};
functions find_if and find_if_not .
system::result< core::string_view > rv = parse( "2022", token_rule( digit_chars ) );
DIGIT = %x30-39
; 0-9
The set of hexadecimal digits
Declared in <boost/url/grammar/hexdig_chars.hpp>
constexpr
_implementation-defined_ hexdig_chars = {};
functions find_if and find_if_not .
system::result< core::string_view > rv = parse( "8086FC19", token_rule( hexdig_chars ) );
HEXDIG = DIGIT
/ "A" / "B" / "C" / "D" / "E" / "F"
/ "a" / "b" / "c" / "d" / "e" / "f"
The RFCs are inconsistent on the case sensitivity of hexadecimal digits. Existing uses suggest case-insensitivity is a de-facto standard.
Return the decimal value of a hex character
Declared in <boost/url/grammar/hexdig_chars.hpp>
signed char
hexdig_value(char ch) noexcept;
This function returns the decimal value of a hexadecimal character, or -1 if the argument is not a valid hexadecimal digit.
HEXDIG = DIGIT
/ "A" / "B" / "C" / "D" / "E" / "F"
/ "a" / "b" / "c" / "d" / "e" / "f"
| Name | Description |
|---|---|
| ch |
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| literal_rule [constructor] | |
| parse |
Declared in <boost/url/grammar/literal_rule.hpp>
constexpr
literal_rule(char const* s) noexcept;
Declared in <boost/url/grammar/literal_rule.hpp>
system::result<value_type>
parse(
char const*& it,
char const* end) const noexcept;
A set of characters
| Name | Description |
|---|---|
| lut_chars [constructor] |
Constructor |
| operator() |
Return true if ch is in the character set. |
| operator~ |
Return a new character set which is the complement of another character set. |
The characters defined by instances of this set are provided upon construction. The `constexpr` implementation allows these to become compile-time constants.
functions find_if and find_if_not .
constexpr lut_chars vowel_chars = "AEIOU" "aeiou";
system::result< core::string_view > rv = parse( "Aiea", token_rule( vowel_chars ) );
find_if , find_if_not , parse , token_rule .
Constructor
constexpr
lut_chars(char ch) noexcept;Constructor
constexpr
lut_chars(char const* s) noexcept;template<
class Pred,
class = void>
constexpr
lut_chars(Pred const& pred) noexcept;Return true if ch is in the character set.
constexpr
bool
operator()(unsigned char ch) const noexcept;Return true if ch is in the character set.
constexpr
bool
operator()(char ch) const noexcept;Return the union of two character sets.
Declared in <boost/url/grammar/lut_chars.hpp>
friend
constexpr
lut_chars
operator+(
lut_chars const& cs0,
lut_chars const& cs1) noexcept;
This function returns a new character set which contains all of the characters in `cs0` as well as all of the characters in `cs`.
includes all letters and numbers
constexpr lut_chars alpha_chars(
"ABCDEFGHIJKLMNOPQRSTUVWXYZ"
"abcdefghijklmnopqrstuvwxyz");
constexpr lut_chars alnum_chars = alpha_chars + "0123456789";
Return a new character set by subtracting
Declared in <boost/url/grammar/lut_chars.hpp>
friend
constexpr
lut_chars
operator-(
lut_chars const& cs0,
lut_chars const& cs1) noexcept;
This function returns a new character set which is formed from all of the characters in `cs0` which are not in `cs`.
containing all the lowercase letters which are not vowels:
constexpr lut_chars consonants = lut_chars("abcdefghijklmnopqrstuvwxyz") - "aeiou";
Return a new character set which is the complement of another character set.
Declared in <boost/url/grammar/lut_chars.hpp>
constexpr
lut_chars
operator~() const noexcept;
This function returns a new character set which contains all of the characters that are not in `*this`.
containing everything but vowels:
constexpr lut_chars not_vowels = ~lut_chars( "AEIOU" "aeiou" );
Return the union of two character sets.
Declared in <boost/url/grammar/lut_chars.hpp>
constexpr
lut_chars
operator+(
lut_chars const& cs0,
lut_chars const& cs1) noexcept;
This function returns a new character set which contains all of the characters in `cs0` as well as all of the characters in `cs`.
includes all letters and numbers
constexpr lut_chars alpha_chars(
"ABCDEFGHIJKLMNOPQRSTUVWXYZ"
"abcdefghijklmnopqrstuvwxyz");
constexpr lut_chars alnum_chars = alpha_chars + "0123456789";
| Name | Description |
|---|---|
| cs0 | |
| cs1 |
Return a new character set by subtracting
Declared in <boost/url/grammar/lut_chars.hpp>
constexpr
lut_chars
operator-(
lut_chars const& cs0,
lut_chars const& cs1) noexcept;
This function returns a new character set which is formed from all of the characters in `cs0` which are not in `cs`.
containing all the lowercase letters which are not vowels:
constexpr lut_chars consonants = lut_chars("abcdefghijklmnopqrstuvwxyz") - "aeiou";
| Name | Description |
|---|---|
| cs0 | |
| cs1 |
Match another rule, if the result is not empty
Declared in <boost/url/grammar/not_empty_rule.hpp>
template
constexpr
_implementation-defined_
not_empty_rule(Rule const& r);
This adapts another rule such that when an empty string is successfully parsed, the result is an error.
using value_type = typename Rule::value_type;
parse .
system::result< decode_view > rv = parse( "Program%20Files",
not_empty_rule( pct_encoded_rule( unreserved_chars ) ) );
| Name | Description |
|---|---|
| r |
Parse a character buffer using a rule
template
system::result
parse(
char const*& it,
char const* end,
Rule const& r); Parse a character buffer using a rule
template
system::result
parse(
core::string_view s,
Rule const& r); Match a rule, or the empty string
Declared in <boost/url/grammar/optional_rule.hpp>
template
constexpr
_implementation-defined_
optional_rule(Rule const& r);
Optional BNF elements are denoted with square brackets. If the specified rule returns any error it is treated as if the rule did not match.
using value_type = optional< typename Rule::value_type >;
system::result< optional< core::string_view > > rv = parse( "", optional_rule( token_rule( alpha_chars ) ) );
optional = [ rule ]
| Name | Description |
|---|---|
| r |
A forward range of parsed elements
| Name | Description |
|---|---|
| const_iterator |
A constant, forward iterator to elements of the range |
| const_reference |
The type of each element of the range |
| difference_type |
The type used to represent signed integers |
| iterator |
A constant, forward iterator to elements of the range |
| pointer |
Provided for compatibility, unused |
| reference |
The type of each element of the range |
| size_type |
The type used to represent unsigned integers |
| value_type |
The type of each element of the range |
| Name | Description |
|---|---|
| begin |
Return an iterator to the beginning |
| empty |
Return true if the range is empty |
| end |
Return an iterator to the end |
| operator= |
Assignment |
| range [constructor] |
Constructor |
| size |
Return the number of elements in the range |
| string |
Return the matching part of the string |
| ~range [destructor] |
Destructor |
Objects of this type are forward ranges returned when parsing using the range_rule . Iteration is performed by re-parsing the underlying character buffer. Ownership of the buffer is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced by the range.
The implementation may use temporary, recycled storage for type-erasure. Objects of type `range` are intended to be used ephemerally. That is, for short durations such as within a function scope. If it is necessary to store the range for a long period of time or with static storage duration, it is necessary to copy the contents to an object of a different type.
parse , range_rule .
The type of each element of the range
The type of each element of the range
The type of each element of the range
Provided for compatibility, unused
The type used to represent unsigned integers
The type used to represent signed integers
A constant, forward iterator to elements of the range
| Name | Description |
|---|---|
| difference_type | |
| iterator_category | |
| pointer | |
| reference | |
| value_type |
| Name | Description |
|---|---|
| iterator [constructor] | |
| operator!= | |
| operator* | |
| operator++ | |
| operator= | |
| operator== |
Declared in <boost/url/grammar/impl/range_rule.hpp>
using difference_type = std::ptrdiff_t;
Declared in <boost/url/grammar/impl/range_rule.hpp>
using iterator_category = std::forward_iterator_tag;
iterator() = default;iterator(iterator const&) = default;
Declared in <boost/url/grammar/impl/range_rule.hpp>
iterator&
operator=(iterator const&) = default;
Declared in <boost/url/grammar/impl/range_rule.hpp>
bool
operator==(iterator const& other) const noexcept;
Declared in <boost/url/grammar/impl/range_rule.hpp>
bool
operator!=(iterator const& other) const noexcept;
iterator&
operator++() noexcept;iterator
operator++(int) noexcept;A constant, forward iterator to elements of the range
Destructor
Constructor
range() noexcept;Constructor
range(range&& other) noexcept;Constructor
range(range const& other) noexcept;Assignment
range&
operator=(range&& other) noexcept;Assignment
range&
operator=(range const& other) noexcept;Return an iterator to the beginning
Return an iterator to the end
Return true if the range is empty
Return the number of elements in the range
Return the matching part of the string
Match a repeating number of elements
template
constexpr
_implementation-defined_
range_rule(
Rule const& next,
std::size_t N = 0,
std::size_t M = std::size_t(-1)) noexcept; Match a repeating number of elements
template<
class Rule1,
class Rule2>
constexpr
_implementation-defined_
range_rule(
Rule1 const& first,
Rule2 const& next,
std::size_t N = 0,
std::size_t M = std::size_t(-1)) noexcept;Provides an aligned storage buffer aligned for T
template
struct aligned_storage
{
/// Return a pointer to the aligned storage area
void* addr() noexcept;
/// Return a pointer to the aligned storage area
void const* addr() const noexcept;
};
A thread-safe collection of instances of T
Instances of this type may be used to control where recycled instances of T come from when used with recycled_ptr .
static recycled< std::string > bin;
recycled_ptr< std::string > ps( bin );
// Put the string into a known state
ps->clear();
Destructor
All recycled instances of T are destroyed. Undefined behavior results if there are any recycled_ptr which reference this recycle bin.
Constructor
A pointer to a shared instance of T
| Name | Description |
|---|---|
| acquire |
Return the referenced object |
| bin |
Return the referenced recycle bin |
| empty |
Return true if this does not reference an object |
| get |
Return the referenced object |
| operator bool |
Return true if this references an object |
| operator* |
Return the referenced object |
| operator-> |
Return the referenced object |
| operator= |
Assignment |
| recycled_ptr [constructor] |
Constructor |
| release |
Release the referenced object |
| ~recycled_ptr [destructor] |
Destructor |
This is a smart pointer container which can acquire shared ownership of an instance of `T` upon or after construction. The instance is guaranteed to be in a valid, but unknown state. Every recycled pointer references a valid recycle bin.
static recycled< std::string > bin;
recycled_ptr< std::string > ps( bin );
// Put the string into a known state
ps->clear();
Destructor
If this is not empty, shared ownership of the pointee is released. If this was the last reference, the object is returned to the original recycle bin.
this->release();
Constructor
recycled_ptr(recycled& bin); Constructor
recycled_ptr(
recycled& bin,
std::nullptr_t) noexcept; Constructor
recycled_ptr();Constructor
recycled_ptr(std::nullptr_t) noexcept;Constructor
recycled_ptr(recycled_ptr const& other) noexcept;Constructor
recycled_ptr(recycled_ptr&& other) noexcept;Assignment
recycled_ptr&
operator=(recycled_ptr&& other) noexcept;Assignment
recycled_ptr&
operator=(recycled_ptr const& other) noexcept;Return true if this does not reference an object
Return true if this references an object
return ! this->empty();
Return the referenced recycle bin
Return the referenced object
If this is empty, `nullptr` is returned.
Return the referenced object
If this is empty, `nullptr` is returned.
Return the referenced object
not this->empty()
Return the referenced object
If this references an object, it is returned. Otherwise, exclusive ownership of a new object of type `T` is acquired and returned.
not this->empty()
Release the referenced object
If this references an object, it is released to the referenced recycle bin. The pointer continues to reference the same recycle bin.
this->empty()
Declared in <boost/url/grammar/string_token.hpp>
namespace string_token = boost::urls::string_token
;
Common functionality for string views
| Name | Description |
|---|---|
| const_iterator |
The const iterator type |
| const_pointer |
The const pointer type |
| const_reference |
The const reference type |
| const_reverse_iterator |
The const reverse iterator type |
| difference_type |
The difference type |
| iterator |
The iterator type |
| pointer |
The pointer type |
| reference |
The reference type |
| reverse_iterator |
The reverse iterator type |
| size_type |
The size type |
| traits_type |
The character traits |
| value_type |
The value type |
| Name | Description |
|---|---|
| at |
Access a character |
| back |
Return the last character |
| begin |
Return an iterator to the beginning |
| cbegin |
Return an iterator to the beginning |
| cend |
Return an iterator to the end |
| compare |
Return the result of comparing to another string |
| contains |
Return true if matching characters are found |
| copy |
Copy the characters to another buffer |
| crbegin |
Return a reverse iterator to the end |
| crend |
Return a reverse iterator to the beginning |
| data |
Return a pointer to the character buffer |
| empty |
Return true if the string is empty |
| end |
Return an iterator to the end |
| ends_with |
Return true if a matching suffix exists |
| find |
Return the position of matching characters |
| find_first_not_of |
Return the position of the first non-match |
| find_first_of |
Return the position of the first match |
| find_last_not_of |
Return the position of the last non-match |
| find_last_of |
Return the position of the last match |
| front |
Return the first character |
| length |
Return the size |
| max_size |
Return the maximum allowed size |
| operator std::string |
Conversion |
| operator core::string_view |
Conversion |
| operator[] |
Access a character |
| rbegin |
Return a reverse iterator to the end |
| rend |
Return a reverse iterator to the beginning |
| rfind |
Return the position of matching characters |
| size |
Return the size |
| starts_with |
Return true if a matching prefix exists |
| substr |
Return a view to part of the string |
| Name | Description |
|---|---|
| npos |
A constant used to represent "no position" |
| Name | Description |
|---|---|
| operator!= |
Compare two string views for inequality |
| operator< |
Compare two string views for less than |
| operator<< |
Format a string to an output stream |
| operator<= |
Compare two string views for less than or equal |
| operator== |
Compare two string views for equality |
| operator> |
Compare two string views for greater than |
| operator>= |
Compare two string views for greater than or equal |
This base class is used to provide common member functions for reference types that behave like string views. This cannot be instantiated directly; Instead, derive from the type and provide constructors which offer any desired preconditions and invariants.
The character traits
The value type
The pointer type
The const pointer type
The reference type
The const reference type
The const iterator type
The iterator type
The const reverse iterator type
Declared in <boost/url/grammar/string_view_base.hpp>
typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
The reverse iterator type
Declared in <boost/url/grammar/string_view_base.hpp>
typedef const_reverse_iterator reverse_iterator;
The size type
The difference type
Declared in <boost/url/grammar/string_view_base.hpp>
typedef std::ptrdiff_t difference_type;
A constant used to represent "no position"
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
static
std::size_t const npos = core::string_view::npos;
Conversion
Declared in <boost/url/grammar/string_view_base.hpp>
operator core::string_view() const noexcept;
Conversion
Declared in <boost/url/grammar/string_view_base.hpp>
operator std::string() const noexcept;
Conversion to std::string is explicit because assigning to string using an implicit constructor does not preserve capacity.
Return an iterator to the beginning
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_iterator
begin() const noexcept;
See `core::string_view::begin`
Return an iterator to the end
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_iterator
end() const noexcept;
See `core::string_view::end`
Return an iterator to the beginning
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_iterator
cbegin() const noexcept;
See `core::string_view::cbegin`
Return an iterator to the end
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_iterator
cend() const noexcept;
See `core::string_view::cend`
Return a reverse iterator to the end
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_reverse_iterator
rbegin() const noexcept;
See `core::string_view::rbegin`
Return a reverse iterator to the beginning
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_reverse_iterator
rend() const noexcept;
See `core::string_view::rend`
Return a reverse iterator to the end
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_reverse_iterator
crbegin() const noexcept;
See `core::string_view::crbegin`
Return a reverse iterator to the beginning
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_reverse_iterator
crend() const noexcept;
See `core::string_view::crend`
Return the size
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
size() const noexcept;
See `core::string_view::size`
Return the size
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
length() const noexcept;
See `core::string_view::length`
Return the maximum allowed size
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
max_size() const noexcept;
See `core::string_view::max_size`
Return true if the string is empty
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
empty() const noexcept;
See `core::string_view::size`
Access a character
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_reference
operator[](size_type pos) const noexcept;
See `core::string_view::operator[]`
Access a character
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_reference
at(size_type pos) const;
See `core::string_view::at`
Return the first character
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_reference
front() const noexcept;
See `core::string_view::front`
Return the last character
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_reference
back() const noexcept;
See `core::string_view::back`
Return a pointer to the character buffer
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_pointer
data() const noexcept;
See `core::string_view::data`
Copy the characters to another buffer
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
copy(
char* s,
size_type n,
size_type pos = 0) const;
See `core::string_view::copy`
Return a view to part of the string
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
core::string_view
substr(
size_type pos = 0,
size_type n = core::string_view::npos) const;
See `core::string_view::substr`
Return the result of comparing to another string
constexpr
int
compare(core::string_view str) const noexcept;Return the result of comparing to another string
constexpr
int
compare(
size_type pos1,
size_type n1,
core::string_view str) const;Return the result of comparing to another string
constexpr
int
compare(
size_type pos1,
size_type n1,
core::string_view str,
size_type pos2,
size_type n2) const;Return the result of comparing to another string
constexpr
int
compare(char const* s) const noexcept;Return the result of comparing to another string
constexpr
int
compare(
size_type pos1,
size_type n1,
char const* s) const;Return the result of comparing to another string
constexpr
int
compare(
size_type pos1,
size_type n1,
char const* s,
size_type n2) const;Return true if a matching prefix exists
constexpr
bool
starts_with(core::string_view x) const noexcept;Return true if a matching prefix exists
constexpr
bool
starts_with(char x) const noexcept;Return true if a matching prefix exists
constexpr
bool
starts_with(char const* x) const noexcept;Return true if a matching suffix exists
constexpr
bool
ends_with(core::string_view x) const noexcept;Return true if a matching suffix exists
constexpr
bool
ends_with(char x) const noexcept;Return true if a matching suffix exists
constexpr
bool
ends_with(char const* x) const noexcept;Return the position of matching characters
constexpr
size_type
find(
core::string_view str,
size_type pos = 0) const noexcept;Return the position of matching characters
constexpr
size_type
find(
char c,
size_type pos = 0) const noexcept;Return the position of matching characters
constexpr
size_type
find(
char const* s,
size_type pos,
size_type n) const noexcept;Return the position of matching characters
constexpr
size_type
find(
char const* s,
size_type pos = 0) const noexcept;Return the position of matching characters
constexpr
size_type
rfind(
core::string_view str,
size_type pos = core::string_view::npos) const noexcept;Return the position of matching characters
constexpr
size_type
rfind(
char c,
size_type pos = core::string_view::npos) const noexcept;Return the position of matching characters
constexpr
size_type
rfind(
char const* s,
size_type pos,
size_type n) const noexcept;Return the position of matching characters
constexpr
size_type
rfind(
char const* s,
size_type pos = core::string_view::npos) const noexcept;Return the position of the first match
constexpr
size_type
find_first_of(
core::string_view str,
size_type pos = 0) const noexcept;Return the position of the first match
constexpr
size_type
find_first_of(
char c,
size_type pos = 0) const noexcept;Return the position of the first match
constexpr
size_type
find_first_of(
char const* s,
size_type pos,
size_type n) const noexcept;Return the position of the first match
constexpr
size_type
find_first_of(
char const* s,
size_type pos = 0) const noexcept;Return the position of the last match
constexpr
size_type
find_last_of(
core::string_view str,
size_type pos = core::string_view::npos) const noexcept;Return the position of the last match
constexpr
size_type
find_last_of(
char c,
size_type pos = core::string_view::npos) const noexcept;Return the position of the last match
constexpr
size_type
find_last_of(
char const* s,
size_type pos,
size_type n) const noexcept;Return the position of the last match
constexpr
size_type
find_last_of(
char const* s,
size_type pos = core::string_view::npos) const noexcept;Return the position of the first non-match
constexpr
size_type
find_first_not_of(
core::string_view str,
size_type pos = 0) const noexcept;Return the position of the first non-match
constexpr
size_type
find_first_not_of(
char c,
size_type pos = 0) const noexcept;Return the position of the first non-match
constexpr
size_type
find_first_not_of(
char const* s,
size_type pos,
size_type n) const noexcept;Return the position of the first non-match
constexpr
size_type
find_first_not_of(
char const* s,
size_type pos = 0) const noexcept;Return the position of the last non-match
constexpr
size_type
find_last_not_of(
core::string_view str,
size_type pos = core::string_view::npos) const noexcept;Return the position of the last non-match
constexpr
size_type
find_last_not_of(
char c,
size_type pos = core::string_view::npos) const noexcept;Return the position of the last non-match
constexpr
size_type
find_last_not_of(
char const* s,
size_type pos,
size_type n) const noexcept;Return the position of the last non-match
constexpr
size_type
find_last_not_of(
char const* s,
size_type pos = core::string_view::npos) const noexcept;Return true if matching characters are found
constexpr
bool
contains(core::string_view sv) const noexcept;Return true if matching characters are found
constexpr
bool
contains(char c) const noexcept;Return true if matching characters are found
constexpr
bool
contains(char const* s) const noexcept;Compare two string views for equality
Declared in <boost/url/grammar/string_view_base.hpp>
template<
class S0,
class S1>
friend
constexpr
bool
operator==(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both arguments are convertible to `core::string_view` and at least one of the arguments is derived from `string_view_base`.
Compare two string views for inequality
Declared in <boost/url/grammar/string_view_base.hpp>
template<
class S0,
class S1>
friend
constexpr
bool
operator!=(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both arguments are convertible to `core::string_view` and at least one of the arguments is derived from `string_view_base`.
Compare two string views for less than
Declared in <boost/url/grammar/string_view_base.hpp>
template<
class S0,
class S1>
friend
constexpr
bool
operator<(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both arguments are convertible to `core::string_view` and at least one of the arguments is derived from `string_view_base`.
Compare two string views for less than or equal
Declared in <boost/url/grammar/string_view_base.hpp>
template<
class S0,
class S1>
friend
constexpr
bool
operator<=(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both arguments are convertible to `core::string_view` and at least one of the arguments is derived from `string_view_base`.
Compare two string views for greater than
Declared in <boost/url/grammar/string_view_base.hpp>
template<
class S0,
class S1>
friend
constexpr
bool
operator>(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both arguments are convertible to `core::string_view` and at least one of the arguments is derived from `string_view_base`.
Compare two string views for greater than or equal
Declared in <boost/url/grammar/string_view_base.hpp>
template<
class S0,
class S1>
friend
constexpr
bool
operator>=(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both arguments are convertible to `core::string_view` and at least one of the arguments is derived from `string_view_base`.
Format a string to an output stream
Declared in <boost/url/grammar/string_view_base.hpp>
friend
std::ostream&
operator<<(
std::ostream& os,
string_view_base const& s);
Compare two string views for equality
Declared in <boost/url/grammar/string_view_base.hpp>
template<
class S0,
class S1>
constexpr
bool
operator==(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both arguments are convertible to `core::string_view` and at least one of the arguments is derived from `string_view_base`.
Compare two string views for inequality
Declared in <boost/url/grammar/string_view_base.hpp>
template<
class S0,
class S1>
constexpr
bool
operator!=(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both arguments are convertible to `core::string_view` and at least one of the arguments is derived from `string_view_base`.
Compare two string views for less than
Declared in <boost/url/grammar/string_view_base.hpp>
template<
class S0,
class S1>
constexpr
bool
operator<(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both arguments are convertible to `core::string_view` and at least one of the arguments is derived from `string_view_base`.
Compare two string views for less than or equal
Declared in <boost/url/grammar/string_view_base.hpp>
template<
class S0,
class S1>
constexpr
bool
operator<=(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both arguments are convertible to `core::string_view` and at least one of the arguments is derived from `string_view_base`.
Compare two string views for greater than
Declared in <boost/url/grammar/string_view_base.hpp>
template<
class S0,
class S1>
constexpr
bool
operator>(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both arguments are convertible to `core::string_view` and at least one of the arguments is derived from `string_view_base`.
Compare two string views for greater than or equal
Declared in <boost/url/grammar/string_view_base.hpp>
template<
class S0,
class S1>
constexpr
bool
operator>=(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both arguments are convertible to `core::string_view` and at least one of the arguments is derived from `string_view_base`.
Format a string to an output stream
Declared in <boost/url/grammar/string_view_base.hpp>
std::ostream&
operator<<(
std::ostream& os,
string_view_base const& s);
Match a non-empty string of characters from a set
Declared in <boost/url/grammar/token_rule.hpp>
template
constexpr
_implementation-defined_
token_rule(CharSet const& cs) noexcept;
If there is no more input, the error code error::need_more is returned.
using value_type = core::string_view;
parse .
system::result< core::string_view > rv = parse( "abcdef", token_rule( alpha_chars ) );
token = 1*( ch )
| Name | Description |
|---|---|
| cs |
Match a series of rules in order
Declared in <boost/url/grammar/tuple_rule.hpp>
template<
class R0,
class... Rn>
constexpr
_implementation-defined_
tuple_rule(
R0 const& r0,
Rn const&... rn) noexcept;
This matches a series of rules in the order specified. Upon success the input is adjusted to point to the first unconsumed character. There is no implicit specification of linear white space between each rule.
using value_type = __see_below__;
The sequence rule usually returns a `std::tuple` containing the the `value_type`
of each corresponding rule in the sequence,
except that `void` values are removed.
However, if there is exactly one non-void
value type `T`, then the sequence rule
returns `system::result
parse .
system::result< std::tuple< unsigned char, unsigned char, unsigned char, unsigned char > > rv =
parse( "192.168.0.1",
tuple_rule(
dec_octet_rule,
squelch( delim_rule('.') ),
dec_octet_rule,
squelch( delim_rule('.') ),
dec_octet_rule,
squelch( delim_rule('.') ),
dec_octet_rule ) );
sequence = rule1 rule2 rule3...
| Name | Description |
|---|---|
| rn |
Squelch the value of a rule
Declared in <boost/url/grammar/tuple_rule.hpp>
template
constexpr
_implementation-defined_
squelch(Rule const& r) noexcept;
This function returns a new rule which matches the specified rule, and converts its value type to `void`. This is useful for matching delimiters in a grammar, where the value for the delimiter is not needed.
using value_type = void;
system::result< std::tuple< decode_view, core::string_view > > rv = parse(
"www.example.com:443",
tuple_rule(
pct_encoded_rule(unreserved_chars + '-' + '.'),
squelch( delim_rule( ':' ) ),
token_rule( digit_chars ) ) );
system::result< std::tuple< decode_view, core::string_view, core::string_view > > rv = parse(
"www.example.com:443",
tuple_rule(
pct_encoded_rule(unreserved_chars + '-' + '.'),
delim_rule( ':' ),
token_rule( digit_chars ) ) );
| Name | Description |
|---|---|
| r |
Match an unsigned decimal
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| parse |
Extra leading zeroes are disallowed.
using value_type = Unsigned;
parse .
system::result< unsigned short > rv = parse( "32767", unsigned_rule< unsigned short >{} );
unsigned = "0" / ( ["1"..."9"] *DIGIT )
Declared in <boost/url/grammar/unsigned_rule.hpp>
system::result<value_type>
parse(
char const*& it,
char const* end) const noexcept;
Match one of a set of rules
Declared in <boost/url/grammar/variant_rule.hpp>
template<
class R0,
class... Rn>
constexpr
_implementation-defined_
variant_rule(
R0 const& r0,
Rn const&... rn) noexcept;
Each specified rule is tried in sequence. When the first match occurs, the result is stored and returned in the variant. If no match occurs, an error is returned.
using value_type = variant< typename Rules::value_type... >;
parse .
// request-target = origin-form
// / absolute-form
// / authority-form
// / asterisk-form
system::result< variant< url_view, url_view, authority_view, core::string_view > > rv = grammar::parse(
"/index.html?width=full",
variant_rule(
origin_form_rule,
absolute_uri_rule,
authority_rule,
delim_rule('*') ) );
variant = rule1 / rule2 / rule3...
The set of visible characters
functions find_if and find_if_not .
system::result< core::string_view > rv = parse( "JohnDoe", token_rule( vchars ) );
VCHAR = 0x21-0x7E
; visible (printing) characters
The set of all characters
Declared in <boost/url/grammar/all_chars.hpp>
constexpr
_implementation-defined_ all_chars = all_chars{};
functions find_if and find_if_not .
system::result< core::string_view > rv = parse( "JohnDoe", token_rule( all_chars ) );
ALL = %x00-FF
| Name | Description |
|---|---|
| error_category |
The type of error category used by the library |
| error_code |
The type of error code used by the library |
| error_condition |
The type of error condition used by the library |
| result |
The type of result returned by library functions |
| system_error |
The type of system error thrown by the library |
The type of error category used by the library
Declared in <boost/url/error_types.hpp>
using error_category = boost::system::error_category;
This alias is no longer supported and should not be used in new code. Please use `system::error_category` instead.
This alias is included for backwards compatibility with earlier versions of the library.
However, it will be removed in future releases, and using it in new code is not recommended.
Please use the updated version instead to ensure compatibility with future versions of the library.
The type of error code used by the library
This alias is no longer supported and should not be used in new code. Please use `system::error_code` instead.
This alias is included for backwards compatibility with earlier versions of the library.
However, it will be removed in future releases, and using it in new code is not recommended.
Please use the updated version instead to ensure compatibility with future versions of the library.
The type of error condition used by the library
Declared in <boost/url/error_types.hpp>
using error_condition = boost::system::error_condition;
This alias is no longer supported and should not be used in new code. Please use `system::error_condition` instead.
This alias is included for backwards compatibility with earlier versions of the library.
However, it will be removed in future releases, and using it in new code is not recommended.
Please use the updated version instead to ensure compatibility with future versions of the library.
The type of system error thrown by the library
This alias is no longer supported and should not be used in new code. Please use `system::system_error` instead.
This alias is included for backwards compatibility with earlier versions of the library.
However, it will be removed in future releases, and using it in new code is not recommended.
Please use the updated version instead to ensure compatibility with future versions of the library.
A function to return the generic error category used by the library
This alias is no longer supported and should not be used in new code. Please use `core::string_view` instead.
This alias is included for backwards compatibility with earlier versions of the library.
However, it will be removed in future releases, and using it in new code is not recommended.
Please use the updated version instead to ensure compatibility with future versions of the library.
| Name |
|---|
A function to return the system error category used by the library
This alias is no longer supported and should not be used in new code. Please use `core::string_view` instead.
This alias is included for backwards compatibility with earlier versions of the library.
However, it will be removed in future releases, and using it in new code is not recommended.
Please use the updated version instead to ensure compatibility with future versions of the library.
| Name |
|---|
The set of constants used for cross-platform error codes
This alias is no longer supported and should not be used in new code. Please use `core::string_view` instead.
This alias is included for backwards compatibility with earlier versions of the library.
However, it will be removed in future releases, and using it in new code is not recommended.
Please use the updated version instead to ensure compatibility with future versions of the library.
The type of result returned by library functions
This alias is no longer supported and should not be used in new code. Please use `system::result` instead.
This alias is included for backwards compatibility with earlier versions of the library.
However, it will be removed in future releases, and using it in new code is not recommended.
Please use the updated version instead to ensure compatibility with future versions of the library.
This is an alias template used as the return type for functions that can either return a container, or fail with an error code. This is a brief synopsis of the type:
template< class T >
class result
{
public:
//
// Return true if the result contains an error
//
constexpr bool has_error() const noexcept;
//
// Return the error
//
constexpr system::error_code error() const noexcept;
//
// Return true if the result contains a value
//
constexpr bool has_value() const noexcept;
constexpr explicit operator bool() const noexcept;
//
// Return the value, or throw an exception
//
constexpr T& value();
constexpr T const& value() const;
// Return the value.
// Precondition: has_value()==true
//
constexpr T& operator*() noexcept;
constexpr T* operator->() noexcept;
constexpr T const& operator*() const noexcept;
constexpr T const* operator->() const noexcept;
...more
parse_uri with this signature:
system::result< url_view > parse_uri( core::string_view s ) noexcept;
The following statement captures the value in a variable upon success, otherwise throws:
url_view u = parse_uri( "http://example.com/path/to/file.txt" ).value();
This statement captures the result in a local variable and inspects the error condition:
system::result< url_view > rv = parse_uri( "http://example.com/path/to/file.txt" );
if(! rv )
std::cout << rv.error();
else
std::cout << *rv;
The type of optional used by the library
This alias is no longer supported and should not be used in new code. Please use `boost::optional` instead.
This alias is included for backwards compatibility with earlier versions of the library.
However, it will be removed in future releases, and using it in new code is not recommended.
Please use the updated version instead to ensure compatibility with future versions of the library.
Error codes returned the library
| Name | Description |
|---|---|
| success | The operation completed successfully. |
| illegal_null | Null encountered in pct-encoded. |
| illegal_reserved_char | Illegal reserved character in encoded string. |
| non_canonical | A grammar element was not in canonical form. |
| bad_pct_hexdig | Bad hexadecimal digit. |
| incomplete_encoding | The percent-encoded sequence is incomplete. |
| missing_pct_hexdig | Missing hexadecimal digit. |
| no_space | No space in output buffer |
| not_a_base | The URL is not a base URL |
The operation completed successfully.
Null encountered in pct-encoded.
Illegal reserved character in encoded string.
A grammar element was not in canonical form.
Bad hexadecimal digit.
This error condition is fatal.
The percent-encoded sequence is incomplete.
This error condition is fatal.
Missing hexadecimal digit.
This error condition is fatal.
No space in output buffer
This error is returned when a provided output buffer was too small to hold the complete result of an algorithm.
The URL is not a base URL
| Name | Description |
|---|---|
| implementation_defined | |
| see_below |
| Name | Description |
|---|---|
| arg |
Base class for string tokens, and algorithm parameters |
| is_token |
Metafunction returning true if T is a StringToken |
| return_string |
A token for returning a plain string |
| Name | Description |
|---|---|
| append_to |
Create a token for appending to a plain string |
| assign_to |
A token for assigning to a plain string |
| preserve_size |
A token for producing a durable core::string_view from a temporary string |
Base class for string tokens, and algorithm parameters
This abstract interface provides a means for an algorithm to generically obtain a modifiable, contiguous character buffer of prescribed size. As the author of an algorithm simply declare an rvalue reference as a parameter type.
Instances of this type are intended only to be used once and then destroyed.
temporary instance of `arg` to be used for writing:
void algorithm( string_token::arg&& dest );
To implement the interface for your type or use-case, derive from the class and implement the prepare function.
Return a modifiable character buffer
This function attempts to obtain a character buffer with space for at least `n` characters. Upon success, a pointer to the beginning of the buffer is returned. Ownership is not transferred; the caller should not attempt to free the storage. The buffer shall remain valid until `this` is destroyed.
This function may only be called once. After invoking the function, the only valid operation is destruction.
Virtual destructor
Default constructor
constexpr
arg() = default;Default move constructor
constexpr
arg(arg&&) = default;Deleted copy constructor
arg(arg const&) = delete;Deleted move assignment
arg&
operator=(arg&&) = delete;Deleted copy assignment
arg&
operator=(arg const&) = delete;| Name | Description |
|---|---|
| is_token |
Metafunction returning true if T is a StringToken |
|
is_token |
Metafunction returning true if T is a StringToken |
Metafunction returning true if T is a StringToken
Declared in <boost/url/grammar/string_token.hpp>
template<
class T,
class = void>
struct is_token
: std::false_type;
Metafunction returning true if T is a StringToken
Declared in <boost/url/grammar/string_token.hpp>
template
struct is_token().prepare(
std::declval())), decltype(std::declval().result())>>
: std::integral_constant().result()), typename T::result_type>::value && std::is_same().prepare(0)), char *>::value && std::is_base_of::value && std::is_convertible::value>;
Metafunction returning true if T is a StringToken
| Name | Description |
|---|---|
| append_to_t | |
| assign_to_t | |
| preserve_size_t | |
| return_string |
| Name | Description |
|---|---|
| result_type |
Declared in <boost/url/grammar/string_token.hpp>
virtual
char*
prepare(std::size_t n) override;
Declared in <boost/url/grammar/string_token.hpp>
_implementation-defined_
result() noexcept;
| Name | Description |
|---|---|
| result_type | |
| string_type |
| Name | Description |
|---|---|
| append_to_t [constructor] | |
| operator= |
Deleted copy assignment Deleted move assignment |
| prepare |
Return a modifiable character buffer |
| result |
Declared in <boost/url/grammar/string_token.hpp>
using string_type = std::basic_string, Alloc>;
Declared in <boost/url/grammar/string_token.hpp>
using result_type = _implementation-defined_&;
Declared in <boost/url/grammar/string_token.hpp>
append_to_t(_implementation-defined_& s) noexcept;
Declared in <boost/url/grammar/string_token.hpp>
virtual
char*
prepare(std::size_t n) override;
Declared in <boost/url/grammar/string_token.hpp>
_implementation-defined_
result() noexcept;
| Name | Description |
|---|---|
| result_type | |
| string_type |
| Name | Description |
|---|---|
| assign_to_t [constructor] | |
| operator= |
Deleted copy assignment Deleted move assignment |
| prepare |
Return a modifiable character buffer |
| result |
Declared in <boost/url/grammar/string_token.hpp>
using string_type = std::basic_string, Alloc>;
Declared in <boost/url/grammar/string_token.hpp>
using result_type = _implementation-defined_&;
Declared in <boost/url/grammar/string_token.hpp>
assign_to_t(_implementation-defined_& s) noexcept;
Declared in <boost/url/grammar/string_token.hpp>
virtual
char*
prepare(std::size_t n) override;
Declared in <boost/url/grammar/string_token.hpp>
_implementation-defined_
result() noexcept;
| Name | Description |
|---|---|
| result_type | |
| string_type |
| Name | Description |
|---|---|
| operator= |
Deleted copy assignment Deleted move assignment |
| prepare |
Return a modifiable character buffer |
| preserve_size_t [constructor] | |
| result |
Declared in <boost/url/grammar/string_token.hpp>
using string_type = std::basic_string, Alloc>;
Declared in <boost/url/grammar/string_token.hpp>
preserve_size_t(_implementation-defined_& s) noexcept;
Declared in <boost/url/grammar/string_token.hpp>
virtual
char*
prepare(std::size_t n) override;
Declared in <boost/url/grammar/string_token.hpp>
_implementation-defined_
result() noexcept;
A token for returning a plain string
Declared in <boost/url/grammar/string_token.hpp>
using return_string = _implementation-defined_;
Create a token for appending to a plain string
Declared in <boost/url/grammar/string_token.hpp>
template>
_implementation-defined_
append_to(std::basic_string, Alloc>& s);
A token for assigning to a plain string
Declared in <boost/url/grammar/string_token.hpp>
template>
_implementation-defined_
assign_to(std::basic_string, Alloc>& s);
A token for producing a durable core::string_view from a temporary string
Declared in <boost/url/grammar/string_token.hpp>
template>
_implementation-defined_
preserve_size(std::basic_string, Alloc>& s);
The type of variant used by the library
This alias is no longer supported and should not be used in new code. Please use `boost::variant2::variant` instead.
This alias is included for backwards compatibility with earlier versions of the library.
However, it will be removed in future releases, and using it in new code is not recommended.
Please use the updated version instead to ensure compatibility with future versions of the library.
Identifies the type of host in a URL.
| Name | Description |
|---|---|
| none | No host is specified. |
| name | A host is specified by reg-name. |
| ipv4 | A host is specified by ipv4_address . |
| ipv6 | A host is specified by ipv6_address . |
| ipvfuture | A host is specified by IPvFuture. |
Values of this type are returned by URL views and containers to indicate the type of host present in a URL.
No host is specified.
A host is specified by reg-name.
A host is specified by ipv4_address .
A host is specified by ipv6_address .
A host is specified by IPvFuture.
An IP version 4 style address.
| Name | Description |
|---|---|
| bytes_type |
The type used to represent an address as an array of bytes |
| uint_type |
The type used to represent an address as an unsigned integer |
| Name | Description |
|---|---|
| ipv4_address [constructor] |
Construct from a string. Construct from an array of bytes. Construct from an unsigned integer. Constructor. |
| is_loopback |
Return true if the address is a loopback address |
| is_multicast |
Return true if the address is a multicast address |
| is_unspecified |
Return true if the address is unspecified |
| operator= |
Copy Assignment. |
| to_buffer |
Write a dotted decimal string representing the address to a buffer |
| to_bytes |
Return the address as bytes, in network byte order. |
| to_string |
Return the address as a string in dotted decimal format |
| to_uint |
Return the address as an unsigned integer. |
| Name | Description |
|---|---|
| any |
Return an address object that represents any address |
| broadcast |
Return an address object that represents the broadcast address |
| loopback |
Return an address object that represents the loopback address |
| Name | Description |
|---|---|
| max_str_len |
The number of characters in the longest possible IPv4 string. |
| Name | Description |
|---|---|
| operator!= |
Return true if two addresses are not equal |
| operator<< |
Format the address to an output stream. |
| operator== |
Return true if two addresses are equal |
Objects of this type are used to construct, parse, and manipulate IP version 6 addresses.
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
The number of characters in the longest possible IPv4 string.
Declared in <boost/url/ipv4_address.hpp>
constexpr
static
std::size_t const max_str_len = 15;
The longest ipv4 address string is "255.255.255.255".
The type used to represent an address as an unsigned integer
The type used to represent an address as an array of bytes
Constructor.
constexpr
ipv4_address() = default;Constructor.
constexpr
ipv4_address(ipv4_address const&) = default;Construct from an unsigned integer.
ipv4_address(uint_type u) noexcept;Construct from an array of bytes.
ipv4_address(bytes_type const& bytes) noexcept;Construct from a string.
ipv4_address(core::string_view s);Copy Assignment.
Declared in <boost/url/ipv4_address.hpp>
constexpr
ipv4_address&
operator=(ipv4_address const&) = default;
Return the address as bytes, in network byte order.
Return the address as an unsigned integer.
Return the address as a string in dotted decimal format
Declared in <boost/url/ipv4_address.hpp>
templatestring_token::return_string>
StringToken::result_type
to_string(StringToken&& token) const;
When called with no arguments, the return type is `std::string`. Otherwise, the return type and style of output is determined by which string token is passed.
assert( ipv4_address(0x01020304).to_string() == "1.2.3.4" );
Calls to allocate may throw. String tokens may throw exceptions.
| Name | Description |
|---|---|
| token |
Write a dotted decimal string representing the address to a buffer
Declared in <boost/url/ipv4_address.hpp>
core::string_view
to_buffer(
char* dest,
std::size_t dest_size) const;
The resulting buffer is not null-terminated.
| Name | Thrown on |
|---|---|
`dest_size |
| Name | Description |
|---|---|
| dest | |
| dest_size |
Return true if the address is a loopback address
Return true if the address is unspecified
Return true if the address is a multicast address
Return true if two addresses are equal
Declared in <boost/url/ipv4_address.hpp>
friend
bool
operator==(
ipv4_address const& a1,
ipv4_address const& a2) noexcept;
Return true if two addresses are not equal
Declared in <boost/url/ipv4_address.hpp>
friend
bool
operator!=(
ipv4_address const& a1,
ipv4_address const& a2) noexcept;
Return an address object that represents any address
Return an address object that represents the loopback address
Return an address object that represents the broadcast address
Format the address to an output stream.
Declared in <boost/url/ipv4_address.hpp>
friend
std::ostream&
operator<<(
std::ostream& os,
ipv4_address const& addr);
IPv4 addresses written to output streams are written in their dotted decimal format.
Return true if two addresses are equal
bool
operator==(
ipv4_address const& a1,
ipv4_address const& a2) noexcept;Return true if two addresses are equal
bool
operator==(
ipv6_address const& a1,
ipv6_address const& a2) noexcept;Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
bool
operator==(
authority_view const& a0,
authority_view const& a1) noexcept;Compare two decode views for equality
template<
class S0,
class S1>
constexpr
bool
operator==(
S0 const& s0,
S1 const& s1) noexcept;bool
operator==(
iterator const& it0,
iterator const& it1) noexcept;Return the result of comparing two URLs
bool
operator==(
url_view_base const& u0,
url_view_base const& u1) noexcept;Return true if two addresses are not equal
bool
operator!=(
ipv4_address const& a1,
ipv4_address const& a2) noexcept;Return true if two addresses are not equal
bool
operator!=(
ipv6_address const& a1,
ipv6_address const& a2) noexcept;Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
bool
operator!=(
authority_view const& a0,
authority_view const& a1) noexcept;Compare two decode views for inequality
template<
class S0,
class S1>
constexpr
bool
operator!=(
S0 const& s0,
S1 const& s1) noexcept;bool
operator!=(
iterator const& it0,
iterator const& it1) noexcept;Return the result of comparing two URLs
bool
operator!=(
url_view_base const& u0,
url_view_base const& u1) noexcept;Format the address to an output stream.
std::ostream&
operator<<(
std::ostream& os,
ipv4_address const& addr);Format the address to an output stream
std::ostream&
operator<<(
std::ostream& os,
ipv6_address const& addr);Format the encoded authority to the output stream
std::ostream&
operator<<(
std::ostream& os,
authority_view const& a);Format the string with percent-decoding applied to the output stream
std::ostream&
operator<<(
std::ostream& os,
decode_view const& s);Format to an output stream
std::ostream&
operator<<(
std::ostream& os,
params_encoded_base const& qp);Format to an output stream
std::ostream&
operator<<(
std::ostream& os,
params_base const& qp);Format to an output stream
std::ostream&
operator<<(
std::ostream& os,
segments_encoded_base const& ps);Format to an output stream
std::ostream&
operator<<(
std::ostream& os,
segments_base const& ps);Format the url to the output stream
std::ostream&
operator<<(
std::ostream& os,
url_view_base const& u);Return an IPv4 address from an IP address string in dotted decimal form
Declared in <boost/url/ipv4_address.hpp>
system::result<ipv4_address>
parse_ipv4_address(core::string_view s) noexcept;
An IP version 6 style address.
| Name | Description |
|---|---|
| bytes_type |
The type used to represent an address as an array of bytes. |
| Name | Description |
|---|---|
| ipv6_address [constructor] |
Construct from a string. Construct from an IPv4 address. Construct from an array of bytes. Constructor. |
| is_loopback |
Return true if the address is a loopback address |
| is_unspecified |
Return true if the address is unspecified |
| is_v4_mapped |
Return true if the address is a mapped IPv4 address |
| operator= |
Copy Assignment |
| to_buffer |
Write a dotted decimal string representing the address to a buffer |
| to_bytes |
Return the address as bytes, in network byte order |
| to_string |
Return the address as a string. |
| Name | Description |
|---|---|
| loopback |
Return an address object that represents the loopback address |
| Name | Description |
|---|---|
| max_str_len |
The number of characters in the longest possible IPv6 string. |
| Name | Description |
|---|---|
| operator!= |
Return true if two addresses are not equal |
| operator<< |
Format the address to an output stream |
| operator== |
Return true if two addresses are equal |
Objects of this type are used to construct, parse, and manipulate IP version 6 addresses.
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
The number of characters in the longest possible IPv6 string.
Declared in <boost/url/ipv6_address.hpp>
constexpr
static
std::size_t const max_str_len = 49;
The longest IPv6 address is:
ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
The type used to represent an address as an array of bytes.
Octets are stored in network byte order.
Constructor.
constexpr
ipv6_address() = default;Constructor.
constexpr
ipv6_address(ipv6_address const&) = default;Construct from an array of bytes.
ipv6_address(bytes_type const& bytes) noexcept;Construct from an IPv4 address.
ipv6_address(ipv4_address const& addr) noexcept;Construct from a string.
ipv6_address(core::string_view s);Copy Assignment
Declared in <boost/url/ipv6_address.hpp>
constexpr
ipv6_address&
operator=(ipv6_address const&) = default;
Return the address as bytes, in network byte order
Return the address as a string.
Declared in <boost/url/ipv6_address.hpp>
templatestring_token::return_string>
StringToken::result_type
to_string(StringToken&& token) const;
The returned string does not contain surrounding square brackets.
When called with no arguments, the return type is `std::string`. Otherwise, the return type and style of output is determined by which string token is passed.
ipv6_address::bytes_type b = {{
0, 1, 0, 2, 0, 3, 0, 4,
0, 5, 0, 6, 0, 7, 0, 8 }};
ipv6_address a(b);
assert(a.to_string() == "1:2:3:4:5:6:7:8");
assert( ipv4_address(0x01020304).to_string() == "1.2.3.4" );
Calls to allocate may throw. String tokens may throw exceptions.
| Name | Description |
|---|---|
| token |
Write a dotted decimal string representing the address to a buffer
Declared in <boost/url/ipv6_address.hpp>
core::string_view
to_buffer(
char* dest,
std::size_t dest_size) const;
The resulting buffer is not null-terminated.
| Name | Thrown on |
|---|---|
`dest_size |
| Name | Description |
|---|---|
| dest | |
| dest_size |
Return true if the address is unspecified
The address 0:0:0:0:0:0:0:0 is called the unspecified address. It indicates the absence of an address.
Return true if the address is a loopback address
The unicast address 0:0:0:0:0:0:0:1 is called the loopback address. It may be used by a node to send an IPv6 packet to itself.
Return true if the address is a mapped IPv4 address
This address type is used to represent the addresses of IPv4 nodes as IPv6 addresses.
Return true if two addresses are equal
Declared in <boost/url/ipv6_address.hpp>
friend
bool
operator==(
ipv6_address const& a1,
ipv6_address const& a2) noexcept;
Return true if two addresses are not equal
Declared in <boost/url/ipv6_address.hpp>
friend
bool
operator!=(
ipv6_address const& a1,
ipv6_address const& a2) noexcept;
Return an address object that represents the loopback address
The unicast address 0:0:0:0:0:0:0:1 is called the loopback address. It may be used by a node to send an IPv6 packet to itself.
Format the address to an output stream
Declared in <boost/url/ipv6_address.hpp>
friend
std::ostream&
operator<<(
std::ostream& os,
ipv6_address const& addr);
This hidden friend function writes the address to an output stream using standard notation.
Parse a string containing an IPv6 address.
Declared in <boost/url/ipv6_address.hpp>
system::result<ipv6_address>
parse_ipv6_address(core::string_view s) noexcept;
This function attempts to parse the string as an IPv6 address and returns a result containing the address upon success, or an error code if the string does not contain a valid IPv6 address.
| Name | Description |
|---|---|
| s |
Percent-encoding options
| Name | Description |
|---|---|
| encoding_opts [constructor] |
| Name | Description |
|---|---|
| disallow_null |
True if nulls are not allowed |
| lower_case |
True if hexadecimal digits are emitted as lower case |
| space_as_plus |
True if spaces encode to and from plus signs |
These options are used to customize the behavior of algorithms which use percent escapes, such as encoding or decoding.
True if spaces encode to and from plus signs
This option controls whether or not the PLUS character ("+") is used to represent the SP character (" ") when encoding or decoding. Although not prescribed by the RFC, plus signs are commonly treated as spaces upon decoding when used in the query of URLs using well known schemes such as HTTP.
True if hexadecimal digits are emitted as lower case
By default, percent-encoding algorithms emit hexadecimal digits A through F as uppercase letters. When this option is `true`, lowercase letters are used.
True if nulls are not allowed
Normally all possible character values (from 0 to 255) are allowed, with reserved characters being replaced with escapes upon encoding. When this option is true, attempting to decode a null will result in an error.
Declared in <boost/url/encoding_opts.hpp>
encoding_opts(
bool space_as_plus_ = false,
bool lower_case_ = false,
bool disallow_null_ = false) noexcept;
A reference to a valid, percent-encoded string
| Name | Description |
|---|---|
| const_iterator |
An iterator of constant, decoded characters. |
| const_reference |
The reference type |
| difference_type |
The signed integer type |
| iterator |
An iterator of constant, decoded characters. |
| reference |
The reference type |
| size_type |
The unsigned integer type |
| value_type |
The value type |
| Name | Description |
|---|---|
| back |
Return the last character |
| begin |
Return an iterator to the beginning |
| compare |
Return the result of comparing to another string |
| decode_view [constructor] |
Constructor |
| empty |
Return true if the string is empty |
| end |
Return an iterator to the end |
| ends_with |
Checks if the string ends with the given prefix |
| find |
Finds the first occurrence of character in this view |
| front |
Return the first character |
| options |
Return the decoding options |
| remove_prefix |
Remove the first characters |
| remove_suffix |
Remove the last characters |
| rfind |
Finds the first occurrence of character in this view |
| size |
Return the number of decoded characters |
| starts_with |
Checks if the string begins with the given prefix |
| Name | Description |
|---|---|
| operator!= |
Compare two decode views for inequality |
| operator< |
Compare two decode views for less than |
| operator<< |
Format the string with percent-decoding applied to the output stream |
| operator<= |
Compare two decode views for less than or equal |
| operator== |
Compare two decode views for equality |
| operator> |
Compare two decode views for greater than |
| operator>= |
Compare two decode views for greater than or equal |
These views reference strings in parts of URLs or other components that are percent-encoded. The special characters (those not in the allowed character set) are stored as three character escapes that consist of a percent sign ('%%') followed by a two-digit hexadecimal number of the corresponding unescaped character code, which may be part of a UTF-8 code point depending on the context.
The view refers to the original character buffer and only decodes escaped sequences when needed. In particular these operations perform percent-decoding automatically without the need to allocate memory:
These objects can only be constructed from strings that have a valid percent-encoding, otherwise construction fails. The caller is responsible for ensuring that the lifetime of the character buffer from which the view is constructed extends unmodified until the view is no longer accessed.
decode_view and any object that is convertible to `core::string_view`
bool operator==( decode_view, decode_view ) noexcept;
bool operator!=( decode_view, decode_view ) noexcept;
bool operator<=( decode_view, decode_view ) noexcept;
bool operator< ( decode_view, decode_view ) noexcept;
bool operator> ( decode_view, decode_view ) noexcept;
bool operator>=( decode_view, decode_view ) noexcept;
The value type
The reference type
The reference type
The unsigned integer type
The signed integer type
An iterator of constant, decoded characters.
| Name | Description |
|---|---|
| const_reference | |
| difference_type | |
| iterator_category | |
| pointer | |
| reference | |
| size_type | |
| value_type |
| Name | Description |
|---|---|
| base | |
| iterator [constructor] | |
| operator!= | |
| operator* | |
| operator++ | |
| operator-- | |
| operator= | |
| operator== |
This iterator is used to access the encoded string as a bidirectional range of characters with percent-decoding applied. Escape sequences are not decoded until the iterator is dereferenced.
Declared in <boost/url/impl/decode_view.hpp>
using iterator_category = std::bidirectional_iterator_tag;
constexpr
iterator() = default;constexpr
iterator(iterator const&) = default;
Declared in <boost/url/impl/decode_view.hpp>
constexpr
iterator&
operator=(iterator const&) = default;
iterator&
operator++() noexcept;iterator
operator++(int) noexcept;iterator&
operator--() noexcept;iterator
operator--(int) noexcept;
Declared in <boost/url/impl/decode_view.hpp>
bool
operator==(iterator const& other) const noexcept;
Declared in <boost/url/impl/decode_view.hpp>
bool
operator!=(iterator const& other) const noexcept;
An iterator of constant, decoded characters.
This iterator is used to access the encoded string as a bidirectional range of characters with percent-decoding applied. Escape sequences are not decoded until the iterator is dereferenced.
Constructor
constexpr
decode_view() noexcept = default;Constructor
decode_view(
pct_string_view s,
encoding_opts opt = = {}) noexcept;Return true if the string is empty
assert( decode_view( "" ).empty() );
Return the number of decoded characters
assert( decode_view( "Program%20Files" ).size() == 13 );
return std::distance( this->begin(), this->end() );
Return an iterator to the beginning
auto it = this->begin();
Return an iterator to the end
auto it = this->end();
Return the first character
assert( decode_view( "Program%20Files" ).front() == 'P' );
not this->empty()
Return the last character
assert( decode_view( "Program%20Files" ).back() == 's' );
not this->empty()
Checks if the string begins with the given prefix
bool
starts_with(core::string_view s) const noexcept;Checks if the string begins with the given prefix
bool
starts_with(char ch) const noexcept;Checks if the string ends with the given prefix
bool
ends_with(core::string_view s) const noexcept;Checks if the string ends with the given prefix
bool
ends_with(char ch) const noexcept;Finds the first occurrence of character in this view
Finds the first occurrence of character in this view
Remove the first characters
decode_view d( "Program%20Files" );
d.remove_prefix( 8 );
assert( d == "Files" );
not this->empty()
Remove the last characters
decode_view d( "Program%20Files" );
d.remove_prefix( 6 );
assert( d == "Program" );
not this->empty()
Return the decoding options
Return the result of comparing to another string
int
compare(core::string_view other) const noexcept;Return the result of comparing to another string
int
compare(decode_view other) const noexcept;Compare two decode views for equality
Declared in <boost/url/decode_view.hpp>
template<
class S0,
class S1>
friend
constexpr
bool
operator==(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`
Compare two decode views for inequality
Declared in <boost/url/decode_view.hpp>
template<
class S0,
class S1>
friend
constexpr
bool
operator!=(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`
Compare two decode views for less than
Declared in <boost/url/decode_view.hpp>
template<
class S0,
class S1>
friend
constexpr
bool
operator<(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`
Compare two decode views for less than or equal
Declared in <boost/url/decode_view.hpp>
template<
class S0,
class S1>
friend
constexpr
bool
operator<=(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`
Compare two decode views for greater than
Declared in <boost/url/decode_view.hpp>
template<
class S0,
class S1>
friend
constexpr
bool
operator>(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`
Compare two decode views for greater than or equal
Declared in <boost/url/decode_view.hpp>
template<
class S0,
class S1>
friend
constexpr
bool
operator>=(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`
Format the string with percent-decoding applied to the output stream
Declared in <boost/url/decode_view.hpp>
friend
std::ostream&
operator<<(
std::ostream& os,
decode_view const& s);
This hidden friend function serializes the decoded view to the output stream.
A reference to a valid percent-encoded string
Declared in <boost/url/pct_string_view.hpp>
class pct_string_view
: public grammar::string_view_base;
| Name | Description |
|---|---|
| const_iterator |
The const iterator type |
| const_pointer |
The const pointer type |
| const_reference |
The const reference type |
| const_reverse_iterator |
The const reverse iterator type |
| difference_type |
The difference type |
| iterator |
The iterator type |
| pointer |
The pointer type |
| reference |
The reference type |
| reverse_iterator |
The reverse iterator type |
| size_type |
The size type |
| traits_type |
The character traits |
| value_type |
The value type |
| Name | Description |
|---|---|
| at |
Access a character |
| back |
Return the last character |
| begin |
Return an iterator to the beginning |
| cbegin |
Return an iterator to the beginning |
| cend |
Return an iterator to the end |
| compare |
Return the result of comparing to another string |
| contains |
Return true if matching characters are found |
| copy |
Copy the characters to another buffer |
| crbegin |
Return a reverse iterator to the end |
| crend |
Return a reverse iterator to the beginning |
| data |
Return a pointer to the character buffer |
| decode |
Return the string with percent-decoding |
| decoded_size |
Return the decoded size |
| empty |
Return true if the string is empty |
| end |
Return an iterator to the end |
| ends_with |
Return true if a matching suffix exists |
| find |
Return the position of matching characters |
| find_first_not_of |
Return the position of the first non-match |
| find_first_of |
Return the position of the first match |
| find_last_not_of |
Return the position of the last non-match |
| find_last_of |
Return the position of the last match |
| front |
Return the first character |
| length |
Return the size |
| max_size |
Return the maximum allowed size |
| operator std::string |
Conversion |
| operator core::string_view |
Conversion |
| operator* |
Return the string as a range of decoded characters |
| operator-> |
Arrow support |
| operator= |
Assignment |
| operator[] |
Access a character |
| pct_string_view [constructor] |
Constructor (deleted) Constructor |
| rbegin |
Return a reverse iterator to the end |
| rend |
Return a reverse iterator to the beginning |
| rfind |
Return the position of matching characters |
| size |
Return the size |
| starts_with |
Return true if a matching prefix exists |
| substr |
Return a view to part of the string |
| swap |
Swap |
| Name | Description |
|---|---|
| npos |
A constant used to represent "no position" |
| Name | Description |
|---|---|
| make_pct_string_view |
Return a valid percent-encoded string |
| operator!= |
Compare two string views for inequality |
| operator< |
Compare two string views for less than |
| operator<< |
Format a string to an output stream |
| operator<= |
Compare two string views for less than or equal |
| operator== |
Compare two string views for equality |
| operator> |
Compare two string views for greater than |
| operator>= |
Compare two string views for greater than or equal |
Objects of this type behave like a `core::string_view` and have the same interface, but offer an additional invariant: they can only be constructed from strings containing valid percent-escapes.
Attempting construction from a string containing invalid or malformed percent escapes results in an exception.
pct_string_view and any object that is convertible to `core::string_view`
bool operator==( pct_string_view, pct_string_view ) noexcept;
bool operator!=( pct_string_view, pct_string_view ) noexcept;
bool operator<=( pct_string_view, pct_string_view ) noexcept;
bool operator< ( pct_string_view, pct_string_view ) noexcept;
bool operator> ( pct_string_view, pct_string_view ) noexcept;
bool operator>=( pct_string_view, pct_string_view ) noexcept;
Constructor
constexpr
pct_string_view() = default;Constructor
constexpr
pct_string_view(pct_string_view const& other) = default;template<
class String,
class = void>
pct_string_view(String const& s);Constructor (deleted)
pct_string_view(std::nullptr_t) = delete;Constructor
pct_string_view(
char const* s,
std::size_t len);Constructor
pct_string_view(core::string_view s);Assignment
Declared in <boost/url/pct_string_view.hpp>
constexpr
pct_string_view&
operator=(pct_string_view const& other) = default;
The copy references the same underlying character buffer. Ownership is not transferred.
this->data() == other.data()
Return a valid percent-encoded string
Declared in <boost/url/pct_string_view.hpp>
friend
system::result<pct_string_view>
make_pct_string_view(core::string_view s) noexcept;
If `s` is a valid percent-encoded string, the function returns the buffer as a valid view which may be used to perform decoding or measurements. Otherwise the result contains an error code. Upon success, the returned view references the original character buffer; Ownership is not transferred.
Return the decoded size
This function returns the number of characters in the resulting string if percent escapes were converted into ordinary characters.
Return the string as a range of decoded characters
Return the string with percent-decoding
Declared in <boost/url/pct_string_view.hpp>
templatestring_token::return_string>
StringToken::result_type
decode(
encoding_opts opt = = {},
StringToken&& token) const;
This function converts percent escapes in the string into ordinary characters and returns the result. When called with no arguments, the return type is `std::string`. Otherwise, the return type and style of output is determined by which string token is passed.
assert( pct_string_view( "Program%20Files" ).decode() == "Program Files" );
String tokens may throw exceptions.
| Name | Description |
|---|---|
| opt | |
| token |
Arrow support
Declared in <boost/url/pct_string_view.hpp>
pct_string_view const*
operator->() const noexcept;
Swap
Return a valid percent-encoded string
Declared in <boost/url/pct_string_view.hpp>
system::result<pct_string_view>
make_pct_string_view(core::string_view s) noexcept;
If `s` is a valid percent-encoded string, the function returns the buffer as a valid view which may be used to perform decoding or measurements. Otherwise the result contains an error code. Upon success, the returned view references the original character buffer; Ownership is not transferred.
Return a valid percent-encoded string
If `s` is a valid percent-encoded string, the function returns the buffer as a valid view which may be used to perform decoding or measurements. Otherwise the result contains an error code. Upon success, the returned view references the original character buffer; Ownership is not transferred.
| Name | Description |
|---|---|
| s | |
| s |
Identifies a known URL scheme
| Name | Description |
|---|---|
| none | Indicates that no scheme is present |
| unknown | Indicates the scheme is not a well-known scheme |
| ftp | File Transfer Protocol (FTP) |
| file | File URI Scheme |
| http | The Hypertext Transfer Protocol URI Scheme |
| https | The Secure Hypertext Transfer Protocol URI Scheme |
| ws | The WebSocket URI Scheme |
| wss | The Secure WebSocket URI Scheme |
Indicates that no scheme is present
Indicates the scheme is not a well-known scheme
File Transfer Protocol (FTP)
FTP is a standard communication protocol used for the transfer of computer files from a server to a client on a computer network.
File URI Scheme
The File URI Scheme is typically used to retrieve files from within one's own computer.
The Hypertext Transfer Protocol URI Scheme
URLs of this type indicate a resource which is interacted with using the HTTP protocol.
The Secure Hypertext Transfer Protocol URI Scheme
URLs of this type indicate a resource which is interacted with using the Secure HTTP protocol.
The WebSocket URI Scheme
URLs of this type indicate a resource which is interacted with using the WebSocket protocol.
The Secure WebSocket URI Scheme
URLs of this type indicate a resource which is interacted with using the Secure WebSocket protocol.
Return the known scheme for a non-normalized string, if known
If the string does not identify a known scheme, the value scheme::unknown is returned.
scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
| Name | Description |
|---|---|
| s |
Return the normalized string for a known scheme
| Name | Description |
|---|---|
| s |
Return the default port for a known scheme
This function returns the default port for the known schemes. If the value does not represent a known scheme or the scheme does not represent a protocol, the function returns zero.
The following ports are returned by the function:
| Name | Description |
|---|---|
| s |
A non-owning reference to a valid URL
| Name | Description |
|---|---|
| authority |
Return the authority |
| buffer |
Return the url string |
| compare |
Return the result of comparing this with another url |
| data |
Return a pointer to the url's character buffer |
| empty |
Return true if the url is empty |
| encoded_authority |
Return the authority. |
| encoded_fragment |
Return the fragment |
| encoded_host |
Return the host |
| encoded_host_address |
Return the host |
| encoded_host_and_port |
Return the host and port |
| encoded_host_name |
Return the host name |
| encoded_origin |
Return the origin |
| encoded_params |
Return the query as a container of parameters |
| encoded_password |
Return the password |
| encoded_path |
Return the path |
| encoded_query |
Return the query |
| encoded_resource |
Return the resource |
| encoded_segments |
Return the path as a container of segments |
| encoded_target |
Return the target |
| encoded_user |
Return the user |
| encoded_userinfo |
Return the userinfo |
| encoded_zone_id |
Return the IPv6 Zone ID |
| fragment |
Return the fragment |
| has_authority |
Return true if an authority is present |
| has_fragment |
Return true if a fragment is present |
| has_password |
Return true if a password is present |
| has_port |
Return true if a port is present |
| has_query |
Return true if a query is present |
| has_scheme |
Return true a scheme is present |
| has_userinfo |
Return true if a userinfo is present |
| host |
Return the host |
| host_address |
Return the host |
| host_ipv4_address |
Return the host IPv4 address |
| host_ipv6_address |
Return the host IPv6 address |
| host_ipvfuture |
Return the host IPvFuture address |
| host_name |
Return the host name |
| host_type |
Return the host type |
| is_path_absolute |
Return true if the path is absolute |
| operator core::string_view |
Return the URL as a core::string_view |
| operator= |
Assignment |
| params |
Return the query as a container of parameters |
| password |
Return the password |
| path |
Return the path |
| persist |
Return a shared, persistent copy of the url |
| port |
Return the port |
| port_number |
Return the port |
| query |
Return the query |
| scheme |
Return the scheme |
| scheme_id |
Return the scheme |
| segments |
Return the path as a container of segments |
| size |
Return the number of characters in the url |
| url_view [constructor] |
Constructor |
| user |
Return the user |
| userinfo |
Return the userinfo |
| zone_id |
Return the IPv6 Zone ID |
| ~url_view [destructor] |
Destructor |
| Name | Description |
|---|---|
| max_size |
Return the maximum number of characters possible |
| Name | Description |
|---|---|
| operator!= |
Return the result of comparing two URLs |
| operator< |
Return the result of comparing two URLs |
| operator<< |
Format the url to the output stream |
| operator<= |
Return the result of comparing two URLs |
| operator== |
Return the result of comparing two URLs |
| operator> |
Return the result of comparing two URLs |
| operator>= |
Return the result of comparing two URLs |
Objects of this type represent valid URL strings constructed from a parsed, external character buffer whose storage is managed by the caller. That is, it acts like a `core::string_view` in terms of ownership. The caller is responsible for ensuring that the lifetime of the underlying character buffer extends until it is no longer referenced.
as a URI-reference and throws an exception on error. Upon success, the constructed object points to the passed character buffer; ownership is not transferred.
url_view u( "https://www.example.com/index.htm?text=none#a1" );
parse_uri_reference return a result containing either a valid url_view upon succcess, otherwise they contain an error. The error can be converted to an exception by the caller if desired:
system::result< url_view > rv = parse_uri_reference( "https://www.example.com/index.htm?text=none#a1" );
URI-reference = URI / relative-ref
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
relative-ref = relative-part [ "?" query ] [ "#" fragment ]
parse_absolute_uri , parse_origin_form , parse_relative_ref , parse_uri , parse_uri_reference .
Destructor
Any params, segments, iterators, or other views which reference the same underlying character buffer remain valid.
Constructor
url_view() noexcept;Constructor
url_view(core::string_view s);template<
class String,
class = void>
url_view(String const& s);Constructor
url_view(url_view const& other) noexcept;Constructor
url_view(url_view_base const& other) noexcept;Assignment
url_view&
operator=(url_view const& other) noexcept;Assignment
url_view&
operator=(url_view_base const& other) noexcept;Return the maximum number of characters possible
This represents the largest number of characters that are possible in a url, not including any null terminator.
Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
bool
operator<(
authority_view const& a0,
authority_view const& a1) noexcept;Compare two decode views for less than
template<
class S0,
class S1>
constexpr
bool
operator<(
S0 const& s0,
S1 const& s1) noexcept;Return the result of comparing two URLs
bool
operator<(
url_view_base const& u0,
url_view_base const& u1) noexcept;Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
bool
operator<=(
authority_view const& a0,
authority_view const& a1) noexcept;Compare two decode views for less than or equal
template<
class S0,
class S1>
constexpr
bool
operator<=(
S0 const& s0,
S1 const& s1) noexcept;Return the result of comparing two URLs
bool
operator<=(
url_view_base const& u0,
url_view_base const& u1) noexcept;Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
bool
operator>(
authority_view const& a0,
authority_view const& a1) noexcept;Compare two decode views for greater than
template<
class S0,
class S1>
constexpr
bool
operator>(
S0 const& s0,
S1 const& s1) noexcept;Return the result of comparing two URLs
bool
operator>(
url_view_base const& u0,
url_view_base const& u1) noexcept;Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
bool
operator>=(
authority_view const& a0,
authority_view const& a1) noexcept;Compare two decode views for greater than or equal
template<
class S0,
class S1>
constexpr
bool
operator>=(
S0 const& s0,
S1 const& s1) noexcept;Return the result of comparing two URLs
bool
operator>=(
url_view_base const& u0,
url_view_base const& u1) noexcept;Return the buffer size needed for percent-encoding
Declared in <boost/url/encode.hpp>
template
std::size_t
encoded_size(
core::string_view s,
CharSet const& unreserved,
encoding_opts opt = = {}) noexcept;
This function returns the exact number of bytes necessary to store the result of applying percent-encoding to the string using the given options and character set. No encoding is actually performed.
assert( encoded_size( "My Stuff", pchars ) == 10 );
| Name | Description |
|---|---|
| s | |
| unreserved | |
| opt |
Apply percent-encoding to a string
template
std::size_t
encode(
char* dest,
std::size_t size,
core::string_view s,
CharSet const& unreserved,
encoding_opts opt = = {}); Return a percent-encoded string
template<
class StringToken = string_token::return_string,
class CharSet>
StringToken::result_type
encode(
core::string_view s,
CharSet const& unreserved,
encoding_opts opt = = {},
StringToken&& token) noexcept;Ignore case when comparing
This value may be optionally passed to functions accepting a parameter of type ignore_case_param to indicate that comparisons should be case-insensitive.
An optional parameter to determine case-sensitivity
| Name | Description |
|---|---|
| ignore_case_param [constructor] |
Constructor |
| operator bool |
True if an algorithm should ignore case |
Functions may use parameters of this type to allow the user to optionally indicate that comparisons should be case-insensitive when the value ignore_case is passed.
Constructor
constexpr
ignore_case_param() noexcept = default;Constructor
constexpr
ignore_case_param(ignore_case_t) noexcept;True if an algorithm should ignore case
Values of type `ignore_case_param` evaluate to true when constructed with the constant ignore_case . Otherwise, they are default-constructed and evaluate to `false`.
A query parameter
| Name | Description |
|---|---|
| operator param |
Conversion |
| operator param_view |
Conversion to param_view |
| operator-> |
Arrow support |
| param_pct_view [constructor] |
Construction Constructor aggregate construction |
Objects of this type represent a single key and value pair in a query string where a key is always present and may be empty, while the presence of a value is indicated by has_value equal to true. An empty value is distinct from no value.
The strings may have percent escapes, and offer an additional invariant: they never contain an invalid percent-encoding.
For most usages, key comparisons are case-sensitive and duplicate keys in a query are possible. However, it is the authority that has final control over how the query is interpreted.
Keys and values in this object reference external character buffers. Ownership of the buffers is not transferred; the caller is responsible for ensuring that the assigned buffers remain valid until they are no longer referenced.
query-params = query-param *( "&" query-param )
query-param = key [ "=" value ]
key = *qpchar
value = *( qpchar / "=" )
param , param_view .
The key
For most usages, key comparisons are case-sensitive and duplicate keys in a query are possible. However, it is the authority that has final control over how the query is interpreted.
The value
The presence of a value is indicated by has_value equal to true. An empty value is distinct from no value.
True if a value is present
The presence of a value is indicated by `has_value == true`. An empty value is distinct from no value.
Constructor
constexpr
param_pct_view() = default;Constructor
param_pct_view(
pct_string_view key,
pct_string_view value) noexcept;Constructor
template
param_pct_view(
pct_string_view key,
OptionalString const& value); Construction
param_pct_view(param_view const& p);aggregate construction
param_pct_view(
pct_string_view key,
pct_string_view value,
bool has_value) noexcept;Conversion
This function performs a conversion from a reference-like query parameter to one retaining ownership of the strings by making a copy.
Conversion to param_view
This function performs a conversion from a pct_string_view query parameter to one using a simple string_view.
Arrow support
A query parameter
| Name | Description |
|---|---|
| operator param |
Conversion |
| operator-> | |
| param_view [constructor] |
Constructor |
Objects of this type represent a single key and value pair in a query string where a key is always present and may be empty, while the presence of a value is indicated by has_value equal to true. An empty value is distinct from no value.
Depending on where the object was obtained, the strings may or may not contain percent escapes.
For most usages, key comparisons are case-sensitive and duplicate keys in a query are possible. However, it is the authority that has final control over how the query is interpreted.
Keys and values in this object reference external character buffers. Ownership of the buffers is not transferred; the caller is responsible for ensuring that the assigned buffers remain valid until they are no longer referenced.
query-params = query-param *( "&" query-param )
query-param = key [ "=" value ]
key = *qpchar
value = *( qpchar / "=" )
param , param_pct_view .
The key
For most usages, key comparisons are case-sensitive and duplicate keys in a query are possible. However, it is the authority that has final control over how the query is interpreted.
The value
The presence of a value is indicated by has_value equal to true. An empty value is distinct from no value.
True if a value is present
The presence of a value is indicated by `has_value == true`. An empty value is distinct from no value.
Constructor
constexpr
param_view() = default;Constructor
template
param_view(
core::string_view key,
OptionalString const& value) noexcept; Constructor
param_view(param const& other) noexcept;param_view(
core::string_view key_,
core::string_view value_,
bool has_value_) noexcept;Conversion
This function performs a conversion from a reference-like query parameter to one retaining ownership of the strings by making a copy. No validation is performed on the strings.
Constant indicating no value in a param
A query parameter
| Name | Description |
|---|---|
| operator-> | |
| operator= |
Assignment |
| param [constructor] |
Constructor |
Objects of this type represent a single key and value pair in a query string where a key is always present and may be empty, while the presence of a value is indicated by has_value equal to true. An empty value is distinct from no value.
Depending on where the object was obtained, the strings may or may not contain percent escapes.
For most usages, key comparisons are case-sensitive and duplicate keys in a query are possible. However, it is the authority that has final control over how the query is interpreted.
query-params = query-param *( "&" query-param )
query-param = key [ "=" value ]
key = *qpchar
value = *( qpchar / "=" )
The key
For most usages, key comparisons are case-sensitive and duplicate keys in a query are possible. However, it is the authority that has final control over how the query is interpreted.
The value
The presence of a value is indicated by has_value equal to true. An empty value is distinct from no value.
True if a value is present
The presence of a value is indicated by `has_value == true`. An empty value is distinct from no value.
Constructor
constexpr
param() = default;Constructor
param(param&& other) noexcept;Constructor
constexpr
param(param const& other) = default;Constructor
template
param(
core::string_view key,
OptionalString const& value); param(
core::string_view key,
core::string_view value,
bool has_value) noexcept;Assignment
param&
operator=(param&& other) noexcept;Assignment
constexpr
param&
operator=(param const&) = default;Assignment
param&
operator=(param_view const& other);Assignment
param&
operator=(param_pct_view const& other);Common functionality for containers
| Name | Description |
|---|---|
| const_iterator |
A Bidirectional iterator to a query parameter |
| const_reference |
The reference type |
| difference_type |
A signed integer type used to represent differences. |
| iterator |
A Bidirectional iterator to a query parameter |
| reference |
The reference type |
| size_type |
An unsigned integer type to represent sizes. |
| value_type |
The value type |
| Name | Description |
|---|---|
| begin |
Return an iterator to the beginning |
| buffer |
Return the query corresponding to these params |
| contains |
Return true if a matching key exists |
| count |
Return the number of matching keys |
| empty |
Return true if there are no params |
| end |
Return an iterator to the end |
| find |
Find a matching key |
| find_last |
Find a matching key |
| size |
Return the number of params |
| Name | Description |
|---|---|
| max_size |
Return the maximum number of characters possible |
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:
A Bidirectional iterator to a query parameter
| Name | Description |
|---|---|
| difference_type | |
| iterator_category | |
| pointer | |
| reference | |
| value_type |
| Name | Description |
|---|---|
| iterator [constructor] | |
| operator* | |
| operator++ | |
| operator-- | |
| operator-> | |
| operator= |
| Name | Description |
|---|---|
| operator!= | |
| operator== |
Objects of this type allow iteration through the parameters in the query. Strings returned by iterators may contain percent escapes. The values returned are read-only; changes to parameters must be made through the container instead, if the container supports modification.
The strings produced when iterators are dereferenced refer to the underlying character buffer. Ownership is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced by any container or iterator.
Declared in <boost/url/impl/params_encoded_base.hpp>
using value_type = params_encoded_base::value_type;
Declared in <boost/url/impl/params_encoded_base.hpp>
using reference = params_encoded_base::reference;
Declared in <boost/url/impl/params_encoded_base.hpp>
using difference_type = std::ptrdiff_t;
Declared in <boost/url/impl/params_encoded_base.hpp>
using iterator_category = std::bidirectional_iterator_tag;
constexpr
iterator() = default;constexpr
iterator(iterator const&) = default;
Declared in <boost/url/impl/params_encoded_base.hpp>
constexpr
iterator&
operator=(iterator const&) = default;
iterator&
operator++() noexcept;iterator
operator++(int) noexcept;iterator&
operator--() noexcept;iterator
operator--(int) noexcept;
Declared in <boost/url/impl/params_encoded_base.hpp>
friend
bool
operator==(
iterator const& it0,
iterator const& it1) noexcept;
Declared in <boost/url/impl/params_encoded_base.hpp>
friend
bool
operator!=(
iterator const& it0,
iterator const& it1) noexcept;
A Bidirectional iterator to a query parameter
Objects of this type allow iteration through the parameters in the query. Strings returned by iterators may contain percent escapes. The values returned are read-only; changes to parameters must be made through the container instead, if the container supports modification.
The strings produced when iterators are dereferenced refer to the underlying character buffer. Ownership is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced by any container or iterator.
The value type
Values of this type represent parameters whose strings retain unique ownership by making a copy.
params_encoded_view::value_type qp( *url_view( "?first=John&last=Doe" ).params().find( "first" ) );
The reference type
This is the type of value returned when iterators of the view are dereferenced.
The reference type
This is the type of value returned when iterators of the view are dereferenced.
An unsigned integer type to represent sizes.
A signed integer type used to represent differences.
Return the maximum number of characters possible
Declared in <boost/url/params_encoded_base.hpp>
constexpr
static
std::size_t
max_size() noexcept;
This represents the largest number of characters that are possible in a path, not including any null terminator.
Return the query corresponding to these params
This function returns the query string referenced by the container. The returned string may contain percent escapes.
assert( url_view( "?first=John&last=Doe" ).encoded_params().buffer() == "first=John&last=Doe" );
query-params = query-param *( "&" query-param )
query-param = key [ "=" value ]
key = *qpchar
value = *( qpchar / "=" )
Return true if there are no params
assert( ! url_view( "?key=value" ).encoded_params().empty() );
Return the number of params
assert( url_view( "?key=value").encoded_params().size() == 1 );
Return an iterator to the beginning
Return an iterator to the end
Return true if a matching key exists
Declared in <boost/url/params_encoded_base.hpp>
bool
contains(
pct_string_view key,
ignore_case_param ic = = {}) const noexcept;
This function examines the parameters in the container to find a match for the specified key, which may contain percent escapes. The comparison is performed as if all escaped characters were decoded first.
assert( url_view( "?first=John&last=Doe" ).encoded_params().contains( "first" ) );
| Name | Thrown on |
|---|---|
`key` |
| Name | Description |
|---|---|
| key | |
| ic |
Return the number of matching keys
Declared in <boost/url/params_encoded_base.hpp>
std::size_t
count(
pct_string_view key,
ignore_case_param ic = = {}) const noexcept;
This function examines the parameters in the container to find the number of matches for the specified key, which may contain percent escapes. The comparison is performed as if all escaped characters were decoded first.
assert( url_view( "?first=John&last=Doe" ).encoded_params().count( "first" ) == 1 );
| Name | Thrown on |
|---|---|
`key` |
| Name | Description |
|---|---|
| key | |
| ic |
Find a matching key
iterator
find(
pct_string_view key,
ignore_case_param ic = = {}) const noexcept;Find a matching key
iterator
find(
iterator from,
pct_string_view key,
ignore_case_param ic = = {}) const noexcept;Find a matching key
iterator
find_last(
pct_string_view key,
ignore_case_param ic = = {}) const noexcept;Find a matching key
iterator
find_last(
iterator before,
pct_string_view key,
ignore_case_param ic = = {}) const noexcept;A view representing query parameters in a URL
| Name | Description |
|---|---|
| const_iterator |
A Bidirectional iterator to a query parameter |
| const_reference |
The reference type |
| difference_type |
A signed integer type used to represent differences. |
| iterator |
A Bidirectional iterator to a query parameter |
| reference |
The reference type |
| size_type |
An unsigned integer type to represent sizes. |
| value_type |
The value type |
| Name | Description |
|---|---|
| append |
Append elements |
| assign |
Assign elements |
| begin |
Return an iterator to the beginning |
| buffer |
Return the referenced character buffer. |
| clear |
Clear the contents of the container |
| contains |
Return true if a matching key exists |
| count |
Return the number of matching keys |
| empty |
Return true if there are no params |
| end |
Return an iterator to the end |
| erase |
Erase elements |
| find |
Find a matching key |
| find_last |
Find a matching key |
| insert |
Insert elements |
| operator params_view |
Conversion |
| operator= |
Assignment |
| params_ref [constructor] |
Constructor |
| replace |
Replace elements |
| set |
Set a value |
| size |
Return the number of params |
| unset |
Remove the value on an element |
| url |
Return the referenced url |
| Name | Description |
|---|---|
| max_size |
Return the maximum number of characters possible |
Objects of this type are used to interpret the query parameters as a bidirectional view of key/value pairs. The view does not retain ownership of the elements and instead references the original url. The caller is responsible for ensuring that the lifetime of the referenced url extends until it is no longer referenced. The view is modifiable; calling non-const members causes changes to the referenced url.
Percent escapes in strings returned when dereferencing iterators are automatically decoded. Reserved characters in strings supplied to modifier functions are automatically percent-escaped.
url u( "?first=John&last=Doe" );
params_ref p = u.params();
can invalidate iterators which reference it. Modifications made through the container invalidate some or all iterators:
Constructor
constexpr
params_ref(params_ref const& other) = default;Constructor
params_ref(
params_ref const& other,
encoding_opts opt) noexcept;Assignment
params_ref&
operator=(params_ref const& other);Assignment
params_ref&
operator=(std::initializer_list<param_view> init);Conversion
Return the referenced url
This function returns the url referenced by the view.
url u( "?key=value" );
assert( &u.segments().url() == &u );
Throws nothing.
Clear the contents of the container
All iterators are invalidated.
this->url().remove_query();
this->empty() == true && this->url().has_query() == false
Assign elements
void
assign(std::initializer_list<param_view> init);Assign elements
template
void
assign(
FwdIt first,
FwdIt last); Append elements
iterator
append(param_view const& p);Append elements
iterator
append(std::initializer_list<param_view> init);Append elements
template
iterator
append(
FwdIt first,
FwdIt last); Insert elements
iterator
insert(
iterator before,
param_view const& p);Insert elements
iterator
insert(
iterator before,
std::initializer_list<param_view> init);Insert elements
template
iterator
insert(
iterator before,
FwdIt first,
FwdIt last); Erase elements
iterator
erase(iterator pos) noexcept;Erase elements
iterator
erase(
iterator first,
iterator last) noexcept;Erase elements
std::size_t
erase(
core::string_view key,
ignore_case_param ic = = {}) noexcept;Replace elements
iterator
replace(
iterator pos,
param_view const& p);Replace elements
iterator
replace(
iterator from,
iterator to,
std::initializer_list<param_view> init);Replace elements
template
iterator
replace(
iterator from,
iterator to,
FwdIt first,
FwdIt last); Remove the value on an element
This function removes the value of an element at the specified position. After the call returns, `has_value` for the element is false.
All iterators that are equal to `pos` or come after are invalidated.
url u( "?first=John&last=Doe" );
u.params().unset( u.params().begin() );
assert( u.encoded_query() == "first&last=Doe" );
| Name | Description |
|---|---|
| pos |
Set a value
iterator
set(
iterator pos,
core::string_view value);Set a value
iterator
set(
core::string_view key,
core::string_view value,
ignore_case_param ic = = {});Common functionality for containers
| Name | Description |
|---|---|
| const_iterator |
A Bidirectional iterator to a query parameter |
| const_reference |
The reference type |
| difference_type |
A signed integer type used to represent differences. |
| iterator |
A Bidirectional iterator to a query parameter |
| reference |
The reference type |
| size_type |
An unsigned integer type to represent sizes. |
| value_type |
The value type |
| Name | Description |
|---|---|
| begin |
Return an iterator to the beginning |
| buffer |
Return the referenced character buffer. |
| contains |
Return true if a matching key exists |
| count |
Return the number of matching keys |
| empty |
Return true if there are no params |
| end |
Return an iterator to the end |
| find |
Find a matching key |
| find_last |
Find a matching key |
| size |
Return the number of params |
| Name | Description |
|---|---|
| max_size |
Return the maximum number of characters possible |
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:
A Bidirectional iterator to a query parameter
| Name | Description |
|---|---|
| difference_type | |
| iterator_category | |
| pointer | |
| reference | |
| value_type |
| Name | Description |
|---|---|
| iterator [constructor] | |
| operator!= | |
| operator* | |
| operator++ | |
| operator-- | |
| operator-> | |
| operator= | |
| operator== |
Objects of this type allow iteration through the parameters in the query. Any percent-escapes in returned strings are decoded first. The values returned are read-only; changes to parameters must be made through the container instead, if the container supports modification.
The strings produced when iterators are dereferenced belong to the iterator and become invalidated when that particular iterator is incremented, decremented, or destroyed.
The implementation may use temporary, recycled storage to store decoded strings. These iterators are meant to be used ephemerally. That is, for short durations such as within a function scope. Do not store iterators with static storage duration or as long-lived objects.
Declared in <boost/url/impl/params_base.hpp>
using difference_type = params_base::difference_type;
Declared in <boost/url/impl/params_base.hpp>
using iterator_category = std::bidirectional_iterator_tag;
constexpr
iterator() = default;constexpr
iterator(iterator const&) = default;
Declared in <boost/url/impl/params_base.hpp>
constexpr
iterator&
operator=(iterator const&) noexcept = default;
iterator&
operator++() noexcept;iterator
operator++(int) noexcept;iterator&
operator--() noexcept;iterator
operator--(int) noexcept;
Declared in <boost/url/impl/params_base.hpp>
bool
operator==(iterator const& other) const noexcept;
Declared in <boost/url/impl/params_base.hpp>
bool
operator!=(iterator const& other) const noexcept;
A Bidirectional iterator to a query parameter
Objects of this type allow iteration through the parameters in the query. Any percent-escapes in returned strings are decoded first. The values returned are read-only; changes to parameters must be made through the container instead, if the container supports modification.
The strings produced when iterators are dereferenced belong to the iterator and become invalidated when that particular iterator is incremented, decremented, or destroyed.
The implementation may use temporary, recycled storage to store decoded strings. These iterators are meant to be used ephemerally. That is, for short durations such as within a function scope. Do not store iterators with static storage duration or as long-lived objects.
The value type
Values of this type represent parameters whose strings retain unique ownership by making a copy.
params_view::value_type qp( *url_view( "?first=John&last=Doe" ).params().find( "first" ) );
The reference type
This is the type of value returned when iterators of the view are dereferenced.
The reference type
This is the type of value returned when iterators of the view are dereferenced.
An unsigned integer type to represent sizes.
A signed integer type used to represent differences.
Return the maximum number of characters possible
This represents the largest number of characters that are possible in a path, not including any null terminator.
Return the referenced character buffer.
This function returns the character buffer referenced by the view. The returned string may contain percent escapes.
assert( url_view( "?first=John&last=Doe" ).params().buffer() == "?first=John&last=Doe" );
Return true if there are no params
assert( ! url_view( "?key=value" ).params().empty() );
Return the number of params
assert( url_view( "?key=value").params().size() == 1 );
Return an iterator to the beginning
Return an iterator to the end
Return true if a matching key exists
Declared in <boost/url/params_base.hpp>
bool
contains(
core::string_view key,
ignore_case_param ic = = {}) const noexcept;
This function examines the parameters in the container to find a match for the specified key. The comparison is performed as if all escaped characters were decoded first.
assert( url_view( "?first=John&last=Doe" ).params().contains( "first" ) );
| Name | Description |
|---|---|
| key | |
| ic |
Return the number of matching keys
Declared in <boost/url/params_base.hpp>
std::size_t
count(
core::string_view key,
ignore_case_param ic = = {}) const noexcept;
This function examines the parameters in the container to find the number of matches for the specified key. The comparison is performed as if all escaped characters were decoded first.
assert( url_view( "?first=John&last=Doe" ).params().count( "first" ) == 1 );
| Name | Description |
|---|---|
| key | |
| ic |
Find a matching key
iterator
find(
core::string_view key,
ignore_case_param ic = = {}) const noexcept;Find a matching key
iterator
find(
iterator from,
core::string_view key,
ignore_case_param ic = = {}) const noexcept;Find a matching key
iterator
find_last(
core::string_view key,
ignore_case_param ic = = {}) const noexcept;Find a matching key
iterator
find_last(
iterator before,
core::string_view key,
ignore_case_param ic = = {}) const noexcept;A view representing query parameters in a URL
| Name | Description |
|---|---|
| const_iterator |
A Bidirectional iterator to a query parameter |
| const_reference |
The reference type |
| difference_type |
A signed integer type used to represent differences. |
| iterator |
A Bidirectional iterator to a query parameter |
| reference |
The reference type |
| size_type |
An unsigned integer type to represent sizes. |
| value_type |
The value type |
| Name | Description |
|---|---|
| begin |
Return an iterator to the beginning |
| buffer |
Return the referenced character buffer. |
| contains |
Return true if a matching key exists |
| count |
Return the number of matching keys |
| empty |
Return true if there are no params |
| end |
Return an iterator to the end |
| find |
Find a matching key |
| find_last |
Find a matching key |
| operator= |
Assignment |
| params_view [constructor] |
Constructor |
| size |
Return the number of params |
| Name | Description |
|---|---|
| max_size |
Return the maximum number of characters possible |
Objects of this type are used to interpret the query parameters as a bidirectional view of key/value pairs.
The view does not retain ownership of the elements and instead references the original character buffer. The caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced.
url_view u( "?first=John&last=Doe" );
params_view p = u.params();
Percent escapes in strings returned when dereferencing iterators are automatically decoded.
can invalidate iterators which reference it.
Constructor
params_view() = default;Constructor
constexpr
params_view(params_view const& other) = default;Constructor
params_view(
params_view const& other,
encoding_opts opt) noexcept;Constructor
params_view(core::string_view s);Constructor
params_view(
core::string_view s,
encoding_opts opt);Assignment
Declared in <boost/url/params_view.hpp>
params_view&
operator=(params_view const&) = default;
After assignment, both views reference the same underlying character buffer.
Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.
this->buffer().data() == other.buffer().data()
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| parse |
Declared in <boost/url/rfc/query_rule.hpp>
system::result<_implementation-defined_>
parse(
char const*& it,
char const* end) const noexcept;
Declared in <boost/url/detail/format_args.hpp>
template
using named_arg = detail::named_arg;
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| parse |
Declared in <boost/url/rfc/absolute_uri_rule.hpp>
system::result<_implementation-defined_>
parse(
char const*& it,
char const* end) const noexcept;
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| parse |
Declared in <boost/url/rfc/ipv4_address_rule.hpp>
system::result<ipv4_address>
parse(
char const*& it,
char const* end) const noexcept;
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| parse |
Declared in <boost/url/rfc/ipv6_address_rule.hpp>
system::result<ipv6_address>
parse(
char const*& it,
char const* end) const noexcept;
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| parse | |
| pct_encoded_rule_t [constructor] |
Declared in <boost/url/rfc/pct_encoded_rule.hpp>
system::result<_implementation-defined_>
parse(
char const*& it,
char const* end) const noexcept;
Declared in <boost/url/rfc/pct_encoded_rule.hpp>
constexpr
pct_encoded_rule_t(CharSet const& cs) noexcept;
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| parse |
Declared in <boost/url/rfc/relative_ref_rule.hpp>
system::result<_implementation-defined_>
parse(
char const*& it,
char const* end) const noexcept;
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| parse |
Declared in <boost/url/rfc/uri_rule.hpp>
system::result<_implementation-defined_>
parse(
char const*& it,
char const const* end) const noexcept;
| Name | Description |
|---|---|
| value_type |
| Name | Description |
|---|---|
| parse |
Declared in <boost/url/rfc/uri_reference_rule.hpp>
system::result<_implementation-defined_>
parse(
char const*& it,
char const* end) const noexcept;
A view representing query parameters in a URL
Declared in <boost/url/params_encoded_view.hpp>
class params_encoded_view
: public params_encoded_base;
| Name | Description |
|---|---|
| const_iterator |
A Bidirectional iterator to a query parameter |
| const_reference |
The reference type |
| difference_type |
A signed integer type used to represent differences. |
| iterator |
A Bidirectional iterator to a query parameter |
| reference |
The reference type |
| size_type |
An unsigned integer type to represent sizes. |
| value_type |
The value type |
| Name | Description |
|---|---|
| begin |
Return an iterator to the beginning |
| buffer |
Return the query corresponding to these params |
| contains |
Return true if a matching key exists |
| count |
Return the number of matching keys |
| empty |
Return true if there are no params |
| end |
Return an iterator to the end |
| find |
Find a matching key |
| find_last |
Find a matching key |
| operator params_view |
Conversion |
| operator= |
Assignment |
| params_encoded_view [constructor] |
Constructor |
| size |
Return the number of params |
| Name | Description |
|---|---|
| max_size |
Return the maximum number of characters possible |
| Name | Description |
|---|---|
| parse_query |
Parse a string and return an encoded params view |
Objects of this type are used to interpret the query parameters as a bidirectional view of key/value pairs.
The view does not retain ownership of the elements and instead references the original character buffer. The caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced.
url_view u( "?first=John&last=Doe" );
params_encoded_view p = u.encoded_params();
Strings produced when elements are returned have type param_pct_view and represent encoded strings. Strings passed to member functions may contain percent escapes, and throw exceptions on invalid inputs.
can invalidate iterators which reference it.
Constructor
constexpr
params_encoded_view() = default;Constructor
constexpr
params_encoded_view(params_encoded_view const& other) = default;Constructor
params_encoded_view(core::string_view s);Assignment
Declared in <boost/url/params_encoded_view.hpp>
constexpr
params_encoded_view&
operator=(params_encoded_view const&) = default;
After assignment, both views reference the same underlying character buffer.
Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.
this->buffer().data() == other.buffer().data()
Conversion
This conversion returns a new view which references the same underlying character buffer, and whose iterators and members return ordinary strings with decoding applied to any percent escapes.
Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.
params_view qp = parse_path( "/path/to/file.txt" ).value();
params_view( *this ).buffer().data() == this->buffer().data()
Parse a string and return an encoded params view
Declared in <boost/url/params_encoded_view.hpp>
friend
system::result<params_encoded_view>
parse_query(core::string_view s) noexcept;
This function parses the string and returns the corresponding params object if the string is valid, otherwise returns an error.
query = *( pchar / "/" / "?" )
Parse a string and return an encoded params view
Declared in <boost/url/params_encoded_view.hpp>
system::result<params_encoded_view>
parse_query(core::string_view s) noexcept;
This function parses the string and returns the corresponding params object if the string is valid, otherwise returns an error.
query = *( pchar / "/" / "?" )
Parse a string and return an encoded params view
This function parses the string and returns the corresponding params object if the string is valid, otherwise returns an error.
query = *( pchar / "/" / "?" )
| Name | Description |
|---|---|
| s | |
| s |
Common functionality for containers
| Name | Description |
|---|---|
| authority |
Return the authority |
| buffer |
Return the url string |
| c_str |
Return the url as a null-terminated string |
| capacity |
Return the number of characters that can be stored without reallocating |
| clear |
Clear the contents while preserving the capacity |
| compare |
Return the result of comparing this with another url |
| data |
Return a pointer to the url's character buffer |
| empty |
Return true if the url is empty |
| encoded_authority |
Return the authority. |
| encoded_fragment |
Return the fragment |
| encoded_host |
Return the host |
| encoded_host_address |
Return the host |
| encoded_host_and_port |
Return the host and port |
| encoded_host_name |
Return the host name |
| encoded_origin |
Return the origin |
| encoded_params |
Return the query as a container of parameters |
| encoded_password |
Return the password |
| encoded_path |
Return the path |
| encoded_query |
Return the query |
| encoded_resource |
Return the resource |
| encoded_segments |
Return the path as a container of segments |
| encoded_target |
Return the target |
| encoded_user |
Return the user |
| encoded_userinfo |
Return the userinfo |
| encoded_zone_id |
Return the IPv6 Zone ID |
| fragment |
Return the fragment |
| has_authority |
Return true if an authority is present |
| has_fragment |
Return true if a fragment is present |
| has_password |
Return true if a password is present |
| has_port |
Return true if a port is present |
| has_query |
Return true if a query is present |
| has_scheme |
Return true a scheme is present |
| has_userinfo |
Return true if a userinfo is present |
| host |
Return the host |
| host_address |
Return the host |
| host_ipv4_address |
Return the host IPv4 address |
| host_ipv6_address |
Return the host IPv6 address |
| host_ipvfuture |
Return the host IPvFuture address |
| host_name |
Return the host name |
| host_type |
Return the host type |
| is_path_absolute |
Return true if the path is absolute |
| normalize |
Normalize the URL components |
| normalize_authority |
Normalize the URL authority |
| normalize_fragment |
Normalize the URL fragment |
| normalize_path |
Normalize the URL path |
| normalize_query |
Normalize the URL query |
| normalize_scheme |
Normalize the URL scheme |
| operator core::string_view |
Return the URL as a core::string_view |
| params |
Return the query as a container of parameters |
| password |
Return the password |
| path |
Return the path |
| persist |
Return a shared, persistent copy of the url |
| port |
Return the port |
| port_number |
Return the port |
| query |
Return the query |
| remove_authority |
Remove the authority |
| remove_fragment |
Remove the fragment |
| remove_origin |
Remove the origin component |
| remove_password |
Remove the password |
| remove_port |
Remove the port |
| remove_query |
Remove the query |
| remove_scheme |
Remove the scheme |
| remove_userinfo |
Remove the userinfo |
| reserve |
Adjust the capacity without changing the size |
| resolve |
Resolve a URL reference against this base URL |
| scheme |
Return the scheme |
| scheme_id |
Return the scheme |
| segments |
Return the path as a container of segments |
| set_encoded_authority |
Set the authority |
| set_encoded_fragment |
Set the fragment. |
| set_encoded_host |
Set the host |
| set_encoded_host_address |
Set the host to an address |
| set_encoded_host_name |
Set the host to a name |
| set_encoded_params |
Set the query params |
| set_encoded_password |
Set the password. |
| set_encoded_path |
Set the path. |
| set_encoded_query |
Set the query |
| set_encoded_user |
Set the user |
| set_encoded_userinfo |
Set the userinfo. |
| set_fragment |
Set the fragment. |
| set_host |
Set the host |
| set_host_address |
Set the host to an address |
| set_host_ipv4 |
Set the host to an address |
| set_host_ipv6 |
Set the host to an address |
| set_host_ipvfuture |
Set the host to an address |
| set_host_name |
Set the host to a name |
| set_params |
Set the query params |
| set_password |
Set the password. |
| set_path |
Set the path. |
| set_path_absolute |
Set if the path is absolute |
| set_port |
Set the port |
| set_port_number |
Set the port |
| set_query |
Set the query |
| set_scheme |
Set the scheme |
| set_scheme_id |
Set the scheme |
| set_user |
Set the user |
| set_userinfo |
Set the userinfo |
| size |
Return the number of characters in the url |
| user |
Return the user |
| userinfo |
Return the userinfo |
| zone_id |
Return the IPv6 Zone ID |
| Name | Description |
|---|---|
| max_size |
Return the maximum number of characters possible |
| Name | Description |
|---|---|
| operator!= |
Return the result of comparing two URLs |
| operator< |
Return the result of comparing two URLs |
| operator<< |
Format the url to the output stream |
| operator<= |
Return the result of comparing two URLs |
| operator== |
Return the result of comparing two URLs |
| operator> |
Return the result of comparing two URLs |
| operator>= |
Return the result of comparing two URLs |
| resolve |
Resolve a URL reference against a base URL |
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:
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.
assert( std::strlen( url( "http://www.example.com" ).c_str() ) == 22 );
Return the number of characters that can be stored without reallocating
This does not include the null terminator, which is always present.
Clear the contents while preserving the capacity
this->empty() == true
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()`.
Calls to allocate may throw.
| Name | Thrown on |
|---|---|
Allocation |
| Name | Description |
|---|---|
| n |
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.
assert( url( "http://www.example.com" ).set_scheme( "https" ).scheme_id() == scheme::https );
Calls to allocate may throw. Exceptions thrown on invalid input.
scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Set the scheme
This function sets the scheme to the specified known urls::scheme id, which may not be scheme::unknown or else an exception is thrown. If the id is scheme::none , this function behaves as if remove_scheme were called.
assert( url( "http://example.com/echo.cgi" ).set_scheme_id( scheme::wss ).buffer() == "wss://example.com/echo.cgi" );
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| id |
Remove the scheme
This function removes the scheme if it is present.
assert( url("http://www.example.com/index.htm" ).remove_scheme().buffer() == "//www.example.com/index.htm" );
this->has_scheme() == false && this->scheme_id() == scheme::none
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
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:
The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.
assert( url( "http://example.com" ).set_userinfo( "user:pass" ).encoded_user() == "user" );
Calls to allocate may throw.
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
| Name | Description |
|---|---|
| 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:
The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.
assert( url( "http://example.com" ).set_encoded_userinfo( "john%20doe" ).user() == "john doe" );
Calls to allocate may throw. Exceptions thrown on invalid input.
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Remove the userinfo
This function removes the userinfo if present, without removing any authority.
assert( url( "http://user@example.com" ).remove_userinfo().has_userinfo() == false );
this->has_userinfo() == false && this->encoded_userinfo().empty == true
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
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.
assert( url().set_user("john doe").encoded_userinfo() == "john%20doe" );
this->has_authority() == true && this->has_userinfo() == true
Calls to allocate may throw.
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
| Name | Description |
|---|---|
| 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.
assert( url().set_encoded_user("john%20doe").userinfo() == "john doe" );
this->has_authority() == true && this->has_userinfo() == true
Calls to allocate may throw.
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| 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.
The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.
assert( url("http://user@example.com").set_password( "pass" ).encoded_userinfo() == "user:pass" );
this->has_password() == true && this->password() == s
Calls to allocate may throw.
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
| Name | Description |
|---|---|
| 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.
The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.
assert( url("http://user@example.com").set_encoded_password( "pass" ).encoded_userinfo() == "user:pass" );
this->has_password() == true
Calls to allocate may throw.
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| 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.
The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.
assert( url( "http://user:pass@example.com" ).remove_password().authority().buffer() == "user@example.com" );
this->has_password() == false && this->encoded_password().empty() == true
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
Set the host
Depending on the contents of the passed string, this function sets the host:
In all cases, when this function returns, the URL contains an authority.
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );
this->has_authority() == true
Calls to allocate may throw.
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")
| Name | Description |
|---|---|
| s |
Set the host
Depending on the contents of the passed string, this function sets the host:
In all cases, when this function returns, the URL contains an authority.
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );
this->has_authority() == true
Calls to allocate may throw. Exceptions thrown on invalid input.
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Set the host to an address
Depending on the contents of the passed string, this function sets the host:
In all cases, when this function returns, the URL contains an authority.
assert( url( "http://www.example.com" ).set_host_address( "127.0.0.1" ).buffer() == "http://127.0.0.1" );
this->has_authority() == true
Calls to allocate may throw.
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 / "-" / ".")
| Name | Description |
|---|---|
| s |
Set the host to an address
Declared in <boost/url/url_base.hpp>
url_base&
set_encoded_host_address(pct_string_view s);
Depending on the contents of the passed string, this function sets the host:
In all cases, when this function returns, the URL contains an authority.
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );
this->has_authority() == true
Calls to allocate may throw. Exceptions thrown on invalid input.
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 / "-" / ".")
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Set the host to an address
The host is set to the specified IPv4 address. The host type is host_type::ipv4 .
assert( url("http://www.example.com").set_host_ipv4( ipv4_address( "127.0.0.1" ) ).buffer() == "http://127.0.0.1" );
this->has_authority() == true && this->host_ipv4_address() == addr && this->host_type() == host_type::ipv4
Calls to allocate may throw.
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
| Name | Description |
|---|---|
| addr |
Set the host to an address
The host is set to the specified IPv6 address. The host type is host_type::ipv6 .
assert( url().set_host_ipv6( ipv6_address( "1::6:c0a8:1" ) ).authority().buffer() == "[1::6:c0a8:1]" );
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::ipv6
Calls to allocate may throw.
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
| Name | Description |
|---|---|
| addr |
Set the host to an address
The host is set to the specified IPvFuture string. The host type is host_type::ipvfuture .
assert( url().set_host_ipvfuture( "v42.bis" ).buffer() == "//[v42.bis]" );
this->has_authority() == true && this->host_ipvfuture) == s && this->host_type() == host_type::ipvfuture
Calls to allocate may throw. Exceptions thrown on invalid input.
IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| 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 host_type::name .
assert( url( "http://www.example.com/index.htm").set_host_name( "localhost" ).host_address() == "localhost" );
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name
Calls to allocate may throw.
reg-name = *( unreserved / pct-encoded / "-" / ".")
| Name | Description |
|---|---|
| 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 host_type::name .
assert( url( "http://www.example.com/index.htm").set_encoded_host_name( "localhost" ).host_address() == "localhost" );
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name
Calls to allocate may throw. Exceptions thrown on invalid input.
reg-name = *( unreserved / pct-encoded / "-" / ".")
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Set the port
The port is set to the specified integer.
assert( url( "http://www.example.com" ).set_port_number( 8080 ).authority().buffer() == "www.example.com:8080" );
this->has_authority() == true && this->has_port() == true && this->port_number() == n
Calls to allocate may throw.
authority = [ userinfo "@" ] host [ ":" port ]
port = *DIGIT
| Name | Description |
|---|---|
| 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.
assert( url( "http://www.example.com" ).set_port( "8080" ).authority().buffer() == "www.example.com:8080" );
this->has_port() == true && this->port_number() == n && this->port() == std::to_string(n)
Calls to allocate may throw. Exceptions thrown on invalid input.
port = *DIGIT
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Remove the port
If a port exists, it is removed. The rest of the authority is unchanged.
assert( url( "http://www.example.com:80" ).remove_port().authority().buffer() == "www.example.com" );
this->has_port() == false && this->port_number() == 0 && this->port() == ""
authority = [ userinfo "@" ] host [ ":" port ]
port = *DIGIT
Set if the path is absolute
This function adjusts the path to make it absolute or not, depending on the parameter.
If an authority is present, the path is always absolute. In this case, the function has no effect.
url u( "path/to/file.txt" );
assert( u.set_path_absolute( true ) );
assert( u.buffer() == "/path/to/file.txt" );
this->is_path_absolute() == true && this->encoded_path().front() == '/'
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
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.
The library may adjust the final result to ensure that no other parts of the url is semantically affected.
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 set_encoded_path or segments should be used instead.
url u( "http://www.example.com" );
u.set_path( "path/to/file.txt" );
assert( u.path() == "/path/to/file.txt" );
Calls to allocate may throw.
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
| Name | Description |
|---|---|
| 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.
The library may adjust the final result to ensure that no other parts of the url is semantically affected.
url u( "http://www.example.com" );
u.set_encoded_path( "path/to/file.txt" );
assert( u.encoded_path() == "/path/to/file.txt" );
Calls to allocate may throw. Exceptions thrown on invalid input.
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
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Return the path as a container of segments
urls::segments_ref
segments() noexcept;Return the path as a container of segments
segments_view
segments() const noexcept;Return the path as a container of segments
segments_encoded_ref
encoded_segments() noexcept;Return the path as a container of segments
segments_encoded_view
encoded_segments() const noexcept;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.
assert( url( "http://example.com" ).set_query( "id=42" ).query() == "id=42" );
this->has_query() == true && this->query() == s
Calls to allocate may throw.
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
| Name | Description |
|---|---|
| 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.
assert( url( "http://example.com" ).set_encoded_query( "id=42" ).encoded_query() == "id=42" );
this->has_query() == true && this->query() == decode_view( s );
Calls to allocate may throw. Exceptions thrown on invalid input.
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Return the query as a container of parameters
params_ref
params() noexcept;params_view
params() const noexcept;Return the query as a container of parameters
params_ref
params(encoding_opts opt) noexcept;Return the query as a container of parameters
params_encoded_view
encoded_params() const noexcept;Return the query as a container of parameters
params_encoded_ref
encoded_params() noexcept;Set the query params
Declared in <boost/url/url_base.hpp>
url_base&
set_params(
std::initializer_list<param_view> ps,
encoding_opts opts = = {}) noexcept;
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.
assert( url( "http://example.com" ).set_params( {"id", "42"} ).query() == "id=42" );
this->has_query() == true
Calls to allocate may throw.
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
| Name | Description |
|---|---|
| ps | |
| opts |
Set the query params
Declared in <boost/url/url_base.hpp>
url_base&
set_encoded_params(std::initializer_list<param_pct_view> ps) noexcept;
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.
assert( url( "http://example.com" ).set_encoded_params( {"id", "42"} ).encoded_query() == "id=42" );
this->has_query() == true
Calls to allocate may throw. Exceptions thrown on invalid input.
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
| Name | Thrown on |
|---|---|
some |
| Name | Description |
|---|---|
| ps |
Remove the query
If a query is present, it is removed. An empty query is distinct from having no query.
assert( url( "http://www.example.com?id=42" ).remove_query().buffer() == "http://www.example.com" );
this->has_query() == false && this->params().empty()
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
Remove the fragment
This function removes the fragment. An empty fragment is distinct from having no fragment.
assert( url( "?first=john&last=doe#anchor" ).remove_fragment().buffer() == "?first=john&last=doe" );
this->has_fragment() == false && this->encoded_fragment() == ""
fragment = *( pchar / "/" / "?" )
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.
assert( url("?first=john&last=doe" ).set_encoded_fragment( "john doe" ).encoded_fragment() == "john%20doe" );
this->has_fragment() == true && this->fragment() == s
Calls to allocate may throw.
fragment = *( pchar / "/" / "?" )
| Name | Description |
|---|---|
| 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.
assert( url("?first=john&last=doe" ).set_encoded_fragment( "john%2Ddoe" ).fragment() == "john-doe" );
this->has_fragment() == true && this->fragment() == decode_view( s )
Calls to allocate may throw. Exceptions thrown on invalid input.
fragment = *( pchar / "/" / "?" )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Remove the origin component
This function removes the origin, which consists of the scheme and authority.
assert( url( "http://www.example.com/index.htm" ).remove_origin().buffer() == "/index.htm" );
this->scheme_id() == scheme::none && this->has_authority() == false
Normalize the URL components
Applies Syntax-based normalization to all components of the URL.
Calls to allocate may throw.
Normalize the URL scheme
Applies Syntax-based normalization to the URL scheme.
The scheme is normalized to lowercase.
Calls to allocate may throw.
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.
Calls to allocate may throw.
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.
Calls to allocate may throw.
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.
Calls to allocate may throw.
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 URI 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 reference within the context of a base 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:
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 result with an `system::error_code` is returned.
Abnormal hrefs where the number of ".." segments exceeds the number of segments in the base path are handled by including the unmatched ".." segments in the result, as described in Errata 4547 .
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" );
absolute-URI = scheme ":" hier-part [ "?" query ]
Calls to allocate may throw.
| Name | Description |
|---|---|
| ref |
Resolve a URL reference against a base URL
Declared in <boost/url/url_base.hpp>
friend
system::result
resolve(
url_view_base const& base,
url_view_base const& ref,
url_base& dest);
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 URI 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 reference within the context of a base 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:
This function places the result of the resolution into `dest`, which can be any of the url containers that inherit from url_base .
If an error occurs, the contents of `dest` is unspecified and `ec` is set.
Abnormal hrefs where the number of ".." segments exceeds the number of segments in the base path are handled by including the unmatched ".." segments in the result, as described in Errata 4547 .
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" );
absolute-URI = scheme ":" hier-part [ "?" query ]
Calls to allocate may throw.
A view representing query parameters in a URL
Declared in <boost/url/params_encoded_ref.hpp>
class params_encoded_ref
: public params_encoded_base;
| Name | Description |
|---|---|
| const_iterator |
A Bidirectional iterator to a query parameter |
| const_reference |
The reference type |
| difference_type |
A signed integer type used to represent differences. |
| iterator |
A Bidirectional iterator to a query parameter |
| reference |
The reference type |
| size_type |
An unsigned integer type to represent sizes. |
| value_type |
The value type |
| Name | Description |
|---|---|
| append |
Append params |
| assign |
Assign params |
| begin |
Return an iterator to the beginning |
| buffer |
Return the query corresponding to these params |
| clear |
Clear the contents of the container |
| contains |
Return true if a matching key exists |
| count |
Return the number of matching keys |
| empty |
Return true if there are no params |
| end |
Return an iterator to the end |
| erase |
Erase params |
| find |
Find a matching key |
| find_last |
Find a matching key |
| insert |
Insert params |
| operator params_encoded_view |
Conversion |
| operator= |
Assignment |
| params_encoded_ref [constructor] |
Constructor |
| replace |
Replace params |
| set |
Set a value |
| size |
Return the number of params |
| unset |
Remove the value on an element |
| url |
Return the referenced url |
| Name | Description |
|---|---|
| max_size |
Return the maximum number of characters possible |
Objects of this type are used to interpret the query parameters as a bidirectional view of key value pairs.
The view does not retain ownership of the elements and instead references the original url. The caller is responsible for ensuring that the lifetime of the referenced url extends until it is no longer referenced.
The view is modifiable; calling non-const members causes changes to the referenced url.
url u( "?first=John&last=Doe" );
params_encoded_ref p = u.encoded_params();
Strings produced when elements are returned have type param_pct_view and represent encoded strings. Strings passed to member functions may contain percent escapes, and throw exceptions on invalid inputs.
can invalidate iterators which reference it. Modifications made through the container invalidate some iterators to the underlying character buffer:
Constructor
Declared in <boost/url/params_encoded_ref.hpp>
constexpr
params_encoded_ref(params_encoded_ref const& other) = default;
After construction, both views reference the same url. Ownership is not transferred; the caller is responsible for ensuring the lifetime of the url extends until it is no longer referenced.
&this->url() == &other.url();
| Name | Description |
|---|---|
| other |
Assignment
params_encoded_ref&
operator=(params_encoded_ref const& other);Assignment
params_encoded_ref&
operator=(std::initializer_list<param_pct_view> init);Conversion
Declared in <boost/url/params_encoded_ref.hpp>
operator params_encoded_view() const noexcept;
Return the referenced url
This function returns the url referenced by the view.
url u( "?key=value" );
assert( &u.encoded_params().url() == &u );
Throws nothing.
Clear the contents of the container
All iterators are invalidated.
this->url().remove_query();
this->empty() == true && this->url().has_query() == false
Assign params
void
assign(std::initializer_list<param_pct_view> init);Assign params
template
void
assign(
FwdIt first,
FwdIt last); Append params
iterator
append(param_pct_view const& p);Append params
iterator
append(std::initializer_list<param_pct_view> init);Append params
template
iterator
append(
FwdIt first,
FwdIt last); Insert params
iterator
insert(
iterator before,
param_pct_view const& p);Insert params
iterator
insert(
iterator before,
std::initializer_list<param_pct_view> init);Insert params
template
iterator
insert(
iterator before,
FwdIt first,
FwdIt last); Erase params
iterator
erase(iterator pos) noexcept;Erase params
iterator
erase(
iterator first,
iterator last) noexcept;Erase params
std::size_t
erase(
pct_string_view key,
ignore_case_param ic = = {}) noexcept;Replace params
iterator
replace(
iterator pos,
param_pct_view const& p);Replace params
iterator
replace(
iterator from,
iterator to,
std::initializer_list<param_pct_view> init);Replace params
template
iterator
replace(
iterator from,
iterator to,
FwdIt first,
FwdIt last); Remove the value on an element
This function removes the value of an element at the specified position. After the call returns, `has_value` for the element is false.
All iterators that are equal to `pos` or come after are invalidated.
url u( "?first=John&last=Doe" );
u.encoded_params().unset( u.encoded_params().begin() );
assert( u.encoded_query() == "first&last=Doe" );
| Name | Description |
|---|---|
| pos |
Set a value
iterator
set(
iterator pos,
pct_string_view value);Set a value
iterator
set(
pct_string_view key,
pct_string_view value,
ignore_case_param ic = = {});Common functionality for containers
| Name | Description |
|---|---|
| const_iterator |
A Bidirectional iterator to a path segment |
| const_reference |
The reference type |
| difference_type |
A signed integer type used to represent differences. |
| iterator |
A Bidirectional iterator to a path segment |
| reference |
The reference type |
| size_type |
An unsigned integer type used to represent size. |
| value_type |
The value type |
| Name | Description |
|---|---|
| back |
Return the last segment |
| begin |
Return an iterator to the beginning |
| buffer |
Return the referenced character buffer. |
| empty |
Return true if there are no segments |
| end |
Return an iterator to the end |
| front |
Return the first segment |
| is_absolute |
Returns true if this references an absolute path. |
| size |
Return the number of segments |
| Name | Description |
|---|---|
| max_size |
Return the maximum number of characters possible |
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:
A Bidirectional iterator to a path segment
| Name | Description |
|---|---|
| difference_type | |
| iterator_category | |
| pointer | |
| reference | |
| value_type |
| Name | Description |
|---|---|
| iterator [constructor] | |
| operator!= | |
| operator* | |
| operator++ | |
| operator-- | |
| operator-> | |
| operator= | |
| operator== |
Objects of this type allow iteration through the segments in the path. Strings returned by iterators may contain percent escapes. The values returned are read-only; changes to segments must be made through the container instead, if the container supports modification.
The strings produced when iterators are dereferenced refer to the underlying character buffer. Ownership is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced by any container or iterator.
Declared in <boost/url/impl/segments_encoded_base.hpp>
using value_type = segments_encoded_base::value_type;
Declared in <boost/url/impl/segments_encoded_base.hpp>
using reference = segments_encoded_base::reference;
Declared in <boost/url/impl/segments_encoded_base.hpp>
using difference_type = std::ptrdiff_t;
Declared in <boost/url/impl/segments_encoded_base.hpp>
using iterator_category = std::bidirectional_iterator_tag;
constexpr
iterator() = default;constexpr
iterator(iterator const&) = default;
Declared in <boost/url/impl/segments_encoded_base.hpp>
constexpr
iterator&
operator=(iterator const&) = default;
Declared in <boost/url/impl/segments_encoded_base.hpp>
reference
operator*() const noexcept;
Declared in <boost/url/impl/segments_encoded_base.hpp>
pointer
operator->() const noexcept;
iterator&
operator++() noexcept;iterator
operator++(int) noexcept;iterator&
operator--() noexcept;iterator
operator--(int) noexcept;
Declared in <boost/url/impl/segments_encoded_base.hpp>
bool
operator==(iterator const& other) const noexcept;
Declared in <boost/url/impl/segments_encoded_base.hpp>
bool
operator!=(iterator const& other) const noexcept;
A Bidirectional iterator to a path segment
Objects of this type allow iteration through the segments in the path. Strings returned by iterators may contain percent escapes. The values returned are read-only; changes to segments must be made through the container instead, if the container supports modification.
The strings produced when iterators are dereferenced refer to the underlying character buffer. Ownership is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced by any container or iterator.
The value type
Values of this type represent a segment where unique ownership is retained by making a copy.
segments_encoded_base::value_type ps( url_view( "/path/to/file.txt" ).encoded_segments().back() );
The reference type
This is the type of value returned when iterators of the view are dereferenced.
The reference type
This is the type of value returned when iterators of the view are dereferenced.
An unsigned integer type used to represent size.
A signed integer type used to represent differences.
Return the maximum number of characters possible
Declared in <boost/url/segments_encoded_base.hpp>
constexpr
static
std::size_t
max_size() noexcept;
This represents the largest number of characters that are possible in a path, not including any null terminator.
Return the referenced character buffer.
This function returns the character buffer referenced by the view. The returned string may contain percent escapes.
assert( url_view( "/path/to/file.txt" ).encoded_segments().buffer() == "/path/to/file.txt" );
Returns true if this references an absolute path.
Absolute paths always start with a forward slash ('/').
assert( url_view( "/path/to/file.txt" ).encoded_segments().is_absolute() == true );
Return true if there are no segments
assert( ! url_view( "/index.htm" ).encoded_segments().empty() );
Return the number of segments
assert( url_view( "/path/to/file.txt" ).encoded_segments().size() == 3 );
Return the first segment
This function returns a string with the first segment of the path without any leading or trailing '/' separators. The returned string may contain percent escapes.
this->empty() == false
return *begin();
assert( url_view( "/path/to/file.txt" ).encoded_segments().front() == "path" );
Return the last segment
This function returns a string with the last segment of the path without any leading or trailing '/' separators. The returned string may contain percent escapes.
this->empty() == false
assert( url_view( "/path/to/file.txt" ).encoded_segments().back() == "file.txt" );
this->empty() == false
return *--end();
Return an iterator to the beginning
constant if `this->empty()`.
Return an iterator to the end
A view representing path segments in a URL
Declared in <boost/url/segments_encoded_view.hpp>
class segments_encoded_view
: public segments_encoded_base;
| Name | Description |
|---|---|
| const_iterator |
A Bidirectional iterator to a path segment |
| const_reference |
The reference type |
| difference_type |
A signed integer type used to represent differences. |
| iterator |
A Bidirectional iterator to a path segment |
| reference |
The reference type |
| size_type |
An unsigned integer type used to represent size. |
| value_type |
The value type |
| Name | Description |
|---|---|
| back |
Return the last segment |
| begin |
Return an iterator to the beginning |
| buffer |
Return the referenced character buffer. |
| empty |
Return true if there are no segments |
| end |
Return an iterator to the end |
| front |
Return the first segment |
| is_absolute |
Returns true if this references an absolute path. |
| operator segments_view |
Conversion |
| operator= |
Assignment |
| segments_encoded_view [constructor] |
Constructor |
| size |
Return the number of segments |
| Name | Description |
|---|---|
| max_size |
Return the maximum number of characters possible |
| Name | Description |
|---|---|
| parse_path |
Parse a string and return an encoded segment view |
Objects of this type are used to interpret the path as a bidirectional view of segment strings.
The view does not retain ownership of the elements and instead references the original character buffer. The caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced.
url_view u( "/path/to/file.txt" );
segments_encoded_view ps = u.encoded_segments();
assert( ps.buffer().data() == u.buffer().data() );
Strings produced when elements are returned have type param_pct_view and represent encoded strings. Strings passed to member functions may contain percent escapes, and throw exceptions on invalid inputs.
can invalidate iterators which reference it.
Constructor
constexpr
segments_encoded_view() = default;Constructor
constexpr
segments_encoded_view(segments_encoded_view const&) noexcept = default;Constructor
segments_encoded_view(core::string_view s);Assignment
Declared in <boost/url/segments_encoded_view.hpp>
constexpr
segments_encoded_view&
operator=(segments_encoded_view const&) = default;
After assignment, both views reference the same underlying character buffer.
Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.
this->buffer().data() == other.buffer().data()
Conversion
This conversion returns a new view which references the same underlying character buffer, and whose iterators and members return ordinary strings with decoding applied to any percent escapes.
Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.
segments_view ps = parse_path( "/path/to/file.txt" ).value();
segments_view( *this ).buffer().data() == this->buffer().data()
Parse a string and return an encoded segment view
Declared in <boost/url/segments_encoded_view.hpp>
friend
system::result<segments_encoded_view>
parse_path(core::string_view s) noexcept;
This function parses the string and returns the corresponding path object if the string is valid, otherwise returns an error.
path = [ "/" ] segment *( "/" segment )
A view representing path segments in a URL
Declared in <boost/url/segments_encoded_ref.hpp>
class segments_encoded_ref
: public segments_encoded_base;
| Name | Description |
|---|---|
| const_iterator |
A Bidirectional iterator to a path segment |
| const_reference |
The reference type |
| difference_type |
A signed integer type used to represent differences. |
| iterator |
A Bidirectional iterator to a path segment |
| reference |
The reference type |
| size_type |
An unsigned integer type used to represent size. |
| value_type |
The value type |
| Name | Description |
|---|---|
| assign |
Assign segments |
| back |
Return the last segment |
| begin |
Return an iterator to the beginning |
| buffer |
Return the referenced character buffer. |
| clear |
Clear the contents of the container |
| empty |
Return true if there are no segments |
| end |
Return an iterator to the end |
| erase |
Erase segments |
| front |
Return the first segment |
| insert |
Insert segments |
| is_absolute |
Returns true if this references an absolute path. |
| operator segments_encoded_view |
Conversion |
| operator= |
Assignment |
| pop_back |
Remove the last segment |
| push_back |
Append a segment |
| replace |
Replace segments |
| segments_encoded_ref [constructor] |
Constructor |
| size |
Return the number of segments |
| url |
Return the referenced url |
| Name | Description |
|---|---|
| max_size |
Return the maximum number of characters possible |
Objects of this type are used to interpret the path as a bidirectional view of segments, where each segment is a string which may contain percent-escapes.
The view does not retain ownership of the elements and instead references the original character buffer. The caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced.
The view is modifiable; calling non-const members causes changes to the referenced url.
url u( "/path/to/file.txt" );
segments_encoded_ref ps = u.encoded_segments();
The strings returned when iterators are dereferenced have type pct_string_view and may contain percent-escapes.
Reserved characters in inputs are automatically escaped. Escapes in inputs are preserved.
Exceptions are thrown on invalid inputs.
can invalidate iterators which reference it. Modifications made through the container invalidate some or all iterators:
Constructor
Declared in <boost/url/segments_encoded_ref.hpp>
constexpr
segments_encoded_ref(segments_encoded_ref const& other) = default;
After construction, both views reference the same url. Ownership is not transferred; the caller is responsible for ensuring the lifetime of the url extends until it is no longer referenced.
&this->url() == &other.url();
| Name | Description |
|---|---|
| other |
Assignment
segments_encoded_ref&
operator=(segments_encoded_ref const& other);segments_encoded_ref&
operator=(segments_encoded_view const& other);Assignment
segments_encoded_ref&
operator=(std::initializer_list<pct_string_view> init);Conversion
Declared in <boost/url/segments_encoded_ref.hpp>
operator segments_encoded_view() const noexcept;
Return the referenced url
This function returns the url referenced by the view.
url u( "/path/to/file.txt" );
assert( &u.encoded_segments().url() == &u );
Clear the contents of the container
All iterators are invalidated.
this->url().set_encoded_path( "" );
this->empty() == true
Assign segments
void
assign(std::initializer_list<pct_string_view> init);Assign segments
template
void
assign(
FwdIt first,
FwdIt last); Insert segments
iterator
insert(
iterator before,
pct_string_view s);Insert segments
iterator
insert(
iterator before,
std::initializer_list<pct_string_view> init);Insert segments
template
iterator
insert(
iterator before,
FwdIt first,
FwdIt last); Erase segments
iterator
erase(iterator pos) noexcept;Erase segments
iterator
erase(
iterator first,
iterator last) noexcept;Replace segments
iterator
replace(
iterator pos,
pct_string_view s);Replace segments
iterator
replace(
iterator from,
iterator to,
pct_string_view s);Replace segments
iterator
replace(
iterator from,
iterator to,
std::initializer_list<pct_string_view> init);Replace segments
template
iterator
replace(
iterator from,
iterator to,
FwdIt first,
FwdIt last); Append a segment
This function appends a segment to the end of the path. Reserved characters in the string are automatically escaped. Escapes in the string are preserved.
All end iterators are invalidated.
this->back() == s
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| s |
Remove the last segment
This function removes the last segment from the container.
Iterators to the last segment as well as all end iterators are invalidated.
not this->empty()
Common functionality for containers
| Name | Description |
|---|---|
| const_iterator |
A Bidirectional iterator to a path segment |
| const_reference |
The reference type |
| difference_type |
A signed integer type used to represent differences. |
| iterator |
A Bidirectional iterator to a path segment |
| reference |
The reference type |
| size_type |
An unsigned integer type used to represent size. |
| value_type |
The value type |
| Name | Description |
|---|---|
| back |
Return the last segment |
| begin |
Return an iterator to the beginning |
| buffer |
Return the referenced character buffer. |
| empty |
Return true if there are no segments |
| end |
Return an iterator to the end |
| front |
Return the first segment |
| is_absolute |
Returns true if this references an absolute path. |
| size |
Return the number of segments |
| Name | Description |
|---|---|
| max_size |
Return the maximum number of characters possible |
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:
A Bidirectional iterator to a path segment
| Name | Description |
|---|---|
| difference_type | |
| iterator_category | |
| pointer | |
| reference | |
| value_type |
| Name | Description |
|---|---|
| iterator [constructor] | |
| operator!= | |
| operator* | |
| operator++ | |
| operator-- | |
| operator-> | |
| operator= | |
| operator== |
Objects of this type allow iteration through the segments in the path. Any percent-escapes in returned strings are decoded first. The values returned are read-only; changes to segments must be made through the container instead, if the container supports modification.
The strings produced when iterators are dereferenced belong to the iterator and become invalidated when that particular iterator is incremented, decremented, or destroyed.
Declared in <boost/url/impl/segments_base.hpp>
using value_type = segments_base::value_type;
Declared in <boost/url/impl/segments_base.hpp>
using difference_type = segments_base::difference_type;
Declared in <boost/url/impl/segments_base.hpp>
using iterator_category = std::bidirectional_iterator_tag;
constexpr
iterator() = default;constexpr
iterator(iterator const&) = default;
Declared in <boost/url/impl/segments_base.hpp>
constexpr
iterator&
operator=(iterator const&) noexcept = default;
iterator&
operator++() noexcept;iterator
operator++(int) noexcept;iterator&
operator--() noexcept;iterator
operator--(int) noexcept;
Declared in <boost/url/impl/segments_base.hpp>
bool
operator==(iterator const& other) const noexcept;
Declared in <boost/url/impl/segments_base.hpp>
bool
operator!=(iterator const& other) const noexcept;
A Bidirectional iterator to a path segment
Objects of this type allow iteration through the segments in the path. Any percent-escapes in returned strings are decoded first. The values returned are read-only; changes to segments must be made through the container instead, if the container supports modification.
The strings produced when iterators are dereferenced belong to the iterator and become invalidated when that particular iterator is incremented, decremented, or destroyed.
The value type
Values of this type represent a segment where unique ownership is retained by making a copy.
segments_base::value_type ps( url_view( "/path/to/file.txt" ).segments().back() );
The reference type
This is the type of value returned when iterators of the view are dereferenced.
The reference type
This is the type of value returned when iterators of the view are dereferenced.
An unsigned integer type used to represent size.
A signed integer type used to represent differences.
Return the maximum number of characters possible
Declared in <boost/url/segments_base.hpp>
constexpr
static
std::size_t
max_size() noexcept;
This represents the largest number of characters that are possible in a path, not including any null terminator.
Return the referenced character buffer.
This function returns the character buffer referenced by the view. The returned string may contain percent escapes.
assert( url_view( "/path/to/file.txt" ).segments().buffer() == "/path/to/file.txt" );
Returns true if this references an absolute path.
Absolute paths always start with a forward slash ('/').
assert( url_view( "/path/to/file.txt" ).segments().is_absolute() == true );
Return true if there are no segments
assert( ! url_view( "/index.htm" ).segments().empty() );
Return the number of segments
assert( url_view( "/path/to/file.txt" ).segments().size() == 3 );
Return the first segment
This function returns a string with the first segment of the path without any leading or trailing '/' separators. Any percent-escapes in the string are decoded first.
this->empty() == false
return *begin();
assert( url_view( "/path/to/file.txt" ).segments().front() == "path" );
Return the last segment
this->empty() == false
assert( url_view( "/path/to/file.txt" ).segments().back() == "file.txt" );
this->empty() == false
return *--end();
Return an iterator to the beginning
constant if `this->empty()`.
Return an iterator to the end
A view representing path segments in a URL
| Name | Description |
|---|---|
| const_iterator |
A Bidirectional iterator to a path segment |
| const_reference |
The reference type |
| difference_type |
A signed integer type used to represent differences. |
| iterator |
A Bidirectional iterator to a path segment |
| reference |
The reference type |
| size_type |
An unsigned integer type used to represent size. |
| value_type |
The value type |
| Name | Description |
|---|---|
| back |
Return the last segment |
| begin |
Return an iterator to the beginning |
| buffer |
Return the referenced character buffer. |
| empty |
Return true if there are no segments |
| end |
Return an iterator to the end |
| front |
Return the first segment |
| is_absolute |
Returns true if this references an absolute path. |
| operator= |
Assignment |
| segments_view [constructor] |
Constructor |
| size |
Return the number of segments |
| Name | Description |
|---|---|
| max_size |
Return the maximum number of characters possible |
Objects of this type are used to interpret the path as a bidirectional view of segment strings.
The view does not retain ownership of the elements and instead references the original character buffer. The caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced.
url_view u( "/path/to/file.txt" );
segments_view ps = u.segments();
assert( ps.buffer().data() == u.buffer().data() );
Percent escapes in strings returned when dereferencing iterators are automatically decoded.
can invalidate iterators which reference it.
segments_encoded_view , segments_encoded_ref , segments_ref .
Constructor
constexpr
segments_view() = default;Constructor
constexpr
segments_view(segments_view const& other) = default;Constructor
segments_view(core::string_view s);Assignment
Declared in <boost/url/segments_view.hpp>
constexpr
segments_view&
operator=(segments_view const& other) = default;
After assignment, both views reference the same underlying character buffer.
Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.
this->buffer().data() == other.buffer().data()
A view representing path segments in a URL
| Name | Description |
|---|---|
| const_iterator |
A Bidirectional iterator to a path segment |
| const_reference |
The reference type |
| difference_type |
A signed integer type used to represent differences. |
| iterator |
A Bidirectional iterator to a path segment |
| reference |
The reference type |
| size_type |
An unsigned integer type used to represent size. |
| value_type |
The value type |
| Name | Description |
|---|---|
| assign |
Assign segments |
| back |
Return the last segment |
| begin |
Return an iterator to the beginning |
| buffer |
Return the referenced character buffer. |
| clear |
Clear the contents of the container |
| empty |
Return true if there are no segments |
| end |
Return an iterator to the end |
| erase |
Erase segments |
| front |
Return the first segment |
| insert |
Insert segments |
| is_absolute |
Returns true if this references an absolute path. |
| operator segments_view |
Conversion |
| operator= |
Assignment |
| pop_back |
Remove the last segment |
| push_back |
Append a segment |
| replace |
Replace segments |
| segments_ref [constructor] |
Constructor |
| size |
Return the number of segments |
| url |
Return the referenced url |
| Name | Description |
|---|---|
| max_size |
Return the maximum number of characters possible |
Objects of this type are used to interpret the path as a bidirectional view of segments, where each segment is a string with percent escapes automatically decoded.
The view does not retain ownership of the elements and instead references the original character buffer. The caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced.
The view is modifiable; calling non-const members causes changes to the referenced url.
url u( "/path/to/file.txt" );
segments_ref ps = u.segments();
Percent escapes in strings returned when dereferencing iterators are automatically decoded. Reserved characters in strings supplied to modifier functions are automatically percent-escaped.
can invalidate iterators which reference it. Modifications made through the container invalidate some or all iterators:
segments_encoded_ref , segments_encoded_view , segments_view .
Constructor
Declared in <boost/url/segments_ref.hpp>
constexpr
segments_ref(segments_ref const& other) = default;
After construction, both views reference the same url. Ownership is not transferred; the caller is responsible for ensuring the lifetime of the url extends until it is no longer referenced.
&this->url() == &other.url();
| Name | Description |
|---|---|
| other |
Assignment
segments_ref&
operator=(segments_ref const& other);segments_ref&
operator=(segments_view const& other);Assignment
segments_ref&
operator=(std::initializer_list init); Conversion
Return the referenced url
This function returns the url referenced by the view.
url u( "/path/to/file.txt" );
assert( &u.segments().url() == &u );
Clear the contents of the container
All iterators are invalidated.
this->url().set_encoded_path( "" );
this->empty() == true
Assign segments
void
assign(std::initializer_list init); Assign segments
template
void
assign(
FwdIt first,
FwdIt last); Insert segments
iterator
insert(
iterator before,
core::string_view s);Insert segments
iterator
insert(
iterator before,
std::initializer_list init); Insert segments
template
iterator
insert(
iterator before,
FwdIt first,
FwdIt last); Erase segments
iterator
erase(iterator pos) noexcept;Erase segments
iterator
erase(
iterator first,
iterator last) noexcept;Replace segments
iterator
replace(
iterator pos,
core::string_view s);Replace segments
iterator
replace(
iterator from,
iterator to,
core::string_view s);Replace segments
iterator
replace(
iterator from,
iterator to,
std::initializer_list init); Replace segments
template
iterator
replace(
iterator from,
iterator to,
FwdIt first,
FwdIt last); Append a segment
This function appends a segment to the end of the path. Reserved characters in the string are automatically escaped.
All end iterators are invalidated.
this->back() == s
Calls to allocate may throw.
| Name | Description |
|---|---|
| s |
Remove the last segment
This function removes the last segment from the container.
Iterators to the last segment as well as all end iterators are invalidated.
not this->empty()
Parse a string and return an encoded segment view
Declared in <boost/url/segments_encoded_view.hpp>
system::result<segments_encoded_view>
parse_path(core::string_view s) noexcept;
This function parses the string and returns the corresponding path object if the string is valid, otherwise returns an error.
path = [ "/" ] segment *( "/" segment )
Parse a string and return an encoded segment view
This function parses the string and returns the corresponding path object if the string is valid, otherwise returns an error.
path = [ "/" ] segment *( "/" segment )
| Name | Description |
|---|---|
| s | |
| s |
Common functionality for containers
| Name | Description |
|---|---|
| authority |
Return the authority |
| buffer |
Return the url string |
| compare |
Return the result of comparing this with another url |
| data |
Return a pointer to the url's character buffer |
| empty |
Return true if the url is empty |
| encoded_authority |
Return the authority. |
| encoded_fragment |
Return the fragment |
| encoded_host |
Return the host |
| encoded_host_address |
Return the host |
| encoded_host_and_port |
Return the host and port |
| encoded_host_name |
Return the host name |
| encoded_origin |
Return the origin |
| encoded_params |
Return the query as a container of parameters |
| encoded_password |
Return the password |
| encoded_path |
Return the path |
| encoded_query |
Return the query |
| encoded_resource |
Return the resource |
| encoded_segments |
Return the path as a container of segments |
| encoded_target |
Return the target |
| encoded_user |
Return the user |
| encoded_userinfo |
Return the userinfo |
| encoded_zone_id |
Return the IPv6 Zone ID |
| fragment |
Return the fragment |
| has_authority |
Return true if an authority is present |
| has_fragment |
Return true if a fragment is present |
| has_password |
Return true if a password is present |
| has_port |
Return true if a port is present |
| has_query |
Return true if a query is present |
| has_scheme |
Return true a scheme is present |
| has_userinfo |
Return true if a userinfo is present |
| host |
Return the host |
| host_address |
Return the host |
| host_ipv4_address |
Return the host IPv4 address |
| host_ipv6_address |
Return the host IPv6 address |
| host_ipvfuture |
Return the host IPvFuture address |
| host_name |
Return the host name |
| host_type |
Return the host type |
| is_path_absolute |
Return true if the path is absolute |
| operator core::string_view |
Return the URL as a core::string_view |
| params |
Return the query as a container of parameters |
| password |
Return the password |
| path |
Return the path |
| persist |
Return a shared, persistent copy of the url |
| port |
Return the port |
| port_number |
Return the port |
| query |
Return the query |
| scheme |
Return the scheme |
| scheme_id |
Return the scheme |
| segments |
Return the path as a container of segments |
| size |
Return the number of characters in the url |
| user |
Return the user |
| userinfo |
Return the userinfo |
| zone_id |
Return the IPv6 Zone ID |
| Name | Description |
|---|---|
| max_size |
Return the maximum number of characters possible |
| Name | Description |
|---|---|
| operator!= |
Return the result of comparing two URLs |
| operator< |
Return the result of comparing two URLs |
| operator<< |
Format the url to the output stream |
| operator<= |
Return the result of comparing two URLs |
| operator== |
Return the result of comparing two URLs |
| operator> |
Return the result of comparing two URLs |
| operator>= |
Return the result of comparing two URLs |
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:
Return the maximum number of characters possible
Declared in <boost/url/url_view_base.hpp>
constexpr
static
std::size_t
max_size() noexcept;
This represents the largest number of characters that are theoretically possible to represent in a url, not including any null terminator. In practice the actual possible size may be lower than this number.
Return the number of characters in the url
This function returns the number of characters in the url's encoded string, not including any null terminator, if present.
assert( url_view( "file:///Program%20Files" ).size() == 23 );
Return true if the url is empty
The empty string matches the relative-ref grammar.
assert( url_view( "" ).empty() );
relative-ref = relative-part [ "?" query ] [ "#" fragment ]
relative-part = "//" authority path-abempty
/ path-absolute
/ path-noscheme
/ path-empty
Return a pointer to the url's character buffer
This function returns a pointer to the first character of the url, which is not guaranteed to be null-terminated.
Return the url string
This function returns the entire url, which may contain percent escapes.
assert( url_view( "http://www.example.com" ).buffer() == "http://www.example.com" );
Return the URL as a core::string_view
Return a shared, persistent copy of the url
This function returns a read-only copy of the url, with shared lifetime. The returned value owns (persists) the underlying string. The algorithm used to create the value minimizes the number of individual memory allocations, making it more efficient than when using direct standard library functions.
std::shared_ptr< url_view const > sp;
{
std::string s( "http://example.com" );
url_view u( s ); // u references characters in s
assert( u.data() == s.data() ); // same buffer
sp = u.persist();
assert( sp->data() != s.data() ); // different buffer
assert( sp->buffer() == s); // same contents
// s is destroyed and thus u
// becomes invalid, but sp remains valid.
}
Return true a scheme is present
This function returns true if this contains a scheme.
assert( url_view( "http://www.example.com" ).has_scheme() );
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
absolute-URI = scheme ":" hier-part [ "?" query ]
scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
Return the scheme
This function returns the scheme if it exists, without a trailing colon (':'). Otherwise it returns an empty string. Note that schemes are case-insensitive, and the canonical form is lowercased.
assert( url_view( "http://www.example.com" ).scheme() == "http" );
scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
absolute-URI = scheme ":" hier-part [ "?" query ]
Return the scheme
This function returns a value which depends on the scheme in the url:
assert( url_view( "wss://www.example.com/crypto.cgi" ).scheme_id() == scheme::wss );
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
absolute-URI = scheme ":" hier-part [ "?" query ]
scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
Return true if a userinfo is present
This function returns true if this contains a userinfo.
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_userinfo() );
userinfo = user [ ":" [ password ] ]
authority = [ userinfo "@" ] host [ ":" port ]
Return true if a password is present
This function returns true if the userinfo is present and contains a password.
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_password() );
userinfo = user [ ":" [ password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
Return the userinfo
Declared in <boost/url/url_view_base.hpp>
templatestring_token::return_string>
StringToken::result_type
userinfo(StringToken&& token) const;
If present, this function returns a string representing the userinfo (which may be empty). Otherwise it returns an empty string. Any percent-escapes in the string are decoded first.
This function uses the string token return type customization. Depending on the token passed, the return type and behavior of the function can be different. See string_token::return_string for more information.
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).userinfo() == "jane-doe:pass" );
userinfo = user [ ":" [ password ] ]
authority = [ userinfo "@" ] host [ ":" port ]
Return the userinfo
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_userinfo() const noexcept;
If present, this function returns a string representing the userinfo (which may be empty). Otherwise it returns an empty string. The returned string may contain percent escapes.
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_userinfo() == "jane%2Ddoe:pass" );
userinfo = user [ ":" [ password ] ]
authority = [ userinfo "@" ] host [ ":" port ]
Return the user
Declared in <boost/url/url_view_base.hpp>
templatestring_token::return_string>
StringToken::result_type
user(StringToken&& token) const;
If present, this function returns a string representing the user (which may be empty). Otherwise it returns an empty string. Any percent-escapes in the string are decoded first.
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).user() == "jane-doe" );
userinfo = user [ ":" [ password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
Return the user
If present, this function returns a string representing the user (which may be empty). Otherwise it returns an empty string. The returned string may contain percent escapes.
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_user() == "jane%2Ddoe" );
userinfo = user [ ":" [ password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
Return the password
Declared in <boost/url/url_view_base.hpp>
templatestring_token::return_string>
StringToken::result_type
password(StringToken&& token) const;
If present, this function returns a string representing the password (which may be an empty string). Otherwise it returns an empty string. Any percent-escapes in the string are decoded first.
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).password() == "pass" );
userinfo = user [ ":" [ password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
Return the password
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_password() const noexcept;
This function returns the password portion of the userinfo as a percent-encoded string.
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_password() == "pass" );
userinfo = user [ ":" [ password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
Return the host type
This function returns one of the following constants representing the type of host present.
When has_authority is false, the host type is host_type::none .
assert( url_view( "https://192.168.0.1/local.htm" ).host_type() == host_type::ipv4 );
Return the host
Declared in <boost/url/url_view_base.hpp>
templatestring_token::return_string>
StringToken::result_type
host(StringToken&& token) const;
This function returns the host portion of the authority as a string, or the empty string if there is no authority. Any percent-escapes in the string are decoded first.
assert( url_view( "https://www%2droot.example.com/" ).host() == "www-root.example.com" );
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")
Return the host
This function returns the host portion of the authority as a string, or the empty string if there is no authority. The returned string may contain percent escapes.
assert( url_view( "https://www%2droot.example.com/" ).encoded_host() == "www%2droot.example.com" );
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")
Return the host
Declared in <boost/url/url_view_base.hpp>
templatestring_token::return_string>
StringToken::result_type
host_address(StringToken&& token) const;
The value returned by this function depends on the type of host returned from the function host_type .
assert( url_view( "https://[1::6:c0a8:1]/" ).host_address() == "1::6:c0a8:1" );
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")
Return the host
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_host_address() const noexcept;
The value returned by this function depends on the type of host returned from the function host_type .
assert( url_view( "https://www%2droot.example.com/" ).encoded_host_address() == "www%2droot.example.com" );
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")
Return the host IPv4 address
If the host type is host_type::ipv4 , this function returns the address as a value of type ipv4_address . Otherwise, if the host type is not an IPv4 address, it returns a default-constructed value which is equal to the unspecified address "0.0.0.0".
assert( url_view( "http://127.0.0.1/index.htm?user=win95" ).host_ipv4_address() == ipv4_address( "127.0.0.1" ) );
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
Return the host IPv6 address
If the host type is host_type::ipv6 , this function returns the address as a value of type ipv6_address . Otherwise, if the host type is not an IPv6 address, it returns a default-constructed value which is equal to the unspecified address "0:0:0:0:0:0:0:0".
assert( url_view( "ftp://[::1]/" ).host_ipv6_address() == ipv6_address( "::1" ) );
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
Return the host IPvFuture address
Declared in <boost/url/url_view_base.hpp>
core::string_view
host_ipvfuture() const noexcept;
If the host type is host_type::ipvfuture , this function returns the address as a string. Otherwise, if the host type is not an IPvFuture address, it returns an empty string.
assert( url_view( "http://[v1fe.d:9]/index.htm" ).host_ipvfuture() == "v1fe.d:9" );
IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )
Return the host name
Declared in <boost/url/url_view_base.hpp>
templatestring_token::return_string>
StringToken::result_type
host_name(StringToken&& token) const;
If the host type is host_type::name , this function returns the name as a string. Otherwise an empty string is returned. Any percent-escapes in the string are decoded first.
assert( url_view( "https://www%2droot.example.com/" ).host_name() == "www-root.example.com" );
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")
Return the host name
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_host_name() const noexcept;
If the host type is host_type::name , this function returns the name as a string. Otherwise, if the host type is not an name, it returns an empty string. The returned string may contain percent escapes.
assert( url_view( "https://www%2droot.example.com/" ).encoded_host_name() == "www%2droot.example.com" );
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")
Return the IPv6 Zone ID
Declared in <boost/url/url_view_base.hpp>
templatestring_token::return_string>
StringToken::result_type
zone_id(StringToken&& token) const;
If the host type is host_type::ipv6 , this function returns the Zone ID as a string. Otherwise an empty string is returned. Any percent-escapes in the string are decoded first.
assert( url_view( "http://[fe80::1%25eth0]/" ).zone_id() == "eth0" );
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPv6addrz / IPvFuture ) "]"
ZoneID = 1*( unreserved / pct-encoded )
IPv6addrz = IPv6address "%25" ZoneID
Return the IPv6 Zone ID
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_zone_id() const noexcept;
If the host type is host_type::ipv6 , this function returns the Zone ID as a string. Otherwise an empty string is returned. The returned string may contain percent escapes.
assert( url_view( "http://[fe80::1%25eth0]/" ).encoded_zone_id() == "eth0" );
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPv6addrz / IPvFuture ) "]"
ZoneID = 1*( unreserved / pct-encoded )
IPv6addrz = IPv6address "%25" ZoneID
Return true if a port is present
This function returns true if an authority is present and contains a port.
assert( url_view( "wss://www.example.com:443" ).has_port() );
authority = [ userinfo "@" ] host [ ":" port ]
port = *DIGIT
Return the port
If present, this function returns a string representing the port (which may be empty). Otherwise it returns an empty string.
assert( url_view( "http://localhost.com:8080" ).port() == "8080" );
port = *DIGIT
Return the port
If a port is present and the numerical value is representable, it is returned as an unsigned integer. Otherwise, the number zero is returned.
assert( url_view( "http://localhost.com:8080" ).port_number() == 8080 );
port = *DIGIT
Return true if the path is absolute
This function returns true if the path begins with a forward slash ('/').
assert( url_view( "/path/to/file.txt" ).is_path_absolute() );
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
Return the path
Declared in <boost/url/url_view_base.hpp>
templatestring_token::return_string>
StringToken::result_type
path(StringToken&& token) const;
This function returns the path as a string. The path may be empty. Any percent-escapes in the string are decoded first.
assert( url_view( "file:///Program%20Files/Games/config.ini" ).path() == "/Program Files/Games/config.ini" );
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
Return the path
This function returns the path as a string. The path may be empty. Any percent-escapes in the string are decoded first.
assert( url_view( "file:///Program%20Files/Games/config.ini" ).encoded_path() == "/Program%20Files/Games/config.ini" );
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
Return the path as a container of segments
This function returns a bidirectional view of strings 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.
segments_view sv = url_view( "/path/to/file.txt" ).segments();
path = [ "/" ] segment *( "/" segment )
Return the path as a container of segments
Declared in <boost/url/url_view_base.hpp>
segments_encoded_view
encoded_segments() const noexcept;
This function returns a bidirectional view of strings 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.
segments_encoded_view sv = url_view( "/path/to/file.txt" ).encoded_segments();
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
Return true if a query is present
This function returns true if this contains a query. An empty query is distinct from having no query.
assert( url_view( "/sql?id=42&col=name&page-size=20" ).has_query() );
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
Return the query
Declared in <boost/url/url_view_base.hpp>
templatestring_token::return_string>
StringToken::result_type
query(StringToken&& token) const;
If this contains a query, it is returned as a string (which may be empty). Otherwise, an empty string is returned. Any percent-escapes in the string are decoded first. When plus signs appear in the query portion of the url, they are converted to spaces automatically upon decoding. This behavior can be changed by setting decode options.
assert( url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).query() == "id=42&name=jane-doe&page size=20" );
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
Return the query
If this contains a query, it is returned as a string (which may be empty). Otherwise, an empty string is returned. The returned string may contain percent escapes.
assert( url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_query() == "id=42&name=jane%2Ddoe&page+size=20" );
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
Return the query as a container of parameters
params_view
params() const noexcept;params_view
params(encoding_opts opt) const noexcept;Return the query as a container of parameters
Declared in <boost/url/url_view_base.hpp>
params_encoded_view
encoded_params() const noexcept;
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.
params_encoded_view pv = url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_params();
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
Return true if a fragment is present
This function returns true if the url contains a fragment. An empty fragment is distinct from no fragment.
assert( url_view( "http://www.example.com/index.htm#anchor" ).has_fragment() );
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
relative-ref = relative-part [ "?" query ] [ "#" fragment ]
Return the fragment
Declared in <boost/url/url_view_base.hpp>
templatestring_token::return_string>
StringToken::result_type
fragment(StringToken&& token) const;
This function calculates the fragment of the url, with percent escapes decoded and without the leading pound sign ('#') whose presence indicates that the url contains a fragment.
This function accepts an optional StringToken parameter which controls the return type and behavior of the function:
assert( url_view( "http://www.example.com/index.htm#a%2D1" ).fragment() == "a-1" );
String tokens may throw exceptions.
fragment = *( pchar / "/" / "?" )
fragment-part = [ "#" fragment ]
| Name | Description |
|---|---|
| token |
Return the fragment
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_fragment() const noexcept;
This function returns the fragment as a string with percent-escapes. Ownership is not transferred; the string returned references the underlying character buffer, which must remain valid or else undefined behavior occurs.
assert( url_view( "http://www.example.com/index.htm#a%2D1" ).encoded_fragment() == "a%2D1" );
fragment = *( pchar / "/" / "?" )
pchar = unreserved / pct-encoded / sub-delims / ":" / "@"
Return the host and port
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_host_and_port() const noexcept;
If an authority is present, this function returns the host and optional port as a string, which may be empty. Otherwise it returns an empty string. The returned string may contain percent escapes.
assert( url_view( "http://www.example.com:8080/index.htm" ).encoded_host_and_port() == "www.example.com:8080" );
authority = [ userinfo "@" ] host [ ":" port ]
Return the origin
If an authority is present, this function returns the scheme and authority portion of the url. Otherwise, an empty string is returned. The returned string may contain percent escapes.
assert( url_view( "http://www.example.com:8080/index.htm?text=none#h1" ).encoded_origin() == "http://www.example.com:8080" );
Return the resource
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_resource() const noexcept;
This function returns the resource, which is the portion of the url that includes only the path, query, and fragment. The returned string may contain percent escapes.
assert( url_view( "http://www.example.com/index.html?query#frag" ).encoded_resource() == "/index.html?query#frag" );
Return the target
This function returns the target, which is the portion of the url that includes only the path and query. The returned string may contain percent escapes.
assert( url_view( "http://www.example.com/index.html?query#frag" ).encoded_target() == "/index.html?query" );
Return the result of comparing this with another url
Declared in <boost/url/url_view_base.hpp>
int
compare(url_view_base const& other) const noexcept;
This function compares two URLs according to Syntax-Based comparison algorithm.
Return the result of comparing two URLs
Declared in <boost/url/url_view_base.hpp>
friend
bool
operator==(
url_view_base const& u0,
url_view_base const& u1) noexcept;
The URLs are compared component by component as if they were first normalized.
url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.a.com/index.htm" );
assert( u0 == u1 );
url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() == b.buffer();
Return the result of comparing two URLs
Declared in <boost/url/url_view_base.hpp>
friend
bool
operator!=(
url_view_base const& u0,
url_view_base const& u1) noexcept;
The URLs are compared component by component as if they were first normalized.
url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.b.com/index.htm" );
assert( u0 != u1 );
url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() != b.buffer();
Return the result of comparing two URLs
Declared in <boost/url/url_view_base.hpp>
friend
bool
operator<(
url_view_base const& u0,
url_view_base const& u1) noexcept;
The URLs are compared component by component as if they were first normalized.
url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.b.com/index.htm" );
assert( u0 < u1 );
url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() < b.buffer();
Return the result of comparing two URLs
Declared in <boost/url/url_view_base.hpp>
friend
bool
operator<=(
url_view_base const& u0,
url_view_base const& u1) noexcept;
The URLs are compared component by component as if they were first normalized.
url_view u0( "http://www.b.com/index.htm" );
url_view u1( "http://www.b.com/index.htm" );
assert( u0 <= u1 );
url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() <= b.buffer();
Return the result of comparing two URLs
Declared in <boost/url/url_view_base.hpp>
friend
bool
operator>(
url_view_base const& u0,
url_view_base const& u1) noexcept;
The URLs are compared component by component as if they were first normalized.
url_view u0( "http://www.b.com/index.htm" );
url_view u1( "http://www.a.com/index.htm" );
assert( u0 > u1 );
url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() > b.buffer();
Return the result of comparing two URLs
Declared in <boost/url/url_view_base.hpp>
friend
bool
operator>=(
url_view_base const& u0,
url_view_base const& u1) noexcept;
The URLs are compared component by component as if they were first normalized.
url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.a.com/index.htm" );
assert( u0 >= u1 );
url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() >= b.buffer();
Format the url to the output stream
Declared in <boost/url/url_view_base.hpp>
friend
std::ostream&
operator<<(
std::ostream& os,
url_view_base const& u);
This function serializes the url to the specified output stream. Any percent-escapes are emitted as-is; no decoding is performed.
url_view u( "http://www.example.com/index.htm" );
std::stringstream ss;
ss << u;
assert( ss.str() == "http://www.example.com/index.htm" );
return os << u.buffer();
Resolve a URL reference against a base URL
Declared in <boost/url/url_base.hpp>
system::result
resolve(
url_view_base const& base,
url_view_base const& ref,
url_base& dest);
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 URI 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 reference within the context of a base 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:
This function places the result of the resolution into `dest`, which can be any of the url containers that inherit from url_base .
If an error occurs, the contents of `dest` is unspecified and `ec` is set.
Abnormal hrefs where the number of ".." segments exceeds the number of segments in the base path are handled by including the unmatched ".." segments in the result, as described in Errata 4547 .
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" );
absolute-URI = scheme ":" hier-part [ "?" query ]
Calls to allocate may throw.
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 URI 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 reference within the context of a base 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:
This function places the result of the resolution into `dest`, which can be any of the url containers that inherit from url_base .
If an error occurs, the contents of `dest` is unspecified and `ec` is set.
Abnormal hrefs where the number of ".." segments exceeds the number of segments in the base path are handled by including the unmatched ".." segments in the result, as described in Errata 4547 .
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" );
absolute-URI = scheme ":" hier-part [ "?" query ]
Calls to allocate may throw.
| Name | Description |
|---|---|
| base | |
| ref | |
| dest | |
| base | |
| ref | |
| dest |
A modifiable container for a URL.
| Name | Description |
|---|---|
| authority |
Return the authority |
| buffer |
Return the url string |
| c_str |
Return the url as a null-terminated string |
| capacity |
Return the number of characters that can be stored without reallocating |
| clear |
Clear the contents while preserving the capacity |
| compare |
Return the result of comparing this with another url |
| data |
Return a pointer to the url's character buffer |
| empty |
Return true if the url is empty |
| encoded_authority |
Return the authority. |
| encoded_fragment |
Return the fragment |
| encoded_host |
Return the host |
| encoded_host_address |
Return the host |
| encoded_host_and_port |
Return the host and port |
| encoded_host_name |
Return the host name |
| encoded_origin |
Return the origin |
| encoded_params |
Return the query as a container of parameters |
| encoded_password |
Return the password |
| encoded_path |
Return the path |
| encoded_query |
Return the query |
| encoded_resource |
Return the resource |
| encoded_segments |
Return the path as a container of segments |
| encoded_target |
Return the target |
| encoded_user |
Return the user |
| encoded_userinfo |
Return the userinfo |
| encoded_zone_id |
Return the IPv6 Zone ID |
| fragment |
Return the fragment |
| has_authority |
Return true if an authority is present |
| has_fragment |
Return true if a fragment is present |
| has_password |
Return true if a password is present |
| has_port |
Return true if a port is present |
| has_query |
Return true if a query is present |
| has_scheme |
Return true a scheme is present |
| has_userinfo |
Return true if a userinfo is present |
| host |
Return the host |
| host_address |
Return the host |
| host_ipv4_address |
Return the host IPv4 address |
| host_ipv6_address |
Return the host IPv6 address |
| host_ipvfuture |
Return the host IPvFuture address |
| host_name |
Return the host name |
| host_type |
Return the host type |
| is_path_absolute |
Return true if the path is absolute |
| normalize |
Normalize the URL components |
| normalize_authority |
Normalize the URL authority |
| normalize_fragment |
Normalize the URL fragment |
| normalize_path |
Normalize the URL path |
| normalize_query |
Normalize the URL query |
| normalize_scheme |
Normalize the URL scheme |
| operator core::string_view |
Return the URL as a core::string_view |
| operator= |
Assignment |
| params |
Return the query as a container of parameters |
| password |
Return the password |
| path |
Return the path |
| persist |
Return a shared, persistent copy of the url |
| port |
Return the port |
| port_number |
Return the port |
| query |
Return the query |
| remove_authority |
Remove the authority |
| remove_fragment |
Remove the fragment |
| remove_origin |
Remove the origin component |
| remove_password |
Remove the password |
| remove_port |
Remove the port |
| remove_query |
Remove the query |
| remove_scheme |
Remove the scheme |
| remove_userinfo |
Remove the userinfo |
| reserve |
Adjust the capacity without changing the size |
| resolve |
Resolve a URL reference against this base URL |
| scheme |
Return the scheme |
| scheme_id |
Return the scheme |
| segments |
Return the path as a container of segments |
| set_encoded_authority |
Set the authority |
| set_encoded_fragment |
Set the fragment. |
| set_encoded_host |
Set the host |
| set_encoded_host_address |
Set the host to an address |
| set_encoded_host_name |
Set the host to a name |
| set_encoded_params |
Set the query params |
| set_encoded_password |
Set the password. |
| set_encoded_path |
Set the path. |
| set_encoded_query |
Set the query |
| set_encoded_user |
Set the user |
| set_encoded_userinfo |
Set the userinfo. |
| set_fragment |
Set the fragment. |
| set_host |
Set the host |
| set_host_address |
Set the host to an address |
| set_host_ipv4 |
Set the host to an address |
| set_host_ipv6 |
Set the host to an address |
| set_host_ipvfuture |
Set the host to an address |
| set_host_name |
Set the host to a name |
| set_params |
Set the query params |
| set_password |
Set the password. |
| set_path |
Set the path. |
| set_path_absolute |
Set if the path is absolute |
| set_port |
Set the port |
| set_port_number |
Set the port |
| set_query |
Set the query |
| set_scheme |
Set the scheme |
| set_scheme_id |
Set the scheme |
| set_user |
Set the user |
| set_userinfo |
Set the userinfo |
| size |
Return the number of characters in the url |
| swap |
Swap the contents. |
| url [constructor] |
Constructor |
| user |
Return the user |
| userinfo |
Return the userinfo |
| zone_id |
Return the IPv6 Zone ID |
| ~url [destructor] |
Destructor |
| Name | Description |
|---|---|
| max_size |
Return the maximum number of characters possible |
| Name | Description |
|---|---|
| operator!= |
Return the result of comparing two URLs |
| operator< |
Return the result of comparing two URLs |
| operator<< |
Format the url to the output stream |
| operator<= |
Return the result of comparing two URLs |
| operator== |
Return the result of comparing two URLs |
| operator> |
Return the result of comparing two URLs |
| operator>= |
Return the result of comparing two URLs |
| resolve |
Resolve a URL reference against a base URL |
| swap |
Swap |
This container owns a url, represented by a null-terminated character buffer which is managed by performing dymamic memory allocations as needed. The contents may be inspected and modified, and the implementation maintains a useful invariant: changes to the url always leave it in a valid state.
URI-reference = URI / relative-ref
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
relative-ref = relative-part [ "?" query ] [ "#" fragment ]
absolute-URI = scheme ":" hier-part [ "?" query ]
parse_absolute_uri , parse_relative_ref , parse_uri , parse_uri_reference , resolve .
Destructor
Any params, segments, iterators, or views which reference this object are invalidated. The underlying character buffer is destroyed, invalidating all references to it.
Constructor
url() noexcept;Constructor
url(core::string_view s);Constructor
url(url&& u) noexcept;Constructor
url(url_view_base const& u);Constructor
url(url const& u);Assignment
url&
operator=(url&& u) noexcept;Assignment
url&
operator=(url_view_base const& u);Assignment
url&
operator=(url const& u);Swap the contents.
Exchanges the contents of this url with another url. All views, iterators and references remain valid.
If `this == &other`, this function call has no effect.
url u1( "https://www.example.com" );
url u2( "https://www.boost.org" );
u1.swap(u2);
assert(u1 == "https://www.boost.org" );
assert(u2 == "https://www.example.com" );
| Name | Description |
|---|---|
| other |
Swap
Exchanges the contents of `v0` with another `v1`. All views, iterators and references remain valid.
If `&v0 ==&v1`, this function call has no effect.
url u1( "https://www.example.com" );
url u2( "https://www.boost.org" );
std::swap(u1, u2);
assert(u1 == "https://www.boost.org" );
assert(u2 == "https://www.example.com" );
v0.swap( v1 );
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.
assert( url( "http://www.example.com" ).set_scheme( "https" ).scheme_id() == scheme::https );
Calls to allocate may throw. Exceptions thrown on invalid input.
scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Set the scheme
This function sets the scheme to the specified known urls::scheme id, which may not be scheme::unknown or else an exception is thrown. If the id is scheme::none , this function behaves as if remove_scheme were called.
assert( url( "http://example.com/echo.cgi" ).set_scheme_id( scheme::wss ).buffer() == "wss://example.com/echo.cgi" );
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| id |
Remove the scheme
This function removes the scheme if it is present.
assert( url("http://www.example.com/index.htm" ).remove_scheme().buffer() == "//www.example.com/index.htm" );
this->has_scheme() == false && this->scheme_id() == scheme::none
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
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:
The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.
assert( url( "http://example.com" ).set_userinfo( "user:pass" ).encoded_user() == "user" );
Calls to allocate may throw.
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
| Name | Description |
|---|---|
| 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:
The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.
assert( url( "http://example.com" ).set_encoded_userinfo( "john%20doe" ).user() == "john doe" );
Calls to allocate may throw. Exceptions thrown on invalid input.
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Remove the userinfo
This function removes the userinfo if present, without removing any authority.
assert( url( "http://user@example.com" ).remove_userinfo().has_userinfo() == false );
this->has_userinfo() == false && this->encoded_userinfo().empty == true
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
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.
assert( url().set_user("john doe").encoded_userinfo() == "john%20doe" );
this->has_authority() == true && this->has_userinfo() == true
Calls to allocate may throw.
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
| Name | Description |
|---|---|
| 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.
assert( url().set_encoded_user("john%20doe").userinfo() == "john doe" );
this->has_authority() == true && this->has_userinfo() == true
Calls to allocate may throw.
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| 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.
The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.
assert( url("http://user@example.com").set_password( "pass" ).encoded_userinfo() == "user:pass" );
this->has_password() == true && this->password() == s
Calls to allocate may throw.
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
| Name | Description |
|---|---|
| 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.
The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.
assert( url("http://user@example.com").set_encoded_password( "pass" ).encoded_userinfo() == "user:pass" );
this->has_password() == true
Calls to allocate may throw.
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| 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.
The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.
assert( url( "http://user:pass@example.com" ).remove_password().authority().buffer() == "user@example.com" );
this->has_password() == false && this->encoded_password().empty() == true
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
Set the host
Depending on the contents of the passed string, this function sets the host:
In all cases, when this function returns, the URL contains an authority.
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );
this->has_authority() == true
Calls to allocate may throw.
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")
| Name | Description |
|---|---|
| s |
Set the host
Depending on the contents of the passed string, this function sets the host:
In all cases, when this function returns, the URL contains an authority.
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );
this->has_authority() == true
Calls to allocate may throw. Exceptions thrown on invalid input.
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Set the host to an address
Depending on the contents of the passed string, this function sets the host:
In all cases, when this function returns, the URL contains an authority.
assert( url( "http://www.example.com" ).set_host_address( "127.0.0.1" ).buffer() == "http://127.0.0.1" );
this->has_authority() == true
Calls to allocate may throw.
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 / "-" / ".")
| Name | Description |
|---|---|
| s |
Set the host to an address
Depending on the contents of the passed string, this function sets the host:
In all cases, when this function returns, the URL contains an authority.
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );
this->has_authority() == true
Calls to allocate may throw. Exceptions thrown on invalid input.
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 / "-" / ".")
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Set the host to an address
The host is set to the specified IPv4 address. The host type is host_type::ipv4 .
assert( url("http://www.example.com").set_host_ipv4( ipv4_address( "127.0.0.1" ) ).buffer() == "http://127.0.0.1" );
this->has_authority() == true && this->host_ipv4_address() == addr && this->host_type() == host_type::ipv4
Calls to allocate may throw.
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
| Name | Description |
|---|---|
| addr |
Set the host to an address
The host is set to the specified IPv6 address. The host type is host_type::ipv6 .
assert( url().set_host_ipv6( ipv6_address( "1::6:c0a8:1" ) ).authority().buffer() == "[1::6:c0a8:1]" );
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::ipv6
Calls to allocate may throw.
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
| Name | Description |
|---|---|
| addr |
Set the host to an address
The host is set to the specified IPvFuture string. The host type is host_type::ipvfuture .
assert( url().set_host_ipvfuture( "v42.bis" ).buffer() == "//[v42.bis]" );
this->has_authority() == true && this->host_ipvfuture) == s && this->host_type() == host_type::ipvfuture
Calls to allocate may throw. Exceptions thrown on invalid input.
IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| 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 host_type::name .
assert( url( "http://www.example.com/index.htm").set_host_name( "localhost" ).host_address() == "localhost" );
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name
Calls to allocate may throw.
reg-name = *( unreserved / pct-encoded / "-" / ".")
| Name | Description |
|---|---|
| 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 host_type::name .
assert( url( "http://www.example.com/index.htm").set_encoded_host_name( "localhost" ).host_address() == "localhost" );
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name
Calls to allocate may throw. Exceptions thrown on invalid input.
reg-name = *( unreserved / pct-encoded / "-" / ".")
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Set the port
The port is set to the specified integer.
assert( url( "http://www.example.com" ).set_port_number( 8080 ).authority().buffer() == "www.example.com:8080" );
this->has_authority() == true && this->has_port() == true && this->port_number() == n
Calls to allocate may throw.
authority = [ userinfo "@" ] host [ ":" port ]
port = *DIGIT
| Name | Description |
|---|---|
| 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.
assert( url( "http://www.example.com" ).set_port( "8080" ).authority().buffer() == "www.example.com:8080" );
this->has_port() == true && this->port_number() == n && this->port() == std::to_string(n)
Calls to allocate may throw. Exceptions thrown on invalid input.
port = *DIGIT
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Remove the port
If a port exists, it is removed. The rest of the authority is unchanged.
assert( url( "http://www.example.com:80" ).remove_port().authority().buffer() == "www.example.com" );
this->has_port() == false && this->port_number() == 0 && this->port() == ""
authority = [ userinfo "@" ] host [ ":" port ]
port = *DIGIT
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.
The library may adjust the final result to ensure that no other parts of the url is semantically affected.
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 set_encoded_path or segments should be used instead.
url u( "http://www.example.com" );
u.set_path( "path/to/file.txt" );
assert( u.path() == "/path/to/file.txt" );
Calls to allocate may throw.
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
| Name | Description |
|---|---|
| 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.
The library may adjust the final result to ensure that no other parts of the url is semantically affected.
url u( "http://www.example.com" );
u.set_encoded_path( "path/to/file.txt" );
assert( u.encoded_path() == "/path/to/file.txt" );
Calls to allocate may throw. Exceptions thrown on invalid input.
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
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
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.
assert( url( "http://example.com" ).set_query( "id=42" ).query() == "id=42" );
this->has_query() == true && this->query() == s
Calls to allocate may throw.
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
| Name | Description |
|---|---|
| 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.
assert( url( "http://example.com" ).set_encoded_query( "id=42" ).encoded_query() == "id=42" );
this->has_query() == true && this->query() == decode_view( s );
Calls to allocate may throw. Exceptions thrown on invalid input.
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Set the query params
Declared in <boost/url/url.hpp>
url&
set_params(
std::initializer_list<param_view> ps,
encoding_opts opts = = {});
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.
assert( url( "http://example.com" ).set_params( {"id", "42"} ).query() == "id=42" );
this->has_query() == true
Calls to allocate may throw.
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
| Name | Description |
|---|---|
| ps | |
| opts |
Set the query params
Declared in <boost/url/url.hpp>
url&
set_encoded_params(std::initializer_list<param_pct_view> ps);
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.
assert( url( "http://example.com" ).set_encoded_params( {"id", "42"} ).encoded_query() == "id=42" );
this->has_query() == true
Calls to allocate may throw. Exceptions thrown on invalid input.
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
| Name | Thrown on |
|---|---|
some |
| Name | Description |
|---|---|
| ps |
Remove the query
If a query is present, it is removed. An empty query is distinct from having no query.
assert( url( "http://www.example.com?id=42" ).remove_query().buffer() == "http://www.example.com" );
this->has_query() == false && this->params().empty()
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
Remove the fragment
This function removes the fragment. An empty fragment is distinct from having no fragment.
assert( url( "?first=john&last=doe#anchor" ).remove_fragment().buffer() == "?first=john&last=doe" );
this->has_fragment() == false && this->encoded_fragment() == ""
fragment = *( pchar / "/" / "?" )
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.
assert( url("?first=john&last=doe" ).set_encoded_fragment( "john doe" ).encoded_fragment() == "john%20doe" );
this->has_fragment() == true && this->fragment() == s
Calls to allocate may throw.
fragment = *( pchar / "/" / "?" )
| Name | Description |
|---|---|
| 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.
assert( url("?first=john&last=doe" ).set_encoded_fragment( "john%2Ddoe" ).fragment() == "john-doe" );
this->has_fragment() == true && this->fragment() == decode_view( s )
Calls to allocate may throw. Exceptions thrown on invalid input.
fragment = *( pchar / "/" / "?" )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Remove the origin component
This function removes the origin, which consists of the scheme and authority.
assert( url( "http://www.example.com/index.htm" ).remove_origin().buffer() == "/index.htm" );
this->scheme_id() == scheme::none && this->has_authority() == false
Normalize the URL components
Applies Syntax-based normalization to all components of the URL.
Calls to allocate may throw.
Normalize the URL scheme
Applies Syntax-based normalization to the URL scheme.
The scheme is normalized to lowercase.
Calls to allocate may throw.
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.
Calls to allocate may throw.
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.
Calls to allocate may throw.
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.
Calls to allocate may throw.
Swap
Exchanges the contents of `v0` with another `v1`. All views, iterators and references remain valid.
If `&v0 ==&v1`, this function call has no effect.
url u1( "https://www.example.com" );
url u2( "https://www.boost.org" );
std::swap(u1, u2);
assert(u1 == "https://www.boost.org" );
assert(u2 == "https://www.example.com" );
v0.swap( v1 );
| Name | Description |
|---|---|
| v0, |
| Name | Description |
|---|---|
| format_arg |
Format arguments into a URL
template
url
format(
core::string_view fmt,
Args&&... args); Format arguments into a URL
url
format(
core::string_view fmt,
std::initializer_list<_see-below_> args);Format arguments into a URL
template
void
format_to(
url_base& u,
core::string_view fmt,
Args&&... args); Format arguments into a URL
void
format_to(
url_base& u,
core::string_view fmt,
std::initializer_list<_see-below_> args);Designate a named argument for a replacement field
Declared in <boost/url/format.hpp>
template
_implementation-defined_
arg(
core::string_view name,
T const& arg);
Construct a named argument for a format URL string that contains named replacement fields.
The function parameters should be convertible to an implementation defined type able to store the name and a reference to any type potentially used as a format argument.
assert(format("user/{id}", arg("id", 1)).buffer() == "user/1");
| Name | Description |
|---|---|
| name | |
| arg |
Return a reference to a parsed URL string
Declared in <boost/url/parse.hpp>
system::result<url_view>
parse_absolute_uri(core::string_view s);
This function parses a string according to the grammar below and returns a view referencing the passed string upon success, else returns an error. Ownership of the string is not transferred; the caller is responsible for ensuring that the lifetime of the character buffer extends until the view is no longer being accessed.
system::result< url_view > rv = parse_absolute_uri( "http://example.com/index.htm?id=1" );
absolute-URI = scheme ":" hier-part [ "?" query ]
hier-part = "//" authority path-abempty
/ path-absolute
/ path-rootless
/ path-empty
| Name | Thrown on |
|---|---|
`s.size() |
| Name | Description |
|---|---|
| s |
Return a reference to a parsed URL string
Declared in <boost/url/parse.hpp>
system::result<url_view>
parse_origin_form(core::string_view s);
This function parses a string according to the grammar below and returns a view referencing the passed string upon success, else returns an error. Ownership of the string is not transferred; the caller is responsible for ensuring that the lifetime of the character buffer extends until the view is no longer being accessed.
system::result< url_view > = parse_origin_form( "/index.htm?layout=mobile" );
origin-form = absolute-path [ "?" query ]
absolute-path = 1*( "/" segment )
| Name | Thrown on |
|---|---|
`s.size() |
| Name | Description |
|---|---|
| s |
Return a reference to a parsed URL string
Declared in <boost/url/parse.hpp>
system::result<url_view>
parse_relative_ref(core::string_view s);
This function parses a string according to the grammar below and returns a view referencing the passed string upon success, else returns an error. Ownership of the string is not transferred; the caller is responsible for ensuring that the lifetime of the character buffer extends until the view is no longer being accessed.
system::result< url_view > = parse_relative_ref( "images/dot.gif?v=hide#a" );
relative-ref = relative-part [ "?" query ] [ "#" fragment ]
relative-part = "//" authority path-abempty
/ path-absolute
/ path-noscheme
/ path-abempty
/ path-empty
| Name | Thrown on |
|---|---|
`s.size() |
| Name | Description |
|---|---|
| s |
Return a reference to a parsed URL string
This function parses a string according to the grammar below and returns a view referencing the passed string upon success, else returns an error. Ownership of the string is not transferred; the caller is responsible for ensuring that the lifetime of the character buffer extends until the view is no longer being accessed.
system::result< url_view > = parse_uri( "https://www.example.com/index.htm?id=guest#s1" );
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
hier-part = "//" authority path-abempty
/ path-absolute
/ path-rootless
/ path-empty
| Name | Thrown on |
|---|---|
`s.size() |
| Name | Description |
|---|---|
| s |
Return a reference to a parsed URL string
Declared in <boost/url/parse.hpp>
system::result<url_view>
parse_uri_reference(core::string_view s);
This function parses a string according to the grammar below and returns a view referencing the passed string upon success, else returns an error. Ownership of the string is not transferred; the caller is responsible for ensuring that the lifetime of the character buffer extends until the view is no longer being accessed.
system::result< url_view > = parse_uri_reference( "ws://echo.example.com/?name=boost#demo" );
URI-reference = URI / relative-ref
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
relative-ref = relative-part [ "?" query ] [ "#" fragment ]
hier-part = "//" authority path-abempty
/ path-absolute
/ path-rootless
/ path-empty
relative-part = "//" authority path-abempty
/ path-absolute
/ path-noscheme
/ path-abempty
/ path-empty
| Name | Thrown on |
|---|---|
`s.size() |
| Name | Description |
|---|---|
| s |
A modifiable container for a URL.
| Name | Description |
|---|---|
| authority |
Return the authority |
| buffer |
Return the url string |
| c_str |
Return the url as a null-terminated string |
| capacity |
Return the number of characters that can be stored without reallocating |
| clear |
Clear the contents while preserving the capacity |
| compare |
Return the result of comparing this with another url |
| data |
Return a pointer to the url's character buffer |
| empty |
Return true if the url is empty |
| encoded_authority |
Return the authority. |
| encoded_fragment |
Return the fragment |
| encoded_host |
Return the host |
| encoded_host_address |
Return the host |
| encoded_host_and_port |
Return the host and port |
| encoded_host_name |
Return the host name |
| encoded_origin |
Return the origin |
| encoded_params |
Return the query as a container of parameters |
| encoded_password |
Return the password |
| encoded_path |
Return the path |
| encoded_query |
Return the query |
| encoded_resource |
Return the resource |
| encoded_segments |
Return the path as a container of segments |
| encoded_target |
Return the target |
| encoded_user |
Return the user |
| encoded_userinfo |
Return the userinfo |
| encoded_zone_id |
Return the IPv6 Zone ID |
| fragment |
Return the fragment |
| has_authority |
Return true if an authority is present |
| has_fragment |
Return true if a fragment is present |
| has_password |
Return true if a password is present |
| has_port |
Return true if a port is present |
| has_query |
Return true if a query is present |
| has_scheme |
Return true a scheme is present |
| has_userinfo |
Return true if a userinfo is present |
| host |
Return the host |
| host_address |
Return the host |
| host_ipv4_address |
Return the host IPv4 address |
| host_ipv6_address |
Return the host IPv6 address |
| host_ipvfuture |
Return the host IPvFuture address |
| host_name |
Return the host name |
| host_type |
Return the host type |
| is_path_absolute |
Return true if the path is absolute |
| normalize |
Normalize the URL components |
| normalize_authority |
Normalize the URL authority |
| normalize_fragment |
Normalize the URL fragment |
| normalize_path |
Normalize the URL path |
| normalize_query |
Normalize the URL query |
| normalize_scheme |
Normalize the URL scheme |
| operator core::string_view |
Return the URL as a core::string_view |
| operator= |
Assignment |
| params |
Return the query as a container of parameters |
| password |
Return the password |
| path |
Return the path |
| persist |
Return a shared, persistent copy of the url |
| port |
Return the port |
| port_number |
Return the port |
| query |
Return the query |
| remove_authority |
Remove the authority |
| remove_fragment |
Remove the fragment |
| remove_origin |
Remove the origin component |
| remove_password |
Remove the password |
| remove_port |
Remove the port |
| remove_query |
Remove the query |
| remove_scheme |
Remove the scheme |
| remove_userinfo |
Remove the userinfo |
| reserve |
Adjust the capacity without changing the size |
| resolve |
Resolve a URL reference against this base URL |
| scheme |
Return the scheme |
| scheme_id |
Return the scheme |
| segments |
Return the path as a container of segments |
| set_encoded_authority |
Set the authority |
| set_encoded_fragment |
Set the fragment. |
| set_encoded_host |
Set the host |
| set_encoded_host_address |
Set the host to an address |
| set_encoded_host_name |
Set the host to a name |
| set_encoded_params |
Set the query params |
| set_encoded_password |
Set the password. |
| set_encoded_path |
Set the path. |
| set_encoded_query |
Set the query |
| set_encoded_user |
Set the user |
| set_encoded_userinfo |
Set the userinfo. |
| set_fragment |
Set the fragment. |
| set_host |
Set the host |
| set_host_address |
Set the host to an address |
| set_host_ipv4 |
Set the host to an address |
| set_host_ipv6 |
Set the host to an address |
| set_host_ipvfuture |
Set the host to an address |
| set_host_name |
Set the host to a name |
| set_params |
Set the query params |
| set_password |
Set the password. |
| set_path |
Set the path. |
| set_path_absolute |
Set if the path is absolute |
| set_port |
Set the port |
| set_port_number |
Set the port |
| set_query |
Set the query |
| set_scheme |
Set the scheme |
| set_scheme_id |
Set the scheme |
| set_user |
Set the user |
| set_userinfo |
Set the userinfo |
| size |
Return the number of characters in the url |
| static_url [constructor] |
Constructor |
| user |
Return the user |
| userinfo |
Return the userinfo |
| zone_id |
Return the IPv6 Zone ID |
| ~static_url [destructor] |
Destructor |
| Name | Description |
|---|---|
| max_size |
Return the maximum number of characters possible |
| Name | Description |
|---|---|
| operator!= |
Return the result of comparing two URLs |
| operator< |
Return the result of comparing two URLs |
| operator<< |
Format the url to the output stream |
| operator<= |
Return the result of comparing two URLs |
| operator== |
Return the result of comparing two URLs |
| operator> |
Return the result of comparing two URLs |
| operator>= |
Return the result of comparing two URLs |
| resolve |
Resolve a URL reference against a base URL |
This container owns a url, represented by an inline, null-terminated character buffer with fixed capacity. The contents may be inspected and modified, and the implementation maintains a useful invariant: changes to the url always leave it in a valid state.
static_url< 1024 > u( "https://www.example.com" );
this->capacity() == Capacity + 1
Destructor
Any params, segments, iterators, or views which reference this object are invalidated. The underlying character buffer is destroyed, invalidating all references to it.
Constructor
static_url() noexcept;Constructor
static_url(core::string_view s);Constructor
static_url(static_url const& u) noexcept;Constructor
static_url(url_view_base const& u);Assignment
static_url&
operator=(static_url const& u) noexcept;Assignment
static_url&
operator=(url_view_base const& u);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.
assert( url( "http://www.example.com" ).set_scheme( "https" ).scheme_id() == scheme::https );
Calls to allocate may throw. Exceptions thrown on invalid input.
scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Set the scheme
This function sets the scheme to the specified known urls::scheme id, which may not be scheme::unknown or else an exception is thrown. If the id is scheme::none , this function behaves as if remove_scheme were called.
assert( url( "http://example.com/echo.cgi" ).set_scheme_id( scheme::wss ).buffer() == "wss://example.com/echo.cgi" );
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| id |
Remove the scheme
This function removes the scheme if it is present.
assert( url("http://www.example.com/index.htm" ).remove_scheme().buffer() == "//www.example.com/index.htm" );
this->has_scheme() == false && this->scheme_id() == scheme::none
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
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:
The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.
assert( url( "http://example.com" ).set_userinfo( "user:pass" ).encoded_user() == "user" );
Calls to allocate may throw.
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
| Name | Description |
|---|---|
| s |
Set the userinfo.
Declared in <boost/url/static_url.hpp>
static_url&
set_encoded_userinfo(pct_string_view s);
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:
The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.
assert( url( "http://example.com" ).set_encoded_userinfo( "john%20doe" ).user() == "john doe" );
Calls to allocate may throw. Exceptions thrown on invalid input.
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Remove the userinfo
This function removes the userinfo if present, without removing any authority.
assert( url( "http://user@example.com" ).remove_userinfo().has_userinfo() == false );
this->has_userinfo() == false && this->encoded_userinfo().empty == true
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
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.
assert( url().set_user("john doe").encoded_userinfo() == "john%20doe" );
this->has_authority() == true && this->has_userinfo() == true
Calls to allocate may throw.
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
| Name | Description |
|---|---|
| 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.
assert( url().set_encoded_user("john%20doe").userinfo() == "john doe" );
this->has_authority() == true && this->has_userinfo() == true
Calls to allocate may throw.
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| 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.
The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.
assert( url("http://user@example.com").set_password( "pass" ).encoded_userinfo() == "user:pass" );
this->has_password() == true && this->password() == s
Calls to allocate may throw.
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
| Name | Description |
|---|---|
| s |
Set the password.
Declared in <boost/url/static_url.hpp>
static_url&
set_encoded_password(pct_string_view s);
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.
The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.
assert( url("http://user@example.com").set_encoded_password( "pass" ).encoded_userinfo() == "user:pass" );
this->has_password() == true
Calls to allocate may throw.
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| 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.
The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.
assert( url( "http://user:pass@example.com" ).remove_password().authority().buffer() == "user@example.com" );
this->has_password() == false && this->encoded_password().empty() == true
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
Set the host
Depending on the contents of the passed string, this function sets the host:
In all cases, when this function returns, the URL contains an authority.
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );
this->has_authority() == true
Calls to allocate may throw.
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")
| Name | Description |
|---|---|
| s |
Set the host
Depending on the contents of the passed string, this function sets the host:
In all cases, when this function returns, the URL contains an authority.
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );
this->has_authority() == true
Calls to allocate may throw. Exceptions thrown on invalid input.
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Set the host to an address
Depending on the contents of the passed string, this function sets the host:
In all cases, when this function returns, the URL contains an authority.
assert( url( "http://www.example.com" ).set_host_address( "127.0.0.1" ).buffer() == "http://127.0.0.1" );
this->has_authority() == true
Calls to allocate may throw.
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 / "-" / ".")
| Name | Description |
|---|---|
| s |
Set the host to an address
Declared in <boost/url/static_url.hpp>
static_url&
set_encoded_host_address(pct_string_view s);
Depending on the contents of the passed string, this function sets the host:
In all cases, when this function returns, the URL contains an authority.
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );
this->has_authority() == true
Calls to allocate may throw. Exceptions thrown on invalid input.
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 / "-" / ".")
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Set the host to an address
Declared in <boost/url/static_url.hpp>
static_url&
set_host_ipv4(ipv4_address const& addr);
The host is set to the specified IPv4 address. The host type is host_type::ipv4 .
assert( url("http://www.example.com").set_host_ipv4( ipv4_address( "127.0.0.1" ) ).buffer() == "http://127.0.0.1" );
this->has_authority() == true && this->host_ipv4_address() == addr && this->host_type() == host_type::ipv4
Calls to allocate may throw.
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
| Name | Description |
|---|---|
| addr |
Set the host to an address
Declared in <boost/url/static_url.hpp>
static_url&
set_host_ipv6(ipv6_address const& addr);
The host is set to the specified IPv6 address. The host type is host_type::ipv6 .
assert( url().set_host_ipv6( ipv6_address( "1::6:c0a8:1" ) ).authority().buffer() == "[1::6:c0a8:1]" );
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::ipv6
Calls to allocate may throw.
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
| Name | Description |
|---|---|
| addr |
Set the host to an address
Declared in <boost/url/static_url.hpp>
static_url&
set_host_ipvfuture(core::string_view s);
The host is set to the specified IPvFuture string. The host type is host_type::ipvfuture .
assert( url().set_host_ipvfuture( "v42.bis" ).buffer() == "//[v42.bis]" );
this->has_authority() == true && this->host_ipvfuture) == s && this->host_type() == host_type::ipvfuture
Calls to allocate may throw. Exceptions thrown on invalid input.
IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| 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 host_type::name .
assert( url( "http://www.example.com/index.htm").set_host_name( "localhost" ).host_address() == "localhost" );
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name
Calls to allocate may throw.
reg-name = *( unreserved / pct-encoded / "-" / ".")
| Name | Description |
|---|---|
| s |
Set the host to a name
Declared in <boost/url/static_url.hpp>
static_url&
set_encoded_host_name(pct_string_view s);
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 host_type::name .
assert( url( "http://www.example.com/index.htm").set_encoded_host_name( "localhost" ).host_address() == "localhost" );
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name
Calls to allocate may throw. Exceptions thrown on invalid input.
reg-name = *( unreserved / pct-encoded / "-" / ".")
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Set the port
The port is set to the specified integer.
assert( url( "http://www.example.com" ).set_port_number( 8080 ).authority().buffer() == "www.example.com:8080" );
this->has_authority() == true && this->has_port() == true && this->port_number() == n
Calls to allocate may throw.
authority = [ userinfo "@" ] host [ ":" port ]
port = *DIGIT
| Name | Description |
|---|---|
| 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.
assert( url( "http://www.example.com" ).set_port( "8080" ).authority().buffer() == "www.example.com:8080" );
this->has_port() == true && this->port_number() == n && this->port() == std::to_string(n)
Calls to allocate may throw. Exceptions thrown on invalid input.
port = *DIGIT
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Remove the port
If a port exists, it is removed. The rest of the authority is unchanged.
assert( url( "http://www.example.com:80" ).remove_port().authority().buffer() == "www.example.com" );
this->has_port() == false && this->port_number() == 0 && this->port() == ""
authority = [ userinfo "@" ] host [ ":" port ]
port = *DIGIT
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.
The library may adjust the final result to ensure that no other parts of the url is semantically affected.
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 set_encoded_path or segments should be used instead.
url u( "http://www.example.com" );
u.set_path( "path/to/file.txt" );
assert( u.path() == "/path/to/file.txt" );
Calls to allocate may throw.
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
| Name | Description |
|---|---|
| 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.
The library may adjust the final result to ensure that no other parts of the url is semantically affected.
url u( "http://www.example.com" );
u.set_encoded_path( "path/to/file.txt" );
assert( u.encoded_path() == "/path/to/file.txt" );
Calls to allocate may throw. Exceptions thrown on invalid input.
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
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
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.
assert( url( "http://example.com" ).set_query( "id=42" ).query() == "id=42" );
this->has_query() == true && this->query() == s
Calls to allocate may throw.
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
| Name | Description |
|---|---|
| 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.
assert( url( "http://example.com" ).set_encoded_query( "id=42" ).encoded_query() == "id=42" );
this->has_query() == true && this->query() == decode_view( s );
Calls to allocate may throw. Exceptions thrown on invalid input.
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Set the query params
Declared in <boost/url/static_url.hpp>
static_url&
set_params(
std::initializer_list<param_view> ps,
encoding_opts opts = = {});
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.
assert( url( "http://example.com" ).set_params( {"id", "42"} ).query() == "id=42" );
this->has_query() == true
Calls to allocate may throw.
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
| Name | Description |
|---|---|
| ps | |
| opts |
Remove the query
If a query is present, it is removed. An empty query is distinct from having no query.
assert( url( "http://www.example.com?id=42" ).remove_query().buffer() == "http://www.example.com" );
this->has_query() == false && this->params().empty()
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
Remove the fragment
This function removes the fragment. An empty fragment is distinct from having no fragment.
assert( url( "?first=john&last=doe#anchor" ).remove_fragment().buffer() == "?first=john&last=doe" );
this->has_fragment() == false && this->encoded_fragment() == ""
fragment = *( pchar / "/" / "?" )
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.
assert( url("?first=john&last=doe" ).set_encoded_fragment( "john doe" ).encoded_fragment() == "john%20doe" );
this->has_fragment() == true && this->fragment() == s
Calls to allocate may throw.
fragment = *( pchar / "/" / "?" )
| Name | Description |
|---|---|
| s |
Set the fragment.
Declared in <boost/url/static_url.hpp>
static_url&
set_encoded_fragment(pct_string_view s);
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.
assert( url("?first=john&last=doe" ).set_encoded_fragment( "john%2Ddoe" ).fragment() == "john-doe" );
this->has_fragment() == true && this->fragment() == decode_view( s )
Calls to allocate may throw. Exceptions thrown on invalid input.
fragment = *( pchar / "/" / "?" )
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Remove the origin component
This function removes the origin, which consists of the scheme and authority.
assert( url( "http://www.example.com/index.htm" ).remove_origin().buffer() == "/index.htm" );
this->scheme_id() == scheme::none && this->has_authority() == false
Normalize the URL components
Applies Syntax-based normalization to all components of the URL.
Calls to allocate may throw.
Normalize the URL scheme
Applies Syntax-based normalization to the URL scheme.
The scheme is normalized to lowercase.
Calls to allocate may throw.
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.
Calls to allocate may throw.
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.
Calls to allocate may throw.
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.
Calls to allocate may throw.
Common implementation for all static URLs
| Name | Description |
|---|---|
| authority |
Return the authority |
| buffer |
Return the url string |
| c_str |
Return the url as a null-terminated string |
| capacity |
Return the number of characters that can be stored without reallocating |
| clear |
Clear the contents while preserving the capacity |
| compare |
Return the result of comparing this with another url |
| data |
Return a pointer to the url's character buffer |
| empty |
Return true if the url is empty |
| encoded_authority |
Return the authority. |
| encoded_fragment |
Return the fragment |
| encoded_host |
Return the host |
| encoded_host_address |
Return the host |
| encoded_host_and_port |
Return the host and port |
| encoded_host_name |
Return the host name |
| encoded_origin |
Return the origin |
| encoded_params |
Return the query as a container of parameters |
| encoded_password |
Return the password |
| encoded_path |
Return the path |
| encoded_query |
Return the query |
| encoded_resource |
Return the resource |
| encoded_segments |
Return the path as a container of segments |
| encoded_target |
Return the target |
| encoded_user |
Return the user |
| encoded_userinfo |
Return the userinfo |
| encoded_zone_id |
Return the IPv6 Zone ID |
| fragment |
Return the fragment |
| has_authority |
Return true if an authority is present |
| has_fragment |
Return true if a fragment is present |
| has_password |
Return true if a password is present |
| has_port |
Return true if a port is present |
| has_query |
Return true if a query is present |
| has_scheme |
Return true a scheme is present |
| has_userinfo |
Return true if a userinfo is present |
| host |
Return the host |
| host_address |
Return the host |
| host_ipv4_address |
Return the host IPv4 address |
| host_ipv6_address |
Return the host IPv6 address |
| host_ipvfuture |
Return the host IPvFuture address |
| host_name |
Return the host name |
| host_type |
Return the host type |
| is_path_absolute |
Return true if the path is absolute |
| normalize |
Normalize the URL components |
| normalize_authority |
Normalize the URL authority |
| normalize_fragment |
Normalize the URL fragment |
| normalize_path |
Normalize the URL path |
| normalize_query |
Normalize the URL query |
| normalize_scheme |
Normalize the URL scheme |
| operator core::string_view |
Return the URL as a core::string_view |
| params |
Return the query as a container of parameters |
| password |
Return the password |
| path |
Return the path |
| persist |
Return a shared, persistent copy of the url |
| port |
Return the port |
| port_number |
Return the port |
| query |
Return the query |
| remove_authority |
Remove the authority |
| remove_fragment |
Remove the fragment |
| remove_origin |
Remove the origin component |
| remove_password |
Remove the password |
| remove_port |
Remove the port |
| remove_query |
Remove the query |
| remove_scheme |
Remove the scheme |
| remove_userinfo |
Remove the userinfo |
| reserve |
Adjust the capacity without changing the size |
| resolve |
Resolve a URL reference against this base URL |
| scheme |
Return the scheme |
| scheme_id |
Return the scheme |
| segments |
Return the path as a container of segments |
| set_encoded_authority |
Set the authority |
| set_encoded_fragment |
Set the fragment. |
| set_encoded_host |
Set the host |
| set_encoded_host_address |
Set the host to an address |
| set_encoded_host_name |
Set the host to a name |
| set_encoded_params |
Set the query params |
| set_encoded_password |
Set the password. |
| set_encoded_path |
Set the path. |
| set_encoded_query |
Set the query |
| set_encoded_user |
Set the user |
| set_encoded_userinfo |
Set the userinfo. |
| set_fragment |
Set the fragment. |
| set_host |
Set the host |
| set_host_address |
Set the host to an address |
| set_host_ipv4 |
Set the host to an address |
| set_host_ipv6 |
Set the host to an address |
| set_host_ipvfuture |
Set the host to an address |
| set_host_name |
Set the host to a name |
| set_params |
Set the query params |
| set_password |
Set the password. |
| set_path |
Set the path. |
| set_path_absolute |
Set if the path is absolute |
| set_port |
Set the port |
| set_port_number |
Set the port |
| set_query |
Set the query |
| set_scheme |
Set the scheme |
| set_scheme_id |
Set the scheme |
| set_user |
Set the user |
| set_userinfo |
Set the userinfo |
| size |
Return the number of characters in the url |
| user |
Return the user |
| userinfo |
Return the userinfo |
| zone_id |
Return the IPv6 Zone ID |
| Name | Description |
|---|---|
| max_size |
Return the maximum number of characters possible |
| Name | Description |
|---|---|
| operator!= |
Return the result of comparing two URLs |
| operator< |
Return the result of comparing two URLs |
| operator<< |
Format the url to the output stream |
| operator<= |
Return the result of comparing two URLs |
| operator== |
Return the result of comparing two URLs |
| operator> |
Return the result of comparing two URLs |
| operator>= |
Return the result of comparing two URLs |
| resolve |
Resolve a URL reference against a base URL |
This base class is used by the library to provide common functionality for static URLs. Users should not use this class directly. Instead, construct an instance of one of the containers or call a parsing function.
The type of string_view used by the library
String views are used to pass character buffers into or out of functions. Ownership of the underlying character buffer is not transferred; the caller is responsible for ensuring that the lifetime of character buffer extends until it is no longer referenced.
This alias is no longer supported and should not be used in new code. Please use `core::string_view` instead.
This alias is included for backwards compatibility with earlier versions of the library.
However, it will be removed in future releases, and using it in new code is not recommended.
Please use the updated version instead to ensure compatibility with future versions of the library.
Rule for absolute-URI
Declared in <boost/url/rfc/absolute_uri_rule.hpp>
constexpr
_implementation-defined_ absolute_uri_rule = {};
using value_type = url_view;
system::result< url_view > rv = grammar::parse( "http://example.com/index.htm?id=1", absolute_uri_rule );
absolute-URI = scheme ":" hier-part [ "?" query ]
hier-part = "//" authority path-abempty
/ path-absolute
/ path-rootless
/ path-empty
The gen-delims character set
Declared in <boost/url/rfc/gen_delim_chars.hpp>
constexpr
grammar::lut_chars const gen_delim_chars = ":/?#[]@";
the functions grammar::find_if and grammar::find_if_not .
system::result< decode_view > rv = grammar::parse( "Program%20Files", pct_encoded_rule( gen_delim_chars ) );
gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@"
Rule for an IP version 4 style address
Declared in <boost/url/rfc/ipv4_address_rule.hpp>
constexpr
_implementation-defined_ ipv4_address_rule = {};
using value_type = ipv4_address;
system::result< ipv4_address > rv = grammar::parse( "192.168.0.1", ipv4_address_rule );
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
Rule for An IP version 6 style address
Declared in <boost/url/rfc/ipv6_address_rule.hpp>
constexpr
_implementation-defined_ ipv6_address_rule = {};
using value_type = ipv6_address;
system::result< ipv6_address > rv = grammar::parse( "2001:0db8:85a3:0000:0000:8a2e:0370:7334", ipv6_address_rule );
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
Rule for origin-form
Declared in <boost/url/rfc/origin_form_rule.hpp>
constexpr
origin_form_rule_t const origin_form_rule = {};
This appears in the HTTP/1 request-line grammar.
using value_type = url_view;
system::result< url_view > rv = grammar::parse( "/index.htm?layout=mobile", origin_form_rule );
origin-form = absolute-path [ "?" query ]
absolute-path = 1*( "/" segment )
The sub-delims character set
Declared in <boost/url/rfc/sub_delim_chars.hpp>
constexpr
grammar::lut_chars const sub_delim_chars = "!$&()*+,;=\x27";
the functions grammar::find_if and grammar::find_if_not .
system::result< decode_view > = grammar::parse( "Program%20Files", pct_encoded_rule( sub_delim_chars ) );
sub-delims = "!" / "$" / "&" / "'" / "(" / ")"
/ "*" / "+" / "," / ";" / "="
The unreserved character set
Declared in <boost/url/rfc/unreserved_chars.hpp>
constexpr
grammar::lut_chars const unreserved_chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
"abcdefghijklmnopqrstuvwxyz"
"0123456789"
"-._~";
the functions grammar::find_if and grammar::find_if_not .
system::result< decode_view > rv = grammar::parse( "Program%20Files", pct_encoded_rule( unreserved_chars ) );
unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
The path character set
Declared in <boost/url/rfc/pchars.hpp>
constexpr
auto const pchars = unreserved_chars + sub_delim_chars + ':' + '@';
the functions grammar::find_if and grammar::find_if_not .
system::result< decode_view > rv = grammar::parse( "Program%20Files", pchars );
pchar = unreserved / pct-encoded / sub-delims / ":" / "@"
Rule for a string with percent-encoded escapes
Declared in <boost/url/rfc/pct_encoded_rule.hpp>
template
constexpr
_implementation-defined_
pct_encoded_rule(CharSet const& cs) noexcept;
This function returns a rule which matches a percent-encoded string, permitting characters in the string which are also in the specified character set to be used unescaped.
using value_type = pct_string_view;
// pchar = unreserved / pct-encoded / sub-delims / ":" / "@"
system::result< pct_string_view > rv = grammar::parse( "Program%20Files", pct_encoded_rule( pchars ) );
pct-encoded = "%" HEXDIG HEXDIG
| Name | Description |
|---|---|
| cs |
Rule for query
Declared in <boost/url/rfc/query_rule.hpp>
constexpr
_implementation-defined_ query_rule = {};
using value_type = params_encoded_view;
system::result< params_encoded_view > rv = grammar::parse( "format=web&id=42&compact", query_rule );
query = *( pchar / "/" / "?" )
query-params = [ query-param ] *( "&" query-param )
query-param = key [ "=" value ]
key = *qpchar
value = *( qpchar / "=" )
qpchar = unreserved
/ pct-encoded
/ "!" / "$" / "'" / "(" / ")"
/ "*" / "+" / "," / ";"
/ ":" / "@" / "/" / "?"
Rule for relative-ref
Declared in <boost/url/rfc/relative_ref_rule.hpp>
constexpr
_implementation-defined_ relative_ref_rule = {};
using value_type = url_view;
system::result< url_view > rv = grammar::parse( "images/dot.gif?v=hide#a", relative_ref_rule );
relative-ref = relative-part [ "?" query ] [ "#" fragment ]
The reserved character set
Declared in <boost/url/rfc/reserved_chars.hpp>
constexpr
auto const reserved_chars = ~unreserved_chars;
the functions grammar::find_if and grammar::find_if_not .
system::result< decode_view > rv = grammar::parse( "Program%20Files", pct_encoded_rule( reserved_chars ) );
Rule for URI
using value_type = url_view;
system::result< url_view > rv = grammar::parse( "https://www.example.com/index.htm?id=guest#s1", uri_rule );
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
Rule for URI-reference
Declared in <boost/url/rfc/uri_reference_rule.hpp>
constexpr
_implementation-defined_ uri_reference_rule = {};
using value_type = url_view;
system::result< url_view > rv = grammar::parse( "ws://echo.example.com/?name=boost#demo", uri_reference_rule );
URI-reference = URI / relative-ref
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
relative-ref = relative-part [ "?" query ] [ "#" fragment ]
| Name |
|---|
| Name |
|---|
Return a reference to a character set
Declared in <boost/url/grammar/charset.hpp>
template
constexpr
_implementation-defined_
ref(CharSet const& cs) noexcept;
This function returns a character set which references the specified object. This is used to reduce the number of bytes of storage (`sizeof`) required by a combinator when it stores a copy of the object. Ownership of the object is not transferred; the caller is responsible for ensuring the lifetime of the object is extended until it is no longer referenced. For best results, `ref` should only be used with compile-time constants.
Return a reference to a rule
Declared in <boost/url/grammar/parse.hpp>
template
constexpr
_implementation-defined_
ref(Rule const& r) noexcept;
This function returns a rule which references the specified object. This is used to reduce the number of bytes of storage (`sizeof`) required by a combinator when it stores a copy of the object. Ownership of the object is not transferred; the caller is responsible for ensuring the lifetime of the object is extended until it is no longer referenced. For best results, `ref` should only be used with compile-time constants.
| Name | Description |
|---|---|
| r |
Return true if s0 equals s1 using case-insensitive comparison
Declared in <boost/url/grammar/ci_string.hpp>
template<
class String0,
class String1>
bool
ci_is_equal(
String0 const& s0,
String1 const& s1);
The function is defined only for strings containing low-ASCII characters.
assert( ci_is_equal( "Boost", "boost" ) );
Return true if s0 equals s1 using case-insensitive comparison
Declared in <boost/url/grammar/ci_string.hpp>
bool
ci_is_equal(
core::string_view s0,
core::string_view s1) noexcept;
The function is defined only for strings containing low-ASCII characters.
assert( ci_is_equal( "Boost", "boost" ) );
Match a character literal
Declared in <boost/url/grammar/delim_rule.hpp>
constexpr
_implementation-defined_
delim_rule(char ch) noexcept;
This matches the specified character. The value is a reference to the character in the underlying buffer, expressed as a `core::string_view`. The function squelch may be used to turn this into `void` instead. If there is no more input, the error code error::need_more is returned.
using value_type = core::string_view;
parse .
system::result< core::string_view > rv = parse( ".", delim_rule('.') );
char = %00-FF
| Name | Description |
|---|---|
| ch |
Match a single character from a character set
Declared in <boost/url/grammar/delim_rule.hpp>
template
constexpr
_implementation-defined_
delim_rule(CharSet const& cs) noexcept;
This matches exactly one character which belongs to the specified character set. The value is a reference to the character in the underlying buffer, expressed as a `core::string_view`. The function squelch may be used to turn this into `void` instead. If there is no more input, the error code error::need_more is returned.
using value_type = core::string_view;
parse .
system::result< core::string_view > rv = parse( "X", delim_rule( alpha_chars ) );
| Name | Description |
|---|---|
| cs |
Return true if ch is in the character set.
Declared in <boost/url/grammar/lut_chars.hpp>
constexpr
bool
operator()(unsigned char ch) const noexcept;
This function returns true if the character `ch` is in the set, otherwise it returns false.
| Name | Description |
|---|---|
| ch |
Return true if ch is in the character set.
Declared in <boost/url/grammar/lut_chars.hpp>
constexpr
bool
operator()(char ch) const noexcept;
This function returns true if the character `ch` is in the set, otherwise it returns false.
| Name | Description |
|---|---|
| ch |
Constructor
This function constructs a character set which has as a single member, the character `ch`.
constexpr lut_chars asterisk( '*' );
| Name | Description |
|---|---|
| ch |
Constructor
This function constructs a character set which has as members, all of the characters present in the null-terminated string `s`.
constexpr lut_chars digits = "0123456789";
if `s` is a constant expression.
| Name | Description |
|---|---|
| s |
Declared in <boost/url/grammar/lut_chars.hpp>
template<
class Pred,
class = void>
constexpr
lut_chars(Pred const& pred) noexcept;
Parse a character buffer using a rule
Declared in <boost/url/grammar/parse.hpp>
template
system::result
parse(
char const*& it,
char const* end,
Rule const& r);
| Name | Description |
|---|---|
| it | |
| end | |
| r |
Parse a character buffer using a rule
Declared in <boost/url/grammar/parse.hpp>
template
system::result
parse(
core::string_view s,
Rule const& r);
This function parses a complete string into the specified sequence of rules. If the string is not completely consumed, an error is returned instead.
| Name | Description |
|---|---|
| s | |
| r |
Constructor
Default-constructed ranges have zero elements.
Constructor
The new range references the same underlying character buffer. Ownership is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced. The moved-from object becomes as if default-constructed.
Constructor
The copy references the same underlying character buffer. Ownership is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced.
Assignment
After the move, this references the same underlying character buffer. Ownership is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced. The moved-from object becomes as if default-constructed.
Assignment
Declared in <boost/url/grammar/range_rule.hpp>
range&
operator=(range const& other) noexcept;
The copy references the same underlying character buffer. Ownership is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced.
Match a repeating number of elements
Declared in <boost/url/grammar/range_rule.hpp>
template
constexpr
_implementation-defined_
range_rule(
Rule const& next,
std::size_t N = 0,
std::size_t M = std::size_t(-1)) noexcept;
Elements are matched using the passed rule. Normally when the rule returns an error, the range ends and the input is rewound to one past the last character that matched successfully. However, if the rule returns the special value error::end_of_range , the input is not rewound. This allows for rules which consume input without producing elements in the range. For example, to relax the grammar for a comma-delimited list by allowing extra commas in between elements.
using value_type = range< typename Rule::value_type >;
parse .
// range = 1*( ";" token )
system::result< range > rv = parse( ";alpha;xray;charlie",
range_rule(
tuple_rule(
squelch( delim_rule( ';' ) ),
token_rule( alpha_chars ) ),
1 ) );
range = *next
| Name | Description |
|---|---|
| next | |
| N | |
| M |
Match a repeating number of elements
Declared in <boost/url/grammar/range_rule.hpp>
template<
class Rule1,
class Rule2>
constexpr
_implementation-defined_
range_rule(
Rule1 const& first,
Rule2 const& next,
std::size_t N = 0,
std::size_t M = std::size_t(-1)) noexcept;
Two rules are used for match. The rule `first` is used for matching the first element, while the `next` rule is used to match every subsequent element. Normally when the rule returns an error, the range ends and the input is rewound to one past the last character that matched successfully. However, if the rule returns the special value error::end_of_range , the input is not rewound. This allows for rules which consume input without producing elements in the range. For example, to relax the grammar for a comma-delimited list by allowing extra commas in between elements.
using value_type = range< typename Rule::value_type >;
parse .
// range = [ token ] *( "," token )
system::result< range< core::string_view > > rv = parse( "whiskey,tango,foxtrot",
range_rule(
token_rule( alpha_chars ), // first
tuple_rule( // next
squelch( delim_rule(',') ),
token_rule( alpha_chars ) ) ) );
range = <1>*<1>first
/ first *next
| Name | Description |
|---|---|
| first | |
| next | |
| N | |
| M |
Assignment
Declared in <boost/url/grammar/recycled.hpp>
recycled_ptr&
operator=(recycled_ptr&& other) noexcept;
If `other` references an object, ownership is transferred including a reference to the recycle bin. After the move, the moved-from object is empty.
this->release()
&this->bin() == &other->bin()
| Name | Description |
|---|---|
| other |
Assignment
Declared in <boost/url/grammar/recycled.hpp>
recycled_ptr&
operator=(recycled_ptr const& other) noexcept;
If `other` references an object, this acquires shared ownership and references the same recycle bin as `other`. The previous object if any is released.
this->release()
&this->bin() == &other->bin() && this->get() == other.get()
| Name | Description |
|---|---|
| other |
Constructor
Upon construction, this acquires exclusive access to an object of type `T` which is either recycled from the specified bin, or newly allocated. The object is in an unknown but valid state.
static recycled< std::string > bin;
recycled_ptr< std::string > ps( bin );
// Put the string into a known state
ps->clear();
&this->bin() == &bin && ! this->empty()
| Name | Description |
|---|---|
| bin |
Constructor
Declared in <boost/url/grammar/recycled.hpp>
recycled_ptr(
recycled& bin,
std::nullptr_t) noexcept;
After construction, this is empty and refers to the specified recycle bin.
static recycled< std::string > bin;
recycled_ptr< std::string > ps( bin, nullptr );
// Acquire a string and put it into a known state
ps->acquire();
ps->clear();
&this->bin() == &bin && this->empty()
| Name | Description |
|---|---|
| bin |
Constructor
Upon construction, this acquires exclusive access to an object of type `T` which is either recycled from a global recycle bin, or newly allocated. The object is in an unknown but valid state.
recycled_ptr< std::string > ps;
// Put the string into a known state
ps->clear();
&this->bin() != nullptr && ! this->empty()
Constructor
After construction, this is empty and refers to a global recycle bin.
recycled_ptr< std::string > ps( nullptr );
// Acquire a string and put it into a known state
ps->acquire();
ps->clear();
&this->bin() != nullptr && this->empty()
Constructor
Declared in <boost/url/grammar/recycled.hpp>
recycled_ptr(recycled_ptr const& other) noexcept;
If `other` references an object, the newly constructed pointer acquires shared ownership. Otherwise this is empty. The new pointer references the same recycle bin as `other`.
&this->bin() == &other->bin() && this->get() == other.get()
| Name | Description |
|---|---|
| other |
Constructor
If `other` references an object, ownership is transferred including a reference to the recycle bin. After the move, the moved-from object is empty.
&this->bin() == &other->bin() && ! this->empty() && other.empty()
| Name | Description |
|---|---|
| other |
Return true if a matching prefix exists
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
starts_with(core::string_view x) const noexcept;
See `core::string_view::starts_with`
Return true if a matching prefix exists
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
starts_with(char x) const noexcept;
See `core::string_view::starts_with`
Return true if a matching prefix exists
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
starts_with(char const* x) const noexcept;
See `core::string_view::starts_with`
Return true if a matching suffix exists
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
ends_with(core::string_view x) const noexcept;
See `core::string_view::ends_with`
Return true if a matching suffix exists
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
ends_with(char x) const noexcept;
See `core::string_view::ends_with`
Return true if a matching suffix exists
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
ends_with(char const* x) const noexcept;
See `core::string_view::ends_with`
Return the position of matching characters
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find(
core::string_view str,
size_type pos = 0) const noexcept;
See `core::string_view::find`
Return the position of matching characters
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find(
char c,
size_type pos = 0) const noexcept;
See `core::string_view::find`
Return the position of matching characters
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find(
char const* s,
size_type pos,
size_type n) const noexcept;
See `core::string_view::find`
Return the position of matching characters
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find(
char const* s,
size_type pos = 0) const noexcept;
See `core::string_view::find`
Return the result of comparing to another string
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
int
compare(core::string_view str) const noexcept;
See `core::string_view::compare`
Return the result of comparing to another string
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
int
compare(
size_type pos1,
size_type n1,
core::string_view str) const;
See `core::string_view::compare`
Return the result of comparing to another string
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
int
compare(
size_type pos1,
size_type n1,
core::string_view str,
size_type pos2,
size_type n2) const;
See `core::string_view::compare`
Return the result of comparing to another string
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
int
compare(char const* s) const noexcept;
See `core::string_view::compare`
Return the result of comparing to another string
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
int
compare(
size_type pos1,
size_type n1,
char const* s) const;
See `core::string_view::compare`
Return the result of comparing to another string
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
int
compare(
size_type pos1,
size_type n1,
char const* s,
size_type n2) const;
See `core::string_view::compare`
Return the position of matching characters
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
rfind(
core::string_view str,
size_type pos = core::string_view::npos) const noexcept;
See `core::string_view::rfind`
Return the position of matching characters
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
rfind(
char c,
size_type pos = core::string_view::npos) const noexcept;
See `core::string_view::rfind`
Return the position of matching characters
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
rfind(
char const* s,
size_type pos,
size_type n) const noexcept;
See `core::string_view::rfind`
Return the position of matching characters
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
rfind(
char const* s,
size_type pos = core::string_view::npos) const noexcept;
See `core::string_view::rfind`
Return the position of the first match
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find_first_of(
core::string_view str,
size_type pos = 0) const noexcept;
See `core::string_view::find_first_of`
Return the position of the first match
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find_first_of(
char c,
size_type pos = 0) const noexcept;
See `core::string_view::find_first_of`
Return the position of the first match
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find_first_of(
char const* s,
size_type pos,
size_type n) const noexcept;
See `core::string_view::find_first_of`
Return the position of the first match
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find_first_of(
char const* s,
size_type pos = 0) const noexcept;
See `core::string_view::find_first_of`
Return the position of the last match
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find_last_of(
core::string_view str,
size_type pos = core::string_view::npos) const noexcept;
See `core::string_view::find_last_of`
Return the position of the last match
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find_last_of(
char c,
size_type pos = core::string_view::npos) const noexcept;
See `core::string_view::find_last_of`
Return the position of the last match
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find_last_of(
char const* s,
size_type pos,
size_type n) const noexcept;
See `core::string_view::find_last_of`
Return the position of the last match
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find_last_of(
char const* s,
size_type pos = core::string_view::npos) const noexcept;
See `core::string_view::find_last_of`
Return true if matching characters are found
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
contains(core::string_view sv) const noexcept;
See `core::string_view::contains`
Return true if matching characters are found
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
contains(char c) const noexcept;
See `core::string_view::contains`
Return true if matching characters are found
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
contains(char const* s) const noexcept;
See `core::string_view::contains`
Return the position of the first non-match
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find_first_not_of(
core::string_view str,
size_type pos = 0) const noexcept;
See `core::string_view::find_first_not_of`
Return the position of the first non-match
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find_first_not_of(
char c,
size_type pos = 0) const noexcept;
See `core::string_view::find_first_not_of`
Return the position of the first non-match
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find_first_not_of(
char const* s,
size_type pos,
size_type n) const noexcept;
See `core::string_view::find_first_not_of`
Return the position of the first non-match
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find_first_not_of(
char const* s,
size_type pos = 0) const noexcept;
See `core::string_view::find_first_not_of`
Return the position of the last non-match
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find_last_not_of(
core::string_view str,
size_type pos = core::string_view::npos) const noexcept;
See `core::string_view::find_last_not_of`
Return the position of the last non-match
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find_last_not_of(
char c,
size_type pos = core::string_view::npos) const noexcept;
See `core::string_view::find_last_not_of`
Return the position of the last non-match
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find_last_not_of(
char const* s,
size_type pos,
size_type n) const noexcept;
See `core::string_view::find_last_not_of`
Return the position of the last non-match
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
find_last_not_of(
char const* s,
size_type pos = core::string_view::npos) const noexcept;
See `core::string_view::find_last_not_of`
Default constructor
Default move constructor
Deleted copy constructor
Deleted move assignment
Deleted copy assignment
Constructor.
Constructor.
Declared in <boost/url/ipv4_address.hpp>
constexpr
ipv4_address(ipv4_address const&) = default;
Construct from an unsigned integer.
This function constructs an address from the unsigned integer `u`, where the most significant byte forms the first octet of the resulting address.
| Name | Description |
|---|---|
| u |
Construct from an array of bytes.
This function constructs an address from the array in `bytes`, which is interpreted in big-endian.
| Name | Description |
|---|---|
| bytes |
Construct from a string.
This function constructs an address from the string `s`, which must contain a valid IPv4 address string or else an exception is thrown.
For a non-throwing parse function, use parse_ipv4_address .
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| s |
Return true if two addresses are not equal
Declared in <boost/url/ipv4_address.hpp>
bool
operator!=(
ipv4_address const& a1,
ipv4_address const& a2) noexcept;
Return true if two addresses are not equal
Declared in <boost/url/ipv6_address.hpp>
bool
operator!=(
ipv6_address const& a1,
ipv6_address const& a2) noexcept;
Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
Declared in <boost/url/authority_view.hpp>
bool
operator!=(
authority_view const& a0,
authority_view const& a1) noexcept;
Compare two decode views for inequality
Declared in <boost/url/decode_view.hpp>
template<
class S0,
class S1>
constexpr
bool
operator!=(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`
Declared in <boost/url/impl/params_encoded_base.hpp>
bool
operator!=(
iterator const& it0,
iterator const& it1) noexcept;
Return the result of comparing two URLs
Declared in <boost/url/url_view_base.hpp>
bool
operator!=(
url_view_base const& u0,
url_view_base const& u1) noexcept;
The URLs are compared component by component as if they were first normalized.
url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.b.com/index.htm" );
assert( u0 != u1 );
url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() != b.buffer();
Return true if two addresses are equal
Declared in <boost/url/ipv4_address.hpp>
bool
operator==(
ipv4_address const& a1,
ipv4_address const& a2) noexcept;
Return true if two addresses are equal
Declared in <boost/url/ipv6_address.hpp>
bool
operator==(
ipv6_address const& a1,
ipv6_address const& a2) noexcept;
Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
Declared in <boost/url/authority_view.hpp>
bool
operator==(
authority_view const& a0,
authority_view const& a1) noexcept;
Compare two decode views for equality
Declared in <boost/url/decode_view.hpp>
template<
class S0,
class S1>
constexpr
bool
operator==(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`
Declared in <boost/url/impl/params_encoded_base.hpp>
bool
operator==(
iterator const& it0,
iterator const& it1) noexcept;
Return the result of comparing two URLs
Declared in <boost/url/url_view_base.hpp>
bool
operator==(
url_view_base const& u0,
url_view_base const& u1) noexcept;
The URLs are compared component by component as if they were first normalized.
url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.a.com/index.htm" );
assert( u0 == u1 );
url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() == b.buffer();
Constructor.
Default constructed objects represent the unspecified address.
Constructor.
Declared in <boost/url/ipv6_address.hpp>
constexpr
ipv6_address(ipv6_address const&) = default;
Construct from an array of bytes.
This function constructs an address from the array in `bytes`, which is interpreted in big-endian.
| Name | Description |
|---|---|
| bytes |
Construct from an IPv4 address.
This function constructs an IPv6 address from the IPv4 address `addr`. The resulting address is an IPv4-Mapped IPv6 Address.
| Name | Description |
|---|---|
| addr |
Construct from a string.
This function constructs an address from the string `s`, which must contain a valid IPv6 address string or else an exception is thrown.
For a non-throwing parse function, use parse_ipv6_address .
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| s |
Format the address to an output stream.
Declared in <boost/url/ipv4_address.hpp>
std::ostream&
operator<<(
std::ostream& os,
ipv4_address const& addr);
IPv4 addresses written to output streams are written in their dotted decimal format.
Format the address to an output stream.
IPv4 addresses written to output streams are written in their dotted decimal format.
| Name | Description |
|---|---|
| os | |
| addr | |
| os | |
| addr |
Format the address to an output stream
Declared in <boost/url/ipv6_address.hpp>
std::ostream&
operator<<(
std::ostream& os,
ipv6_address const& addr);
This hidden friend function writes the address to an output stream using standard notation.
Format the address to an output stream
This function writes the address to an output stream using standard notation.
| Name | Description |
|---|---|
| os | |
| addr | |
| os | |
| addr |
Format the encoded authority to the output stream
Declared in <boost/url/authority_view.hpp>
std::ostream&
operator<<(
std::ostream& os,
authority_view const& a);
This hidden friend function serializes the encoded URL to the output stream.
authority_view a( "www.example.com" );
std::cout << a << std::endl;
Format the encoded authority to the output stream
This function serializes the encoded URL to the output stream.
authority_view a( "www.example.com" );
std::cout << a << std::endl;
| Name | Description |
|---|---|
| os | |
| a | |
| os | |
| a |
Format the string with percent-decoding applied to the output stream
Declared in <boost/url/decode_view.hpp>
std::ostream&
operator<<(
std::ostream& os,
decode_view const& s);
This hidden friend function serializes the decoded view to the output stream.
Format the string with percent-decoding applied to the output stream
This function serializes the decoded view to the output stream.
| Name | Description |
|---|---|
| os | |
| s | |
| os | |
| s |
Format to an output stream
Declared in <boost/url/params_encoded_base.hpp>
std::ostream&
operator<<(
std::ostream& os,
params_encoded_base const& qp);
Any percent-escapes are emitted as-is; no decoding is performed.
return os << ps.buffer();
Format to an output stream
Declared in <boost/url/params_base.hpp>
std::ostream&
operator<<(
std::ostream& os,
params_base const& qp);
Any percent-escapes are emitted as-is; no decoding is performed.
return os << ps.buffer();
Format to an output stream
Declared in <boost/url/segments_encoded_base.hpp>
std::ostream&
operator<<(
std::ostream& os,
segments_encoded_base const& ps);
Any percent-escapes are emitted as-is; no decoding is performed.
return os << ps.buffer();
Format to an output stream
Declared in <boost/url/segments_base.hpp>
std::ostream&
operator<<(
std::ostream& os,
segments_base const& ps);
Any percent-escapes are emitted as-is; no decoding is performed.
return os << ps.buffer();
Format the url to the output stream
Declared in <boost/url/url_view_base.hpp>
std::ostream&
operator<<(
std::ostream& os,
url_view_base const& u);
This function serializes the url to the specified output stream. Any percent-escapes are emitted as-is; no decoding is performed.
url_view u( "http://www.example.com/index.htm" );
std::stringstream ss;
ss << u;
assert( ss.str() == "http://www.example.com/index.htm" );
return os << u.buffer();
Format the url to the output stream
This function serializes the url to the specified output stream. Any percent-escapes are emitted as-is; no decoding is performed.
url_view u( "http://www.example.com/index.htm" );
std::stringstream ss;
ss << u;
assert( ss.str() == "http://www.example.com/index.htm" );
return os << u.buffer();
| Name | Description |
|---|---|
| os | |
| u | |
| os | |
| u |
Declared in <boost/url/impl/decode_view.hpp>
constexpr
iterator(iterator const&) = default;
Constructor
Default-constructed views represent empty strings.
decode_view ds;
this->empty() == true
Constructor
Declared in <boost/url/decode_view.hpp>
decode_view(
pct_string_view s,
encoding_opts opt = = {}) noexcept;
This constructs a view from the character buffer `s`, which must remain valid and unmodified until the view is no longer accessed.
decode_view ds( "Program%20Files" );
this->encoded() == s
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| s | |
| opt |
Checks if the string begins with the given prefix
Declared in <boost/url/decode_view.hpp>
bool
starts_with(core::string_view s) const noexcept;
assert( decode_view( "Program%20Files" ).starts_with("Program") );
Checks if the string begins with the given prefix
assert( decode_view( "Program%20Files" ).starts_with('P') );
Checks if the string ends with the given prefix
Declared in <boost/url/decode_view.hpp>
bool
ends_with(core::string_view s) const noexcept;
assert( decode_view( "Program%20Files" ).ends_with("Files") );
Checks if the string ends with the given prefix
assert( decode_view( "Program%20Files" ).ends_with('s') );
Return the result of comparing to another string
Declared in <boost/url/decode_view.hpp>
int
compare(core::string_view other) const noexcept;
The length of the sequences to compare is the smaller of `size()` and `other.size()`.
The function compares the two strings as if by calling `char_traits
| Name | Description |
|---|---|
| other |
Return the result of comparing to another string
The length of the sequences to compare is the smaller of `size()` and `other.size()`.
The function compares the two strings as if by calling `char_traits
| Name | Description |
|---|---|
| other |
Constructor
Default constructed string are empty.
Constructor
Declared in <boost/url/pct_string_view.hpp>
constexpr
pct_string_view(pct_string_view const& other) = default;
The copy references the same underlying character buffer. Ownership is not transferred.
this->data() == other.data()
Declared in <boost/url/pct_string_view.hpp>
template<
class String,
class = void>
pct_string_view(String const& s);
Constructor (deleted)
Constructor
Declared in <boost/url/pct_string_view.hpp>
pct_string_view(
char const* s,
std::size_t len);
The newly constructed string references the specified character buffer. Ownership is not transferred.
this->data() == s && this->size() == len
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| s, |
Constructor
The newly constructed string references the specified character buffer. Ownership is not transferred.
this->data() == s.data() && this->size() == s.size()
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| s |
Assignment
After assignment, both views reference the same underlying character buffer. Ownership is not transferred.
this->buffer().data() == other.buffer().data()
Assignment
Declared in <boost/url/url_view.hpp>
url_view&
operator=(url_view_base const& other) noexcept;
After assignment, both views reference the same underlying character buffer. Ownership is not transferred.
this->buffer().data() == other.buffer().data()
Constructor
Default constructed views refer to a string with zero length, which always remains valid. This matches the grammar for a relative-ref with an empty path and no query or fragment.
url_view u;
this->empty() == true
relative-ref = relative-part [ "?" query ] [ "#" fragment ]
Constructor
This function constructs a URL from the string `s`, which must contain a valid URI or relative-ref or else an exception is thrown. Upon successful construction, the view refers to the characters in the buffer pointed to by `s`. Ownership is not transferred; The caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced.
url_view u( "http://www.example.com/index.htm" );
return parse_uri_reference( s ).value();
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
relative-ref = relative-part [ "?" query ] [ "#" fragment ]
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| s |
Declared in <boost/url/url_view.hpp>
template<
class String,
class = void>
url_view(String const& s);
Constructor
After construction, both views reference the same underlying character buffer. Ownership is not transferred.
this->buffer().data() == other.buffer().data()
Constructor
After construction, both views reference the same underlying character buffer. Ownership is not transferred.
this->buffer().data() == other.buffer().data()
Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
Declared in <boost/url/authority_view.hpp>
bool
operator<(
authority_view const& a0,
authority_view const& a1) noexcept;
Compare two decode views for less than
Declared in <boost/url/decode_view.hpp>
template<
class S0,
class S1>
constexpr
bool
operator<(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`
Return the result of comparing two URLs
Declared in <boost/url/url_view_base.hpp>
bool
operator<(
url_view_base const& u0,
url_view_base const& u1) noexcept;
The URLs are compared component by component as if they were first normalized.
url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.b.com/index.htm" );
assert( u0 < u1 );
url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() < b.buffer();
Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
Declared in <boost/url/authority_view.hpp>
bool
operator<=(
authority_view const& a0,
authority_view const& a1) noexcept;
Compare two decode views for less than or equal
Declared in <boost/url/decode_view.hpp>
template<
class S0,
class S1>
constexpr
bool
operator<=(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`
Return the result of comparing two URLs
Declared in <boost/url/url_view_base.hpp>
bool
operator<=(
url_view_base const& u0,
url_view_base const& u1) noexcept;
The URLs are compared component by component as if they were first normalized.
url_view u0( "http://www.b.com/index.htm" );
url_view u1( "http://www.b.com/index.htm" );
assert( u0 <= u1 );
url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() <= b.buffer();
Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
Declared in <boost/url/authority_view.hpp>
bool
operator>(
authority_view const& a0,
authority_view const& a1) noexcept;
Compare two decode views for greater than
Declared in <boost/url/decode_view.hpp>
template<
class S0,
class S1>
constexpr
bool
operator>(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`
Return the result of comparing two URLs
Declared in <boost/url/url_view_base.hpp>
bool
operator>(
url_view_base const& u0,
url_view_base const& u1) noexcept;
The URLs are compared component by component as if they were first normalized.
url_view u0( "http://www.b.com/index.htm" );
url_view u1( "http://www.a.com/index.htm" );
assert( u0 > u1 );
url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() > b.buffer();
Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
Declared in <boost/url/authority_view.hpp>
bool
operator>=(
authority_view const& a0,
authority_view const& a1) noexcept;
Compare two decode views for greater than or equal
Declared in <boost/url/decode_view.hpp>
template<
class S0,
class S1>
constexpr
bool
operator>=(
S0 const& s0,
S1 const& s1) noexcept;
This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`
Return the result of comparing two URLs
Declared in <boost/url/url_view_base.hpp>
bool
operator>=(
url_view_base const& u0,
url_view_base const& u1) noexcept;
The URLs are compared component by component as if they were first normalized.
url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.a.com/index.htm" );
assert( u0 >= u1 );
url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() >= b.buffer();
Constructor
By default, comparisons are case-sensitive.
comparisons when called with no arguments:
void f( ignore_case_param = {} );
Constructor
Declared in <boost/url/ignore_case.hpp>
constexpr
ignore_case_param(ignore_case_t) noexcept;
Construction from ignore_case indicates that comparisons should be case-insensitive.
ignore_case is passed as an argument, this function ignores case when performing comparisons:
void f( ignore_case_param = {} );
Apply percent-encoding to a string
Declared in <boost/url/encode.hpp>
template
std::size_t
encode(
char* dest,
std::size_t size,
core::string_view s,
CharSet const& unreserved,
encoding_opts opt = = {});
This function applies percent-encoding to the string using the given options and character set. The destination buffer provided by the caller is used to store the result, which may be truncated if there is insufficient space.
char buf[100];
assert( encode( buf, sizeof(buf), "Program Files", pchars ) == 15 );
| Name | Description |
|---|---|
| dest | |
| size | |
| s | |
| unreserved | |
| opt |
Return a percent-encoded string
Declared in <boost/url/encode.hpp>
template<
class StringToken = string_token::return_string,
class CharSet>
StringToken::result_type
encode(
core::string_view s,
CharSet const& unreserved,
encoding_opts opt = = {},
StringToken&& token) noexcept;
This function applies percent-encoding to the string using the given options and character set, and returns the result as a string when called with default arguments.
encoding_opts opt;
opt.space_as_plus = true;
std::string s = encode( "My Stuff", opt, pchars );
assert( s == "My+Stuff" );
| Name | Description |
|---|---|
| s | |
| unreserved | |
| opt | |
| token |
Constructor
Default constructed query parameters have an empty key and no value.
param_pct_view qp;
this->key == "" && this->value == "" && this->has_value == false
Constructor
Declared in <boost/url/param.hpp>
param_pct_view(
pct_string_view key,
pct_string_view value) noexcept;
This constructs a parameter with a key and value, which may both contain percent escapes. The new key and value reference the same corresponding underlying character buffers. Ownership of the buffers is not transferred; the caller is responsible for ensuring that the assigned buffers remain valid until they are no longer referenced.
param_pct_view qp( "key", "value" );
this->key.data() == key.data() && this->value.data() == value.data() && this->has_value == true
| Name | Thrown on |
|---|---|
`key` |
| Name | Description |
|---|---|
| key, |
Constructor
Declared in <boost/url/param.hpp>
template
param_pct_view(
pct_string_view key,
OptionalString const& value);
This constructs a parameter with a key and optional value, which may both contain percent escapes.
The new key and value reference the same corresponding underlying character buffers.
Ownership of the buffers is not transferred; the caller is responsible for ensuring that the assigned buffers remain valid until they are no longer referenced.
param_pct_view qp( "key", optional("value") );
this->key.data() == key.data() && this->value->data() == value->data() && this->has_value == true
| Name | Thrown on |
|---|---|
`key` |
| Name | Description |
|---|---|
| key, |
Construction
This converts a param which may contain unvalidated percent-escapes into a param whose key and value are guaranteed to contain strings with no invalid percent-escapes, otherwise an exception is thrown.
The new key and value reference the same corresponding underlying character buffers. Ownership of the buffers is not transferred; the caller is responsible for ensuring that the assigned buffers remain valid until they are no longer referenced.
param_pct_view qp( param_view( "key", "value" ) );
| Name | Thrown on |
|---|---|
`key` |
| Name | Description |
|---|---|
| p |
aggregate construction
Declared in <boost/url/param.hpp>
param_pct_view(
pct_string_view key,
pct_string_view value,
bool has_value) noexcept;
Constructor
Default constructed query parameters have an empty key and no value.
param_view qp;
this->key == "" && this->value == "" && this->has_value == false
Constructor
Declared in <boost/url/param.hpp>
template
param_view(
core::string_view key,
OptionalString const& value) noexcept;
This constructs a parameter with a key and value. No validation is performed on the strings. The new key and value reference the same corresponding underlying character buffers. Ownership of the buffers is not transferred; the caller is responsible for ensuring that the assigned buffers remain valid until they are no longer referenced.
param_view qp( "key", "value" );
this->key.data() == key.data() && this->value.data() == value.data() && this->has_value == true
| Name | Description |
|---|---|
| key, |
Constructor
This function constructs a param which references the character buffers representing the key and value in another container. Ownership of the buffers is not transferred; the caller is responsible for ensuring that the assigned buffers remain valid until they are no longer referenced.
param qp( "key", "value" );
param_view qpv( qp );
this->key == key && this->value == value && this->has_value == other.has_value
| Name | Description |
|---|---|
| other |
Declared in <boost/url/param.hpp>
param_view(
core::string_view key_,
core::string_view value_,
bool has_value_) noexcept;
Constructor
Default constructed query parameters have an empty key and no value.
param qp;
this->key == "" && this->value == "" && this->has_value == false
Constructor
Upon construction, this acquires ownership of the members of other via move construction. The moved from object is as if default constructed.
Constructor
Upon construction, this becomes a copy of `other`.
this->key == other.key && this->value == other.value && this->has_value == other.has_value
Constructor
Declared in <boost/url/param.hpp>
template
param(
core::string_view key,
OptionalString const& value);
This constructs a parameter with a key and value.
No validation is performed on the strings. Ownership of the key and value is acquired by making copies.
param qp( "key", "value" );
param qp( "key", optional("value") );
param qp( "key", boost::none );
param qp( "key", nullptr );
param qp( "key", no_value );
this->key == key && this->value == value && this->has_value == true
| Name | Description |
|---|---|
| key, |
Declared in <boost/url/param.hpp>
param(
core::string_view key,
core::string_view value,
bool has_value) noexcept;
Assignment
Upon assignment, this acquires ownership of the members of other via move assignment. The moved from object is as if default constructed.
Assignment
Upon assignment, this becomes a copy of `other`.
this->key == other.key && this->value == other.value && this->has_value == other.has_value
Assignment
The members of `other` are copied, re-using already existing string capacity.
this->key == other.key && this->value == other.value && this->has_value == other.has_value
| Name | Description |
|---|---|
| other |
Assignment
The members of `other` are copied, re-using already existing string capacity.
this->key == other.key && this->value == other.value && this->has_value == other.has_value
| Name | Description |
|---|---|
| other |
Declared in <boost/url/impl/params_encoded_base.hpp>
constexpr
iterator(iterator const&) = default;
Find a matching key
Declared in <boost/url/params_encoded_base.hpp>
iterator
find_last(
pct_string_view key,
ignore_case_param ic = = {}) const noexcept;
This function examines the parameters in the container to find a match for the specified key, which may contain percent escapes. The comparison is performed as if all escaped characters were decoded first.
The search starts from the last param and proceeds backwards until either the key is found or the beginning of the range is reached, in which case `end()` is returned.
assert( url_view( "?first=John&last=Doe" ).encoded_params().find_last( "last" )->value == "Doe" );
| Name | Thrown on |
|---|---|
`key` |
| Name | Description |
|---|---|
| key | |
| ic |
Find a matching key
Declared in <boost/url/params_encoded_base.hpp>
iterator
find_last(
iterator before,
pct_string_view key,
ignore_case_param ic = = {}) const noexcept;
This function examines the parameters in the container to find a match for the specified key, which may contain percent escapes. The comparison is performed as if all escaped characters were decoded first.
The search starts prior to `before` and proceeds backwards until either the key is found or the beginning of the range is reached, in which case `end()` is returned.
url_view u( "?First=John&Last=Doe" );
assert( u.encoded_params().find_last( "last" ) != u.encoded_params().find_last( "last", ignore_case ) );
| Name | Description |
|---|---|
| before | |
| key | |
| ic |
Find a matching key
Declared in <boost/url/params_encoded_base.hpp>
iterator
find(
pct_string_view key,
ignore_case_param ic = = {}) const noexcept;
This function examines the parameters in the container to find a match for the specified key, which may contain percent escapes. The comparison is performed as if all escaped characters were decoded first.
The search starts from the first param and proceeds forward until either the key is found or the end of the range is reached, in which case `end()` is returned.
assert( url_view( "?first=John&last=Doe" ).encoded_params().find( "First", ignore_case )->value == "John" );
return this->find( this->begin(), key, ic );
| Name | Thrown on |
|---|---|
`key` |
| Name | Description |
|---|---|
| key | |
| ic |
Find a matching key
Declared in <boost/url/params_encoded_base.hpp>
iterator
find(
iterator from,
pct_string_view key,
ignore_case_param ic = = {}) const noexcept;
This function examines the parameters in the container to find a match for the specified key, which may contain percent escapes. The comparison is performed as if all escaped characters were decoded first.
The search starts at `from` and proceeds forward until either the key is found or the end of the range is reached, in which case `end()` is returned.
url_view u( "?First=John&Last=Doe" );
assert( u.encoded_params().find( "first" ) != u.encoded_params().find( "first", ignore_case ) );
| Name | Thrown on |
|---|---|
`key` |
| Name | Description |
|---|---|
| from | |
| key | |
| ic |
Constructor
Declared in <boost/url/params_ref.hpp>
constexpr
params_ref(params_ref const& other) = default;
After construction, both views reference the same url. Ownership is not transferred; the caller is responsible for ensuring the lifetime of the url extends until it is no longer referenced.
&this->url() == &other.url()
| Name | Description |
|---|---|
| other |
Constructor
Declared in <boost/url/params_ref.hpp>
params_ref(
params_ref const& other,
encoding_opts opt) noexcept;
After construction, both views will reference the same url but this instance will use the specified encoding_opts when the values are decoded.
Ownership is not transferred; the caller is responsible for ensuring the lifetime of the url extends until it is no longer referenced.
&this->url() == &other.url()
| Name | Description |
|---|---|
| other | |
| opt |
Assignment
The previous contents of this are replaced by the contents of `other.
All iterators are invalidated.
The strings referenced by `other` must not come from the underlying url, or else the behavior is undefined.
this->assign( other.begin(), other.end() );
Calls to allocate may throw.
| Name | Description |
|---|---|
| other |
Assignment
Declared in <boost/url/params_ref.hpp>
params_ref&
operator=(std::initializer_list<param_view> init);
After assignment, the previous contents of the query parameters are replaced by the contents of the initializer-list.
`init` may overlap the character buffer of the underlying url, or else the behavior is undefined.
this->assign( init );
Calls to allocate may throw.
| Name | Description |
|---|---|
| init |
Assign elements
Declared in <boost/url/params_ref.hpp>
void
assign(std::initializer_list<param_view> init);
This function replaces the entire contents of the view with the params in the initializer-list .
All iterators are invalidated.
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.
url u;
u.params().assign( {{ "first", "John" }, { "last", "Doe" }} );
Calls to allocate may throw.
| Name | Description |
|---|---|
| init |
Assign elements
This function replaces the entire contents of the view with the params in the range.
All iterators are invalidated.
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == true
Calls to allocate may throw.
| Name | Description |
|---|---|
| first, |
Append elements
This function appends a param to the view.
The `end()` iterator is invalidated.
url u;
u.params().append( { "first", "John" } );
Calls to allocate may throw.
| Name | Description |
|---|---|
| p |
Append elements
Declared in <boost/url/params_ref.hpp>
iterator
append(std::initializer_list<param_view> init);
This function appends the params in an initializer-list to the view.
The `end()` iterator is invalidated.
url u;
u.params().append({ { "first", "John" }, { "last", "Doe" } });
Calls to allocate may throw.
| Name | Description |
|---|---|
| init |
Append elements
This function appends a range of params to the view.
The `end()` iterator is invalidated.
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == true
Calls to allocate may throw.
| Name | Description |
|---|---|
| first, |
Insert elements
Declared in <boost/url/params_ref.hpp>
iterator
insert(
iterator before,
param_view const& p);
This function inserts a param before the specified position.
All iterators that are equal to `before` or come after are invalidated.
Calls to allocate may throw.
| Name | Description |
|---|---|
| before | |
| p |
Insert elements
Declared in <boost/url/params_ref.hpp>
iterator
insert(
iterator before,
std::initializer_list<param_view> init);
This function inserts the params in an initializer-list before the specified position.
All iterators that are equal to `before` or come after are invalidated.
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.
Calls to allocate may throw.
| Name | Description |
|---|---|
| before | |
| init |
Insert elements
Declared in <boost/url/params_ref.hpp>
template
iterator
insert(
iterator before,
FwdIt first,
FwdIt last);
This function inserts a range of params before the specified position.
All iterators that are equal to `before` or come after are invalidated.
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == true
Calls to allocate may throw.
| Name | Description |
|---|---|
| before | |
| first, |
Erase elements
This function removes an element from the container.
All iterators that are equal to `pos` or come after are invalidated.
url u( "?first=John&last=Doe" );
params_ref::iterator it = u.params().erase( u.params().begin() );
assert( u.encoded_query() == "last=Doe" );
| Name | Description |
|---|---|
| pos |
Erase elements
Declared in <boost/url/params_ref.hpp>
iterator
erase(
iterator first,
iterator last) noexcept;
This function removes a range of elements from the container.
All iterators that are equal to `first` or come after are invalidated.
| Name | Description |
|---|---|
| first, |
Erase elements
Declared in <boost/url/params_ref.hpp>
std::size_t
erase(
core::string_view key,
ignore_case_param ic = = {}) noexcept;
All iterators are invalidated.
this->count( key, ic ) == 0
| Name | Description |
|---|---|
| key | |
| ic |
Set a value
Declared in <boost/url/params_ref.hpp>
iterator
set(
iterator pos,
core::string_view value);
This function replaces the value of an element at the specified position.
All iterators that are equal to `pos` or come after are invalidated.
url u( "?id=42&id=69" );
u.params().set( u.params().begin(), "none" );
assert( u.encoded_query() == "id=none&id=69" );
Calls to allocate may throw.
| Name | Description |
|---|---|
| pos | |
| value |
Set a value
Declared in <boost/url/params_ref.hpp>
iterator
set(
core::string_view key,
core::string_view value,
ignore_case_param ic = = {});
This function performs one of two actions depending on the value of `this->contains( key, ic )`.
All iterators are invalidated.
url u( "?id=42&id=69" );
u.params().set( "id", "none" );
assert( u.params().count( "id" ) == 1 );
this->count( key, ic ) == 1 && this->find( key, ic )->value == value
Calls to allocate may throw.
| Name | Description |
|---|---|
| key | |
| value | |
| ic |
Replace elements
Declared in <boost/url/params_ref.hpp>
iterator
replace(
iterator pos,
param_view const& p);
This function replaces the contents of the element at `pos` with the specified param.
All iterators that are equal to `pos` or come after are invalidated.
url u( "?first=John&last=Doe" );
u.params().replace( u.params().begin(), { "title", "Mr" });
assert( u.encoded_query() == "title=Mr&last=Doe" );
Calls to allocate may throw.
| Name | Description |
|---|---|
| pos | |
| p |
Replace elements
Declared in <boost/url/params_ref.hpp>
iterator
replace(
iterator from,
iterator to,
std::initializer_list<param_view> init);
This function replaces a range of elements with the params in an initializer-list .
All iterators that are equal to `from` or come after are invalidated.
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.
Calls to allocate may throw.
| Name | Description |
|---|---|
| from,to | |
| init |
Replace elements
Declared in <boost/url/params_ref.hpp>
template
iterator
replace(
iterator from,
iterator to,
FwdIt first,
FwdIt last);
This function replaces a range of elements with a range of params.
All iterators that are equal to `from` or come after are invalidated.
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == true
Calls to allocate may throw.
| Name | Description |
|---|---|
| from,to | |
| first, |
Declared in <boost/url/impl/params_base.hpp>
constexpr
iterator(iterator const&) = default;
Find a matching key
Declared in <boost/url/params_base.hpp>
iterator
find(
core::string_view key,
ignore_case_param ic = = {}) const noexcept;
This function examines the parameters in the container to find a match for the specified key. The comparison is performed as if all escaped characters were decoded first.
The search starts from the first param and proceeds forward until either the key is found or the end of the range is reached, in which case `end()` is returned.
assert( (*url_view( "?first=John&last=Doe" ).params().find( "First", ignore_case )).value == "John" );
return this->find( this->begin(), key, ic );
| Name | Description |
|---|---|
| key | |
| ic |
Find a matching key
Declared in <boost/url/params_base.hpp>
iterator
find(
iterator from,
core::string_view key,
ignore_case_param ic = = {}) const noexcept;
This function examines the parameters in the container to find a match for the specified key. The comparison is performed as if all escaped characters were decoded first.
The search starts at `from` and proceeds forward until either the key is found or the end of the range is reached, in which case `end()` is returned.
url_view u( "?First=John&Last=Doe" );
assert( u.params().find( "first" ) != u.params().find( "first", ignore_case ) );
| Name | Description |
|---|---|
| from | |
| key | |
| ic |
Find a matching key
Declared in <boost/url/params_base.hpp>
iterator
find_last(
core::string_view key,
ignore_case_param ic = = {}) const noexcept;
This function examines the parameters in the container to find a match for the specified key. The comparison is performed as if all escaped characters were decoded first.
The search starts from the last param and proceeds backwards until either the key is found or the beginning of the range is reached, in which case `end()` is returned.
assert( (*url_view( "?first=John&last=Doe" ).params().find_last( "last" )).value == "Doe" );
| Name | Description |
|---|---|
| key | |
| ic |
Find a matching key
Declared in <boost/url/params_base.hpp>
iterator
find_last(
iterator before,
core::string_view key,
ignore_case_param ic = = {}) const noexcept;
This function examines the parameters in the container to find a match for the specified key. The comparison is performed as if all escaped characters were decoded first.
The search starts prior to `before` and proceeds backwards until either the key is found or the beginning of the range is reached, in which case `end()` is returned.
url_view u( "?First=John&Last=Doe" );
assert( u.params().find_last( "last" ) != u.params().find_last( "last", ignore_case ) );
| Name | Description |
|---|---|
| before | |
| key | |
| ic |
Constructor
Default-constructed params have zero elements.
params_view qp;
return params_view( "" );
Constructor
Declared in <boost/url/params_view.hpp>
constexpr
params_view(params_view const& other) = default;
After construction both views reference the same character buffer.
Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.
this->buffer().data() == other.buffer().data()
Constructor
Declared in <boost/url/params_view.hpp>
params_view(
params_view const& other,
encoding_opts opt) noexcept;
After construction both views will reference the same character buffer but this instance will use the specified encoding_opts when the values are decoded.
Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.
this->buffer().data() == other.buffer().data()
Constructor
This function constructs params from a valid query parameter string, which can contain percent escapes. Unlike the parameters in URLs, the string passed here should not start with "?". Upon construction, the view references the character buffer pointed to by `s`. The caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced.
params_view qp( "first=John&last=Doe" );
return parse_query( s ).value();
this->buffer().data() == s.data()
query-params = [ query-param ] *( "&" query-param )
query-param = key [ "=" value ]
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Constructor
Declared in <boost/url/params_view.hpp>
params_view(
core::string_view s,
encoding_opts opt);
This function constructs params from a valid query parameter string, which can contain percent escapes.
This instance will use the specified encoding_opts when the values are decoded.
Unlike the parameters in URLs, the string passed here should not start with "?". Upon construction, the view will reference the character buffer pointed to by `s`. The caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced.
encoding_opts opt;
opt.space_as_plus = true;
params_view qp( "name=John+Doe", opt );
return params_view(parse_query( s ).value(), opt);
this->buffer().data() == s.data()
query-params = [ query-param ] *( "&" query-param )
query-param = key [ "=" value ]
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s | |
| opt |
Constructor
Default-constructed params have zero elements.
params_encoded_view qp;
return params_encoded_view( "" );
Constructor
Declared in <boost/url/params_encoded_view.hpp>
constexpr
params_encoded_view(params_encoded_view const& other) = default;
After construction both views reference the same character buffer.
Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.
this->buffer().data() == other.buffer().data()
Constructor
This function constructs params from a valid query parameter string, which can contain percent escapes. Unlike the parameters in URLs, the string passed here should not start with "?". Upon construction, the view references the character buffer pointed to by `s`. The caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced.
params_encoded_view qp( "first=John&last=Doe" );
return parse_query( s ).value();
this->buffer().data() == s.data()
query-params = [ query-param ] *( "&" query-param )
query-param = key [ "=" value ]
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| 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.
url u( "http://example.com/path/to/file.txt" );
segments sv = u.segments();
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
Return the path as a container of segments
This function returns a bidirectional view of strings 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.
segments_view sv = url_view( "/path/to/file.txt" ).segments();
path = [ "/" ] segment *( "/" segment )
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.
url u( "http://example.com/path/to/file.txt" );
segments_encoded_ref sv = u.encoded_segments();
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
Return the path as a container of segments
Declared in <boost/url/url_base.hpp>
segments_encoded_view
encoded_segments() const noexcept;
This function returns a bidirectional view of strings 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.
segments_encoded_view sv = url_view( "/path/to/file.txt" ).encoded_segments();
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
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.
params_encoded_view pv = url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_params();
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
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.
params_encoded_ref pv = url( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_params();
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
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.
params_ref pv = url( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).params();
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
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.
encoding_opts opt;
opt.space_as_plus = true;
params_ref pv = url( "/sql?id=42&name=jane+doe&page+size=20" ).params(opt);
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
| Name | Description |
|---|---|
| opt |
Assignment
Declared in <boost/url/params_encoded_ref.hpp>
params_encoded_ref&
operator=(params_encoded_ref const& other);
The previous contents of this are replaced by the contents of `other.
All iterators are invalidated.
The strings referenced by `other` must not come from the underlying url, or else the behavior is undefined.
this->assign( other.begin(), other.end() );
Calls to allocate may throw.
| Name | Description |
|---|---|
| other |
Assignment
Declared in <boost/url/params_encoded_ref.hpp>
params_encoded_ref&
operator=(std::initializer_list<param_pct_view> init);
After assignment, the previous contents of the query parameters are replaced by the contents of the initializer-list.
All iterators are invalidated.
`init` may overlap the character buffer of the underlying url, or else the behavior is undefined.
this->assign( init.begin(), init.end() );
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
`init` |
| Name | Description |
|---|---|
| init |
Assign params
Declared in <boost/url/params_encoded_ref.hpp>
void
assign(std::initializer_list<param_pct_view> init);
This function replaces the entire contents of the view with the params in the initializer-list .
All iterators are invalidated.
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.
url u;
u.encoded_params().assign({ { "first", "John" }, { "last", "Doe" } });
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
`init` |
| Name | Description |
|---|---|
| init |
Assign params
Declared in <boost/url/params_encoded_ref.hpp>
template
void
assign(
FwdIt first,
FwdIt last);
This function replaces the entire contents of the view with the params in the range.
All iterators are invalidated.
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == true
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| first, |
Append params
This function appends a param to the view.
The `end()` iterator is invalidated.
url u;
u.encoded_params().append( { "first", "John" } );
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
`p` |
| Name | Description |
|---|---|
| p |
Append params
Declared in <boost/url/params_encoded_ref.hpp>
iterator
append(std::initializer_list<param_pct_view> init);
This function appends the params in an initializer-list to the view.
The `end()` iterator is invalidated.
url u;
u.encoded_params().append({ {"first", "John"}, {"last", "Doe"} });
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
`init` |
| Name | Description |
|---|---|
| init |
Append params
Declared in <boost/url/params_encoded_ref.hpp>
template
iterator
append(
FwdIt first,
FwdIt last);
This function appends a range of params to the view.
The `end()` iterator is invalidated.
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == true
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| first, |
Erase params
This function removes an element from the container.
All iterators that are equal to `pos` or come after are invalidated.
url u( "?first=John&last=Doe" );
params_encoded_ref::iterator it = u.encoded_params().erase( u.encoded_params().begin() );
assert( u.encoded_query() == "last=Doe" );
| Name | Description |
|---|---|
| pos |
Erase params
Declared in <boost/url/params_encoded_ref.hpp>
iterator
erase(
iterator first,
iterator last) noexcept;
This function removes a range of params from the container.
All iterators that are equal to `first` or come after are invalidated.
| Name | Description |
|---|---|
| first, |
Erase params
Declared in <boost/url/params_encoded_ref.hpp>
std::size_t
erase(
pct_string_view key,
ignore_case_param ic = = {}) noexcept;
All iterators are invalidated.
this->count( key, ic ) == 0
| Name | Thrown on |
|---|---|
`key` |
| Name | Description |
|---|---|
| key | |
| ic |
Insert params
Declared in <boost/url/params_encoded_ref.hpp>
iterator
insert(
iterator before,
param_pct_view const& p);
This function inserts a param before the specified position.
All iterators that are equal to `before` or come after are invalidated.
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
`p` |
| Name | Description |
|---|---|
| before | |
| p |
Insert params
Declared in <boost/url/params_encoded_ref.hpp>
iterator
insert(
iterator before,
std::initializer_list<param_pct_view> init);
This function inserts the params in an initializer-list before the specified position.
All iterators that are equal to `before` or come after are invalidated.
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
`init` |
| Name | Description |
|---|---|
| before | |
| init |
Insert params
Declared in <boost/url/params_encoded_ref.hpp>
template
iterator
insert(
iterator before,
FwdIt first,
FwdIt last);
This function inserts a range of params before the specified position.
All iterators that are equal to `before` or come after are invalidated.
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == true
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| before | |
| first, |
Replace params
Declared in <boost/url/params_encoded_ref.hpp>
iterator
replace(
iterator pos,
param_pct_view const& p);
This function replaces the contents of the element at `pos` with the specified param.
All iterators that are equal to `pos` or come after are invalidated.
The strings passed in must not come from the element being replaced, or else the behavior is undefined.
url u( "?first=John&last=Doe" );
u.encoded_params().replace( u.encoded_params().begin(), { "title", "Mr" });
assert( u.encoded_query() == "title=Mr&last=Doe" );
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
`p` |
| Name | Description |
|---|---|
| pos | |
| p |
Replace params
Declared in <boost/url/params_encoded_ref.hpp>
iterator
replace(
iterator from,
iterator to,
std::initializer_list<param_pct_view> init);
This function replaces a range of params with the params in an initializer-list .
All iterators that are equal to `from` or come after are invalidated.
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
`init` |
| Name | Description |
|---|---|
| from,to | |
| init |
Replace params
Declared in <boost/url/params_encoded_ref.hpp>
template
iterator
replace(
iterator from,
iterator to,
FwdIt first,
FwdIt last);
This function replaces a range of params with a range of params.
All iterators that are equal to `from` or come after are invalidated.
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == true
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| from,to | |
| first, |
Set a value
Declared in <boost/url/params_encoded_ref.hpp>
iterator
set(
iterator pos,
pct_string_view value);
This function replaces the value of an element at the specified position.
All iterators that are equal to `pos` or come after are invalidated.
The string passed in must not come from the element being replaced, or else the behavior is undefined.
url u( "?id=42&id=69" );
u.encoded_params().set( u.encoded_params().begin(), "none" );
assert( u.encoded_query() == "id=none&id=69" );
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
`value` |
| Name | Description |
|---|---|
| pos | |
| value |
Set a value
Declared in <boost/url/params_encoded_ref.hpp>
iterator
set(
pct_string_view key,
pct_string_view value,
ignore_case_param ic = = {});
This function performs one of two actions depending on the value of `this->contains( key, ic )`.
All iterators are invalidated.
The strings passed in must not come from the element being replaced, or else the behavior is undefined.
url u( "?id=42&id=69" );
u.encoded_params().set( "id", "none" );
assert( u.encoded_params().count( "id" ) == 1 );
this->count( key, ic ) == 1 && this->find( key, ic )->value == value
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
`key` |
| Name | Description |
|---|---|
| key | |
| value | |
| ic |
Declared in <boost/url/impl/segments_encoded_base.hpp>
constexpr
iterator(iterator const&) = default;
Constructor
Declared in <boost/url/segments_encoded_view.hpp>
constexpr
segments_encoded_view() = default;
Default-constructed segments have zero elements.
segments_encoded_view ps;
return segments_encoded_view( "" );
Constructor
Declared in <boost/url/segments_encoded_view.hpp>
constexpr
segments_encoded_view(segments_encoded_view const&) noexcept = default;
After construction, both views reference the same character buffer.
Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.
this->buffer().data() == other.buffer().data()
Constructor
Declared in <boost/url/segments_encoded_view.hpp>
segments_encoded_view(core::string_view s);
This function constructs segments from a valid path string, which can contain percent escapes. Upon construction, the view references the character buffer pointed to by `s`. caller is responsible for ensuring that the lifetime of the buffer extends until the view is destroyed.
segments_encoded_view ps( "/path/to/file.txt" );
return parse_path( s ).value();
this->buffer().data() == s.data()
path = [ "/" ] [ segment *( "/" segment ) ]
segment = *pchar
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Assignment
Declared in <boost/url/segments_encoded_ref.hpp>
segments_encoded_ref&
operator=(segments_encoded_ref const& other);
The existing contents are replaced by a copy of the other segments.
All iterators are invalidated.
None of the character buffers referenced by `other` may overlap the buffer of the underlying url, or else the behavior is undefined.
this->assign( other.begin(), other.end() );
Calls to allocate may throw.
@{
| Name | Description |
|---|---|
| other |
Declared in <boost/url/segments_encoded_ref.hpp>
segments_encoded_ref&
operator=(segments_encoded_view const& other);
Assignment
Declared in <boost/url/segments_encoded_ref.hpp>
segments_encoded_ref&
operator=(std::initializer_list<pct_string_view> init);
The existing contents are replaced by a copy of the contents of the initializer list. Reserved characters in the list are automatically escaped. Escapes in the list are preserved.
All iterators are invalidated.
url u;
u.encoded_segments() = {"path", "to", "file.txt"};
by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.
this->assign( init.begin(), init.end() );
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| init |
Assign segments
Declared in <boost/url/segments_encoded_ref.hpp>
void
assign(std::initializer_list<pct_string_view> init);
The existing contents are replaced by a copy of the contents of the initializer list. Reserved characters in the list are automatically escaped. Escapes in the list are preserved.
All iterators are invalidated.
None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.
url u;
u.segments().assign( {"path", "to", "file.txt"} );
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| init |
Assign segments
Declared in <boost/url/segments_encoded_ref.hpp>
template
void
assign(
FwdIt first,
FwdIt last);
The existing contents are replaced by a copy of the contents of the range. Reserved characters in the range are automatically escaped. Escapes in the range are preserved.
All iterators are invalidated.
None of the character buffers referenced by the range may overlap the character buffer of the underlying url, or else the behavior is undefined.
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, pct_string_view >::value == true
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| first, |
Erase segments
This function removes a segment.
All iterators that are equal to `pos` or come after are invalidated.
| Name | Description |
|---|---|
| pos |
Erase segments
Declared in <boost/url/segments_encoded_ref.hpp>
iterator
erase(
iterator first,
iterator last) noexcept;
This function removes a range of segments from the container.
All iterators that are equal to `first` or come after are invalidated.
| Name | Description |
|---|---|
| first, |
Insert segments
Declared in <boost/url/segments_encoded_ref.hpp>
iterator
insert(
iterator before,
pct_string_view s);
This function inserts a segment before the specified position. Reserved characters in the segment are automatically escaped. Escapes in the segment are preserved.
All iterators that are equal to `before` or come after are invalidated.
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| before | |
| s |
Insert segments
Declared in <boost/url/segments_encoded_ref.hpp>
iterator
insert(
iterator before,
std::initializer_list<pct_string_view> init);
This function inserts the segments in an initializer list before the specified position. Reserved characters in the list are automatically escaped. Escapes in the list are preserved.
All iterators that are equal to `before` or come after are invalidated.
None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.
url u( "/file.txt" );
u.encoded_segments().insert( u.encoded_segments().begin(), { "path", "to" } );
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| before | |
| init |
Insert segments
Declared in <boost/url/segments_encoded_ref.hpp>
template
iterator
insert(
iterator before,
FwdIt first,
FwdIt last);
This function inserts the segments in a range before the specified position. Reserved characters in the range are automatically escaped. Escapes in the range are preserved.
All iterators that are equal to `before` or come after are invalidated.
None of the character buffers referenced by the range may overlap the character buffer of the underlying url, or else the behavior is undefined.
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, pct_string_view >::value == true
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| before | |
| first, |
Replace segments
Declared in <boost/url/segments_encoded_ref.hpp>
iterator
replace(
iterator pos,
pct_string_view s);
This function replaces the segment at the specified position. Reserved characters in the string are automatically escaped. Escapes in the string are preserved.
All iterators that are equal to `pos` or come after are invalidated.
Calls to allocate may throw.
| Name | Description |
|---|---|
| pos | |
| s |
Replace segments
Declared in <boost/url/segments_encoded_ref.hpp>
iterator
replace(
iterator from,
iterator to,
pct_string_view s);
This function replaces a range of segments with one segment. Reserved characters in the string are automatically escaped. Escapes in the string are preserved.
All iterators that are equal to `from` or come after are invalidated.
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| from, | |
| s |
Replace segments
Declared in <boost/url/segments_encoded_ref.hpp>
iterator
replace(
iterator from,
iterator to,
std::initializer_list<pct_string_view> init);
This function replaces a range of segments with a list of segments in an initializer list. Reserved characters in the list are automatically escaped. Escapes in the list are preserved.
All iterators that are equal to `from` or come after are invalidated.
by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| from, | |
| init |
Replace segments
Declared in <boost/url/segments_encoded_ref.hpp>
template
iterator
replace(
iterator from,
iterator to,
FwdIt first,
FwdIt last);
This function replaces a range of segments with annother range of segments. Reserved characters in the new range are automatically escaped. Escapes in the new range are preserved.
All iterators that are equal to `from` or come after are invalidated.
by the new range may overlap the character buffer of the underlying url, or else the behavior is undefined.
Calls to allocate may throw. Exceptions thrown on invalid input.
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| from, | |
| first, |
Declared in <boost/url/impl/segments_base.hpp>
constexpr
iterator(iterator const&) = default;
Constructor
Default-constructed segments have zero elements.
segments_view ps;
return segments_view( "" );
Constructor
Declared in <boost/url/segments_view.hpp>
constexpr
segments_view(segments_view const& other) = default;
After construction, viewss reference the same underlying character buffer.
Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.
this->buffer().data() == other.buffer().data()
Constructor
This function constructs segments from a valid path string, which can contain percent escapes. Upon construction, the view references the character buffer pointed to by `s`. caller is responsible for ensuring that the lifetime of the buffer extends until the view is destroyed.
segments_view ps( "/path/to/file.txt" );
return parse_path( s ).value();
this->buffer().data() == s.data()
path = [ "/" ] [ segment *( "/" segment ) ]
segment = *pchar
| Name | Thrown on |
|---|---|
`s` |
| Name | Description |
|---|---|
| s |
Assignment
Declared in <boost/url/segments_ref.hpp>
segments_ref&
operator=(segments_ref const& other);
The existing contents are replaced by a copy of the other segments.
All iterators are invalidated.
None of the character buffers referenced by `other` may overlap the buffer of the underlying url, or else the behavior is undefined.
this->assign( other.begin(), other.end() );
Calls to allocate may throw.
@{
| Name | Description |
|---|---|
| other |
Declared in <boost/url/segments_ref.hpp>
segments_ref&
operator=(segments_view const& other);
Assignment
Declared in <boost/url/segments_ref.hpp>
segments_ref&
operator=(std::initializer_list init);
The existing contents are replaced by a copy of the contents of the initializer list. Reserved characters in the list are automatically escaped.
All iterators are invalidated.
url u;
u.segments() = { "path", "to", "file.txt" };
by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.
this->assign( init.begin(), init.end() );
Calls to allocate may throw.
| Name | Description |
|---|---|
| init |
Assign segments
The existing contents are replaced by a copy of the contents of the initializer list. Reserved characters in the list are automatically escaped.
All iterators are invalidated.
None of the character buffers referenced by `init` may overlap the character buffer of the underlying url, or else the behavior is undefined.
url u;
u.segments().assign( { "path", "to", "file.txt" } );
Calls to allocate may throw.
| Name | Description |
|---|---|
| init |
Assign segments
The existing contents are replaced by a copy of the contents of the range. Reserved characters in the range are automatically escaped.
All iterators are invalidated.
None of the character buffers referenced by the range may overlap the character buffer of the underlying url, or else the behavior is undefined.
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, core::string_view >::value == true
Calls to allocate may throw.
| Name | Description |
|---|---|
| first, |
Erase segments
This function removes a segment.
All iterators that are equal to `pos` or come after are invalidated.
| Name | Description |
|---|---|
| pos |
Erase segments
Declared in <boost/url/segments_ref.hpp>
iterator
erase(
iterator first,
iterator last) noexcept;
This function removes a range of segments.
All iterators that are equal to `first` or come after are invalidated.
| Name | Description |
|---|---|
| first, |
Insert segments
Declared in <boost/url/segments_ref.hpp>
iterator
insert(
iterator before,
core::string_view s);
This function inserts a segment before the specified position. Reserved characters in the segment are automatically escaped.
All iterators that are equal to `before` or come after are invalidated.
Calls to allocate may throw.
| Name | Description |
|---|---|
| before | |
| s |
Insert segments
Declared in <boost/url/segments_ref.hpp>
iterator
insert(
iterator before,
std::initializer_list init);
This function inserts the segments in an initializer list before the specified position. Reserved characters in the list are percent-escaped in the result.
All iterators that are equal to `before` or come after are invalidated.
None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.
url u( "/file.txt" );
u.segments().insert( u.segments().begin(), { "path", "to" } );
Calls to allocate may throw.
| Name | Description |
|---|---|
| before | |
| init |
Insert segments
Declared in <boost/url/segments_ref.hpp>
template
iterator
insert(
iterator before,
FwdIt first,
FwdIt last);
This function inserts the segments in a range before the specified position. Reserved characters in the list are automatically escaped.
All iterators that are equal to `before` or come after are invalidated.
None of the character buffers referenced by the range may overlap the character buffer of the underlying url, or else the behavior is undefined.
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, core::string_view >::value == true
Calls to allocate may throw.
| Name | Description |
|---|---|
| before | |
| first, |
Replace segments
Declared in <boost/url/segments_ref.hpp>
iterator
replace(
iterator pos,
core::string_view s);
This function replaces the segment at the specified position. Reserved characters in the string are automatically escaped.
All iterators that are equal to `pos` or come after are invalidated.
Calls to allocate may throw.
| Name | Description |
|---|---|
| pos | |
| s |
Replace segments
Declared in <boost/url/segments_ref.hpp>
iterator
replace(
iterator from,
iterator to,
core::string_view s);
This function replaces a range of segments with one segment. Reserved characters in the string are automatically escaped.
All iterators that are equal to `from` or come after are invalidated.
Calls to allocate may throw.
| Name | Description |
|---|---|
| from, | |
| s |
Replace segments
Declared in <boost/url/segments_ref.hpp>
iterator
replace(
iterator from,
iterator to,
std::initializer_list init);
This function replaces a range of segments with a list of segments in an initializer list. Reserved characters in the list are automatically escaped.
All iterators that are equal to `from` or come after are invalidated.
by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.
Calls to allocate may throw.
| Name | Description |
|---|---|
| from, | |
| init |
Replace segments
Declared in <boost/url/segments_ref.hpp>
template
iterator
replace(
iterator from,
iterator to,
FwdIt first,
FwdIt last);
This function replaces a range of segments with annother range of segments. Reserved characters in the new range are automatically escaped.
All iterators that are equal to `from` or come after are invalidated.
by the new range may overlap the character buffer of the underlying url, or else the behavior is undefined.
Calls to allocate may throw.
| Name | Description |
|---|---|
| from, | |
| first, |
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.
params_view pv = url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).params();
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )
Declared in <boost/url/url_view_base.hpp>
params_view
params(encoding_opts opt) const noexcept;
Constructor
Default constructed urls contain a zero-length string. This matches the grammar for a relative-ref with an empty path and no query or fragment.
url u;
this->empty() == true
relative-ref = relative-part [ "?" query ] [ "#" fragment ]
Constructor
This function constructs a URL from the string `s`, which must contain a valid URI or relative-ref or else an exception is thrown. The new url retains ownership by allocating a copy of the passed string.
url u( "https://www.example.com" );
return url( parse_uri_reference( s ).value() );
this->buffer().data() != s.data()
Exceptions thrown on invalid input.
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
relative-ref = relative-part [ "?" query ] [ "#" fragment ]
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| s |
Constructor
The contents of `u` are transferred to the newly constructed object, which includes the underlying character buffer. After construction, the moved-from object is as if default constructed.
u.empty() == true
| Name | Description |
|---|---|
| u |
Constructor
The newly constructed object contains a copy of `u`.
this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()
Calls to allocate may throw.
| Name | Thrown on |
|---|---|
`u.size() |
| Name | Description |
|---|---|
| u |
Constructor
The newly constructed object contains a copy of `u`.
this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()
Calls to allocate may throw.
| Name | Thrown on |
|---|---|
`u.size() |
| Name | Description |
|---|---|
| u |
Assignment
The contents of `u` are transferred to `this`, including the underlying character buffer. The previous contents of `this` are destroyed. After assignment, the moved-from object is as if default constructed.
u.empty() == true
| Name | Description |
|---|---|
| u |
Assignment
The contents of `u` are copied and the previous contents of `this` are destroyed. Capacity is preserved, or increases.
this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()
Calls to allocate may throw.
| Name | Thrown on |
|---|---|
`u.size() |
| Name | Description |
|---|---|
| u |
Assignment
The contents of `u` are copied and the previous contents of `this` are destroyed. Capacity is preserved, or increases.
this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()
Calls to allocate may throw.
| Name | Description |
|---|---|
| u |
Format arguments into a URL
Declared in <boost/url/format.hpp>
template
url
format(
core::string_view fmt,
Args&&... args);
Format arguments according to the format URL string into a url .
The rules for a format URL string are the same as for a `std::format_string`, where replacement fields are delimited by curly braces.
The URL components to which replacement fields belong are identified before replacement is applied and any invalid characters for that formatted argument are percent-escaped.
Hence, the delimiters between URL components, such as `:`, `//`, `?`, and `#`, should be included in the URL format string. Likewise, a format string with a single `"{}"` is interpreted as a path and any replacement characters invalid in this component will be encoded to form a valid URL.
assert(format("{}", "Hello world!").buffer() == "Hello%20world%21");
resulting URL should be valid after arguments are formatted into the URL.
Because any invalid characters for a URL component are encoded by this function, only replacements in the scheme and port components might be invalid, as these components do not allow percent-encoding of arbitrary characters.
replacement_field ::= "{" [arg_id] [":" (format_spec | chrono_format_spec)] "}"
arg_id ::= integer | identifier
integer ::= digit+
digit ::= "0"..."9"
identifier ::= id_start id_continue*
id_start ::= "a"..."z" | "A"..."Z" | "_"
id_continue ::= id_start | digit
| Name | Thrown on |
|---|---|
`fmt` |
| Name | Description |
|---|---|
| fmt | |
| args |
Format arguments into a URL
Declared in <boost/url/format.hpp>
url
format(
core::string_view fmt,
std::initializer_list<_see-below_> args);
Format arguments according to the format URL string into a url .
This overload allows type-erased arguments to be passed as an initializer_list, which is mostly convenient for named parameters.
All arguments must be convertible to a implementation defined type able to store a type-erased reference to any valid format argument.
The rules for a format URL string are the same as for a `std::format_string`, where replacement fields are delimited by curly braces.
The URL components to which replacement fields belong are identified before replacement is applied and any invalid characters for that formatted argument are percent-escaped.
Hence, the delimiters between URL components, such as `:`, `//`, `?`, and `#`, should be included in the URL format string. Likewise, a format string with a single `"{}"` is interpreted as a path and any replacement characters invalid in this component will be encoded to form a valid URL.
assert(format("user/{id}", {{"id", 1}}).buffer() == "user/1");
resulting URL should be valid after arguments are formatted into the URL.
Because any invalid characters for a URL component are encoded by this function, only replacements in the scheme and port components might be invalid, as these components do not allow percent-encoding of arbitrary characters.
replacement_field ::= "{" [arg_id] [":" (format_spec | chrono_format_spec)] "}"
arg_id ::= integer | identifier
integer ::= digit+
digit ::= "0"..."9"
identifier ::= id_start id_continue*
id_start ::= "a"..."z" | "A"..."Z" | "_"
id_continue ::= id_start | digit
| Name | Thrown on |
|---|---|
`fmt` |
| Name | Description |
|---|---|
| fmt | |
| args |
Format arguments into a URL
Declared in <boost/url/format.hpp>
template
void
format_to(
url_base& u,
core::string_view fmt,
Args&&... args);
Format arguments according to the format URL string into a url_base .
The rules for a format URL string are the same as for a `std::format_string`, where replacement fields are delimited by curly braces.
The URL components to which replacement fields belong are identified before replacement is applied and any invalid characters for that formatted argument are percent-escaped.
Hence, the delimiters between URL components, such as `:`, `//`, `?`, and `#`, should be included in the URL format string. Likewise, a format string with a single `"{}"` is interpreted as a path and any replacement characters invalid in this component will be encoded to form a valid URL.
static_url<30> u;
format(u, "{}", "Hello world!");
assert(u.buffer() == "Hello%20world%21");
resulting URL should be valid after arguments are formatted into the URL.
Because any invalid characters for a URL component are encoded by this function, only replacements in the scheme and port components might be invalid, as these components do not allow percent-encoding of arbitrary characters.
replacement_field ::= "{" [arg_id] [":" (format_spec | chrono_format_spec)] "}"
arg_id ::= integer | identifier
integer ::= digit+
digit ::= "0"..."9"
identifier ::= id_start id_continue*
id_start ::= "a"..."z" | "A"..."Z" | "_"
id_continue ::= id_start | digit
| Name | Thrown on |
|---|---|
`fmt` |
| Name | Description |
|---|---|
| u | |
| fmt | |
| args |
Format arguments into a URL
Declared in <boost/url/format.hpp>
void
format_to(
url_base& u,
core::string_view fmt,
std::initializer_list<_see-below_> args);
Format arguments according to the format URL string into a url_base .
This overload allows type-erased arguments to be passed as an initializer_list, which is mostly convenient for named parameters.
All arguments must be convertible to a implementation defined type able to store a type-erased reference to any valid format argument.
The rules for a format URL string are the same as for a `std::format_string`, where replacement fields are delimited by curly braces.
The URL components to which replacement fields belong are identified before replacement is applied and any invalid characters for that formatted argument are percent-escaped.
Hence, the delimiters between URL components, such as `:`, `//`, `?`, and `#`, should be included in the URL format string. Likewise, a format string with a single `"{}"` is interpreted as a path and any replacement characters invalid in this component will be encoded to form a valid URL.
static_url<30> u;
format_to(u, "user/{id}", {{"id", 1}})
assert(u.buffer() == "user/1");
resulting URL should be valid after arguments are formatted into the URL.
Because any invalid characters for a URL component are encoded by this function, only replacements in the scheme and port components might be invalid, as these components do not allow percent-encoding of arbitrary characters.
replacement_field ::= "{" [arg_id] [":" (format_spec | chrono_format_spec)] "}"
arg_id ::= integer | identifier
integer ::= digit+
digit ::= "0"..."9"
identifier ::= id_start id_continue*
id_start ::= "a"..."z" | "A"..."Z" | "_"
id_continue ::= id_start | digit
| Name | Thrown on |
|---|---|
`fmt` |
| Name | Description |
|---|---|
| u | |
| fmt | |
| args |
Assignment
Declared in <boost/url/static_url.hpp>
static_url&
operator=(static_url const& u) noexcept;
The contents of `u` are copied and the previous contents of `this` are discarded. Capacity remains unchanged.
this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()
| Name | Description |
|---|---|
| u |
Assignment
The contents of `u` are copied and the previous contents of `this` are discarded.
this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()
Exception thrown if capacity exceeded.
| Name | Thrown on |
|---|---|
Capacity |
| Name | Description |
|---|---|
| u |
Constructor
Default constructed urls contain a zero-length string. This matches the grammar for a relative-ref with an empty path and no query or fragment.
static_url< 1024 > u;
this->empty() == true
relative-ref = relative-part [ "?" query ] [ "#" fragment ]
Constructor
This function constructs a url from the string `s`, which must contain a valid URI or relative-ref or else an exception is thrown. The new url retains ownership by making a copy of the passed string.
static_url< 1024 > u( "https://www.example.com" );
return static_url( parse_uri_reference( s ).value() );
this->buffer().data() != s.data()
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
relative-ref = relative-part [ "?" query ] [ "#" fragment ]
| Name | Thrown on |
|---|---|
The |
| Name | Description |
|---|---|
| s |
Constructor
The newly constructed object contains a copy of `u`.
this->buffer() == u.buffer() && this->buffer.data() != u.buffer().data()
| Name | Description |
|---|---|
| u |
Constructor
The newly constructed object contains a copy of `u`.
this->buffer() == u.buffer() && this->buffer.data() != u.buffer().data()
| Name | Thrown on |
|---|---|
Capacity |
| Name | Description |
|---|---|
| u |