Namespaces
Name |
boost::urls namespace
Namespaces
Name |
Types
Name |
Description |
A non‐owning reference to a valid authority |
|
A reference to a valid, percent‐encoded string |
|
Percent‐encoding options |
|
An optional parameter to determine case‐sensitivity |
|
An IP version 4 style address. |
|
An IP version 6 style address. |
|
The type of |
|
A query parameter |
|
A view of a percent‐encoded query parameter |
|
A view of a query parameter |
|
Common functionality for query parameter containers |
|
Common functionality for containers |
|
A view representing query parameters in a URL |
|
A view representing query parameters in a URL |
|
A view representing query parameters in a URL |
|
A view representing query parameters in a URL |
|
A reference to a valid percent‐encoded string |
|
Common functionality for containers |
|
Common functionality for containers |
|
A view representing path segments in a URL |
|
A view representing path segments in a URL |
|
A view representing path segments in a URL |
|
A view representing path segments in a URL |
|
A modifiable container for a URL. |
|
Common implementation for all static URLs |
|
A modifiable container for a URL. |
|
Common functionality for containers |
|
A non‐owning reference to a valid URL |
|
Common functionality for containers |
|
A temporary reference to a formatting argument |
|
A temporary reference to a named formatting argument |
|
The type of optional used by the library |
|
The type of string_view used by the library |
|
The type of variant used by the library |
Enums
Name |
Description |
Error codes returned the library |
|
Identifies the type of host in a URL. |
|
Identifies a known URL scheme |
Functions
Name |
Description |
Designate a named argument for a replacement field |
|
Return the default port for a known scheme |
|
|
|
Return the buffer size needed for percent‐encoding |
|
Format arguments into a URL |
|
Format arguments into a URL |
|
Return a valid percent‐encoded string |
|
Return a reference to a parsed URL string |
|
Parse an authority |
|
Return an IPv4 address from an IP address string in dotted decimal form |
|
Parse a string containing an IPv6 address. |
|
Return a reference to a parsed URL string |
|
Parse a string and return an encoded segment view |
|
Parse a string and return an encoded params view |
|
Return a reference to a parsed URL string |
|
Return a reference to a parsed URL string |
|
Return a reference to a parsed URL string |
|
Rule for a string with percent‐encoded escapes |
|
Resolve a URL reference against a base URL |
|
Return the known scheme for a non‐normalized string, if known |
|
Swap |
|
Return the normalized string for a known scheme |
|
Stream insertion operators |
|
Equality operators |
|
Inequality operators |
|
Less‐than operators |
|
Less‐than‐or‐equal operators |
|
Greater‐than operators |
|
Greater‐than‐or‐equal operators |
Variables
Name |
Description |
Rule for absolute‐URI |
|
Rule for authority |
|
The gen‐delims character set |
|
Ignore case when comparing |
|
Rule for an IP version 4 style address |
|
Rule for An IP version 6 style address |
|
Constant indicating no value in a param |
|
Rule for origin‐form |
|
The path character set |
|
Rule for a query string |
|
Rule for relative‐ref |
|
The reserved character set |
|
The sub‐delims character set |
|
The unreserved character set |
|
Rule for URI‐reference |
|
Rule for URI |
Using Namespace Directives
Name |
boost::urls::error_types namespace
Namespace Aliases
Name |
Description |
The set of constants used for cross‐platform error codes |
Types
Name |
Description |
The type of error category used by the library |
|
The type of error code used by the library |
|
The type of error condition used by the library |
|
The type of result returned by library functions |
|
The type of system error thrown by the library |
Using Declarations
Name |
Description |
A function to return the generic error category used by the library |
|
A function to return the system error category used by the library |
boost::urls::grammar namespace
Namespace Aliases
Name |
Types
Name |
Description |
Match a string literal exactly |
|
A set of characters |
|
A forward range of parsed elements |
|
A thread‐safe collection of instances of T |
|
A pointer to a shared instance of T |
|
Common functionality for string views |
|
Match an unsigned decimal |
|
Provides an aligned storage buffer aligned for T |
|
A case‐insensitive equals predicate for strings |
|
A case‐insensitive hash function object for strings |
|
A case‐insensitive less predicate for strings |
|
Alias for |
|
Determine if T meets the requirements of |
Enums
Name |
Description |
Error conditions for errors received from rules |
|
Error codes returned when using rules |
Functions
Name |
Description |
Return the case‐insensitive comparison of s0 and s1 |
|
Return the case‐insensitive digest of a string |
|
Return true if s0 equals s1 using case‐insensitive comparison |
|
Return true if s0 is less than s1 using case‐insensitive comparison |
|
|
|
Find the first character in the string that is in the set. |
|
Find the first character in the string that is not in CharSet |
|
Return the decimal value of a hex character |
|
Match another rule, if the result is not empty |
|
Return the union of two character sets. |
|
Return a new character set by subtracting |
|
Match a rule, or the empty string |
|
Parse a character buffer using a rule |
|
Match a repeating number of elements |
|
|
|
Squelch the value of a rule |
|
Return c converted to lowercase |
|
Return c converted to uppercase |
|
Match a non‐empty string of characters from a set |
|
Match a series of rules in order |
|
Match one of a set of rules |
|
Format a string to an output stream |
|
Compare two string views for equality |
|
Compare two string views for inequality |
|
Compare two string views for less than |
|
Compare two string views for less than or equal |
|
Compare two string views for greater than |
|
Compare two string views for greater than or equal |
Variables
Name |
Description |
The set of all characters |
|
The set of letters and digits |
|
The set of all letters |
|
Match a decimal octet |
|
The set of decimal digits |
|
The set of hexadecimal digits |
|
The set of visible characters |
boost::urls::string_token namespace
Types
Name |
Description |
Base class for string tokens, and algorithm parameters |
|
Trait to determine if a type is a string token |
|
A string token for returning a plain string |
Functions
Name |
Description |
Create a string token for appending to a plain string |
|
Create a string token for assigning to a plain string |
|
Create a string token for a durable core::string_view |
Concepts
Name |
Description |
Concept for a string token |
Namespaces
Name |
Namespaces
Types
Name |
Description |
A non‐owning reference to a valid authority |
|
A reference to a valid, percent‐encoded string |
|
Percent‐encoding options |
|
An optional parameter to determine case‐sensitivity |
|
An IP version 4 style address. |
|
An IP version 6 style address. |
|
The type of |
|
A query parameter |
|
A view of a percent‐encoded query parameter |
|
A view of a query parameter |
|
Common functionality for query parameter containers |
|
Common functionality for containers |
|
A view representing query parameters in a URL |
|
A view representing query parameters in a URL |
|
A view representing query parameters in a URL |
|
A view representing query parameters in a URL |
|
A reference to a valid percent‐encoded string |
|
Common functionality for containers |
|
Common functionality for containers |
|
A view representing path segments in a URL |
|
A view representing path segments in a URL |
|
A view representing path segments in a URL |
|
A view representing path segments in a URL |
|
A modifiable container for a URL. |
|
Common implementation for all static URLs |
|
A modifiable container for a URL. |
|
Common functionality for containers |
|
A non‐owning reference to a valid URL |
|
Common functionality for containers |
|
A temporary reference to a formatting argument |
|
A temporary reference to a named formatting argument |
|
The type of optional used by the library |
|
The type of string_view used by the library |
|
The type of variant used by the library |
Enums
Functions
Name |
Description |
Designate a named argument for a replacement field |
|
Return the default port for a known scheme |
|
|
|
Return the buffer size needed for percent‐encoding |
|
Format arguments into a URL |
|
Format arguments into a URL |
|
Return a valid percent‐encoded string |
|
Return a reference to a parsed URL string |
|
Parse an authority |
|
Return an IPv4 address from an IP address string in dotted decimal form |
|
Parse a string containing an IPv6 address. |
|
Return a reference to a parsed URL string |
|
Parse a string and return an encoded segment view |
|
Parse a string and return an encoded params view |
|
Return a reference to a parsed URL string |
|
Return a reference to a parsed URL string |
|
Return a reference to a parsed URL string |
|
Rule for a string with percent‐encoded escapes |
|
Resolve a URL reference against a base URL |
|
Return the known scheme for a non‐normalized string, if known |
|
Swap |
|
Return the normalized string for a known scheme |
|
Stream insertion operators |
|
Equality operators |
|
Inequality operators |
|
Less‐than operators |
|
Less‐than‐or‐equal operators |
|
Greater‐than operators |
|
Greater‐than‐or‐equal operators |
Variables
Name |
Description |
Rule for absolute‐URI |
|
Rule for authority |
|
The gen‐delims character set |
|
Ignore case when comparing |
|
Rule for an IP version 4 style address |
|
Rule for An IP version 6 style address |
|
Constant indicating no value in a param |
|
Rule for origin‐form |
|
The path character set |
|
Rule for a query string |
|
Rule for relative‐ref |
|
The reserved character set |
|
The sub‐delims character set |
|
The unreserved character set |
|
Rule for URI‐reference |
|
Rule for URI |
Using Namespace Directives
Name |
Namespace Aliases
Name |
Description |
The set of constants used for cross‐platform error codes |
Types
Name |
Description |
The type of error category used by the library |
|
The type of error code used by the library |
|
The type of error condition used by the library |
|
The type of result returned by library functions |
|
The type of system error thrown by the library |
Using Declarations
Name |
Description |
A function to return the generic error category used by the library |
|
A function to return the system error category used by the library |
The set of constants used for cross‐platform error codes
Synopsis
Declared in <boost/url/error_types.hpp>
namespace errc = boost::system::errc;Description
|
Warning
|
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 error category used by the library
Synopsis
Declared in <boost/url/error_types.hpp>
using error_category = boost::system::error_category;Description
|
Warning
|
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
Synopsis
Declared in <boost/url/error_types.hpp>
using error_code = boost::system::error_code;Description
|
Warning
|
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
Synopsis
Declared in <boost/url/error_types.hpp>
using error_condition = boost::system::error_condition;Description
|
Warning
|
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 result returned by library functions
Synopsis
Declared in <boost/url/error_types.hpp>
template<class T>
using result = boost::system::result<T, system::error_code>;Description
|
Warning
|
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:
Declaration
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;
...moreUsage
Given the function 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;Template Parameters
Name |
Description |
T |
The type of value held by the result. |
See Also
The type of system error thrown by the library
Synopsis
Declared in <boost/url/error_types.hpp>
using system_error = boost::system::system_error;Description
|
Warning
|
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
Synopsis
Declared in <boost/url/error_types.hpp>
using boost::system::generic_category;Description
|
Warning
|
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.
A function to return the system error category used by the library
Synopsis
Declared in <boost/url/error_types.hpp>
using boost::system::system_category;Description
|
Warning
|
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.
Namespace Aliases
Name |
Types
Name |
Description |
Match a string literal exactly |
|
A set of characters |
|
A forward range of parsed elements |
|
A thread‐safe collection of instances of T |
|
A pointer to a shared instance of T |
|
Common functionality for string views |
|
Match an unsigned decimal |
|
Provides an aligned storage buffer aligned for T |
|
A case‐insensitive equals predicate for strings |
|
A case‐insensitive hash function object for strings |
|
A case‐insensitive less predicate for strings |
|
Alias for |
|
Determine if T meets the requirements of |
Enums
Functions
Name |
Description |
Return the case‐insensitive comparison of s0 and s1 |
|
Return the case‐insensitive digest of a string |
|
Return true if s0 equals s1 using case‐insensitive comparison |
|
Return true if s0 is less than s1 using case‐insensitive comparison |
|
|
|
Find the first character in the string that is in the set. |
|
Find the first character in the string that is not in CharSet |
|
Return the decimal value of a hex character |
|
Match another rule, if the result is not empty |
|
Return the union of two character sets. |
|
Return a new character set by subtracting |
|
Match a rule, or the empty string |
|
Parse a character buffer using a rule |
|
Match a repeating number of elements |
|
|
|
Squelch the value of a rule |
|
Return c converted to lowercase |
|
Return c converted to uppercase |
|
Match a non‐empty string of characters from a set |
|
Match a series of rules in order |
|
Match one of a set of rules |
|
Format a string to an output stream |
|
Compare two string views for equality |
|
Compare two string views for inequality |
|
Compare two string views for less than |
|
Compare two string views for less than or equal |
|
Compare two string views for greater than |
|
Compare two string views for greater than or equal |
Variables
Name |
Description |
The set of all characters |
|
The set of letters and digits |
|
The set of all letters |
|
Match a decimal octet |
|
The set of decimal digits |
|
The set of hexadecimal digits |
|
The set of visible characters |
Synopsis
Declared in <boost/url/grammar/string_token.hpp>
namespace string_token = boost::urls::string_token;Provides an aligned storage buffer aligned for T
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
template<class T>
using aligned_storage = /* implementation-defined */;Description
template<class T>
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 case‐insensitive equals predicate for strings
Synopsis
Declared in <boost/url/grammar/ci_string.hpp>
using ci_equal = /* implementation-defined */;Description
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.
Example
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)Synopsis
Declared in <boost/url/grammar/ci_string.hpp>
using ci_hash = /* implementation-defined */;Description
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.
Example
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)Synopsis
Declared in <boost/url/grammar/ci_string.hpp>
using ci_less = /* implementation-defined */;Description
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.
Example
boost::container::map< std::string, std::string, ci_less > m1;
std::map< std::string, std::string, ci_less > m2; // (since C++14)Synopsis
Declared in <boost/url/grammar/charset.hpp>
template<class T>
using is_charset = /* implementation-defined */;Description
This metafunction determines if the type T meets these requirements of CharSet:
-
An instance of
Tis invocable with this equivalent function signature:
bool T::operator()( char ) const noexcept;Example
Use with enable_if on the return value:
template< class CharSet >
typename std::enable_if< is_charset<T>::value >::type
func( CharSet const& cs );Template Parameters
Name |
Description |
T |
the type to check. |
Determine if T meets the requirements of Rule
Synopsis
Declared in <boost/url/grammar/type_traits.hpp>
template<class T>
using is_rule = /* implementation-defined */;Description
This is an alias for std::true_type if T meets the requirements, otherwise it is an alias for std::false_type.
Example
struct U
{
struct value_type;
auto
parse(
char const*& it,
char const* end) const ->
system::result<value_type>
};
static_assert( is_rule<U>::value, "Requirements not met" );See Also
Match a string literal exactly
Synopsis
Declared in <boost/url/grammar/literal_rule.hpp>
class literal_rule;Types
Name |
Member Functions
Name |
Description |
|
Construct from |
Description
If there is no more input, or if the end of the input is reached, and a prefix of the literal matches exactly, the error returned is error::need_more.
Value Type
using value_type = core::string_view;Example
Rules are used with the function parse.
system::result< core::string_view > rv = parse( "HTTP", literal_rule( "HTTP" ) );See Also
Synopsis
Declared in <boost/url/grammar/literal_rule.hpp>
using value_type = core::string_view;Construct from char
Synopsis
Declared in <boost/url/grammar/literal_rule.hpp>
constexpr
explicit
literal_rule(char const* s) noexcept;Parameters
Name |
Description |
s |
The value to construct from |
Synopsis
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
Synopsis
Declared in <boost/url/grammar/lut_chars.hpp>
class lut_chars;Member Functions
Name |
Description |
|
Constructors |
Return true if ch is in the character set. |
|
Return a new character set which is the complement of another character set. |
Friends
Name |
Description |
Return a new character set by subtracting |
|
Return the union of two character sets. |
Description
The characters defined by instances of this set are provided upon construction. The constexpr implementation allows these to become compile‐time constants.
Example
Character sets are used with rules and the 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 ) );See Also
Constructors
Synopses
Declared in <boost/url/grammar/lut_chars.hpp>
Constructor
constexpr
lut_chars(char ch) noexcept;Constructor
constexpr
lut_chars(char const* s) noexcept;Constructor.
template<class Pred>
requires detail::is_pred<Pred>::value &&
! std::is_base_of<
lut_chars, Pred>::value
constexpr
lut_chars(Pred const& pred) noexcept;Parameters
Name |
Description |
ch |
A character. |
s |
A null‐terminated string. |
pred |
The function object to use for determining membership in the character set. |
Constructor
Synopsis
Declared in <boost/url/grammar/lut_chars.hpp>
constexpr
lut_chars(char ch) noexcept;Description
This function constructs a character set which has as a single member, the character ch.
Example
constexpr lut_chars asterisk( '*' );Complexity
Constant.
Exception Safety
Throws nothing.
Parameters
Name |
Description |
ch |
A character. |
Constructor
Synopsis
Declared in <boost/url/grammar/lut_chars.hpp>
constexpr
lut_chars(char const* s) noexcept;Description
This function constructs a character set which has as members, all of the characters present in the null‐terminated string s.
Example
constexpr lut_chars digits = "0123456789";Complexity
Linear in ::strlen(s), or constant if s is a constant expression.
Exception Safety
Throws nothing.
Parameters
Name |
Description |
s |
A null‐terminated string. |
Constructor.
Synopsis
Declared in <boost/url/grammar/lut_chars.hpp>
template<class Pred>
requires detail::is_pred<Pred>::value &&
! std::is_base_of<
lut_chars, Pred>::value
constexpr
lut_chars(Pred const& pred) noexcept;Description
This function constructs a character set which has as members, every value of char ch for which the expression pred(ch) returns true.
Example
struct is_digit
{
constexpr bool
operator()(char c ) const noexcept
{
return c >= '0' && c <= '9';
}
};
constexpr lut_chars digits( is_digit{} );Complexity
Linear in pred, or constant if pred(ch) is a constant expression.
Exception Safety
Throws nothing.
Parameters
Name |
Description |
pred |
The function object to use for determining membership in the character set. |
Return true if ch is in the character set.
Synopses
Declared in <boost/url/grammar/lut_chars.hpp>
Return true if ch is in the character set.
constexpr
bool
operator()(char ch) const noexcept;Return true if ch is in the character set.
constexpr
bool
operator()(unsigned char ch) const noexcept;Return Value
true if ch is in the set.
Parameters
Name |
Description |
ch |
The character to test. |
Return true if ch is in the character set.
Synopsis
Declared in <boost/url/grammar/lut_chars.hpp>
constexpr
bool
operator()(char ch) const noexcept;Description
This function returns true if the character ch is in the set, otherwise it returns false.
Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
true if ch is in the set.
Parameters
Name |
Description |
ch |
The character to test. |
Return true if ch is in the character set.
Synopsis
Declared in <boost/url/grammar/lut_chars.hpp>
constexpr
bool
operator()(unsigned char ch) const noexcept;Description
This function returns true if the character ch is in the set, otherwise it returns false.
Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
true if ch is in the set.
Parameters
Name |
Description |
ch |
The character to test. |
Return a new character set which is the complement of another character set.
Synopsis
Declared in <boost/url/grammar/lut_chars.hpp>
constexpr
lut_chars
operator~() const noexcept;Description
This function returns a new character set which contains all of the characters that are not in *this.
Example
This statement declares a character set containing everything but vowels:
constexpr lut_chars not_vowels = ~lut_chars( "AEIOU" "aeiou" );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
The new character set.
A forward range of parsed elements
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
template<class T>
class range;Types
Name |
Description |
A constant, forward iterator to elements of the range |
|
A constant, forward iterator to elements of the range |
|
The type of each element of the range |
|
The type used to represent signed integers |
|
Provided for compatibility, unused |
|
The type of each element of the range |
|
The type used to represent unsigned integers |
|
The type of each element of the range |
Member Functions
Description
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.
Template Parameters
Name |
Description |
T |
The value type of the range |
See Also
A constant, forward iterator to elements of the range
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
using const_iterator = iterator;The type of each element of the range
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
using const_reference = T const&;The type used to represent signed integers
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
using difference_type = std::ptrdiff_t;Provided for compatibility, unused
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
using pointer = void const*;The type of each element of the range
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
using reference = T const&;The type used to represent unsigned integers
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
using size_type = std::size_t;The type of each element of the range
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
using value_type = T;A constant, forward iterator to elements of the range
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
class iterator;Friends
Name |
Description |
A forward range of parsed elements |
Constructor
Synopses
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
range() noexcept;Description
Default‐constructed ranges have zero elements.
Exception Safety
Throws nothing.
Constructor
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
range(range const& other) noexcept;Description
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.
Exception Safety
Throws nothing.
Parameters
Name |
Description |
other |
The object to copy construct from |
Constructor
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
range(range&& other) noexcept;Description
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.
Exception Safety
Throws nothing.
Parameters
Name |
Description |
other |
The object to move construct from |
Destructor
Synopsis
Synopses
Return Value
*this
Assignment
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
Description
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.
Exception Safety
Throws nothing.
Return Value
*this
Parameters
Name |
Description |
other |
The object to copy assign from |
Assignment
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
Description
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.
Exception Safety
Throws nothing.
Return Value
*this
Parameters
Name |
Description |
other |
The object to move assign from |
Return an iterator to the beginning
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
iterator
begin() const noexcept;Return Value
An iterator to the first element
Return true if the range is empty
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
bool
empty() const noexcept;Return Value
true if the range is empty
Return an iterator to the end
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
iterator
end() const noexcept;Return Value
An iterator to one past the last element
Return the number of elements in the range
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
std::size_t
size() const noexcept;Return Value
The number of elements
Return the matching part of the string
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
core::string_view
string() const noexcept;Return Value
A string view representing the range
A thread‐safe collection of instances of T
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
template<class T>
class recycled;Member Functions
Friends
Name |
Description |
A pointer to a shared instance of T |
Description
Instances of this type may be used to control where recycled instances of T come from when used with recycled_ptr.
Example
static recycled< std::string > bin;
recycled_ptr< std::string > ps( bin );
// Put the string into a known state
ps->clear();See Also
Constructor
Synopsis
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
~recycled();Description
All recycled instances of T are destroyed. Undefined behavior results if there are any recycled_ptr which reference this recycle bin.
A pointer to a shared instance of T
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
template<class T>
class recycled_ptr;Member Functions
Name |
Description |
|
Constructor |
|
Destructor |
Assignment |
|
Return the referenced object |
|
Return the referenced recycle bin |
|
Return true if this does not reference an object |
|
Return the referenced object |
|
Return the referenced object |
|
Return the referenced object |
|
Release the referenced object |
|
Return true if this references an object |
Friends
Name |
Description |
A thread‐safe collection of instances of T |
Description
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.
Example
static recycled< std::string > bin;
recycled_ptr< std::string > ps( bin );
// Put the string into a known state
ps->clear();Template Parameters
Name |
Description |
T |
the type of object to acquire, which must be DefaultConstructible. |
Constructor
Synopses
Declared in <boost/url/grammar/recycled.hpp>
Constructor
recycled_ptr();Constructor
recycled_ptr(recycled_ptr const& other) noexcept;Constructor
recycled_ptr(recycled_ptr&& other) noexcept;Constructor
recycled_ptr(std::nullptr_t value) noexcept;Constructor
explicit
recycled_ptr(recycled<T>& bin);Constructor
recycled_ptr(
recycled<T>& bin,
std::nullptr_t) noexcept;Parameters
Name |
Description |
other |
The pointer to copy |
bin |
The recycle bin to use |
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
recycled_ptr();Description
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.
Example
recycled_ptr< std::string > ps;
// Put the string into a known state
ps->clear();Postconditions
&this->bin() != nullptr && ! this->empty()See Also
Constructor
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
recycled_ptr(recycled_ptr const& other) noexcept;Description
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.
Postconditions
&this->bin() == &other->bin() && this->get() == other.get()Exception Safety
Throws nothing.
Parameters
Name |
Description |
other |
The pointer to copy |
Constructor
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
recycled_ptr(recycled_ptr&& other) noexcept;Description
If other references an object, ownership is transferred including a reference to the recycle bin. After the move, the moved‐from object is empty.
Postconditions
&this->bin() == &other->bin() && ! this->empty() && other.empty()Exception Safety
Throws nothing.
Parameters
Name |
Description |
other |
The pointer to move from |
Constructor
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
recycled_ptr(std::nullptr_t value) noexcept;Description
After construction, this is empty and refers to a global recycle bin.
Example
recycled_ptr< std::string > ps( nullptr );
// Acquire a string and put it into a known state
ps->acquire();
ps->clear();Postconditions
&this->bin() != nullptr && this->empty()Exception Safety
Throws nothing.
Parameters
Name |
Description |
value |
The object to construct from |
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
explicit
recycled_ptr(recycled<T>& bin);Description
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.
Example
static recycled< std::string > bin;
recycled_ptr< std::string > ps( bin );
// Put the string into a known state
ps->clear();Postconditions
&this->bin() == &bin && ! this->empty()Parameters
Name |
Description |
bin |
The recycle bin to use |
See Also
Constructor
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
recycled_ptr(
recycled<T>& bin,
std::nullptr_t) noexcept;Description
After construction, this is empty and refers to the specified recycle bin.
Example
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();Postconditions
&this->bin() == &bin && this->empty()Exception Safety
Throws nothing.
Parameters
Name |
Description |
bin |
The recycle bin to use |
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
~recycled_ptr();Description
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.
Effects
this->release();Assignment
Synopses
Declared in <boost/url/grammar/recycled.hpp>
Assignment
recycled_ptr&
operator=(recycled_ptr const& other) noexcept;Assignment
recycled_ptr&
operator=(recycled_ptr&& other) noexcept;Return Value
*this
Parameters
Name |
Description |
other |
The pointer to copy from |
Assignment
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
recycled_ptr&
operator=(recycled_ptr const& other) noexcept;Description
If other references an object, this acquires shared ownership and references the same recycle bin as other. The previous object if any is released.
Effects
this->release()Postconditions
&this->bin() == &other->bin() && this->get() == other.get()Exception Safety
Throws nothing.
Return Value
*this
Parameters
Name |
Description |
other |
The pointer to copy from |
Assignment
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
recycled_ptr&
operator=(recycled_ptr&& other) noexcept;Description
If other references an object, ownership is transferred including a reference to the recycle bin. After the move, the moved‐from object is empty.
Effects
this->release()Postconditions
&this->bin() == &other->bin()Exception Safety
Throws nothing.
Return Value
*this
Parameters
Name |
Description |
other |
The pointer to move from |
Return the referenced object
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
T&
acquire();Description
If this references an object, it is returned. Otherwise, exclusive ownership of a new object of type T is acquired and returned.
Postconditions
not this->empty()Return Value
A reference to the object
Return the referenced recycle bin
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
recycled<T>&
bin() const noexcept;Description
Exception Safety
Throws nothing.
Return Value
A reference to the recycle bin
Return true if this does not reference an object
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
bool
empty() const noexcept;Description
Exception Safety
Throws nothing.
Return Value
`p`_ == nullptr_
Return the referenced object
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
T*
get() const noexcept;Description
If this is empty, nullptr is returned.
Exception Safety
Throws nothing.
Return Value
A pointer to the object
Return the referenced object
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
T&
operator*() const noexcept;Description
Preconditions
not this->empty()Return Value
A reference to the object
Return the referenced object
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
T*
operator‐>() const noexcept;Description
If this is empty, nullptr is returned.
Exception Safety
Throws nothing.
Return Value
A pointer to the object
Release the referenced object
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
void
release() noexcept;Description
If this references an object, it is released to the referenced recycle bin. The pointer continues to reference the same recycle bin.
Postconditions
this->empty()Exception Safety
Throws nothing.
Return true if this references an object
Synopsis
Declared in <boost/url/grammar/recycled.hpp>
explicit
operator bool() const noexcept;Description
Effects
return ! this->empty();Exception Safety
Throws nothing.
Return Value
!this‐>empty()
Common functionality for string views
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
class string_view_base;Types
Name |
Description |
The const iterator type |
|
The const pointer type |
|
The const reference type |
|
The const reverse iterator type |
|
The difference type |
|
The iterator type |
|
The pointer type |
|
The reference type |
|
The reverse iterator type |
|
The size type |
|
The character traits |
|
The value type |
Member Functions
Name |
Description |
Access a character |
|
Return the last character |
|
Return an iterator to the beginning |
|
Return an iterator to the beginning |
|
Return an iterator to the end |
|
Return the result of comparing to another string |
|
Return true if matching characters are found |
|
Copy the characters to another buffer |
|
Return a reverse iterator to the end |
|
Return a reverse iterator to the beginning |
|
Return a pointer to the character buffer |
|
Return true if the string is empty |
|
Return an iterator to the end |
|
Return true if a matching suffix exists |
|
Return the position of matching characters |
|
Return the position of the first non‐match |
|
Return the position of the first match |
|
Return the position of the last non‐match |
|
Return the position of the last match |
|
Return the first character |
|
Return the size |
|
Return the maximum allowed size |
|
Access a character |
|
Return a reverse iterator to the end |
|
Return a reverse iterator to the beginning |
|
Return the position of matching characters |
|
Return the size |
|
Return true if a matching prefix exists |
|
Return a view to part of the string |
|
Conversion |
|
Conversion |
Static Data Members
Name |
Description |
A constant used to represent "no position" |
Protected Member Functions
Name |
Description |
|
Constructor |
Assignment |
|
Swap |
Protected Data Members
Name |
Description |
The referenced character buffer |
Friends
Name |
Description |
Format a string to an output stream |
|
Compare two string views for greater than or equal |
|
Compare two string views for greater than |
|
Compare two string views for less than or equal |
|
Compare two string views for less than |
|
Compare two string views for inequality |
|
Compare two string views for equality |
Derived Classes
Name |
Description |
A reference to a valid percent‐encoded string |
Description
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 const iterator type
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
typedef char const* const_iterator;The const pointer type
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
typedef char const* const_pointer;The const reference type
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
typedef char const& const_reference;The const reverse iterator type
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
typedef std::reverse_iterator<const_iterator> const_reverse_iterator;The difference type
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
typedef std::ptrdiff_t difference_type;The iterator type
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
typedef const_iterator iterator;The pointer type
Synopsis
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
typedef char& reference;The reverse iterator type
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
typedef const_reverse_iterator reverse_iterator;The size type
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
typedef std::size_t size_type;The character traits
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
typedef std::char_traits<char> traits_type;The value type
Synopsis
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_reference
at(size_type pos) const;Description
See core::string_view::at
Return Value
The character at the position
Parameters
Name |
Description |
pos |
The position to access |
Return the last character
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_reference
back() const noexcept;Description
See core::string_view::back
Return Value
The last character
Return an iterator to the beginning
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_iterator
begin() const noexcept;Description
See core::string_view::begin
Return Value
An iterator to the beginning
Return an iterator to the beginning
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_iterator
cbegin() const noexcept;Description
See core::string_view::cbegin
Return Value
An iterator to the beginning
Return an iterator to the end
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_iterator
cend() const noexcept;Description
See core::string_view::cend
Return Value
An iterator to the end
Return the result of comparing to another string
Synopses
Declared in <boost/url/grammar/string_view_base.hpp>
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(char const* s) const noexcept;Return the result of comparing to another string
Return the result of comparing to another string
Return the result of comparing to another string
Return the result of comparing to another string
Return Value
The result of the comparison
Parameters
Name |
Description |
str |
The string to compare |
s |
The string to compare |
pos1 |
The position to start comparing from |
n1 |
The number of characters to compare |
n2 |
The number of characters to compare |
pos2 |
The position to start comparing from |
Return the result of comparing to another string
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
int
compare(core::string_view str) const noexcept;Description
See core::string_view::compare
Return Value
The result of the comparison
Parameters
Name |
Description |
str |
The string to compare |
Return the result of comparing to another string
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
int
compare(char const* s) const noexcept;Description
See core::string_view::compare
Return Value
The result of the comparison
Parameters
Name |
Description |
s |
The string to compare |
Return the result of comparing to another string
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::compare
Return Value
The result of the comparison
Parameters
Name |
Description |
pos1 |
The position to start comparing from |
n1 |
The number of characters to compare |
str |
The string to compare |
Return the result of comparing to another string
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::compare
Return Value
The result of the comparison
Parameters
Name |
Description |
pos1 |
The position to start comparing from |
n1 |
The number of characters to compare |
s |
The string to compare |
Return the result of comparing to another string
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::compare
Return Value
The result of the comparison
Parameters
Name |
Description |
pos1 |
The position to start comparing from |
n1 |
The number of characters to compare |
s |
The string to compare |
n2 |
The number of characters to compare |
Return the result of comparing to another string
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::compare
Return Value
The result of the comparison
Parameters
Name |
Description |
pos1 |
The position to start comparing from |
n1 |
The number of characters to compare |
str |
The string to compare |
pos2 |
The position to start comparing from |
n2 |
The number of characters to compare |
Return true if matching characters are found
Synopses
Declared in <boost/url/grammar/string_view_base.hpp>
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;Return Value
-
trueif the string contains the characters, otherwisefalse -
trueif the string contains the character, otherwisefalse
Parameters
Name |
Description |
sv |
The string to search for |
c |
The character to search for |
s |
The string to search for |
Return true if matching characters are found
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
contains(core::string_view sv) const noexcept;Description
See core::string_view::contains
Return Value
true if the string contains the characters, otherwise false
Parameters
Name |
Description |
sv |
The string to search for |
Return true if matching characters are found
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
contains(char c) const noexcept;Description
See core::string_view::contains
Return Value
true if the string contains the character, otherwise false
Parameters
Name |
Description |
c |
The character to search for |
Return true if matching characters are found
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
contains(char const* s) const noexcept;Description
See core::string_view::contains
Return Value
true if the string contains the characters, otherwise false
Parameters
Name |
Description |
s |
The string to search for |
Copy the characters to another buffer
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::copy
Return Value
The number of characters copied
Parameters
Name |
Description |
s |
The destination buffer |
n |
The number of characters to copy |
pos |
The position to start from |
Return a reverse iterator to the end
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_reverse_iterator
crbegin() const noexcept;Description
See core::string_view::crbegin
Return Value
A reverse iterator to the end
Return a reverse iterator to the beginning
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_reverse_iterator
crend() const noexcept;Description
See core::string_view::crend
Return Value
A reverse iterator to the beginning
Return a pointer to the character buffer
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_pointer
data() const noexcept;Description
See core::string_view::data
Return Value
A pointer to the character buffer
Return true if the string is empty
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
empty() const noexcept;Description
See core::string_view::size
Return Value
true if the string is empty
Return an iterator to the end
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_iterator
end() const noexcept;Description
See core::string_view::end
Return Value
An iterator to the end
Return true if a matching suffix exists
Synopses
Declared in <boost/url/grammar/string_view_base.hpp>
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 Value
true if the suffix matches
Parameters
Name |
Description |
x |
The string to search for |
Return true if a matching suffix exists
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
ends_with(core::string_view x) const noexcept;Description
See core::string_view::ends_with
Return Value
true if the suffix matches
Parameters
Name |
Description |
x |
The string to search for |
Return true if a matching suffix exists
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
ends_with(char x) const noexcept;Description
See core::string_view::ends_with
Return Value
true if the suffix matches
Parameters
Name |
Description |
x |
The character to search for |
Return true if a matching suffix exists
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
ends_with(char const* x) const noexcept;Description
See core::string_view::ends_with
Return Value
true if the suffix matches
Parameters
Name |
Description |
x |
The string to search for |
Return the position of matching characters
Synopses
Declared in <boost/url/grammar/string_view_base.hpp>
Return the position of matching characters
Return the position of matching characters
Return the position of matching characters
Return the position of matching characters
Return Value
The position of the first match
Parameters
Name |
Description |
str |
The characters to search for |
pos |
The position to start searching from |
c |
The character to search for |
s |
The characters to search for |
n |
The number of characters to search for |
Return the position of matching characters
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find
Return Value
The position of the first match
Parameters
Name |
Description |
str |
The characters to search for |
pos |
The position to start searching from |
Return the position of matching characters
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find
Return Value
The position of the first match
Parameters
Name |
Description |
c |
The character to search for |
pos |
The position to start searching from |
Return the position of matching characters
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find
Return Value
The position of the first match
Parameters
Name |
Description |
s |
The characters to search for |
pos |
The position to start searching from |
Return the position of matching characters
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find
Return Value
The position of the first match
Parameters
Name |
Description |
s |
The characters to search for |
pos |
The position to start searching from |
n |
The number of characters to search for |
Return the position of the first non‐match
Synopses
Declared in <boost/url/grammar/string_view_base.hpp>
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 = 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 Value
The position of the first non‐match
Parameters
Name |
Description |
str |
The characters to search for |
pos |
The position to start searching from |
c |
The character to search for |
s |
The characters to search for |
n |
The number of characters to search for |
Return the position of the first non‐match
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find_first_not_of
Return Value
The position of the first non‐match
Parameters
Name |
Description |
str |
The characters to search for |
pos |
The position to start searching from |
Return the position of the first non‐match
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find_first_not_of
Return Value
The position of the first non‐match
Parameters
Name |
Description |
c |
The character to search for |
pos |
The position to start searching from |
Return the position of the first non‐match
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find_first_not_of
Return Value
The position of the first non‐match
Parameters
Name |
Description |
s |
The characters to search for |
pos |
The position to start searching from |
Return the position of the first non‐match
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find_first_not_of
Return Value
The position of the first non‐match
Parameters
Name |
Description |
s |
The characters to search for |
pos |
The position to start searching from |
n |
The number of characters to search for |
Return the position of the first match
Synopses
Declared in <boost/url/grammar/string_view_base.hpp>
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 = 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 Value
The position of the first match
Parameters
Name |
Description |
str |
The characters to search for |
pos |
The position to start searching from |
c |
The character to search for |
s |
The characters to search for |
n |
The number of characters to search for |
Return the position of the first match
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find_first_of
Return Value
The position of the first match
Parameters
Name |
Description |
str |
The characters to search for |
pos |
The position to start searching from |
Return the position of the first match
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find_first_of
Return Value
The position of the first match
Parameters
Name |
Description |
c |
The character to search for |
pos |
The position to start searching from |
Return the position of the first match
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find_first_of
Return Value
The position of the first match
Parameters
Name |
Description |
s |
The characters to search for |
pos |
The position to start searching from |
Return the position of the first match
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find_first_of
Return Value
The position of the first match
Parameters
Name |
Description |
s |
The characters to search for |
pos |
The position to start searching from |
n |
The number of characters to search for |
Return the position of the last non‐match
Synopses
Declared in <boost/url/grammar/string_view_base.hpp>
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 = 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 Value
The position of the last non‐match
Parameters
Name |
Description |
str |
The characters to search for |
pos |
The position to start searching from |
c |
The character to search for |
s |
The characters to search for |
n |
The number of characters to search for |
Return the position of the last non‐match
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find_last_not_of
Return Value
The position of the last non‐match
Parameters
Name |
Description |
str |
The characters to search for |
pos |
The position to start searching from |
Return the position of the last non‐match
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find_last_not_of
Return Value
The position of the last non‐match
Parameters
Name |
Description |
c |
The character to search for |
pos |
The position to start searching from |
Return the position of the last non‐match
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find_last_not_of
Return Value
The position of the last non‐match
Parameters
Name |
Description |
s |
The characters to search for |
pos |
The position to start searching from |
Return the position of the last non‐match
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find_last_not_of
Return Value
The position of the last non‐match
Parameters
Name |
Description |
s |
The characters to search for |
pos |
The position to start searching from |
n |
The number of characters to search for |
Return the position of the last match
Synopses
Declared in <boost/url/grammar/string_view_base.hpp>
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 = 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 Value
The position of the last match
Parameters
Name |
Description |
str |
The characters to search for |
pos |
The position to start searching from |
c |
The character to search for |
s |
The characters to search for |
n |
The number of characters to search for |
Return the position of the last match
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find_last_of
Return Value
The position of the last match
Parameters
Name |
Description |
str |
The characters to search for |
pos |
The position to start searching from |
Return the position of the last match
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find_last_of
Return Value
The position of the last match
Parameters
Name |
Description |
c |
The character to search for |
pos |
The position to start searching from |
Return the position of the last match
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find_last_of
Return Value
The position of the last match
Parameters
Name |
Description |
s |
The characters to search for |
pos |
The position to start searching from |
Return the position of the last match
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::find_last_of
Return Value
The position of the last match
Parameters
Name |
Description |
s |
The characters to search for |
pos |
The position to start searching from |
n |
The number of characters to search for |
Return the first character
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_reference
front() const noexcept;Description
See core::string_view::front
Return Value
The first character
Return the size
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
length() const noexcept;Description
See core::string_view::length
Return Value
The size
Return the maximum allowed size
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
max_size() const noexcept;Description
See core::string_view::max_size
Return Value
The maximum allowed size
Access a character
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_reference
operator[](size_type pos) const noexcept;Description
See core::string_view::operator[]
Return Value
The character at the position
Parameters
Name |
Description |
pos |
The position to access |
Return a reverse iterator to the end
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_reverse_iterator
rbegin() const noexcept;Description
See core::string_view::rbegin
Return Value
A reverse iterator to the end
Return a reverse iterator to the beginning
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
const_reverse_iterator
rend() const noexcept;Description
See core::string_view::rend
Return Value
A reverse iterator to the beginning
Return the position of matching characters
Synopses
Declared in <boost/url/grammar/string_view_base.hpp>
Return the position of matching characters
Return the position of matching characters
Return the position of matching characters
Return the position of matching characters
Return Value
The position of the first match
Parameters
Name |
Description |
str |
The characters to search for |
pos |
The position to start searching from |
c |
The character to search for |
s |
The characters to search for |
n |
The number of characters to search for |
Return the position of matching characters
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::rfind
Return Value
The position of the first match
Parameters
Name |
Description |
str |
The characters to search for |
pos |
The position to start searching from |
Return the position of matching characters
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::rfind
Return Value
The position of the first match
Parameters
Name |
Description |
c |
The character to search for |
pos |
The position to start searching from |
Return the position of matching characters
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::rfind
Return Value
The position of the first match
Parameters
Name |
Description |
s |
The characters to search for |
pos |
The position to start searching from |
Return the position of matching characters
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::rfind
Return Value
The position of the first match
Parameters
Name |
Description |
s |
The characters to search for |
pos |
The position to start searching from |
n |
The number of characters to search for |
Return the size
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
size_type
size() const noexcept;Description
See core::string_view::size
Return Value
The size
Return true if a matching prefix exists
Synopses
Declared in <boost/url/grammar/string_view_base.hpp>
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 Value
true if the prefix matches
Parameters
Name |
Description |
x |
The string to search for |
Return true if a matching prefix exists
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
starts_with(core::string_view x) const noexcept;Description
See core::string_view::starts_with
Return Value
true if the prefix matches
Parameters
Name |
Description |
x |
The string to search for |
Return true if a matching prefix exists
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
starts_with(char x) const noexcept;Description
See core::string_view::starts_with
Return Value
true if the prefix matches
Parameters
Name |
Description |
x |
The character to search for |
Return true if a matching prefix exists
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
bool
starts_with(char const* x) const noexcept;Description
See core::string_view::starts_with
Return Value
true if the prefix matches
Parameters
Name |
Description |
x |
The string to search for |
Return a view to part of the string
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
Description
See core::string_view::substr
Return Value
A view to the substring
Parameters
Name |
Description |
pos |
The position to start from |
n |
The number of characters |
Conversion
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
explicit
operator std::string() const noexcept;Description
Conversion to std::string is explicit because assigning to string using an implicit constructor does not preserve capacity.
Return Value
A string with the same contents
Conversion
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
operator std::string_view() const noexcept;Return Value
A string view with the same contents
A constant used to represent "no position"
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
inline constexpr static
std::size_t npos = core::string_view::npos;Constructor
Synopses
Declared in <boost/url/grammar/string_view_base.hpp>
Constructor
constexpr
string_view_base() = default;Constructor
constexpr
string_view_base(string_view_base const& other) = default;Constructor
constexpr
string_view_base(core::string_view s) noexcept;Constructor
constexpr
string_view_base(
char const* data,
std::size_t size) noexcept;Parameters
Name |
Description |
s |
The string view |
data |
The character buffer |
size |
The number of characters |
Constructor
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
string_view_base() = default;Constructor
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
string_view_base(string_view_base const& other) = default;Parameters
Name |
Description |
other |
The object to copy construct from |
Constructor
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
string_view_base(core::string_view s) noexcept;Parameters
Name |
Description |
s |
The string view |
Constructor
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
string_view_base(
char const* data,
std::size_t size) noexcept;Parameters
Name |
Description |
data |
The character buffer |
size |
The number of characters |
Assignment
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
constexpr
string_view_base&
operator=(string_view_base const& other) = default;Return Value
A reference to this object
Parameters
Name |
Description |
other |
The object to assign |
Swap
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
void
swap(string_view_base& s) noexcept;Parameters
Name |
Description |
s |
The object to swap with |
The referenced character buffer
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
core::string_view s_;Match an unsigned decimal
Synopsis
Declared in <boost/url/grammar/unsigned_rule.hpp>
template<class Unsigned>
struct unsigned_rule;Types
Name |
Member Functions
Name |
Description
Extra leading zeroes are disallowed.
Value Type
using value_type = Unsigned;Example
Rules are used with the function parse.
system::result< unsigned short > rv = parse( "32767", unsigned_rule< unsigned short >{} );BNF
unsigned = "0" / ( ["1"..."9"] *DIGIT )Template Parameters
Name |
Description |
Unsigned |
The unsigned integer type used to store the result. |
See Also
Synopsis
Declared in <boost/url/grammar/unsigned_rule.hpp>
using value_type = Unsigned;Synopsis
Declared in <boost/url/grammar/unsigned_rule.hpp>
system::result<value_type>
parse(
char const*& it,
char const* end) const noexcept;Error conditions for errors received from rules
Synopsis
Declared in <boost/url/grammar/error.hpp>
enum class condition : int;Members
Name |
Description |
|
A fatal error in syntax was encountered. |
Synopsis
Declared in <boost/url/grammar/error.hpp>
enum class error : int;Members
Name |
Description |
|
More input is needed to match the rule |
|
The rule did not match the input. |
|
A rule reached the end of a range |
|
Leftover input remaining after match. |
|
A rule encountered unrecoverable invalid input. |
|
An integer overflowed during parsing. |
|
An unspecified syntax error was found. |
Synopsis
Declared in <boost/url/grammar/ci_string.hpp>
int
ci_compare(
core::string_view s0,
core::string_view s1) noexcept;Description
This returns the lexicographical comparison of two strings, ignoring case. The function is defined only for strings containing low‐ASCII characters.
Example
assert( ci_compare( "boost", "Boost" ) == 0 );Exception Safety
Throws nothing.
Return Value
0 if the strings are equal, ‐1 if s0 is less than s1, or 1 if s0 is greater than s1.
Parameters
Name |
Description |
s0 |
The first string |
s1 |
The second string |
See Also
Return the case‐insensitive digest of a string
Synopsis
Declared in <boost/url/grammar/ci_string.hpp>
std::size_t
ci_digest(core::string_view s) noexcept;Description
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.
Return Value
The digest
Parameters
Name |
Description |
s |
The string |
Return true if s0 equals s1 using case‐insensitive comparison
Synopses
Declared in <boost/url/grammar/ci_string.hpp>
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 equals s1 using case‐insensitive comparison
template<
class String0,
class String1>
bool
ci_is_equal(
String0 const& s0,
String1 const& s1)
requires ! std::is_convertible<
String0, core::string_view>::value ||
! std::is_convertible<
String1, core::string_view>::value;Return Value
true if s0 case‐insensitively equals s1, otherwise false
Parameters
Name |
Description |
s0 |
The first string |
s1 |
The second string |
See Also
Return true if s0 equals s1 using case‐insensitive comparison
Synopsis
Declared in <boost/url/grammar/ci_string.hpp>
bool
ci_is_equal(
core::string_view s0,
core::string_view s1) noexcept;Description
The function is defined only for strings containing low‐ASCII characters.
Example
assert( ci_is_equal( "Boost", "boost" ) );Return Value
true if s0 case‐insensitively equals s1, otherwise false
Parameters
Name |
Description |
s0 |
The first string |
s1 |
The second string |
See Also
Return true if s0 equals s1 using case‐insensitive comparison
Synopsis
Declared in <boost/url/grammar/ci_string.hpp>
template<
class String0,
class String1>
bool
ci_is_equal(
String0 const& s0,
String1 const& s1)
requires ! std::is_convertible<
String0, core::string_view>::value ||
! std::is_convertible<
String1, core::string_view>::value;Description
The function is defined only for strings containing low‐ASCII characters.
Example
assert( ci_is_equal( "Boost", "boost" ) );Return Value
true if s0 case‐insensitively equals s1, otherwise false
Parameters
Name |
Description |
s0 |
The first string |
s1 |
The second string |
See Also
Return true if s0 is less than s1 using case‐insensitive comparison
Synopsis
Declared in <boost/url/grammar/ci_string.hpp>
bool
ci_is_less(
core::string_view s0,
core::string_view s1) noexcept;Description
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.
Example
assert( ! ci_is_less( "Boost", "boost" ) );Return Value
true if s0 is case‐insensitively less than s1, otherwise false
Parameters
Name |
Description |
s0 |
The first string |
s1 |
The second string |
See Also
delim_rule overloads
Synopses
Declared in <boost/url/grammar/delim_rule.hpp>
Match a character literal
constexpr
/* implementation-defined */
delim_rule(char ch) noexcept;Match a single character from a character set
template<CharSet CS>
constexpr
/* implementation-defined */
delim_rule(CS const& cs) noexcept
requires ! std::is_convertible<
CS, char>::value;Return Value
-
A rule which matches the character.
-
A rule which matches a single character from the set.
Parameters
Name |
Description |
ch |
The character to match |
cs |
The character set to use. |
See Also
Synopsis
Declared in <boost/url/grammar/delim_rule.hpp>
constexpr
/* implementation-defined */
delim_rule(char ch) noexcept;Description
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.
Value Type
using value_type = core::string_view;Example
Rules are used with the function parse.
system::result< core::string_view > rv = parse( ".", delim_rule('.') );BNF
char = %00-FFReturn Value
A rule which matches the character.
Parameters
Name |
Description |
ch |
The character to match |
Synopsis
Declared in <boost/url/grammar/delim_rule.hpp>
template<CharSet CS>
constexpr
/* implementation-defined */
delim_rule(CS const& cs) noexcept
requires ! std::is_convertible<
CS, char>::value;Description
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.
Value Type
using value_type = core::string_view;Example
Rules are used with the function parse.
system::result< core::string_view > rv = parse( "X", delim_rule( alpha_chars ) );Return Value
A rule which matches a single character from the set.
Parameters
Name |
Description |
cs |
The character set to use. |
See Also
Find the first character in the string that is in the set.
Synopsis
Declared in <boost/url/grammar/charset.hpp>
template<CharSet CS>
char const*
find_if(
char const const* first,
char const const* last,
CS const& cs) noexcept;Description
Exception Safety
Throws nothing.
Return Value
A pointer to the found character, otherwise the value last.
Parameters
Name |
Description |
first |
A pointer to the first character in the string to search. |
last |
A pointer to one past the last character in the string to search. |
cs |
The character set to use. |
See Also
Find the first character in the string that is not in CharSet
Synopsis
Declared in <boost/url/grammar/charset.hpp>
template<CharSet CS>
char const*
find_if_not(
char const const* first,
char const const* last,
CS const& cs) noexcept;Description
Exception Safety
Throws nothing.
Return Value
A pointer to the found character, otherwise the value last.
Parameters
Name |
Description |
first |
A pointer to the first character in the string to search. |
last |
A pointer to one past the last character in the string to search. |
cs |
The character set to use. |
See Also
Return the decimal value of a hex character
Synopsis
Declared in <boost/url/grammar/hexdig_chars.hpp>
signed char
hexdig_value(char ch) noexcept;Description
This function returns the decimal value of a hexadecimal character, or ‐1 if the argument is not a valid hexadecimal digit.
BNF
HEXDIG = DIGIT
/ "A" / "B" / "C" / "D" / "E" / "F"
/ "a" / "b" / "c" / "d" / "e" / "f"Return Value
The decimal value or ‐1
Parameters
Name |
Description |
ch |
The character to check |
Match another rule, if the result is not empty
Synopsis
Declared in <boost/url/grammar/not_empty_rule.hpp>
template<Rule R>
constexpr
/* implementation-defined */
not_empty_rule(R const& r);Description
This adapts another rule such that when an empty string is successfully parsed, the result is an error.
Value Type
using value_type = typename Rule::value_type;Example
Rules are used with the function parse.
system::result< decode_view > rv = parse( "Program%20Files",
not_empty_rule( pct_encoded_rule( unreserved_chars ) ) );Return Value
The adapted rule
Parameters
Name |
Description |
r |
The rule to match |
See Also
Return the union of two character sets.
Synopsis
Declared in <boost/url/grammar/lut_chars.hpp>
Description
This function returns a new character set which contains all of the characters in cs0 as well as all of the characters in cs.
Example
This creates a character set which includes all letters and numbers
constexpr lut_chars alpha_chars(
"ABCDEFGHIJKLMNOPQRSTUVWXYZ"
"abcdefghijklmnopqrstuvwxyz");
constexpr lut_chars alnum_chars = alpha_chars + "0123456789";Complexity
Constant.
Return Value
The new character set.
Parameters
Name |
Description |
cs0 |
A character to join |
cs1 |
A character to join |
Return a new character set by subtracting
Synopsis
Declared in <boost/url/grammar/lut_chars.hpp>
Description
This function returns a new character set which is formed from all of the characters in cs0 which are not in cs.
Example
This statement declares a character set containing all the lowercase letters which are not vowels:
constexpr lut_chars consonants = lut_chars("abcdefghijklmnopqrstuvwxyz") - "aeiou";Complexity
Constant.
Return Value
The new character set.
Parameters
Name |
Description |
cs0 |
A character set to join. |
cs1 |
A character set to join. |
Match a rule, or the empty string
Synopsis
Declared in <boost/url/grammar/optional_rule.hpp>
template<Rule R>
constexpr
/* implementation-defined */
optional_rule(R const& r);Description
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.
Value Type
using value_type = optional< typename Rule::value_type >;Example
Rules are used with the function grammar::parse.
system::result< optional< core::string_view > > rv = parse( "", optional_rule( token_rule( alpha_chars ) ) );BNF
optional = [ rule ]Return Value
The adapted rule
Parameters
Name |
Description |
r |
The rule to match |
See Also
Parse a character buffer using a rule
Synopses
Declared in <boost/url/grammar/parse.hpp>
Parse a character buffer using a rule
Parse a character buffer using a rule
Return Value
The parsed value upon success, otherwise an error.
Parameters
Name |
Description |
s |
The input string |
r |
The rule to use |
it |
A pointer to the start. The caller's variable is changed to reflect the amount of input consumed. |
end |
A pointer to the end. |
Parse a character buffer using a rule
Synopsis
Declared in <boost/url/grammar/parse.hpp>
template<Rule R>
system::result<R::value_type>
parse(
core::string_view s,
R const& r);Description
This function parses a complete string into the specified sequence of rules. If the string is not completely consumed, an error is returned instead.
Return Value
The parsed value upon success, otherwise an error.
Parameters
Name |
Description |
s |
The input string |
r |
The rule to use |
Parse a character buffer using a rule
Synopsis
Declared in <boost/url/grammar/parse.hpp>
template<Rule R>
system::result<R::value_type>
parse(
char const*& it,
char const* end,
R const& r);Return Value
The parsed value upon success, otherwise an error.
Parameters
Name |
Description |
it |
A pointer to the start. The caller's variable is changed to reflect the amount of input consumed. |
end |
A pointer to the end. |
r |
The rule to use |
Match a repeating number of elements
Synopses
Declared in <boost/url/grammar/range_rule.hpp>
Match a repeating number of elements
template<Rule R>
constexpr
/* implementation-defined */
range_rule(
R const& next,
std::size_t N = 0,
std::size_t M = std::size_t(‐1)) noexcept;Match a repeating number of elements
template<
Rule R1,
Rule R2>
constexpr
/* implementation-defined */
range_rule(
R1 const& first,
R2 const& next,
std::size_t N = 0,
std::size_t M = std::size_t(‐1)) noexcept
requires ! std::is_integral<R2>::value;Return Value
A rule that matches the range.
Parameters
Name |
Description |
next |
The rule to use for matching each element. The range extends until this rule returns an error. |
N |
The minimum number of elements for the range to be valid. If omitted, this defaults to zero. |
M |
The maximum number of elements for the range to be valid. If omitted, this defaults to unlimited. |
first |
The rule to use for matching the first element. If this rule returns an error, the range is empty. |
See Also
Match a repeating number of elements
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
template<Rule R>
constexpr
/* implementation-defined */
range_rule(
R const& next,
std::size_t N = 0,
std::size_t M = std::size_t(‐1)) noexcept;Description
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.
Value Type
using value_type = range< typename Rule::value_type >;Example
Rules are used with the function parse.
// range = 1*( ";" token )
system::result< range<core::string_view> > rv = parse( ";alpha;xray;charlie",
range_rule(
tuple_rule(
squelch( delim_rule( ';' ) ),
token_rule( alpha_chars ) ),
1 ) );BNF
range = <N>*<M>nextReturn Value
A rule that matches the range.
Parameters
Name |
Description |
next |
The rule to use for matching each element. The range extends until this rule returns an error. |
N |
The minimum number of elements for the range to be valid. If omitted, this defaults to zero. |
M |
The maximum number of elements for the range to be valid. If omitted, this defaults to unlimited. |
See Also
Match a repeating number of elements
Synopsis
Declared in <boost/url/grammar/range_rule.hpp>
Description
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.
Value Type
using value_type = range< typename Rule::value_type >;Example
Rules are used with the function 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 ) ) ) );BNF
range = <1>*<1>first
/ first <N-1>*<M-1>nextReturn Value
A rule that matches the range.
Parameters
Name |
Description |
first |
The rule to use for matching the first element. If this rule returns an error, the range is empty. |
next |
The rule to use for matching each subsequent element. The range extends until this rule returns an error. |
N |
The minimum number of elements for the range to be valid. If omitted, this defaults to zero. |
M |
The maximum number of elements for the range to be valid. If omitted, this defaults to unlimited. |
See Also
ref overloads
Synopses
Declared in <boost/url/grammar/charset.hpp>
Return a reference to a character set
Return a reference to a rule
Return Value
-
The character set as a reference type
-
The rule as a reference type
Template Parameters
Name |
Description |
CharSet |
The character set type |
Parameters
Name |
Description |
cs |
The character set to use |
r |
The rule to use |
Return a reference to a character set
Synopsis
Declared in <boost/url/grammar/charset.hpp>
template<CharSet CS>
constexpr
/* implementation-defined */
ref(CS const& cs) noexcept
requires is_charset<CS>::value &&
! std::is_same<CS,
implementation_defined::charset_ref<CS> >::value;Description
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 Value
The character set as a reference type
Template Parameters
Name |
Description |
CharSet |
The character set type |
Parameters
Name |
Description |
cs |
The character set to use |
Return a reference to a rule
Synopsis
Declared in <boost/url/grammar/parse.hpp>
template<Rule R>
constexpr
/* implementation-defined */
ref(R const& r) noexcept
requires is_rule<R>::value &&
! std::is_same<R,
implementation_defined::rule_ref<R> >::value;Description
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.
Return Value
The rule as a reference type
Parameters
Name |
Description |
r |
The rule to use |
Squelch the value of a rule
Synopsis
Declared in <boost/url/grammar/tuple_rule.hpp>
template<Rule R>
constexpr
/* implementation-defined */
squelch(R const& r) noexcept;Description
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.
Value Type
using value_type = void;Example 1
With squelch:
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 ) ) );Example 2
Without squelch:
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 ) ) );Return Value
The squelched rule
Parameters
Name |
Description |
r |
The rule to squelch |
See Also
delim_rule, digit_chars, parse, tuple_rule, token_rule, decode_view, pct_encoded_rule, unreserved_chars.
Return c converted to lowercase
Synopsis
Declared in <boost/url/grammar/ci_string.hpp>
constexpr
char
to_lower(char c) noexcept;Description
This function returns the character, converting it to lowercase if it is uppercase. The function is defined only for low‐ASCII characters.
Example
assert( to_lower( 'A' ) == 'a' );Exception Safety
Throws nothing.
Return Value
The converted character
Parameters
Name |
Description |
c |
The character to convert |
See Also
Return c converted to uppercase
Synopsis
Declared in <boost/url/grammar/ci_string.hpp>
constexpr
char
to_upper(char c) noexcept;Description
This function returns the character, converting it to uppercase if it is lowercase. The function is defined only for low‐ASCII characters.
Example
assert( to_upper( 'a' ) == 'A' );Exception Safety
Throws nothing.
Return Value
The converted character
Parameters
Name |
Description |
c |
The character to convert |
See Also
Match a non‐empty string of characters from a set
Synopsis
Declared in <boost/url/grammar/token_rule.hpp>
template<CharSet CS>
constexpr
/* implementation-defined */
token_rule(CS const& cs) noexcept;Description
If there is no more input, the error code error::need_more is returned.
Value Type
using value_type = core::string_view;Example
Rules are used with the function parse.
system::result< core::string_view > rv = parse( "abcdef", token_rule( alpha_chars ) );BNF
token = 1*( ch )Return Value
The token rule
Parameters
Name |
Description |
cs |
The character set to use |
See Also
Match a series of rules in order
Synopsis
Declared in <boost/url/grammar/tuple_rule.hpp>
Description
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.
Value Type
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<T> instead of system::result<tuple<...>>.
Example
Rules are used with the function 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 ) );BNF
sequence = rule1 rule2 rule3...Return Value
The sequence rule
Parameters
Name |
Description |
r0 |
The first rule to match |
rn |
A list of one or more rules to match |
See Also
Match one of a set of rules
Synopsis
Declared in <boost/url/grammar/variant_rule.hpp>
Description
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.
Value Type
using value_type = variant< typename Rules::value_type... >;Example
Rules are used with the function 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('*') ) );BNF
variant = rule1 / rule2 / rule3...Specification
Return Value
The variant rule
Parameters
Name |
Description |
r0 |
The first rule to match |
rn |
A list of one or more rules to match |
See Also
Format a string to an output stream
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
std::ostream&
operator<<(
std::ostream& os,
string_view_base const& s);Description
Format a string to an output stream
Return Value
A reference to the output stream, for chaining
Parameters
Name |
Description |
os |
The output stream to write to |
s |
The string to write |
Compare two string views for equality
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
template<
class S0,
class S1>
constexpr
bool
operator==(
S0 const& s0,
S1 const& s1) noexcept
requires is_match<S0, S1>::value;Description
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.
Return Value
true if the strings are equal, otherwise false
Parameters
Name |
Description |
s0 |
The first string |
s1 |
The second string |
Compare two string views for inequality
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
template<
class S0,
class S1>
constexpr
bool
operator!=(
S0 const& s0,
S1 const& s1) noexcept
requires is_match<S0, S1>::value;Description
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.
Return Value
true if the strings are not equal, otherwise false
Parameters
Name |
Description |
s0 |
The first string |
s1 |
The second string |
Compare two string views for less than
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
template<
class S0,
class S1>
constexpr
bool
operator<(
S0 const& s0,
S1 const& s1) noexcept
requires is_match<S0, S1>::value;Description
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.
Return Value
true if the first string is less than the second, otherwise false
Parameters
Name |
Description |
s0 |
The first string |
s1 |
The second string |
Compare two string views for less than or equal
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
template<
class S0,
class S1>
constexpr
bool
operator<=(
S0 const& s0,
S1 const& s1) noexcept
requires is_match<S0, S1>::value;Description
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.
Return Value
true if the first string is less than or equal to the second, otherwise false
Parameters
Name |
Description |
s0 |
The first string |
s1 |
The second string |
Compare two string views for greater than
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
template<
class S0,
class S1>
constexpr
bool
operator>(
S0 const& s0,
S1 const& s1) noexcept
requires is_match<S0, S1>::value;Description
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.
Return Value
true if the first string is greater than the second, otherwise false
Parameters
Name |
Description |
s0 |
The first string |
s1 |
The second string |
Compare two string views for greater than or equal
Synopsis
Declared in <boost/url/grammar/string_view_base.hpp>
template<
class S0,
class S1>
constexpr
bool
operator>=(
S0 const& s0,
S1 const& s1) noexcept
requires is_match<S0, S1>::value;Description
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.
Return Value
true if the first string is greater than or equal to the second, otherwise false
Parameters
Name |
Description |
s0 |
The first string |
s1 |
The second string |
The set of all characters
Synopsis
Declared in <boost/url/grammar/all_chars.hpp>
inline constexpr /* implementation-defined */ all_chars = all_chars{};Description
Example
Character sets are used with rules and the functions find_if and find_if_not.
system::result< core::string_view > rv = parse( "JohnDoe", token_rule( all_chars ) );BNF
ALL = %x00-FFSee Also
The set of letters and digits
Synopsis
Declared in <boost/url/grammar/alnum_chars.hpp>
constexpr /* implementation-defined */ alnum_chars = {};Description
Example
Character sets are used with rules and the functions find_if and find_if_not.
system::result< core::string_view > = parse( "Johnny42", token_rule( alnumchars ) );BNF
ALNUM = ALPHA / DIGIT
ALPHA = %x41-5A / %x61-7A
; A-Z / a-z
DIGIT = %x30-39
; 0-9See Also
The set of all letters
Synopsis
Declared in <boost/url/grammar/alpha_chars.hpp>
constexpr /* implementation-defined */ alpha_chars = alpha_chars{};Description
Example
Character sets are used with rules and the functions find_if and find_if_not.
system::result< core::string_view > rv = parse( "JohnDoe", token_rule( alpha_chars ) );BNF
ALPHA = %x41-5A / %x61-7A
; A-Z / a-zSee Also
Match a decimal octet
Synopsis
Declared in <boost/url/grammar/dec_octet_rule.hpp>
constexpr /* implementation-defined */ dec_octet_rule = {};Description
A decimal octet is precise way of saying a number from 0 to 255. These are commonly used in IPv4 addresses.
Value Type
using value_type = unsigned char;Example
Rules are used with the function parse.
system::result< unsigned char > rv = parse( "255", dec_octet_rule );BNF
dec-octet = DIGIT ; 0-9
/ %x31-39 DIGIT ; 10-99
/ "1" 2DIGIT ; 100-199
/ "2" %x30-34 DIGIT ; 200-249
/ "25" %x30-35 ; 250-255See Also
The set of decimal digits
Synopsis
Declared in <boost/url/grammar/digit_chars.hpp>
constexpr /* implementation-defined */ digit_chars = {};Description
Example
Character sets are used with rules and the functions find_if and find_if_not.
system::result< core::string_view > rv = parse( "2022", token_rule( digit_chars ) );BNF
DIGIT = %x30-39
; 0-9See Also
The set of hexadecimal digits
Synopsis
Declared in <boost/url/grammar/hexdig_chars.hpp>
constexpr /* implementation-defined */ hexdig_chars = {};Description
Example
Character sets are used with rules and the functions find_if and find_if_not.
system::result< core::string_view > rv = parse( "8086FC19", token_rule( hexdig_chars ) );BNF
HEXDIG = DIGIT
/ "A" / "B" / "C" / "D" / "E" / "F"
/ "a" / "b" / "c" / "d" / "e" / "f"|
Note
|
The RFCs are inconsistent on the case sensitivity of hexadecimal digits. Existing uses suggest case‐insensitivity is a de‐facto standard. |
Specification
See Also
The set of visible characters
Synopsis
Declared in <boost/url/grammar/vchars.hpp>
constexpr /* implementation-defined */ vchars = {};Description
Example
Character sets are used with rules and the functions find_if and find_if_not.
system::result< core::string_view > rv = parse( "JohnDoe", token_rule( vchars ) );BNF
VCHAR = 0x21-0x7E
; visible (printing) charactersSee Also
Concept for a CharSet
Synopsis
Declared in <boost/url/grammar/charset.hpp>
template<class T>
concept CharSet = requires (T const t, char c)
{
{ t(c) } ‐> std::convertible_to<bool>;
};Description
A CharSet is a unary predicate which is invocable with this equivalent signature:
bool( char ch ) const noexcept;The predicate returns true if ch is a member of the set, or false otherwise.
Exemplar
For best results, it is suggested that all constructors and member functions for character sets be marked constexpr.
struct CharSet
{
bool operator()( char c ) const noexcept;
// These are both optional. If either or both are left
// unspecified, a default implementation will be used.
//
char const* find_if( char const* first, char const* last ) const noexcept;
char const* find_if_not( char const* first, char const* last ) const noexcept;
};Models
-
alnum_chars -
alpha_chars -
digit_chars -
hexdig_chars -
lut_chars
See Also
Concept for a grammar Rule
Synopsis
Declared in <boost/url/grammar/type_traits.hpp>
template<class T>
concept Rule = requires (T t, char const*& it, char const* end)
{
typename T::value_type;
{ t.parse(it, end) } ‐> std::same_as<system::result<typename T::value_type>>;
};Description
This concept is satisfied if T is a valid grammar Rule
A Rule defines an algorithm used to match an input buffer of ASCII characters against a set of syntactical specifications.
Each rule represents either a terminal symbol or a composition in the represented grammar.
The library comes with a set of rules for productions typically found in RFC documents. Rules are not invoked directly; instead, rule variables are used with overloads of parse which provide a convenient, uniform front end.
Exemplar
For best results, it is suggested that all constructors for rules be marked constexpr.
struct Rule
{
struct value_type;
constexpr Rule( Rule const& ) noexcept = default;
auto parse( char const*& it, char const* end ) const -> result< value_type >;
};
// Declare a variable of type Rule for notational convenience
constexpr Rule rule{};Model
-
dec_octet_rule -
delim_rule -
not_empty_rule -
optional_rule -
range_rule -
token_rule -
tuple_rule -
unsigned_rule -
variant_rule
Types
Name |
Description |
Base class for string tokens, and algorithm parameters |
|
Trait to determine if a type is a string token |
|
A string token for returning a plain string |
Functions
Name |
Description |
Create a string token for appending to a plain string |
|
Create a string token for assigning to a plain string |
|
Create a string token for a durable core::string_view |
Concepts
Name |
Description |
Concept for a string token |
Trait to determine if a type is a string token
Synopsis
Declared in <boost/url/grammar/string_token.hpp>
template<class T>
using is_token = /* implementation-defined */;Description
This trait returns true if T is a valid StringToken type, and false otherwise.
Example
static_assert( string_token::is_token<T>::value );A string token for returning a plain string
Synopsis
Declared in <boost/url/grammar/string_token.hpp>
using return_string = /* implementation-defined */;Description
This StringToken is used to customize a function to return a plain string.
This is default token type used by the methods of url_view_base that return decoded strings.
Base class for string tokens, and algorithm parameters
Synopsis
Declared in <boost/url/grammar/string_token.hpp>
struct arg;Member Functions
Description
This abstract interface provides a means for an algorithm to generically obtain a modifiable, contiguous character buffer of prescribed size.
A StringToken should be derived from this class. As the author of an algorithm using a StringToken, simply declare an rvalue reference as a parameter type.
Instances of this type are intended only to be used once and then destroyed.
Example
The declared function accepts any 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.
Constructors
Synopses
Synopsis
Declared in <boost/url/grammar/string_token.hpp>
constexpr
arg() = default;Deleted copy constructor
Synopsis
Declared in <boost/url/grammar/string_token.hpp>
arg(arg const& other) = delete;Parameters
Name |
Description |
other |
The object to copy construct from |
Default move constructor
Synopsis
Declared in <boost/url/grammar/string_token.hpp>
constexpr
arg(arg&& other) = default;Parameters
Name |
Description |
other |
The object to move construct from |
Virtual destructor
Synopsis
Declared in <boost/url/grammar/string_token.hpp>
constexpr
virtual
~arg() = default;Assignment operators
Synopses
Synopsis
Declared in <boost/url/grammar/string_token.hpp>
Return Value
Reference to the current object
Parameters
Name |
Description |
other |
The object to copy assign from |
Deleted move assignment
Synopsis
Declared in <boost/url/grammar/string_token.hpp>
Return Value
Reference to the current object
Parameters
Name |
Description |
other |
The object to move assign from |
Return a modifiable character buffer
Synopsis
Declared in <boost/url/grammar/string_token.hpp>
virtual
char*
prepare(std::size_t n) = 0;Description
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.
|
Note
|
This function may only be called once. After invoking the function, the only valid operation is destruction. |
Return Value
A pointer to the buffer
Parameters
Name |
Description |
n |
The number of characters needed |
Create a string token for appending to a plain string
Synopsis
Declared in <boost/url/grammar/string_token.hpp>
template<class Alloc = std::allocator<char>>
/* implementation-defined */
append_to(std::basic_string<char, std::char_traits<char>, Alloc>& s);Description
This function creates a StringToken which appends to an existing plain string.
Functions using this token will append the result to the existing string and return a reference to it.
Return Value
A string token
Parameters
Name |
Description |
s |
The string to append |
Create a string token for assigning to a plain string
Synopsis
Declared in <boost/url/grammar/string_token.hpp>
template<class Alloc = std::allocator<char>>
/* implementation-defined */
assign_to(std::basic_string<char, std::char_traits<char>, Alloc>& s);Description
This function creates a StringToken which assigns to an existing plain string.
Functions using this token will assign the result to the existing string and return a reference to it.
Return Value
A string token
Parameters
Name |
Description |
s |
The string to assign |
Create a string token for a durable core::string_view
Synopsis
Declared in <boost/url/grammar/string_token.hpp>
template<class Alloc = std::allocator<char>>
/* implementation-defined */
preserve_size(std::basic_string<char, std::char_traits<char>, Alloc>& s);Description
This function creates a StringToken which assigns to an existing plain string.
Functions using this token will assign the result to the existing string and return a core::string_view to it.
Return Value
A string token
Parameters
Name |
Description |
s |
The string to preserve |
Concept for a string token
Synopsis
Declared in <boost/url/grammar/string_token.hpp>
template<class T>
concept StringToken = std::derived_from<T, string_token::arg> &&
requires (T t, std::size_t n)
{
typename T::result_type;
{ t.prepare(n) } ‐> std::same_as<char*>;
{ t.result() } ‐> std::convertible_to<typename T::result_type>;
};Description
This concept is satisfied if T is a valid string token type.
A string token is an rvalue passed to a function template which customizes the return type of the function and also controls how a modifiable character buffer is obtained and presented.
The string token's lifetime extends only for the duration of the function call in which it appears as a parameter.
A string token cannot be copied, moved, or assigned, and must be destroyed when the function returns or throws.
Semantics
T::result_type determines the return type of functions that accept a string token.
The prepare() function overrides the virtual function in the base class arg. It must return a pointer to a character buffer of at least size n, otherwise throw an exception. This function is called only once or not at all.
The result() function is invoked by the algorithm to receive the result from the string token. It is only invoked if prepare() returned successfully and the string token was not destroyed. It is only called after prepare() returns successfully, and the string token is destroyed when the algorithm completes or if an exception is thrown.
String tokens cannot be reused.
Exemplars
String token prototype:
struct StringToken : string_token::arg
{
using result_type = std::string;
char* prepare( std::size_t n ) override;
result_type result();
};Algorithm prototype:
namespace detail {
// Algorithm implementation may be placed
// out of line, and written as an ordinary
// function (no template required).
void algorithm_impl( string_token::arg& token )
{
std::size_t n = 0;
// calculate space needed in n
// ...
// acquire a destination buffer
char* dest = token.prepare( n );
// write the characters to the buffer
}
} // detail
// public interface is a function template,
// defaulting to return std::string.
template< class StringToken = string_token::return_string >
auto
algorithm( StringToken&& token = {} ) ->
typename StringToken::result_type
{
// invoke the algorithm with the token
algorithm_impl( token );
// return the result from the token
return token.result();
}Models
The following classes and functions implement and generate string tokens.
-
return_string -
assign_to -
preserve_size
A temporary reference to a formatting argument
Synopsis
Declared in <boost/url/format.hpp>
using format_arg = /* implementation-defined */;Description
This class represents a temporary reference to a formatting argument used by the format function.
A format argument should always be created by passing the argument to be formatted directly to the format function.
Any type that can be formatted into a URL with the format function is convertible to this type.
This includes basic types, types convertible to core::string_view, and named_arg.
Synopsis
Declared in <boost/url/format.hpp>
template<class T>
using named_arg = /* implementation-defined */;Description
This class represents a temporary reference to a named formatting argument used by the format function.
Named arguments should always be created with the arg function.
Any type that can be formatted into a URL with the format function can also be used in a named argument. All named arguments are convertible to format_arg and can be used in the format function.
See Also
arg, format, format_to, format_arg.
The type of optional used by the library
Synopsis
Declared in <boost/url/optional.hpp>
template<class T>
using optional = boost::optional<T>;Description
|
Warning
|
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.
The type of string_view used by the library
Synopsis
Declared in <boost/url/string_view.hpp>
using string_view = boost::core::string_view;Description
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.
|
Warning
|
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 variant used by the library
Synopsis
Declared in <boost/url/variant.hpp>
template<class... Ts>
using variant = boost::variant2::variant<Ts...>;Description
|
Warning
|
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.
A non‐owning reference to a valid authority
Synopsis
Declared in <boost/url/authority_view.hpp>
class authority_view;Member Functions
Name |
Description |
|
Constructors |
|
Destructor |
Assignment |
|
Return the complete authority |
|
Return the result of comparing this with another authority |
|
Return a pointer to the first character |
|
Return true if the authority is empty |
|
Return the host |
|
Return the host |
|
Return the host and port |
|
Return the host name |
|
Return the password |
|
Return the user |
|
Return the userinfo |
|
Return true if a password is present |
|
Return true if a port is present |
|
Return true if a userinfo is present |
|
Return the host |
|
Return the host |
|
Return the host IPv4 address |
|
Return the host IPv6 address |
|
Return the host IPvFuture address |
|
Return the host name |
|
Return the host type |
|
Return the password |
|
Return the port |
|
Return the port |
|
Return the number of characters in the authority |
|
Return the user |
|
Return the userinfo |
Friends
Name |
Description |
Format the encoded authority to the output stream |
|
Return the result of comparing two authorities. The authorities are compared component by component as if they were first normalized. |
|
Return the result of comparing two authorities. The authorities are compared component by component as if they were first normalized. |
|
Return the result of comparing two authorities. The authorities are compared component by component as if they were first normalized. |
|
Return the result of comparing two authorities. The authorities are compared component by component as if they were first normalized. |
|
Return the result of comparing two authorities. The authorities are compared component by component as if they were first normalized. |
|
Return the result of comparing two authorities. The authorities are compared component by component as if they were first normalized. |
Non-Member Functions
Name |
Description |
Parse an authority |
Description
Objects of this type represent valid authority 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.
Example 1
Construction from a string parses the input as an authority and throws an exception on error. Upon success, the constructed object points to the passed character buffer; ownership is not transferred.
authority_view a( "user:pass@www.example.com:8080" );Example 2
The parsing function parse_authority returns a boost::system::result containing either a valid authority_view upon success, otherwise it contains an error. The error can be converted to an exception by the caller if desired:
system::result< authority_view > rv = parse_authority( "user:pass@www.example.com:8080" );BNF
authority = [ userinfo "@" ] host [ ":" port ]
userinfo = user [ ":" [ password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
host = IP-literal / IPv4address / reg-name
port = *DIGITSee Also
Constructors
Synopses
Declared in <boost/url/authority_view.hpp>
Constructor
authority_view() noexcept;Constructor
authority_view(authority_view const& other) noexcept;Construct from a string.
explicit
authority_view(core::string_view s);Parameters
Name |
Description |
s |
The string to parse |
See Also
Constructor
Synopsis
Declared in <boost/url/authority_view.hpp>
authority_view() noexcept;Description
Default constructed authorities refer to a string with zero length, which is always valid. This matches the grammar for a zero‐length host.
Exception Safety
Throws nothing.
Specification
Constructor
Synopsis
Declared in <boost/url/authority_view.hpp>
authority_view(authority_view const& other) noexcept;Parameters
Name |
Description |
other |
The object to copy construct from |
Construct from a string.
Synopsis
Declared in <boost/url/authority_view.hpp>
explicit
authority_view(core::string_view s);Description
This function attempts to construct an authority from the string s, which must be a valid authority 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 the view is destroyed.
BNF
authority = [ userinfo "@" ] host [ ":" port ]
userinfo = user [ ":" [ password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
host = IP-literal / IPv4address / reg-name
port = *DIGITParameters
Name |
Description |
s |
The string to parse |
See Also
Destructor
Synopsis
Synopsis
Declared in <boost/url/authority_view.hpp>
authority_view&
operator=(authority_view const& other) noexcept;Description
This function assigns the contents of other to this object.
Exception Safety
Throws nothing.
Return Value
A reference to this object
Parameters
Name |
Description |
other |
The object to assign |
Return the complete authority
Synopsis
Declared in <boost/url/authority_view.hpp>
core::string_view
buffer() const noexcept;Description
This function returns the authority as a percent‐encoded string.
Example
assert( parse_authority( "www.example.com" ).value().buffer() == "www.example.com" );BNF
authority = [ userinfo "@" ] host [ ":" port ]Exception Safety
Throws nothing.
Return Value
The complete authority
Return the result of comparing this with another authority
Synopsis
Declared in <boost/url/authority_view.hpp>
int
compare(authority_view const& other) const noexcept;Description
This function compares two authorities according to Syntax‐Based comparison algorithm.
Exception Safety
Throws nothing.
Return Value
‐1 if *this < other, 0 if this == other, and 1 if this > other.
Parameters
Name |
Description |
other |
The authority to compare |
Return a pointer to the first character
Synopsis
Declared in <boost/url/authority_view.hpp>
char const*
data() const noexcept;Description
This function returns a pointer to the beginning of the view, which is not guaranteed to be null‐terminated.
Exception Safety
Throws nothing.
Return Value
A pointer to the first character
Return true if the authority is empty
Synopsis
Declared in <boost/url/authority_view.hpp>
bool
empty() const noexcept;Description
An empty authority has an empty host, no userinfo, and no port.
Example
assert( authority_view( "" ).empty() );Exception Safety
Throws nothing.
Return Value
true if the authority is empty
Return the host
Synopsis
Declared in <boost/url/authority_view.hpp>
pct_string_view
encoded_host() const noexcept;Description
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.
Example
assert( url_view( "https://www%2droot.example.com/" ).encoded_host() == "www%2droot.example.com" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")Return Value
The host
Return the host
Synopsis
Declared in <boost/url/authority_view.hpp>
pct_string_view
encoded_host_address() const noexcept;Description
The value returned by this function depends on the type of host returned from the function host_type.
-
If the type is
host_type::ipv4, then the IPv4 address string is returned. -
If the type is
host_type::ipv6, then the IPv6 address string is returned, without any enclosing brackets. -
If the type is
host_type::ipvfuture, then the IPvFuture address string is returned, without any enclosing brackets. -
If the type is
host_type::name, then the host name string is returned. Any percent‐escapes in the string are decoded first. -
If the type is
host_type::none, then an empty string is returned. The returned string may contain percent escapes.
Example
assert( url_view( "https://www%2droot.example.com/" ).encoded_host_address() == "www%2droot.example.com" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")Return Value
The host address
Return the host and port
Synopsis
Declared in <boost/url/authority_view.hpp>
pct_string_view
encoded_host_and_port() const noexcept;Description
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.
Example
assert( url_view( "http://www.example.com:8080/index.htm" ).encoded_host_and_port() == "www.example.com:8080" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
authority = [ userinfo "@" ] host [ ":" port ]Specification
Return Value
The host and port
See Also
Return the host name
Synopsis
Declared in <boost/url/authority_view.hpp>
pct_string_view
encoded_host_name() const noexcept;Description
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.
Example
assert( url_view( "https://www%2droot.example.com/" ).encoded_host_name() == "www%2droot.example.com" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")Return Value
The host name
Return the password
Synopsis
Declared in <boost/url/authority_view.hpp>
pct_string_view
encoded_password() const noexcept;Description
This function returns the password portion of the userinfo as a percent‐encoded string.
Example
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_password() == "pass" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
userinfo = user [ ":" [ password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
The password
See Also
Return the user
Synopsis
Declared in <boost/url/authority_view.hpp>
pct_string_view
encoded_user() const noexcept;Description
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.
Example
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_user() == "jane%2Ddoe" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
userinfo = user [ ":" [ password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
The user
See Also
Return the userinfo
Synopsis
Declared in <boost/url/authority_view.hpp>
pct_string_view
encoded_userinfo() const noexcept;Description
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.
Example
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_userinfo() == "jane%2Ddoe:pass" );Complexity
Constant.
Exception Safety
Throws nothing
BNF
userinfo = user [ ":" [ password ] ]
authority = [ userinfo "@" ] host [ ":" port ]Return Value
The userinfo
See Also
Return true if a password is present
Synopsis
Declared in <boost/url/authority_view.hpp>
bool
has_password() const noexcept;Description
This function returns true if the userinfo is present and contains a password.
Example
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_password() );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
userinfo = user [ ":" [ password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
true if a password is present
See Also
Return true if a port is present
Synopsis
Declared in <boost/url/authority_view.hpp>
bool
has_port() const noexcept;Description
This function returns true if an authority is present and contains a port.
Example
assert( url_view( "wss://www.example.com:443" ).has_port() );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
authority = [ userinfo "@" ] host [ ":" port ]
port = *DIGITReturn Value
true if a port is present, otherwise false
See Also
Return true if a userinfo is present
Synopsis
Declared in <boost/url/authority_view.hpp>
bool
has_userinfo() const noexcept;Description
This function returns true if this contains a userinfo.
Example
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_userinfo() );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
userinfo = user [ ":" [ password ] ]
authority = [ userinfo "@" ] host [ ":" port ]Return Value
true if a userinfo is present
See Also
Return the host
Synopsis
Declared in <boost/url/authority_view.hpp>
template<string_token::StringToken StringToken = string_token::return_string>
StringToken::result_type
host(StringToken&& token) const;Description
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.
Example
assert( url_view( "https://www%2droot.example.com/" ).host() == "www-root.example.com" );Complexity
Linear in this‐>host().size().
Exception Safety
Calls to allocate may throw.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")Return Value
The host
Parameters
Name |
Description |
token |
A string token to receive the result. |
Return the host
Synopsis
Declared in <boost/url/authority_view.hpp>
template<string_token::StringToken StringToken = string_token::return_string>
StringToken::result_type
host_address(StringToken&& token) const;Description
The value returned by this function depends on the type of host returned from the function host_type.
-
If the type is
host_type::ipv4, then the IPv4 address string is returned. -
If the type is
host_type::ipv6, then the IPv6 address string is returned, without any enclosing brackets. -
If the type is
host_type::ipvfuture, then the IPvFuture address string is returned, without any enclosing brackets. -
If the type is
host_type::name, then the host name string is returned. Any percent‐escapes in the string are decoded first. -
If the type is
host_type::none, then an empty string is returned.
Example
assert( url_view( "https://[1::6:c0a8:1]/" ).host_address() == "1::6:c0a8:1" );Complexity
Linear in this‐>host_address().size().
Exception Safety
Calls to allocate may throw.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")Return Value
The host address
Parameters
Name |
Description |
token |
A string token to receive the result. |
Return the host IPv4 address
Synopsis
Declared in <boost/url/authority_view.hpp>
ipv4_address
host_ipv4_address() const noexcept;Description
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".
Example
assert( url_view( "http://127.0.0.1/index.htm?user=win95" ).host_ipv4_address() == ipv4_address( "127.0.0.1" ) );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
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-255Return Value
The host IPv4 address
Return the host IPv6 address
Synopsis
Declared in <boost/url/authority_view.hpp>
ipv6_address
host_ipv6_address() const noexcept;Description
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".
Example
assert( url_view( "ftp://[::1]/" ).host_ipv6_address() == ipv6_address( "::1" ) );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
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 hexadecimalReturn Value
The host IPv6 address
Return the host IPvFuture address
Synopsis
Declared in <boost/url/authority_view.hpp>
core::string_view
host_ipvfuture() const noexcept;Description
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.
Example
assert( url_view( "http://[v1fe.d:9]/index.htm" ).host_ipvfuture() == "v1fe.d:9" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )Return Value
The host IPvFuture address
Return the host name
Synopsis
Declared in <boost/url/authority_view.hpp>
template<string_token::StringToken StringToken = string_token::return_string>
StringToken::result_type
host_name(StringToken&& token) const;Description
If the host type is host_type::name, this function returns the name as a string. Otherwise, if the host type is not a name, it returns an empty string. Any percent‐escapes in the string are decoded first.
Example
assert( url_view( "https://www%2droot.example.com/" ).host_name() == "www-root.example.com" );Complexity
Linear in this‐>host_name().size().
Exception Safety
Calls to allocate may throw.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")Return Value
The host name
Parameters
Name |
Description |
token |
A string token to receive the result |
Return the host type
Synopsis
Declared in <boost/url/authority_view.hpp>
urls::host_type
host_type() const noexcept;Description
This function returns one of the following constants representing the type of host present.
-
host_type::ipv4 -
host_type::ipv6 -
host_type::ipvfuture -
host_type::name
Example
assert( url_view( "https://192.168.0.1/local.htm" ).host_type() == host_type::ipv4 );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
The host type
Return the password
Synopsis
Declared in <boost/url/authority_view.hpp>
template<string_token::StringToken StringToken = string_token::return_string>
StringToken::result_type
password(StringToken&& token) const;Description
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.
Example
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).password() == "pass" );Complexity
Linear in this‐>password().size().
Exception Safety
Calls to allocate may throw.
BNF
userinfo = user [ ":" [ password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
The password
Parameters
Name |
Description |
token |
A string token to receive the result. |
See Also
Return the port
Synopsis
Declared in <boost/url/authority_view.hpp>
core::string_view
port() const noexcept;Description
If present, this function returns a string representing the port (which may be empty). Otherwise it returns an empty string.
Example
assert( url_view( "http://localhost.com:8080" ).port() == "8080" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
port = *DIGITReturn Value
The port as a string
See Also
Return the port
Synopsis
Declared in <boost/url/authority_view.hpp>
uint16_t
port_number() const noexcept;Description
If a port is present and the numerical value is representable, it is returned as an unsigned integer. Otherwise, the number zero is returned.
Example
assert( url_view( "http://localhost.com:8080" ).port_number() == 8080 );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
port = *DIGITReturn Value
The port number
See Also
Return the number of characters in the authority
Synopsis
Declared in <boost/url/authority_view.hpp>
std::size_t
size() const noexcept;Description
This function returns the number of characters in the authority.
Example
assert( authority_view( "user:pass@www.example.com:8080" ).size() == 30 );Exception Safety
Throws nothing.
Return Value
The number of characters in the authority
Return the user
Synopsis
Declared in <boost/url/authority_view.hpp>
template<string_token::StringToken StringToken = string_token::return_string>
StringToken::result_type
user(StringToken&& token) const;Description
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.
Example
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).user() == "jane-doe" );Complexity
Linear in this‐>user().size().
Exception Safety
Calls to allocate may throw.
BNF
userinfo = user [ ":" [ password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
The user
Parameters
Name |
Description |
token |
A string token to receive the result. |
See Also
Return the userinfo
Synopsis
Declared in <boost/url/authority_view.hpp>
template<string_token::StringToken StringToken = string_token::return_string>
StringToken::result_type
userinfo(StringToken&& token) const;Description
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.
Example
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).userinfo() == "jane-doe:pass" );Complexity
Linear in this‐>userinfo().size().
Exception Safety
Calls to allocate may throw.
BNF
userinfo = user [ ":" [ password ] ]
authority = [ userinfo "@" ] host [ ":" port ]Return Value
The userinfo
Parameters
Name |
Description |
token |
A string token to receive the result. |
See Also
A reference to a valid, percent‐encoded string
Synopsis
Declared in <boost/url/decode_view.hpp>
class decode_view;Types
Name |
Description |
An iterator of constant, decoded characters. |
|
An iterator of constant, decoded characters. |
|
The reference type |
|
The signed integer type |
|
The reference type |
|
The unsigned integer type |
|
The value type |
Member Functions
Name |
Description |
|
Constructor |
Return the last character |
|
Return an iterator to the beginning |
|
Return the result of comparing to another string |
|
Return true if the string is empty |
|
Return an iterator to the end |
|
Checks if the string ends with the given prefix |
|
Finds the first occurrence of character in this view |
|
Return the first character |
|
Return the decoding options |
|
Remove the first characters |
|
Remove the last characters |
|
Finds the first occurrence of character in this view |
|
Return the number of decoded characters |
|
Checks if the string begins with the given prefix |
Friends
Name |
Description |
Format the string with percent‐decoding applied to the output stream |
|
Compare two decode views for greater than or equal |
|
Compare two decode views for greater than or equal |
|
Compare two decode views for greater than or equal |
|
Compare two decode views for greater than |
|
Compare two decode views for greater than |
|
Compare two decode views for greater than |
|
Compare two decode views for less than or equal |
|
Compare two decode views for less than or equal |
|
Compare two decode views for less than or equal |
|
Compare two decode views for less than |
|
Compare two decode views for less than |
|
Compare two decode views for less than |
|
Compare two decode views for inequality |
|
Compare two decode views for inequality |
|
Compare two decode views for inequality |
|
Compare two decode views for equality |
|
Compare two decode views for equality |
|
Compare two decode views for equality |
Description
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:
-
Iteration of the string
-
Accessing the encoded character buffer
-
Comparison to encoded or plain strings
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.
An iterator of constant, decoded characters.
Synopsis
Declared in <boost/url/decode_view.hpp>
using const_iterator = iterator;Description
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.
The reference type
Synopsis
Synopsis
Synopsis
Synopsis
Synopsis
Declared in <boost/url/decode_view.hpp>
using value_type = char;An iterator of constant, decoded characters.
Synopsis
Declared in <boost/url/decode_view.hpp>
class iterator { /* see-below */ };Friends
Name |
Description |
A reference to a valid, percent‐encoded string |
Description
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
Synopses
Declared in <boost/url/decode_view.hpp>
Constructor
constexpr
decode_view() noexcept = default;Constructor
constexpr
explicit
decode_view(
pct_string_view s,
encoding_opts opt = {}) noexcept;Parameters
Name |
Description |
s |
A percent‐encoded string that has already been validated. Implicit conversion from other string types is supported but may throw exceptions. |
opt |
The options for decoding. If this parameter is omitted, the default options are used. |
Constructor
Synopsis
Declared in <boost/url/decode_view.hpp>
constexpr
decode_view() noexcept = default;Description
Default‐constructed views represent empty strings.
Example
decode_view ds;Postconditions
this->empty() == trueComplexity
Constant.
Exception Safety
Throws nothing.
Constructor
Synopsis
Declared in <boost/url/decode_view.hpp>
constexpr
explicit
decode_view(
pct_string_view s,
encoding_opts opt = {}) noexcept;Description
This constructs a view from the character buffer s, which must remain valid and unmodified until the view is no longer accessed.
Example
decode_view ds( "Program%20Files" );Postconditions
this->encoded() == sComplexity
Linear in s.size().
Exception Safety
Although this function does not throw exceptions, implicitly constructing a pct_string_view for the first argument can throw exceptions on invalid input.
Parameters
Name |
Description |
s |
A percent‐encoded string that has already been validated. Implicit conversion from other string types is supported but may throw exceptions. |
opt |
The options for decoding. If this parameter is omitted, the default options are used. |
Return the last character
Synopsis
Declared in <boost/url/decode_view.hpp>
reference
back() const noexcept;Description
Example
assert( decode_view( "Program%20Files" ).back() == 's' );Preconditions
not this->empty()Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
The last decoded character
Return an iterator to the beginning
Synopsis
Declared in <boost/url/decode_view.hpp>
iterator
begin() const noexcept;Description
Example
auto it = this->begin();Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
An iterator to the first decoded character
Return the result of comparing to another string
Synopses
Declared in <boost/url/decode_view.hpp>
Return the result of comparing to another string
constexpr
int
compare(decode_view other) const noexcept;Return the result of comparing to another string
constexpr
int
compare(core::string_view other) const noexcept;Return Value
Negative value if this string is less than the other character sequence, zero if the both character sequences are equal, positive value if this string is greater than the other character sequence
Parameters
Name |
Description |
other |
string to compare |
Return the result of comparing to another string
Synopsis
Declared in <boost/url/decode_view.hpp>
constexpr
int
compare(decode_view other) const noexcept;Description
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<char>::compare(to_string().data(), v.to_string().data(), rlen). This means the comparison is performed with percent‐decoding applied to the current string.
Return Value
Negative value if this string is less than the other character sequence, zero if the both character sequences are equal, positive value if this string is greater than the other character sequence
Parameters
Name |
Description |
other |
string to compare |
Return the result of comparing to another string
Synopsis
Declared in <boost/url/decode_view.hpp>
constexpr
int
compare(core::string_view other) const noexcept;Description
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<char>::compare(to_string().data(), v.data(), rlen). This means the comparison is performed with percent‐decoding applied to the current string.
Return Value
Negative value if this string is less than the other character sequence, zero if the both character sequences are equal, positive value if this string is greater than the other character sequence
Parameters
Name |
Description |
other |
string to compare |
Return true if the string is empty
Synopsis
Declared in <boost/url/decode_view.hpp>
bool
empty() const noexcept;Description
Example
assert( decode_view( "" ).empty() );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
true if the string is empty
Return an iterator to the end
Synopsis
Declared in <boost/url/decode_view.hpp>
iterator
end() const noexcept;Description
Example
auto it = this->end();Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
An iterator to one past the last decoded character
Checks if the string ends with the given prefix
Synopses
Declared in <boost/url/decode_view.hpp>
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;Return Value
-
trueif the decoded string ends withs -
trueif the decoded string ends withch
Parameters
Name |
Description |
s |
The string to search for |
ch |
The character to search for |
Checks if the string ends with the given prefix
Synopsis
Declared in <boost/url/decode_view.hpp>
bool
ends_with(core::string_view s) const noexcept;Description
Example
assert( decode_view( "Program%20Files" ).ends_with("Files") );Complexity
Linear.
Exception Safety
Throws nothing.
Return Value
true if the decoded string ends with s
Parameters
Name |
Description |
s |
The string to search for |
Checks if the string ends with the given prefix
Synopsis
Declared in <boost/url/decode_view.hpp>
bool
ends_with(char ch) const noexcept;Description
Example
assert( decode_view( "Program%20Files" ).ends_with('s') );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
true if the decoded string ends with ch
Parameters
Name |
Description |
ch |
The character to search for |
Finds the first occurrence of character in this view
Synopsis
Declared in <boost/url/decode_view.hpp>
const_iterator
find(char ch) const noexcept;Description
Complexity
Linear.
Exception Safety
Throws nothing.
Return Value
An iterator to the first decoded occurrence of ch or end()
Parameters
Name |
Description |
ch |
The character to search for |
Return the first character
Synopsis
Declared in <boost/url/decode_view.hpp>
reference
front() const noexcept;Description
Example
assert( decode_view( "Program%20Files" ).front() == 'P' );Preconditions
not this->empty()Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
The first decoded character
Return the decoding options
Synopsis
Declared in <boost/url/decode_view.hpp>
encoding_opts
options() const noexcept;Return Value
The decoding options used by this view
Remove the first characters
Synopsis
Declared in <boost/url/decode_view.hpp>
void
remove_prefix(size_type n);Description
Example
decode_view d( "Program%20Files" );
d.remove_prefix( 8 );
assert( d == "Files" );Preconditions
not this->empty()Complexity
Linear.
Parameters
Name |
Description |
n |
The number of characters to remove |
Remove the last characters
Synopsis
Declared in <boost/url/decode_view.hpp>
void
remove_suffix(size_type n);Description
Example
decode_view d( "Program%20Files" );
d.remove_prefix( 6 );
assert( d == "Program" );Preconditions
not this->empty()Complexity
Linear.
Parameters
Name |
Description |
n |
The number of characters to remove |
Finds the first occurrence of character in this view
Synopsis
Declared in <boost/url/decode_view.hpp>
const_iterator
rfind(char ch) const noexcept;Description
Complexity
Linear.
Exception Safety
Throws nothing.
Return Value
An iterator to the last occurrence of ch or end()
Parameters
Name |
Description |
ch |
The character to search for |
Return the number of decoded characters
Synopsis
Declared in <boost/url/decode_view.hpp>
size_type
size() const noexcept;Description
Example
assert( decode_view( "Program%20Files" ).size() == 13 );Effects
return std::distance( this->begin(), this->end() );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
The number of decoded characters
Checks if the string begins with the given prefix
Synopses
Declared in <boost/url/decode_view.hpp>
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;Return Value
-
trueif the decoded string starts withs -
trueif the decoded string starts withch
Parameters
Name |
Description |
s |
The string to search for |
ch |
The character to search for |
Checks if the string begins with the given prefix
Synopsis
Declared in <boost/url/decode_view.hpp>
bool
starts_with(core::string_view s) const noexcept;Description
Example
assert( decode_view( "Program%20Files" ).starts_with("Program") );Complexity
Linear.
Exception Safety
Throws nothing.
Return Value
true if the decoded string starts with s
Parameters
Name |
Description |
s |
The string to search for |
Checks if the string begins with the given prefix
Synopsis
Declared in <boost/url/decode_view.hpp>
bool
starts_with(char ch) const noexcept;Description
Example
assert( decode_view( "Program%20Files" ).starts_with('P') );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
true if the decoded string starts with ch
Parameters
Name |
Description |
ch |
The character to search for |
Percent‐encoding options
Synopsis
Declared in <boost/url/encoding_opts.hpp>
struct encoding_opts;Member Functions
Name |
Description |
|
Constructs an |
Data Members
Name |
Description |
True if nulls are not allowed |
|
True if hexadecimal digits are emitted as lower case |
|
True if spaces encode to and from plus signs |
Description
These options are used to customize the behavior of algorithms which use percent escapes, such as encoding or decoding.
See Also
Constructs an encoding_opts object with the specified options.
Synopsis
Declared in <boost/url/encoding_opts.hpp>
constexpr
encoding_opts(
bool const space_as_plus = false,
bool const lower_case = false,
bool const disallow_null = false) noexcept;Parameters
Name |
Description |
space_as_plus |
If true, spaces will be encoded as plus signs. |
lower_case |
If true, hexadecimal digits will be emitted as lower case. |
disallow_null |
If true, null characters will not be allowed. |
True if nulls are not allowed
Synopsis
Declared in <boost/url/encoding_opts.hpp>
bool disallow_null = false;Description
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.
True if hexadecimal digits are emitted as lower case
Synopsis
Declared in <boost/url/encoding_opts.hpp>
bool lower_case = false;Description
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 spaces encode to and from plus signs
Synopsis
Declared in <boost/url/encoding_opts.hpp>
bool space_as_plus = false;Description
Although not prescribed by RFC 3986, many applications decode plus signs in URL queries as spaces. In particular, the form‐urlencoded Media Type in HTML for submitting forms uses this convention.
This option controls whether the PLUS character ("+") is used to represent the SP character (" ") when encoding or decoding.
When this option is true, both the encoded SP ("%20") and the PLUS character ("+") represent a space (" ") when decoding. To represent a plus sign, its encoded form ("%2B") is used.
The encode and encoded_size functions will encode spaces as plus signs when this option is true, regardless of the allowed character set. They will also encode plus signs as "%2B" when this option is true, regardless of the allowed character set.
Note that when a URL is normalized, all unreserved percent‐encoded characters are replaced with their unreserved equivalents. However, normalizing the URL query maintains the decoded and encoded "&=+" as they are because they might have different meanings.
This behavior is not optional because normalization can only mitigate false negatives, but it should eliminate false positives. Making it optional would allow a false positive because there's at least one very relevant schema (HTTP) where a decoded or encoded "&=+" has different meanings and represents different resources.
The same considerations apply to URL comparison algorithms in the library, as they treat URLs as if they were normalized.
Specification
An optional parameter to determine case‐sensitivity
Synopsis
Declared in <boost/url/ignore_case.hpp>
class ignore_case_param;Member Functions
Name |
Description |
|
Constructor |
True if an algorithm should ignore case |
Description
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.
See Also
Constructor
Synopses
Declared in <boost/url/ignore_case.hpp>
Constructor
constexpr
ignore_case_param() noexcept = default;Constructor
constexpr
ignore_case_param(/* implementation-defined */ value) noexcept;Constructor
Synopsis
Declared in <boost/url/ignore_case.hpp>
constexpr
ignore_case_param() noexcept = default;Description
By default, comparisons are case‐sensitive.
Example
This function performs case‐sensitive comparisons when called with no arguments:
void f( ignore_case_param = {} );Constructor
Synopsis
Declared in <boost/url/ignore_case.hpp>
constexpr
ignore_case_param(/* implementation-defined */ value) noexcept;Description
Construction from ignore_case indicates that comparisons should be case‐insensitive.
The first parameter to this function should be the variable ignore_case.
Example
When ignore_case is passed as an argument, this function ignores case when performing comparisons:
void f( ignore_case_param(ignore_case) );Parameters
Name |
Description |
value |
The object to construct from |
True if an algorithm should ignore case
Synopsis
Declared in <boost/url/ignore_case.hpp>
operator bool() const noexcept;Description
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.
Return Value
true if case should be ignored
An IP version 4 style address.
Synopsis
Declared in <boost/url/ipv4_address.hpp>
class ipv4_address;Types
Name |
Description |
The type used to represent an address as an array of bytes |
|
The type used to represent an address as an unsigned integer |
Member Functions
Name |
Description |
|
Constructors |
Copy Assignment. |
|
Return true if the address is a loopback address |
|
Return true if the address is a multicast address |
|
Return true if the address is unspecified |
|
Write a dotted decimal string representing the address to a buffer |
|
Return the address as bytes, in network byte order. |
|
Return the address as a string in dotted decimal format |
|
Return the address as an unsigned integer. |
Static Member Functions
Static Data Members
Name |
Description |
The number of characters in the longest possible IPv4 string. |
Friends
Name |
Description |
An IP version 6 style address. |
|
Format the address to an output stream. |
|
Return true if two addresses are not equal |
|
Return true if two addresses are equal |
Non-Member Functions
Name |
Description |
Return an IPv4 address from an IP address string in dotted decimal form |
Description
Objects of this type are used to construct, parse, and manipulate IP version 6 addresses.
BNF
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-255Specification
See Also
The type used to represent an address as an array of bytes
Synopsis
Declared in <boost/url/ipv4_address.hpp>
using bytes_type = std::array<unsigned char, 4>;The type used to represent an address as an unsigned integer
Synopsis
Synopses
Declared in <boost/url/ipv4_address.hpp>
Constructor.
constexpr
ipv4_address() = default;Constructor.
constexpr
ipv4_address(ipv4_address const& other) = default;Construct from a string.
explicit
ipv4_address(core::string_view s);Construct from an unsigned integer.
explicit
ipv4_address(uint_type u) noexcept;Construct from an array of bytes.
explicit
ipv4_address(bytes_type const& bytes) noexcept;Exceptions
Name |
Thrown on |
|
The input failed to parse correctly. |
Parameters
Name |
Description |
s |
The string to parse. |
u |
The integer to construct from. |
bytes |
The value to construct from. |
See Also
Constructor.
Synopsis
Synopsis
Declared in <boost/url/ipv4_address.hpp>
constexpr
ipv4_address(ipv4_address const& other) = default;Parameters
Name |
Description |
other |
The object to copy construct from |
Construct from a string.
Synopsis
Declared in <boost/url/ipv4_address.hpp>
explicit
ipv4_address(core::string_view s);Description
This function constructs an address from the string s, which must contain a valid IPv4 address string or else an exception is thrown.
|
Note
|
For a non‐throwing parse function, use parse_ipv4_address.
|
Exception Safety
Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The input failed to parse correctly. |
Parameters
Name |
Description |
s |
The string to parse. |
See Also
Construct from an unsigned integer.
Synopsis
Declared in <boost/url/ipv4_address.hpp>
explicit
ipv4_address(uint_type u) noexcept;Description
This function constructs an address from the unsigned integer u, where the most significant byte forms the first octet of the resulting address.
Parameters
Name |
Description |
u |
The integer to construct from. |
Construct from an array of bytes.
Synopsis
Declared in <boost/url/ipv4_address.hpp>
explicit
ipv4_address(bytes_type const& bytes) noexcept;Description
This function constructs an address from the array in bytes, which is interpreted in big‐endian.
Parameters
Name |
Description |
bytes |
The value to construct from. |
Copy Assignment.
Synopsis
Declared in <boost/url/ipv4_address.hpp>
constexpr
ipv4_address&
operator=(ipv4_address const& other) = default;Return Value
A reference to this object.
Parameters
Name |
Description |
other |
The object to copy. |
Return true if the address is a loopback address
Synopsis
Declared in <boost/url/ipv4_address.hpp>
bool
is_loopback() const noexcept;Return Value
true if the address is a loopback address
Return true if the address is a multicast address
Synopsis
Declared in <boost/url/ipv4_address.hpp>
bool
is_multicast() const noexcept;Return Value
true if the address is a multicast address
Return true if the address is unspecified
Synopsis
Declared in <boost/url/ipv4_address.hpp>
bool
is_unspecified() const noexcept;Return Value
true if the address is unspecified
Write a dotted decimal string representing the address to a buffer
Synopsis
Declared in <boost/url/ipv4_address.hpp>
core::string_view
to_buffer(
char* dest,
std::size_t dest_size) const;Description
The resulting buffer is not null‐terminated.
Exceptions
Name |
Thrown on |
|
|
Return Value
The formatted string
Parameters
Name |
Description |
dest |
The buffer in which to write, which must have at least |
dest_size |
The size of the output buffer. |
Return the address as bytes, in network byte order.
Synopsis
Declared in <boost/url/ipv4_address.hpp>
bytes_type
to_bytes() const noexcept;Return Value
The address as an array of bytes.
Return the address as a string in dotted decimal format
Synopsis
Declared in <boost/url/ipv4_address.hpp>
template<string_token::StringToken StringToken = string_token::return_string>
StringToken::result_type
to_string(StringToken&& token = {}) const;Description
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.
Example
assert( ipv4_address(0x01020304).to_string() == "1.2.3.4" );Complexity
Constant.
Exception Safety
Strong guarantee. Calls to allocate may throw. String tokens may throw exceptions.
Return Value
The return type of the string token. If the token parameter is omitted, then a new std::string is returned. Otherwise, the function return type is the result type of the token.
Parameters
Name |
Description |
token |
An optional string token. |
Return the address as an unsigned integer.
Synopsis
Declared in <boost/url/ipv4_address.hpp>
uint_type
to_uint() const noexcept;Return Value
The address as an unsigned integer.
Return an address object that represents any address
Synopsis
Declared in <boost/url/ipv4_address.hpp>
static
ipv4_address
any() noexcept;Return Value
The any address.
Return an address object that represents the broadcast address
Synopsis
Declared in <boost/url/ipv4_address.hpp>
static
ipv4_address
broadcast() noexcept;Return Value
The broadcast address.
Return an address object that represents the loopback address
Synopsis
Declared in <boost/url/ipv4_address.hpp>
static
ipv4_address
loopback() noexcept;Return Value
The loopback address.
The number of characters in the longest possible IPv4 string.
Synopsis
Declared in <boost/url/ipv4_address.hpp>
inline constexpr static
std::size_t max_str_len = 15;Description
The longest ipv4 address string is "255.255.255.255".
An IP version 6 style address.
Synopsis
Declared in <boost/url/ipv6_address.hpp>
class ipv6_address;Types
Name |
Description |
The type used to represent an address as an array of bytes. |
Member Functions
Name |
Description |
|
Constructors |
Copy Assignment |
|
Return true if the address is a loopback address |
|
Return true if the address is unspecified |
|
Return true if the address is a mapped IPv4 address |
|
Write a dotted decimal string representing the address to a buffer |
|
Return the address as bytes, in network byte order |
|
Return the address as a string. |
Static Member Functions
Name |
Description |
Return an address object that represents the loopback address |
Static Data Members
Name |
Description |
The number of characters in the longest possible IPv6 string. |
Friends
Name |
Description |
Format the address to an output stream |
|
Return true if two addresses are not equal |
|
Return true if two addresses are equal |
Non-Member Functions
Name |
Description |
Parse a string containing an IPv6 address. |
Description
Objects of this type are used to construct, parse, and manipulate IP version 6 addresses.
BNF
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 hexadecimalSpecification
See Also
The type used to represent an address as an array of bytes.
Synopsis
Declared in <boost/url/ipv6_address.hpp>
using bytes_type = std::array<unsigned char, 16>;Description
Octets are stored in network byte order.
Constructors
Synopses
Declared in <boost/url/ipv6_address.hpp>
Constructor.
constexpr
ipv6_address() = default;Constructor.
constexpr
ipv6_address(ipv6_address const& other) = default;Construct from a string.
ipv6_address(core::string_view s);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;Exceptions
Name |
Thrown on |
|
The input failed to parse correctly. |
Parameters
Name |
Description |
s |
The string to parse. |
bytes |
The value to construct from. |
addr |
The address to construct from. |
See Also
Synopsis
Declared in <boost/url/ipv6_address.hpp>
constexpr
ipv6_address() = default;Description
Default constructed objects represent the unspecified address.
See Also
Constructor.
Synopsis
Declared in <boost/url/ipv6_address.hpp>
constexpr
ipv6_address(ipv6_address const& other) = default;Parameters
Name |
Description |
other |
The object to copy construct from |
Construct from a string.
Synopsis
Declared in <boost/url/ipv6_address.hpp>
ipv6_address(core::string_view s);Description
This function constructs an address from the string s, which must contain a valid IPv6 address string or else an exception is thrown.
|
Note
|
For a non‐throwing parse function, use parse_ipv6_address.
|
Exception Safety
Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The input failed to parse correctly. |
Parameters
Name |
Description |
s |
The string to parse. |
See Also
Construct from an array of bytes.
Synopsis
Declared in <boost/url/ipv6_address.hpp>
ipv6_address(bytes_type const& bytes) noexcept;Description
This function constructs an address from the array in bytes, which is interpreted in big‐endian.
Parameters
Name |
Description |
bytes |
The value to construct from. |
Construct from an IPv4 address.
Synopsis
Declared in <boost/url/ipv6_address.hpp>
ipv6_address(ipv4_address const& addr) noexcept;Description
This function constructs an IPv6 address from the IPv4 address addr. The resulting address is an IPv4‐Mapped IPv6 Address.
Parameters
Name |
Description |
addr |
The address to construct from. |
Copy Assignment
Synopsis
Declared in <boost/url/ipv6_address.hpp>
constexpr
ipv6_address&
operator=(ipv6_address const& other) = default;Return Value
*this
Parameters
Name |
Description |
other |
The object to copy assign from |
Return true if the address is a loopback address
Synopsis
Declared in <boost/url/ipv6_address.hpp>
bool
is_loopback() const noexcept;Description
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 Value
true if the address is a loopback address
Return true if the address is unspecified
Synopsis
Declared in <boost/url/ipv6_address.hpp>
bool
is_unspecified() const noexcept;Description
The address 0:0:0:0:0:0:0:0 is called the unspecified address. It indicates the absence of an address.
Return Value
true if the address is unspecified
Return true if the address is a mapped IPv4 address
Synopsis
Declared in <boost/url/ipv6_address.hpp>
bool
is_v4_mapped() const noexcept;Description
This address type is used to represent the addresses of IPv4 nodes as IPv6 addresses.
Return Value
true if the address is a mapped IPv4 address
Write a dotted decimal string representing the address to a buffer
Synopsis
Declared in <boost/url/ipv6_address.hpp>
core::string_view
to_buffer(
char* dest,
std::size_t dest_size) const;Description
The resulting buffer is not null‐terminated.
Exceptions
Name |
Thrown on |
|
|
Return Value
The formatted string
Parameters
Name |
Description |
dest |
The buffer in which to write, which must have at least |
dest_size |
The size of the output buffer. |
Return the address as bytes, in network byte order
Synopsis
Declared in <boost/url/ipv6_address.hpp>
bytes_type
to_bytes() const noexcept;Return Value
The address as an array of bytes.
Return the address as a string.
Synopsis
Declared in <boost/url/ipv6_address.hpp>
template<string_token::StringToken StringToken = string_token::return_string>
StringToken::result_type
to_string(StringToken&& token) const;Description
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.
Example
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" );Complexity
Constant.
Exception Safety
Strong guarantee. Calls to allocate may throw. String tokens may throw exceptions.
Return Value
The return type of the string token. If the token parameter is omitted, then a new std::string is returned. Otherwise, the function return type is the result type of the token.
Parameters
Name |
Description |
token |
An optional string token. |
Return an address object that represents the loopback address
Synopsis
Declared in <boost/url/ipv6_address.hpp>
static
ipv6_address
loopback() noexcept;Description
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 Value
The loopback address.
The number of characters in the longest possible IPv6 string.
Synopsis
Declared in <boost/url/ipv6_address.hpp>
inline constexpr static
std::size_t max_str_len = 49;Description
The longest IPv6 address is:
ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffffSynopsis
Synopsis
Declared in <boost/url/param.hpp>
struct param;Member Functions
Name |
Description |
|
Constructors |
Assignment |
|
Arrow support |
Description
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.
BNF
query-params = query-param *( "&" query-param )
query-param = key [ "=" value ]
key = *qpchar
value = *( qpchar / "=" )Specification
See Also
Constructors
Synopses
Declared in <boost/url/param.hpp>
Constructor
constexpr
param() = default;Constructor
Constructor
Constructor
template<class OptionalString>
param(
core::string_view key,
OptionalString const& value);Aggregate construction
param(
core::string_view key,
core::string_view value,
bool has_value) noexcept;Return Value
A reference to this object.
Template Parameters
Name |
Description |
OptionalString |
An optional string type, such as |
Parameters
Name |
Description |
other |
The object to construct from. |
key |
The key to set. |
value |
The value to set. |
has_value |
True if a value is present. |
Constructor
Synopsis
Declared in <boost/url/param.hpp>
constexpr
param() = default;Description
Default constructed query parameters have an empty key and no value.
Example
param qp;Postconditions
this->key == "" && this->value == "" && this->has_value == falseComplexity
Constant.
Exception Safety
Throws nothing.
Constructor
Synopsis
Declared in <boost/url/param.hpp>
constexpr
param(param const& other) = default;Description
Upon construction, this becomes a copy of other.
Postconditions
this->key == other.key && this->value == other.value && this->has_value == other.has_valueComplexity
Linear in other.key.size() + other.value.size().
Exception Safety
Calls to allocate may throw.
Return Value
A reference to this object.
Parameters
Name |
Description |
other |
The object to construct from. |
Constructor
Synopsis
Declared in <boost/url/param.hpp>
param(param&& other) noexcept;Description
Upon construction, this acquires ownership of the members of other via move construction. The moved from object is as if default constructed.
Complexity
Constant.
Exception Safety
Throws nothing.
Parameters
Name |
Description |
other |
The object to construct from. |
Constructor
Synopsis
Declared in <boost/url/param.hpp>
template<class OptionalString>
param(
core::string_view key,
OptionalString const& value);Description
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.
Example
param qp( "key", "value" );param qp( "key", optional<core::string_view>("value") );param qp( "key", boost::none );param qp( "key", nullptr );param qp( "key", no_value );Postconditions
this->key == key && this->value == value && this->has_value == trueComplexity
Linear in key.size() + value.size().
Exception Safety
Calls to allocate may throw.
Template Parameters
Name |
Description |
OptionalString |
An optional string type, such as |
Parameters
Name |
Description |
key |
The key to set. |
value |
The value to set. |
Aggregate construction
Synopsis
Declared in <boost/url/param.hpp>
param(
core::string_view key,
core::string_view value,
bool has_value) noexcept;Parameters
Name |
Description |
key |
The key to set. |
value |
The value to set. |
has_value |
True if a value is present. |
Assignment
Synopses
Declared in <boost/url/param.hpp>
Assignment
Assignment
Assignment
param&
operator=(param_pct_view const& other);Assignment
param&
operator=(param_view const& other);Return Value
A reference to this object.
Parameters
Name |
Description |
other |
The object to assign from. |
Assignment
Synopsis
Declared in <boost/url/param.hpp>
Description
Upon assignment, this becomes a copy of other.
Postconditions
this->key == other.key && this->value == other.value && this->has_value == other.has_valueComplexity
Linear in other.key.size() + other.value.size().
Exception Safety
Calls to allocate may throw.
Return Value
A reference to this object.
Parameters
Name |
Description |
other |
The object to assign from. |
Assignment
Synopsis
Declared in <boost/url/param.hpp>
Description
Upon assignment, this acquires ownership of the members of other via move assignment. The moved from object is as if default constructed.
Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
A reference to this object.
Parameters
Name |
Description |
other |
The object to assign from. |
Assignment
Synopsis
Declared in <boost/url/param.hpp>
param&
operator=(param_pct_view const& other);Description
The members of other are copied, re‐using already existing string capacity.
Postconditions
this->key == other.key && this->value == other.value && this->has_value == other.has_valueComplexity
Linear in other.key.size() + other.value.size().
Exception Safety
Calls to allocate may throw.
Return Value
A reference to this object.
Parameters
Name |
Description |
other |
The parameter to copy. |
Assignment
Synopsis
Declared in <boost/url/param.hpp>
param&
operator=(param_view const& other);Description
The members of other are copied, re‐using already existing string capacity.
Postconditions
this->key == other.key && this->value == other.value && this->has_value == other.has_valueComplexity
Linear in other.key.size() + other.value.size().
Exception Safety
Calls to allocate may throw.
Return Value
A reference to this object.
Parameters
Name |
Description |
other |
The parameter to copy. |
Arrow support
Synopsis
Declared in <boost/url/param.hpp>
param const*
operator‐>() const noexcept;Description
This operator returns the address of the object so that it can be used in pointer contexts.
Return Value
A pointer to the object.
True if a value is present
Synopsis
Declared in <boost/url/param.hpp>
bool has_value = false;Description
The presence of a value is indicated by has_value == true. An empty value is distinct from no value.
The key
Synopsis
Declared in <boost/url/param.hpp>
std::string key;Description
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
Synopsis
Declared in <boost/url/param.hpp>
std::string value;Description
The presence of a value is indicated by has_value equal to true. An empty value is distinct from no value.
A view of a percent‐encoded query parameter
Synopsis
Declared in <boost/url/param.hpp>
struct param_pct_view;Member Functions
Name |
Description |
|
Constructors |
Arrow support |
|
Conversion |
|
Conversion to param_view |
Description
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.
BNF
query-params = query-param *( "&" query-param )
query-param = key [ "=" value ]
key = *qpchar
value = *( qpchar / "=" )Specification
See Also
Constructors
Synopses
Declared in <boost/url/param.hpp>
Constructor
constexpr
param_pct_view() = default;Construction
explicit
param_pct_view(param_view const& p);Constructor
param_pct_view(
pct_string_view key,
pct_string_view value) noexcept;Constructor
template<class OptionalString>
param_pct_view(
pct_string_view key,
OptionalString const& value);Aggregate construction
param_pct_view(
pct_string_view key,
pct_string_view value,
bool has_value) noexcept;Exceptions
Name |
Thrown on |
|
|
Return Value
A param object
Template Parameters
Name |
Description |
OptionalString |
An optional |
Parameters
Name |
Description |
p |
The param to construct from. |
key |
The key to set. |
value |
The value to set. |
has_value |
True if a value is present |
Constructor
Synopsis
Declared in <boost/url/param.hpp>
constexpr
param_pct_view() = default;Description
Default constructed query parameters have an empty key and no value.
Example
param_pct_view qp;Postconditions
this->key == "" && this->value == "" && this->has_value == falseComplexity
Constant.
Exception Safety
Throws nothing.
Construction
Synopsis
Declared in <boost/url/param.hpp>
explicit
param_pct_view(param_view const& p);Description
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.
Example
param_pct_view qp( param_view( "key", "value" ) );Complexity
Linear in key.size() + value.size().
Exception Safety
Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
|
Parameters
Name |
Description |
p |
The param to construct from. |
Constructor
Synopsis
Declared in <boost/url/param.hpp>
param_pct_view(
pct_string_view key,
pct_string_view value) noexcept;Description
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.
Example
param_pct_view qp( "key", "value" );Postconditions
this->key.data() == key.data() && this->value.data() == value.data() && this->has_value == trueComplexity
Linear in key.size() + value.size().
Exception Safety
Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
|
Parameters
Name |
Description |
key |
The key to set. |
value |
The value to set. |
Constructor
Synopsis
Declared in <boost/url/param.hpp>
template<class OptionalString>
param_pct_view(
pct_string_view key,
OptionalString const& value);Description
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.
Example
param_pct_view qp( "key", optional<core::string_view>("value") );Postconditions
this->key.data() == key.data() && this->value->data() == value->data() && this->has_value == trueComplexity
Linear in key.size() + value‐>size().
Exception Safety
Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
|
Return Value
A param object
Template Parameters
Name |
Description |
OptionalString |
An optional |
Parameters
Name |
Description |
key |
The key to set. |
value |
The optional value to set. |
Aggregate construction
Synopsis
Declared in <boost/url/param.hpp>
param_pct_view(
pct_string_view key,
pct_string_view value,
bool has_value) noexcept;Parameters
Name |
Description |
key |
The key |
value |
The value |
has_value |
True if a value is present |
Arrow support
Synopsis
Declared in <boost/url/param.hpp>
param_pct_view const*
operator‐>() const noexcept;Description
This operator returns the address of the object so that it can be used in pointer contexts.
Return Value
A pointer to this object
Conversion
Synopsis
Declared in <boost/url/param.hpp>
explicit
operator param() const;Description
This function performs a conversion from a reference‐like query parameter to one retaining ownership of the strings by making a copy.
Complexity
Linear in this‐>key.size() + this‐>value.size().
Exception Safety
Calls to allocate may throw.
Return Value
A param object
Conversion to param_view
Synopsis
Declared in <boost/url/param.hpp>
operator param_view() const noexcept;Description
This function performs a conversion from a pct_string_view query parameter to one using a simple string_view.
Exception Safety
Calls to allocate may throw.
Return Value
A param_view object
True if a value is present
Synopsis
Declared in <boost/url/param.hpp>
bool has_value = false;Description
The presence of a value is indicated by has_value == true. An empty value is distinct from no value.
The key
Synopsis
Declared in <boost/url/param.hpp>
pct_string_view key;Description
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
Synopsis
Declared in <boost/url/param.hpp>
pct_string_view value;Description
The presence of a value is indicated by has_value equal to true. An empty value is distinct from no value.
A view of a query parameter
Synopsis
Declared in <boost/url/param.hpp>
struct param_view;Member Functions
Name |
Description |
|
Constructors |
Arrow support |
|
Conversion |
Description
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. Some functions and objects might expect encoded strings in this view, while others expect decoded strings. The caller should be aware of the context in which the object will be used.
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.
BNF
query-params = query-param *( "&" query-param )
query-param = key [ "=" value ]
key = *qpchar
value = *( qpchar / "=" )Specification
See Also
Constructors
Synopses
Declared in <boost/url/param.hpp>
Constructor
constexpr
param_view() = default;Constructor
param_view(param const& other) noexcept;Constructor
template<class OptionalString>
param_view(
core::string_view key,
OptionalString const& value) noexcept;Aggregate construction
param_view(
core::string_view key_,
core::string_view value_,
bool has_value_) noexcept;Template Parameters
Name |
Description |
OptionalString |
An optional string type, such as |
Parameters
Name |
Description |
other |
The param to reference |
key |
The key to set. |
value |
The value to set. |
key_ |
The key to set. |
value_ |
The value to set. |
has_value_ |
True if a value is present. |
Constructor
Synopsis
Declared in <boost/url/param.hpp>
constexpr
param_view() = default;Description
Default constructed query parameters have an empty key and no value.
Example
param_view qp;Postconditions
this->key == "" && this->value == "" && this->has_value == falseComplexity
Constant.
Exception Safety
Throws nothing.
Constructor
Synopsis
Declared in <boost/url/param.hpp>
param_view(param const& other) noexcept;Description
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.
Example
param qp( "key", "value" );
param_view qpv( qp );Postconditions
this->key == key && this->value == value && this->has_value == other.has_valueComplexity
Constant.
Exception Safety
Throws nothing.
Parameters
Name |
Description |
other |
The param to reference |
Constructor
Synopsis
Declared in <boost/url/param.hpp>
template<class OptionalString>
param_view(
core::string_view key,
OptionalString const& value) noexcept;Description
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.
Example
param_view qp( "key", "value" );Postconditions
this->key.data() == key.data() && this->value.data() == value.data() && this->has_value == trueComplexity
Constant.
Exception Safety
Throws nothing.
Template Parameters
Name |
Description |
OptionalString |
An optional string type, such as |
Parameters
Name |
Description |
key |
The key to set. |
value |
The value to set. |
Aggregate construction
Synopsis
Declared in <boost/url/param.hpp>
param_view(
core::string_view key_,
core::string_view value_,
bool has_value_) noexcept;Parameters
Name |
Description |
key_ |
The key to set. |
value_ |
The value to set. |
has_value_ |
True if a value is present. |
Arrow support
Synopsis
Declared in <boost/url/param.hpp>
param_view const*
operator‐>() const noexcept;Description
This operator returns the address of the object so that it can be used in pointer contexts.
Return Value
A pointer to the object.
Conversion
Synopsis
Declared in <boost/url/param.hpp>
explicit
operator param();Description
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.
Complexity
Linear in this‐>key.size() + this‐>value.size().
Exception Safety
Calls to allocate may throw.
Return Value
A new query parameter.
True if a value is present
Synopsis
Declared in <boost/url/param.hpp>
bool has_value = false;Description
The presence of a value is indicated by has_value == true. An empty value is distinct from no value.
The key
Synopsis
Declared in <boost/url/param.hpp>
core::string_view key;Description
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
Synopsis
Declared in <boost/url/param.hpp>
core::string_view value;Description
The presence of a value is indicated by has_value equal to true. An empty value is distinct from no value.
Common functionality for query parameter containers
Synopsis
Declared in <boost/url/params_base.hpp>
class params_base;Types
Name |
Description |
A Bidirectional iterator to a query parameter |
|
A Bidirectional iterator to a query parameter |
|
The reference type |
|
A signed integer type used to represent differences. |
|
The reference type |
|
An unsigned integer type to represent sizes. |
|
The value type |
Member Functions
Name |
Description |
Return an iterator to the beginning |
|
Return the referenced character buffer. |
|
Return true if a matching key exists |
|
Return the number of matching keys |
|
Return true if there are no params |
|
Return an iterator to the end |
|
Find a matching key |
|
Find a matching key |
|
Return the number of params |
Static Member Functions
Name |
Description |
Return the maximum number of characters possible |
Friends
Name |
Description |
A view representing query parameters in a URL |
|
A view representing query parameters in a URL |
|
Common functionality for containers |
Derived Classes
Name |
Description |
A view representing query parameters in a URL |
|
A view representing query parameters in a URL |
Description
The library uses this base class to provide common member functions for containers of query parameters.
This class should not be instantiated directly; Instead, use one of the containers or functions:
Containers
-
params_ref -
params_view -
params_encoded_ref -
params_encoded_view
A Bidirectional iterator to a query parameter
Synopsis
Declared in <boost/url/params_base.hpp>
using const_iterator = iterator;Description
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 reference type
Synopsis
Declared in <boost/url/params_base.hpp>
using const_reference = param;Description
This is the type of value returned when iterators of the view are dereferenced.
See Also
A signed integer type used to represent differences.
Synopsis
Synopsis
Declared in <boost/url/params_base.hpp>
using reference = param;Description
This is the type of value returned when iterators of the view are dereferenced.
See Also
An unsigned integer type to represent sizes.
Synopsis
Synopsis
Declared in <boost/url/params_base.hpp>
using value_type = param;Description
Values of this type represent parameters whose strings retain unique ownership by making a copy.
Example
params_view::value_type qp( *url_view( "?first=John&last=Doe" ).params().find( "first" ) );See Also
A Bidirectional iterator to a query parameter
Synopsis
Declared in <boost/url/impl/params_base.hpp>
class iterator { /* see-below */ };Friends
Name |
Description |
A view representing query parameters in a URL |
|
Common functionality for query parameter containers |
Description
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.
Return an iterator to the beginning
Synopsis
Declared in <boost/url/params_base.hpp>
iterator
begin() const noexcept;Description
Complexity
Linear in the size of the first param.
Exception Safety
Throws nothing.
Return Value
An iterator to the beginning.
Return the referenced character buffer.
Synopsis
Declared in <boost/url/params_base.hpp>
pct_string_view
buffer() const noexcept;Description
This function returns the character buffer referenced by the view. The returned string may contain percent escapes.
Example
assert( url_view( "?first=John&last=Doe" ).params().buffer() == "?first=John&last=Doe" );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
The buffer.
Return true if a matching key exists
Synopsis
Declared in <boost/url/params_base.hpp>
bool
contains(
core::string_view key,
ignore_case_param ic = {}) const noexcept;Description
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.
Example
assert( url_view( "?first=John&last=Doe" ).params().contains( "first" ) );Complexity
Linear in this‐>buffer().size().
Exception Safety
Throws nothing.
Return Value
true if a matching key exists.
Parameters
Name |
Description |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
Return the number of matching keys
Synopsis
Declared in <boost/url/params_base.hpp>
std::size_t
count(
core::string_view key,
ignore_case_param ic = {}) const noexcept;Description
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.
Example
assert( url_view( "?first=John&last=Doe" ).params().count( "first" ) == 1 );Complexity
Linear in this‐>buffer().size().
Exception Safety
Throws nothing.
Return Value
The number of matching keys.
Parameters
Name |
Description |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
Return true if there are no params
Synopsis
Declared in <boost/url/params_base.hpp>
bool
empty() const noexcept;Description
Example
assert( ! url_view( "?key=value" ).params().empty() );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
true if there are no params.
Return an iterator to the end
Synopsis
Declared in <boost/url/params_base.hpp>
iterator
end() const noexcept;Description
Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
An iterator to the end.
Find a matching key
Synopses
Declared in <boost/url/params_base.hpp>
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;Return Value
an iterator to the param
Parameters
Name |
Description |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
from |
The position to begin the search from. This can be |
Find a matching key
Synopsis
Declared in <boost/url/params_base.hpp>
iterator
find(
core::string_view key,
ignore_case_param ic = {}) const noexcept;Description
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.
Example
assert( (*url_view( "?first=John&last=Doe" ).params().find( "First", ignore_case )).value == "John" );Effects
return this->find( this->begin(), key, ic );Complexity
Linear in this‐>buffer().size().
Return Value
an iterator to the param
Parameters
Name |
Description |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
Find a matching key
Synopsis
Declared in <boost/url/params_base.hpp>
iterator
find(
iterator from,
core::string_view key,
ignore_case_param ic = {}) const noexcept;Description
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.
Example
url_view u( "?First=John&Last=Doe" );
assert( u.params().find( "first" ) != u.params().find( "first", ignore_case ) );Complexity
Linear in this‐>buffer().size().
Return Value
an iterator to the param
Parameters
Name |
Description |
from |
The position to begin the search from. This can be |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
Find a matching key
Synopses
Declared in <boost/url/params_base.hpp>
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;Return Value
an iterator to the param
Parameters
Name |
Description |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
before |
One past the position to begin the search from. This can be |
Find a matching key
Synopsis
Declared in <boost/url/params_base.hpp>
iterator
find_last(
core::string_view key,
ignore_case_param ic = {}) const noexcept;Description
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.
Example
assert( (*url_view( "?first=John&last=Doe" ).params().find_last( "last" )).value == "Doe" );Complexity
Linear in this‐>buffer().size().
Return Value
an iterator to the param
Parameters
Name |
Description |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
Find a matching key
Synopsis
Declared in <boost/url/params_base.hpp>
iterator
find_last(
iterator before,
core::string_view key,
ignore_case_param ic = {}) const noexcept;Description
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.
Example
url_view u( "?First=John&Last=Doe" );
assert( u.params().find_last( "last" ) != u.params().find_last( "last", ignore_case ) );Complexity
Linear in this‐>buffer().size().
Return Value
an iterator to the param
Parameters
Name |
Description |
before |
One past the position to begin the search from. This can be |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
Return the number of params
Synopsis
Declared in <boost/url/params_base.hpp>
std::size_t
size() const noexcept;Description
Example
assert( url_view( "?key=value").params().size() == 1 );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
The number of params.
Return the maximum number of characters possible
Synopsis
Declared in <boost/url/params_base.hpp>
constexpr
static
std::size_t
max_size() noexcept;Description
This represents the largest number of characters that are possible in a path, not including any null terminator.
Exception Safety
Throws nothing.
Return Value
The maximum number of characters possible.
Common functionality for containers
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
class params_encoded_base;Types
Name |
Description |
A Bidirectional iterator to a query parameter |
|
A Bidirectional iterator to a query parameter |
|
The reference type |
|
A signed integer type used to represent differences. |
|
The reference type |
|
An unsigned integer type to represent sizes. |
|
The value type |
Member Functions
Name |
Description |
Return an iterator to the beginning |
|
Return the query corresponding to these params |
|
Return true if a matching key exists |
|
Return the number of matching keys |
|
Return true if there are no params |
|
Return an iterator to the end |
|
Find a matching key |
|
Find a matching key |
|
Return the number of params |
Static Member Functions
Name |
Description |
Return the maximum number of characters possible |
Friends
Name |
Description |
A view representing query parameters in a URL |
|
A view representing query parameters in a URL |
|
Common functionality for containers |
Derived Classes
Name |
Description |
A view representing query parameters in a URL |
|
A view representing query parameters in a URL |
Description
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:
Containers
-
params_ref -
params_view -
params_encoded_ref -
params_encoded_view
A Bidirectional iterator to a query parameter
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
using const_iterator = iterator;Description
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 reference type
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
using const_reference = param_pct_view;Description
This is the type of value returned when iterators of the view are dereferenced.
See Also
A signed integer type used to represent differences.
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
using difference_type = std::ptrdiff_t;The reference type
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
using reference = param_pct_view;Description
This is the type of value returned when iterators of the view are dereferenced.
See Also
An unsigned integer type to represent sizes.
Synopsis
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
using value_type = param;Description
Values of this type represent parameters whose strings retain unique ownership by making a copy.
Example
params_encoded_view::value_type qp( *url_view( "?first=John&last=Doe" ).params().find( "first" ) );See Also
A Bidirectional iterator to a query parameter
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
class iterator { /* see-below */ };Friends
Name |
Description |
|
|
|
|
A view representing query parameters in a URL |
|
Common functionality for containers |
Description
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.
Return an iterator to the beginning
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
iterator
begin() const noexcept;Description
Complexity
Linear in the size of the first param.
Exception Safety
Throws nothing.
Return Value
An iterator to the beginning.
Return the query corresponding to these params
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
pct_string_view
buffer() const noexcept;Description
This function returns the query string referenced by the container. The returned string may contain percent escapes.
Example
assert( url_view( "?first=John&last=Doe" ).encoded_params().buffer() == "first=John&last=Doe" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
query-params = query-param *( "&" query-param )
query-param = key [ "=" value ]
key = *qpchar
value = *( qpchar / "=" )Specification
Return Value
The query string.
Return true if a matching key exists
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
bool
contains(
pct_string_view key,
ignore_case_param ic = {}) const noexcept;Description
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.
Example
assert( url_view( "?first=John&last=Doe" ).encoded_params().contains( "first" ) );Complexity
Linear in this‐>buffer().size().
Exception Safety
Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
|
Return Value
true if a matching key exists.
Parameters
Name |
Description |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
Return the number of matching keys
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
std::size_t
count(
pct_string_view key,
ignore_case_param ic = {}) const noexcept;Description
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.
Example
assert( url_view( "?first=John&last=Doe" ).encoded_params().count( "first" ) == 1 );Complexity
Linear in this‐>buffer().size().
Exception Safety
Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
|
Return Value
The number of matching keys.
Parameters
Name |
Description |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
Return true if there are no params
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
bool
empty() const noexcept;Description
Example
assert( ! url_view( "?key=value" ).encoded_params().empty() );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
true if there are no params.
Return an iterator to the end
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
iterator
end() const noexcept;Description
Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
An iterator to the end.
Find a matching key
Synopses
Declared in <boost/url/params_encoded_base.hpp>
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;Exceptions
Name |
Thrown on |
|
|
Return Value
an iterator to the param
Parameters
Name |
Description |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
from |
The position to begin the search from. This can be |
Find a matching key
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
iterator
find(
pct_string_view key,
ignore_case_param ic = {}) const noexcept;Description
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.
Example
assert( url_view( "?first=John&last=Doe" ).encoded_params().find( "First", ignore_case )->value == "John" );Effects
return this->find( this->begin(), key, ic );Complexity
Linear in this‐>buffer().size().
Exception Safety
Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
|
Return Value
an iterator to the param
Parameters
Name |
Description |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
Find a matching key
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
iterator
find(
iterator from,
pct_string_view key,
ignore_case_param ic = {}) const noexcept;Description
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.
Example
url_view u( "?First=John&Last=Doe" );
assert( u.encoded_params().find( "first" ) != u.encoded_params().find( "first", ignore_case ) );Complexity
Linear in this‐>buffer().size().
Exception Safety
Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
|
Return Value
an iterator to the param
Parameters
Name |
Description |
from |
The position to begin the search from. This can be |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
Find a matching key
Synopses
Declared in <boost/url/params_encoded_base.hpp>
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;Exceptions
Name |
Thrown on |
|
|
Return Value
an iterator to the param
Parameters
Name |
Description |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
before |
One past the position to begin the search from. This can be |
Find a matching key
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
iterator
find_last(
pct_string_view key,
ignore_case_param ic = {}) const noexcept;Description
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.
Example
assert( url_view( "?first=John&last=Doe" ).encoded_params().find_last( "last" )->value == "Doe" );Complexity
Linear in this‐>buffer().size().
Exception Safety
Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
|
Return Value
an iterator to the param
Parameters
Name |
Description |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
Find a matching key
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
iterator
find_last(
iterator before,
pct_string_view key,
ignore_case_param ic = {}) const noexcept;Description
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.
Example
url_view u( "?First=John&Last=Doe" );
assert( u.encoded_params().find_last( "last" ) != u.encoded_params().find_last( "last", ignore_case ) );Complexity
Linear in this‐>buffer().size().
Return Value
an iterator to the param
Parameters
Name |
Description |
before |
One past the position to begin the search from. This can be |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
Return the number of params
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
std::size_t
size() const noexcept;Description
Example
assert( url_view( "?key=value").encoded_params().size() == 1 );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
The number of params.
Return the maximum number of characters possible
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
constexpr
static
std::size_t
max_size() noexcept;Description
This represents the largest number of characters that are possible in a path, not including any null terminator.
Exception Safety
Throws nothing.
Return Value
The maximum number of characters possible.
A view representing query parameters in a URL
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
class params_encoded_ref
: public params_encoded_baseBase Classes
Name |
Description |
Common functionality for containers |
Types
Name |
Description |
A Bidirectional iterator to a query parameter |
|
A Bidirectional iterator to a query parameter |
|
The reference type |
|
A signed integer type used to represent differences. |
|
The reference type |
|
An unsigned integer type to represent sizes. |
|
The value type |
Member Functions
Name |
Description |
|
Constructor |
Assignment |
|
Append params |
|
Assign params |
|
Return an iterator to the beginning |
|
Return the query corresponding to these params |
|
Clear the contents of the container |
|
Return true if a matching key exists |
|
Return the number of matching keys |
|
Return true if there are no params |
|
Return an iterator to the end |
|
Erase params |
|
Find a matching key |
|
Find a matching key |
|
Insert params |
|
Replace params |
|
Set a value |
|
Return the number of params |
|
Remove the value on an element |
|
Return the referenced url |
|
Conversion |
Static Member Functions
Name |
Description |
Return the maximum number of characters possible |
Friends
Name |
Description |
Common functionality for containers |
Description
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.
Example
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.
Iterator Invalidation
Changes to the underlying character buffer can invalidate iterators which reference it. Modifications made through the container invalidate some iterators to the underlying character buffer:
-
append: Onlyend(). -
assign,clear,operator=: All params. -
erase: Erased params and all params after (includingend()). -
insert: All params at or after the insertion point (includingend()). -
replace,set: Modified params and all params after (includingend()).
Constructor
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
constexpr
params_encoded_ref(params_encoded_ref const& other) = default;Description
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.
Postconditions
&this->url() == &other.url();Complexity
Constant.
Exception Safety
Throws nothing.
Parameters
Name |
Description |
other |
The other view. |
Assignment
Synopses
Declared in <boost/url/params_encoded_ref.hpp>
Assignment
params_encoded_ref&
operator=(params_encoded_ref const& other);Assignment
params_encoded_ref&
operator=(std::initializer_list<param_pct_view> init);Exceptions
Name |
Thrown on |
|
|
Return Value
*this
Parameters
Name |
Description |
other |
The params to assign. |
init |
The list of params to assign. |
Assignment
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
params_encoded_ref&
operator=(params_encoded_ref const& other);Description
The previous contents of this are replaced by the contents of other.
All iterators are invalidated.
|
Note
|
The strings referenced by other must not come from the underlying url, or else the behavior is undefined.
|
Effects
this->assign( other.begin(), other.end() );Complexity
Linear in other.buffer().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Parameters
Name |
Description |
other |
The params to assign. |
Assignment
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
params_encoded_ref&
operator=(std::initializer_list<param_pct_view> init);Description
After assignment, the previous contents of the query parameters are replaced by the contents of the initializer‐list.
All iterators are invalidated.
Preconditions
None of character buffers referenced by init may overlap the character buffer of the underlying url, or else the behavior is undefined.
Effects
this->assign( init.begin(), init.end() );Complexity
Linear in init.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
|
Return Value
*this
Parameters
Name |
Description |
init |
The list of params to assign. |
Append params
Synopses
Exceptions
Name |
Thrown on |
|
|
Return Value
-
An iterator to the first new element.
-
An iterator to the new element.
Parameters
Name |
Description |
init |
The list of params to append. |
p |
The param to append. |
first |
The first element to append. |
last |
One past the last element to append. |
Append params
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
iterator
append(std::initializer_list<param_pct_view> init);Description
This function appends the params in an initializer‐list to the view.
The end() iterator is invalidated.
Example
url u;
u.encoded_params().append({ {"first", "John"}, {"last", "Doe"} });Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
|
Return Value
An iterator to the first new element.
Parameters
Name |
Description |
init |
The list of params to append. |
Append params
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
iterator
append(param_pct_view const& p);Description
This function appends a param to the view.
The end() iterator is invalidated.
Example
url u;
u.encoded_params().append( { "first", "John" } );Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
|
Return Value
An iterator to the new element.
Parameters
Name |
Description |
p |
The param to append. |
Append params
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
template<class FwdIt>
iterator
append(
FwdIt first,
FwdIt last);Description
This function appends a range of params to the view.
The end() iterator is invalidated.
|
Note
|
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. |
Mandates
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == trueComplexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The range contains an invalid percent‐encoding. |
Return Value
-
An iterator to the first new element.
-
An iterator to the first new element.
Parameters
Name |
Description |
first |
The first element to append. |
last |
One past the last element to append. |
Assign params
Synopses
Declared in <boost/url/params_encoded_ref.hpp>
Assign params
void
assign(std::initializer_list<param_pct_view> init);Assign params
template<class FwdIt>
void
assign(
FwdIt first,
FwdIt last);Exceptions
Name |
Thrown on |
|
|
Parameters
Name |
Description |
init |
The list of params to assign. |
first |
The first element to assign. |
last |
One past the last element to assign. |
Assign params
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
void
assign(std::initializer_list<param_pct_view> init);Description
This function replaces the entire contents of the view with the params in the initializer‐list.
All iterators are invalidated.
|
Note
|
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. |
Example
url u;
u.encoded_params().assign({ { "first", "John" }, { "last", "Doe" } });Complexity
Linear in init.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
|
Parameters
Name |
Description |
init |
The list of params to assign. |
Assign params
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
template<class FwdIt>
void
assign(
FwdIt first,
FwdIt last);Description
This function replaces the entire contents of the view with the params in the range.
All iterators are invalidated.
|
Note
|
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. |
Mandates
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == trueComplexity
Linear in the size of the range.
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The range contains an invalid percent‐encoding. |
Parameters
Name |
Description |
first |
The first element to assign. |
last |
One past the last element to assign. |
Clear the contents of the container
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
void
clear() noexcept;Description
All iterators are invalidated.
Effects
this->url().remove_query();Postconditions
this->empty() == true && this->url().has_query() == falseComplexity
Constant.
Exception Safety
Throws nothing.
Erase params
Synopses
Declared in <boost/url/params_encoded_ref.hpp>
Erase params
Erase params
Erase params
std::size_t
erase(
pct_string_view key,
ignore_case_param ic = {}) noexcept;Exceptions
Name |
Thrown on |
|
|
Return Value
-
An iterator to one past the removed element.
-
An iterator to one past the removed range.
-
An iterator to one past the removed range.
-
The number of params removed from the container.
Parameters
Name |
Description |
pos |
An iterator to the element. |
first |
The first element to remove. |
last |
One past the last element to remove. |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
Erase params
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
Description
This function removes an element from the container.
All iterators that are equal to pos or come after are invalidated.
Example
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" );Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Throws nothing.
Return Value
An iterator to one past the removed element.
Parameters
Name |
Description |
pos |
An iterator to the element. |
Erase params
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
Description
This function removes a range of params from the container.
All iterators that are equal to first or come after are invalidated.
Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Throws nothing.
Return Value
-
An iterator to one past the removed range.
-
An iterator to one past the removed range.
Parameters
Name |
Description |
first |
The first element to remove. |
last |
One past the last element to remove. |
Erase params
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
std::size_t
erase(
pct_string_view key,
ignore_case_param ic = {}) noexcept;Description
All iterators are invalidated.
Postconditions
this->count( key, ic ) == 0Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
|
Return Value
The number of params removed from the container.
Parameters
Name |
Description |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
Insert params
Synopses
Declared in <boost/url/params_encoded_ref.hpp>
Insert params
Insert params
iterator
insert(
iterator before,
param_pct_view const& p);Insert params
Exceptions
Name |
Thrown on |
|
|
Return Value
-
An iterator to the first element inserted, or
beforeifinit.size() == 0. -
An iterator to the inserted element.
-
An iterator to the first element inserted, or
beforeiffirst == last. -
An iterator to the first element inserted.
Parameters
Name |
Description |
before |
An iterator before which the element is inserted. This may be equal to |
init |
The list of params to insert. |
p |
The param to insert. |
first |
The first element to insert. |
last |
One past the last element to insert. |
Insert params
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
Description
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.
|
Note
|
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. |
Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
|
Return Value
An iterator to the first element inserted, or before if init.size() == 0.
Parameters
Name |
Description |
before |
An iterator before which the element is inserted. This may be equal to |
init |
The list of params to insert. |
Insert params
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
iterator
insert(
iterator before,
param_pct_view const& p);Description
This function inserts a param before the specified position.
All iterators that are equal to before or come after are invalidated.
Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
|
Return Value
An iterator to the inserted element.
Parameters
Name |
Description |
before |
An iterator before which the param is inserted. This may be equal to |
p |
The param to insert. |
Insert params
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
Description
This function inserts a range of params before the specified position.
All iterators that are equal to before or come after are invalidated.
|
Note
|
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. |
Mandates
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == trueComplexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The range contains an invalid percent‐encoding. |
Return Value
-
An iterator to the first element inserted, or
beforeiffirst == last. -
An iterator to the first element inserted.
Parameters
Name |
Description |
before |
An iterator before which the element is inserted. This may be equal to |
first |
The first element to insert. |
last |
One past the last element to insert. |
Replace params
Synopses
Declared in <boost/url/params_encoded_ref.hpp>
Replace params
iterator
replace(
iterator pos,
param_pct_view const& p);Replace params
Replace params
Exceptions
Name |
Thrown on |
|
|
Return Value
-
An iterator to the element.
-
An iterator to the first element inserted, or one past
toifinit.size() == 0. -
An iterator to the first element inserted, or one past
toiffirst == last. -
An iterator to the first element inserted, or one past
toiffirst == last.
Parameters
Name |
Description |
pos |
An iterator to the element. |
p |
The param to assign. |
from,to |
The range of params to replace. |
init |
The list of params to assign. |
from |
The first element to replace. |
to |
One past the last element to replace. |
first |
The first element to insert. |
last |
One past the last element to insert. |
Replace params
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
iterator
replace(
iterator pos,
param_pct_view const& p);Description
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.
|
Note
|
The strings passed in must not come from the element being replaced, or else the behavior is undefined. |
Example
url u( "?first=John&last=Doe" );
u.encoded_params().replace( u.encoded_params().begin(), { "title", "Mr" });
assert( u.encoded_query() == "title=Mr&last=Doe" );Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
|
Return Value
An iterator to the element.
Parameters
Name |
Description |
pos |
An iterator to the element. |
p |
The param to assign. |
Replace params
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
Description
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.
|
Note
|
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. |
Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
|
Return Value
An iterator to the first element inserted, or one past to if init.size() == 0.
Parameters
Name |
Description |
from,to |
The range of params to replace. |
init |
The list of params to assign. |
Replace params
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
Description
This function replaces a range of params with a range of params.
All iterators that are equal to from or come after are invalidated.
|
Note
|
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. |
Mandates
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == trueComplexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The range contains an invalid percent‐encoding. |
Return Value
-
An iterator to the first element inserted, or one past
toiffirst == last. -
An iterator to the first element inserted, or one past
toiffirst == last.
Parameters
Name |
Description |
from |
The first element to replace. |
to |
One past the last element to replace. |
first |
The first element to insert. |
last |
One past the last element to insert. |
Set a value
Synopses
Declared in <boost/url/params_encoded_ref.hpp>
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 = {});Exceptions
Name |
Thrown on |
|
|
Return Value
-
An iterator to the element.
-
An iterator to the appended or modified element.
Parameters
Name |
Description |
pos |
An iterator to the element. |
value |
The value to assign. The empty string still counts as a value. That is, |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
Set a value
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
iterator
set(
iterator pos,
pct_string_view value);Description
This function replaces the value of an element at the specified position.
All iterators that are equal to pos or come after are invalidated.
|
Note
|
The string passed in must not come from the element being replaced, or else the behavior is undefined. |
Example
url u( "?id=42&id=69" );
u.encoded_params().set( u.encoded_params().begin(), "none" );
assert( u.encoded_query() == "id=none&id=69" );Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
|
Return Value
An iterator to the element.
Parameters
Name |
Description |
pos |
An iterator to the element. |
value |
The value to assign. The empty string still counts as a value. That is, |
Set a value
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
iterator
set(
pct_string_view key,
pct_string_view value,
ignore_case_param ic = {});Description
This function performs one of two actions depending on the value of this‐>contains( key, ic ).
-
If key is contained in the view then one of the matching params has its value changed to the specified value. The remaining params with a matching key are erased. Otherwise,
-
If
keyis not contained in the view, then the function apppends the param{ key, value }.
All iterators are invalidated.
|
Note
|
The strings passed in must not come from the element being replaced, or else the behavior is undefined. |
Example
url u( "?id=42&id=69" );
u.encoded_params().set( "id", "none" );
assert( u.encoded_params().count( "id" ) == 1 );Postconditions
this->count( key, ic ) == 1 && this->find( key, ic )->value == valueComplexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
|
Return Value
An iterator to the appended or modified element.
Parameters
Name |
Description |
key |
The key to match. By default, a case‐sensitive comparison is used. |
value |
The value to assign. The empty string still counts as a value. That is, |
ic |
An optional parameter. If the value |
Remove the value on an element
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
Description
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.
Example
url u( "?first=John&last=Doe" );
u.encoded_params().unset( u.encoded_params().begin() );
assert( u.encoded_query() == "first&last=Doe" );Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Throws nothing.
Return Value
An iterator to the element.
Parameters
Name |
Description |
pos |
An iterator to the element. |
Return the referenced url
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
url_base&
url() const noexcept;Description
This function returns the url referenced by the view.
Example
url u( "?key=value" );
assert( &u.encoded_params().url() == &u );Exception Safety
Throws nothing.Return Value
A reference to the url.
Conversion
Synopsis
Declared in <boost/url/params_encoded_ref.hpp>
operator params_encoded_view() const noexcept;Description
Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
A view of the params.
A view representing query parameters in a URL
Synopsis
Declared in <boost/url/params_encoded_view.hpp>
class params_encoded_view
: public params_encoded_baseBase Classes
Name |
Description |
Common functionality for containers |
Types
Name |
Description |
A Bidirectional iterator to a query parameter |
|
A Bidirectional iterator to a query parameter |
|
The reference type |
|
A signed integer type used to represent differences. |
|
The reference type |
|
An unsigned integer type to represent sizes. |
|
The value type |
Member Functions
Name |
Description |
|
Constructor |
Assignment |
|
Return an iterator to the beginning |
|
Return the query corresponding to these params |
|
Return true if a matching key exists |
|
Return the number of matching keys |
|
Return true if there are no params |
|
Return an iterator to the end |
|
Find a matching key |
|
Find a matching key |
|
Return the number of params |
|
Conversion |
Static Member Functions
Name |
Description |
Return the maximum number of characters possible |
Friends
Name |
Description |
Parse a string and return an encoded params view |
|
A view representing query parameters in a URL |
|
A view representing query parameters in a URL |
|
Common functionality for containers |
Description
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.
Example
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.
Iterator Invalidation
Changes to the underlying character buffer can invalidate iterators which reference it.
Constructor
Synopses
Declared in <boost/url/params_encoded_view.hpp>
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);Exceptions
Name |
Thrown on |
|
|
Parameters
Name |
Description |
other |
The object to copy |
s |
The string to parse. |
Constructor
Synopsis
Declared in <boost/url/params_encoded_view.hpp>
constexpr
params_encoded_view() = default;Description
Default‐constructed params have zero elements.
Example
params_encoded_view qp;Effects
return params_encoded_view( "" );Complexity
Constant.
Exception Safety
Throws nothing.
Constructor
Synopsis
Declared in <boost/url/params_encoded_view.hpp>
constexpr
params_encoded_view(params_encoded_view const& other) = default;Description
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.
Postconditions
this->buffer().data() == other.buffer().data()Complexity
Constant.
Exception Safety
Throws nothing
Parameters
Name |
Description |
other |
The object to copy |
Constructor
Synopsis
Declared in <boost/url/params_encoded_view.hpp>
params_encoded_view(core::string_view s);Description
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.
Example
params_encoded_view qp( "first=John&last=Doe" );Effects
return parse_query( s ).value();Postconditions
this->buffer().data() == s.data()Complexity
Linear in s.
Exception Safety
Exceptions thrown on invalid input.
BNF
query-params = [ query-param ] *( "&" query-param )
query-param = key [ "=" value ]Exceptions
Name |
Thrown on |
|
|
Parameters
Name |
Description |
s |
The string to parse. |
Assignment
Synopsis
Declared in <boost/url/params_encoded_view.hpp>
constexpr
params_encoded_view&
operator=(params_encoded_view const& other) = default;Description
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.
Postconditions
this->buffer().data() == other.buffer().data()Complexity
Constant
Exception Safety
Throws nothing
Return Value
*this
Parameters
Name |
Description |
other |
The object to assign |
Conversion
Synopsis
Declared in <boost/url/params_encoded_view.hpp>
operator params_view() const noexcept;Description
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.
Example
params_view qp = parse_path( "/path/to/file.txt" ).value();Postconditions
params_view( *this ).buffer().data() == this->buffer().data()Complexity
Constant
Exception Safety
Throws nothing
Return Value
A new view with percent escapes decoded.
A view representing query parameters in a URL
Synopsis
Declared in <boost/url/params_ref.hpp>
class params_ref
: public params_baseBase Classes
Name |
Description |
Common functionality for query parameter containers |
Types
Name |
Description |
A Bidirectional iterator to a query parameter |
|
A Bidirectional iterator to a query parameter |
|
The reference type |
|
A signed integer type used to represent differences. |
|
The reference type |
|
An unsigned integer type to represent sizes. |
|
The value type |
Member Functions
Name |
Description |
|
Constructor |
Assignment |
|
Append elements |
|
Assign elements |
|
Return an iterator to the beginning |
|
Return the referenced character buffer. |
|
Clear the contents of the container |
|
Return true if a matching key exists |
|
Return the number of matching keys |
|
Return true if there are no params |
|
Return an iterator to the end |
|
Erase elements |
|
Find a matching key |
|
Find a matching key |
|
Insert elements |
|
Replace elements |
|
Set a value |
|
Return the number of params |
|
Remove the value on an element |
|
Return the referenced url |
|
Conversion |
Static Member Functions
Name |
Description |
Return the maximum number of characters possible |
Friends
Name |
Description |
Common functionality for containers |
Description
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.
Example
url u( "?first=John&last=Doe" );
params_ref p = u.params();Iterator Invalidation
Changes to the underlying character buffer can invalidate iterators which reference it. Modifications made through the container invalidate some or all iterators:
-
append: Onlyend(). -
assign,clear,operator=: All elements. -
erase: Erased elements and all elements after (includingend()). -
insert: All elements at or after the insertion point (includingend()). -
replace,set: Modified elements and all elements after (includingend()).
Constructor
Synopses
Declared in <boost/url/params_ref.hpp>
Constructor
constexpr
params_ref(params_ref const& other) = default;Constructor
params_ref(
params_ref const& other,
encoding_opts opt) noexcept;Parameters
Name |
Description |
other |
The other view. |
opt |
The options for decoding. If this parameter is omitted, |
Constructor
Synopsis
Declared in <boost/url/params_ref.hpp>
constexpr
params_ref(params_ref const& other) = default;Description
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.
Postconditions
&this->url() == &other.url()Complexity
Constant.
Exception Safety
Throws nothing.
Parameters
Name |
Description |
other |
The other view. |
Constructor
Synopsis
Declared in <boost/url/params_ref.hpp>
params_ref(
params_ref const& other,
encoding_opts opt) noexcept;Description
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.
Postconditions
&this->url() == &other.url()Complexity
Constant.
Exception Safety
Throws nothing.
Parameters
Name |
Description |
other |
The other view. |
opt |
The options for decoding. If this parameter is omitted, |
Assignment
Synopses
Declared in <boost/url/params_ref.hpp>
Assignment
params_ref&
operator=(params_ref const& other);Assignment
params_ref&
operator=(std::initializer_list<param_view> init);Return Value
*this
Parameters
Name |
Description |
other |
The params to assign. |
init |
The list of params to assign. |
Assignment
Synopsis
Declared in <boost/url/params_ref.hpp>
params_ref&
operator=(params_ref const& other);Description
The previous contents of this are replaced by the contents of other.
All iterators are invalidated.
|
Note
|
The strings referenced by other must not come from the underlying url, or else the behavior is undefined.
|
Effects
this->assign( other.begin(), other.end() );Complexity
Linear in other.buffer().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Parameters
Name |
Description |
other |
The params to assign. |
Assignment
Synopsis
Declared in <boost/url/params_ref.hpp>
params_ref&
operator=(std::initializer_list<param_view> init);Description
After assignment, the previous contents of the query parameters are replaced by the contents of the initializer‐list.
Preconditions
None of character buffers referenced by init may overlap the character buffer of the underlying url, or else the behavior is undefined.
Effects
this->assign( init );Complexity
Linear in init.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Parameters
Name |
Description |
init |
The list of params to assign. |
Append elements
Synopses
Return Value
-
An iterator to the first new element.
-
An iterator to the new element.
Parameters
Name |
Description |
init |
The list of params to append. |
p |
The param to append. |
first |
The first element to append. |
last |
One past the last element to append. |
Append elements
Synopsis
Declared in <boost/url/params_ref.hpp>
iterator
append(std::initializer_list<param_view> init);Description
This function appends the params in an initializer‐list to the view.
The end() iterator is invalidated.
Example
url u;
u.params().append({ { "first", "John" }, { "last", "Doe" } });Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
An iterator to the first new element.
Parameters
Name |
Description |
init |
The list of params to append. |
Append elements
Synopsis
Declared in <boost/url/params_ref.hpp>
iterator
append(param_view const& p);Description
This function appends a param to the view.
The end() iterator is invalidated.
Example
url u;
u.params().append( { "first", "John" } );Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
An iterator to the new element.
Parameters
Name |
Description |
p |
The param to append. |
Append elements
Synopsis
Declared in <boost/url/params_ref.hpp>
template<class FwdIt>
iterator
append(
FwdIt first,
FwdIt last);Description
This function appends a range of params to the view.
The end() iterator is invalidated.
|
Note
|
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. |
Mandates
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == trueComplexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
An iterator to the first new element.
Parameters
Name |
Description |
first |
The first element to append. |
last |
One past the last element to append. |
Assign elements
Synopses
Declared in <boost/url/params_ref.hpp>
Assign elements
void
assign(std::initializer_list<param_view> init);Assign elements
template<class FwdIt>
void
assign(
FwdIt first,
FwdIt last);Parameters
Name |
Description |
init |
The list of params to assign. |
first |
The first element to assign. |
last |
One past the last element to assign. |
Assign elements
Synopsis
Declared in <boost/url/params_ref.hpp>
void
assign(std::initializer_list<param_view> init);Description
This function replaces the entire contents of the view with the params in the initializer‐list.
All iterators are invalidated.
|
Note
|
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. |
Example
url u;
u.params().assign( {{ "first", "John" }, { "last", "Doe" }} );Complexity
Linear in init.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Parameters
Name |
Description |
init |
The list of params to assign. |
Assign elements
Synopsis
Declared in <boost/url/params_ref.hpp>
template<class FwdIt>
void
assign(
FwdIt first,
FwdIt last);Description
This function replaces the entire contents of the view with the params in the range.
All iterators are invalidated.
|
Note
|
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. |
Mandates
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == trueComplexity
Linear in the size of the range.
Exception Safety
Strong guarantee. Calls to allocate may throw.
Parameters
Name |
Description |
first |
The first element to assign. |
last |
One past the last element to assign. |
Clear the contents of the container
Synopsis
Declared in <boost/url/params_ref.hpp>
void
clear() noexcept;Description
All iterators are invalidated.
Effects
this->url().remove_query();Postconditions
this->empty() == true && this->url().has_query() == falseComplexity
Constant.
Exception Safety
Throws nothing.
Erase elements
Synopses
Return Value
-
An iterator to one past the removed element.
-
An iterator to one past the removed range.
-
The number of elements removed from the container.
Parameters
Name |
Description |
pos |
An iterator to the element. |
first |
The first element to remove. |
last |
One past the last element to remove. |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
Erase elements
Synopsis
Declared in <boost/url/params_ref.hpp>
Description
This function removes an element from the container.
All iterators that are equal to pos or come after are invalidated.
Example
url u( "?first=John&last=Doe" );
params_ref::iterator it = u.params().erase( u.params().begin() );
assert( u.encoded_query() == "last=Doe" );Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Throws nothing.
Return Value
An iterator to one past the removed element.
Parameters
Name |
Description |
pos |
An iterator to the element. |
Erase elements
Synopsis
Declared in <boost/url/params_ref.hpp>
Description
This function removes a range of elements from the container.
All iterators that are equal to first or come after are invalidated.
Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Throws nothing.
Return Value
An iterator to one past the removed range.
Parameters
Name |
Description |
first |
The first element to remove. |
last |
One past the last element to remove. |
Erase elements
Synopsis
Declared in <boost/url/params_ref.hpp>
std::size_t
erase(
core::string_view key,
ignore_case_param ic = {}) noexcept;Description
All iterators are invalidated.
Postconditions
this->count( key, ic ) == 0Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Throws nothing.
Return Value
The number of elements removed from the container.
Parameters
Name |
Description |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
Insert elements
Synopses
Declared in <boost/url/params_ref.hpp>
Insert elements
Insert elements
iterator
insert(
iterator before,
param_view const& p);Insert elements
Return Value
-
An iterator to the first element inserted, or
beforeifinit.size() == 0. -
An iterator to the inserted element.
-
An iterator to the first element inserted, or
beforeiffirst == last. -
An iterator to the first element inserted, or
beforeiffirst == last.
Parameters
Name |
Description |
before |
An iterator before which the element is inserted. This may be equal to |
init |
The list of params to insert. |
p |
The param to insert. |
first |
The first element to insert. |
last |
One past the last element to insert. |
Insert elements
Synopsis
Declared in <boost/url/params_ref.hpp>
Description
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.
|
Note
|
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. |
Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
An iterator to the first element inserted, or before if init.size() == 0.
Parameters
Name |
Description |
before |
An iterator before which the element is inserted. This may be equal to |
init |
The list of params to insert. |
Insert elements
Synopsis
Declared in <boost/url/params_ref.hpp>
iterator
insert(
iterator before,
param_view const& p);Description
This function inserts a param before the specified position.
All iterators that are equal to before or come after are invalidated.
Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
An iterator to the inserted element.
Parameters
Name |
Description |
before |
An iterator before which the param is inserted. This may be equal to |
p |
The param to insert. |
Insert elements
Synopsis
Declared in <boost/url/params_ref.hpp>
Description
This function inserts a range of params before the specified position.
All iterators that are equal to before or come after are invalidated.
|
Note
|
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. |
Mandates
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == trueComplexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
-
An iterator to the first element inserted, or
beforeiffirst == last. -
An iterator to the first element inserted, or
beforeiffirst == last.
Parameters
Name |
Description |
before |
An iterator before which the element is inserted. This may be equal to |
first |
The first element to insert. |
last |
One past the last element to insert. |
Replace elements
Synopses
Declared in <boost/url/params_ref.hpp>
Replace elements
iterator
replace(
iterator pos,
param_view const& p);Replace elements
Replace elements
Return Value
-
An iterator to the element.
-
An iterator to the first element inserted, or one past
toifinit.size() == 0. -
An iterator to the first element inserted, or one past
toiffirst == last. -
An iterator to the first element inserted, or one past
toiffirst == last.
Parameters
Name |
Description |
pos |
An iterator to the element. |
p |
The param to assign. |
from,to |
The range of elements to replace. |
init |
The list of params to assign. |
from |
The first element to replace. |
to |
One past the last element to replace. |
first |
The first element to insert. |
last |
One past the last element to insert. |
Replace elements
Synopsis
Declared in <boost/url/params_ref.hpp>
iterator
replace(
iterator pos,
param_view const& p);Description
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.
Example
url u( "?first=John&last=Doe" );
u.params().replace( u.params().begin(), { "title", "Mr" });
assert( u.encoded_query() == "title=Mr&last=Doe" );Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
An iterator to the element.
Parameters
Name |
Description |
pos |
An iterator to the element. |
p |
The param to assign. |
Replace elements
Synopsis
Declared in <boost/url/params_ref.hpp>
Description
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.
|
Note
|
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. |
Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
An iterator to the first element inserted, or one past to if init.size() == 0.
Parameters
Name |
Description |
from,to |
The range of elements to replace. |
init |
The list of params to assign. |
Replace elements
Synopsis
Declared in <boost/url/params_ref.hpp>
Description
This function replaces a range of elements with a range of params.
All iterators that are equal to from or come after are invalidated.
|
Note
|
The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. |
Mandates
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == trueComplexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
-
An iterator to the first element inserted, or one past
toiffirst == last. -
An iterator to the first element inserted, or one past
toiffirst == last.
Parameters
Name |
Description |
from |
The first element to replace. |
to |
One past the last element to replace. |
first |
The first element to insert. |
last |
One past the last element to insert. |
Set a value
Synopses
Declared in <boost/url/params_ref.hpp>
Set a value
Set a value
iterator
set(
core::string_view key,
core::string_view value,
ignore_case_param ic = {});Return Value
-
An iterator to the element.
-
An iterator to the appended or modified element.
Parameters
Name |
Description |
pos |
An iterator to the element. |
value |
The value to assign. The empty string still counts as a value. That is, |
key |
The key to match. By default, a case‐sensitive comparison is used. |
ic |
An optional parameter. If the value |
Set a value
Synopsis
Declared in <boost/url/params_ref.hpp>
Description
This function replaces the value of an element at the specified position.
All iterators that are equal to pos or come after are invalidated.
Example
url u( "?id=42&id=69" );
u.params().set( u.params().begin(), "none" );
assert( u.encoded_query() == "id=none&id=69" );Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
An iterator to the element.
Parameters
Name |
Description |
pos |
An iterator to the element. |
value |
The value to assign. The empty string still counts as a value. That is, |
Set a value
Synopsis
Declared in <boost/url/params_ref.hpp>
iterator
set(
core::string_view key,
core::string_view value,
ignore_case_param ic = {});Description
This function performs one of two actions depending on the value of this‐>contains( key, ic ).
-
If key is contained in the view then one of the matching elements has its value changed to the specified value. The remaining elements with a matching key are erased. Otherwise,
-
If
keyis not contained in the view, then the function apppends the param{ key, value }.
All iterators are invalidated.
Example
url u( "?id=42&id=69" );
u.params().set( "id", "none" );
assert( u.params().count( "id" ) == 1 );Postconditions
this->count( key, ic ) == 1 && this->find( key, ic )->value == valueComplexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
An iterator to the appended or modified element.
Parameters
Name |
Description |
key |
The key to match. By default, a case‐sensitive comparison is used. |
value |
The value to assign. The empty string still counts as a value. That is, |
ic |
An optional parameter. If the value |
Remove the value on an element
Synopsis
Declared in <boost/url/params_ref.hpp>
Description
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.
Example
url u( "?first=John&last=Doe" );
u.params().unset( u.params().begin() );
assert( u.encoded_query() == "first&last=Doe" );Complexity
Linear in this‐>url().encoded_query().size().
Exception Safety
Throws nothing.
Return Value
An iterator to the element.
Parameters
Name |
Description |
pos |
An iterator to the element. |
Return the referenced url
Synopsis
Declared in <boost/url/params_ref.hpp>
url_base&
url() const noexcept;Description
This function returns the url referenced by the view.
Example
url u( "?key=value" );
assert( &u.segments().url() == &u );Exception Safety
Throws nothing.Return Value
A reference to the url.
Conversion
Synopsis
Declared in <boost/url/params_ref.hpp>
operator params_view() const noexcept;Return Value
A view of the query parameters.
A view representing query parameters in a URL
Synopsis
Declared in <boost/url/params_view.hpp>
class params_view
: public params_baseBase Classes
Name |
Description |
Common functionality for query parameter containers |
Types
Name |
Description |
A Bidirectional iterator to a query parameter |
|
A Bidirectional iterator to a query parameter |
|
The reference type |
|
A signed integer type used to represent differences. |
|
The reference type |
|
An unsigned integer type to represent sizes. |
|
The value type |
Member Functions
Name |
Description |
|
Constructor |
Assignment |
|
Return an iterator to the beginning |
|
Return the referenced character buffer. |
|
Return true if a matching key exists |
|
Return the number of matching keys |
|
Return true if there are no params |
|
Return an iterator to the end |
|
Find a matching key |
|
Find a matching key |
|
Return the number of params |
Static Member Functions
Name |
Description |
Return the maximum number of characters possible |
Friends
Name |
Description |
A view representing query parameters in a URL |
|
A view representing query parameters in a URL |
|
Common functionality for containers |
Description
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.
Example
url_view u( "?first=John&last=Doe" );
params_view p = u.params();Percent escapes in strings returned when dereferencing iterators are automatically decoded.
Iterator Invalidation
Changes to the underlying character buffer can invalidate iterators which reference it.
Constructor
Synopses
Declared in <boost/url/params_view.hpp>
Constructor
params_view() = default;Constructor
constexpr
params_view(params_view const& other) = default;Constructor
params_view(core::string_view s);Constructor
params_view(
core::string_view s,
encoding_opts opt);Constructor
params_view(
params_view const& other,
encoding_opts opt) noexcept;Exceptions
Name |
Thrown on |
|
|
Parameters
Name |
Description |
other |
The object to copy |
s |
The string to parse. |
opt |
The options for decoding. If this parameter is omitted, |
Constructor
Synopsis
Declared in <boost/url/params_view.hpp>
params_view() = default;Description
Default‐constructed params have zero elements.
Example
params_view qp;Effects
return params_view( "" );Complexity
Constant.
Exception Safety
Throws nothing.
Constructor
Synopsis
Declared in <boost/url/params_view.hpp>
constexpr
params_view(params_view const& other) = default;Description
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.
Postconditions
this->buffer().data() == other.buffer().data()Complexity
Constant.
Exception Safety
Throws nothing
Parameters
Name |
Description |
other |
The object to copy |
Constructor
Synopsis
Declared in <boost/url/params_view.hpp>
params_view(core::string_view s);Description
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.
Example
params_view qp( "first=John&last=Doe" );Effects
return parse_query( s ).value();Postconditions
this->buffer().data() == s.data()Complexity
Linear in s.
Exception Safety
Exceptions thrown on invalid input.
BNF
query-params = [ query-param ] *( "&" query-param )
query-param = key [ "=" value ]Exceptions
Name |
Thrown on |
|
|
Parameters
Name |
Description |
s |
The string to parse. |
Constructor
Synopsis
Declared in <boost/url/params_view.hpp>
params_view(
core::string_view s,
encoding_opts opt);Description
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.
Example
encoding_opts opt;
opt.space_as_plus = true;
params_view qp( "name=John+Doe", opt );Effects
return params_view(parse_query( s ).value(), opt);Postconditions
this->buffer().data() == s.data()Complexity
Linear in s.
Exception Safety
Exceptions thrown on invalid input.
BNF
query-params = [ query-param ] *( "&" query-param )
query-param = key [ "=" value ]Exceptions
Name |
Thrown on |
|
|
Parameters
Name |
Description |
s |
The string to parse. |
opt |
The options for decoding. If this parameter is omitted, |
Constructor
Synopsis
Declared in <boost/url/params_view.hpp>
params_view(
params_view const& other,
encoding_opts opt) noexcept;Description
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.
Postconditions
this->buffer().data() == other.buffer().data()Complexity
Constant.
Exception Safety
Throws nothing
Parameters
Name |
Description |
other |
The object to copy |
opt |
The options for decoding |
Assignment
Synopsis
Declared in <boost/url/params_view.hpp>
params_view&
operator=(params_view const& other) = default;Description
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.
Postconditions
this->buffer().data() == other.buffer().data()Complexity
Constant
Exception Safety
Throws nothing
Return Value
A reference to this object
Parameters
Name |
Description |
other |
The object to assign |
A reference to a valid percent‐encoded string
Synopsis
Declared in <boost/url/pct_string_view.hpp>
class pct_string_view final
: public grammar::string_view_baseBase Classes
Name |
Description |
Common functionality for string views |
Types
Name |
Description |
The const iterator type |
|
The const pointer type |
|
The const reference type |
|
The const reverse iterator type |
|
The difference type |
|
The iterator type |
|
The pointer type |
|
The reference type |
|
The reverse iterator type |
|
The size type |
|
The character traits |
|
The value type |
Member Functions
Name |
Description |
|
Constructors |
Assignment |
|
Access a character |
|
Return the last character |
|
Return an iterator to the beginning |
|
Return an iterator to the beginning |
|
Return an iterator to the end |
|
Return the result of comparing to another string |
|
Return true if matching characters are found |
|
Copy the characters to another buffer |
|
Return a reverse iterator to the end |
|
Return a reverse iterator to the beginning |
|
Return a pointer to the character buffer |
|
Return the string with percent‐decoding |
|
Return the decoded size |
|
Return true if the string is empty |
|
Return an iterator to the end |
|
Return true if a matching suffix exists |
|
Return the position of matching characters |
|
Return the position of the first non‐match |
|
Return the position of the first match |
|
Return the position of the last non‐match |
|
Return the position of the last match |
|
Return the first character |
|
Return the size |
|
Return the maximum allowed size |
|
Return the string as a range of decoded characters |
|
Arrow support |
|
Access a character |
|
Return a reverse iterator to the end |
|
Return a reverse iterator to the beginning |
|
Return the position of matching characters |
|
Return the size |
|
Return true if a matching prefix exists |
|
Return a view to part of the string |
|
Swap |
|
Conversion |
|
Conversion |
Static Data Members
Name |
Description |
A constant used to represent "no position" |
Protected Data Members
Name |
Description |
The referenced character buffer |
Friends
Name |
Description |
Return a valid percent‐encoded string |
Description
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.
Constructors
Synopses
Declared in <boost/url/pct_string_view.hpp>
Constructor
constexpr
pct_string_view() = default;Constructor
constexpr
pct_string_view(pct_string_view const& other) = default;Constructor (deleted)
pct_string_view(std::nullptr_t value) = delete;Constructor
pct_string_view(core::string_view s);Constructor
template<std::convertible_to<core::string_view> String>
requires std::is_convertible<
String,
core::string_view
>::value
constexpr
pct_string_view(String const& s);Constructor
pct_string_view(
char const* s,
std::size_t len);Exceptions
Name |
Thrown on |
|
The string contains an invalid percent encoding. |
Template Parameters
Name |
Description |
String |
A type convertible to |
Parameters
Name |
Description |
other |
The string to copy. |
s |
The string to construct from. |
len |
The length of the string. |
Constructor
Synopsis
Declared in <boost/url/pct_string_view.hpp>
constexpr
pct_string_view() = default;Description
Default constructed string are empty.
Complexity
Constant.
Exception Safety
Throws nothing.
Constructor
Synopsis
Declared in <boost/url/pct_string_view.hpp>
constexpr
pct_string_view(pct_string_view const& other) = default;Description
The copy references the same underlying character buffer. Ownership is not transferred.
Postconditions
this->data() == other.data()Complexity
Constant.
Exception Safety
Throws nothing.
Parameters
Name |
Description |
other |
The string to copy. |
Constructor (deleted)
Synopsis
Declared in <boost/url/pct_string_view.hpp>
pct_string_view(std::nullptr_t value) = delete;Parameters
Name |
Description |
value |
The object to construct from |
Constructor
Synopsis
Declared in <boost/url/pct_string_view.hpp>
pct_string_view(core::string_view s);Description
The newly constructed string references the specified character buffer. Ownership is not transferred.
Postconditions
this->data() == s.data() && this->size() == s.size()Complexity
Linear in s.size().
Exception Safety
Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The string contains an invalid percent encoding. |
Parameters
Name |
Description |
s |
The string to construct from. |
Constructor
Synopsis
Declared in <boost/url/pct_string_view.hpp>
template<std::convertible_to<core::string_view> String>
requires std::is_convertible<
String,
core::string_view
>::value
constexpr
pct_string_view(String const& s);Description
The newly constructed string references the specified character buffer. Ownership is not transferred.
Postconditions
this->data() == core::string_view(s).data()Complexity
Linear in core::string_view(s).size().
Exception Safety
Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The string contains an invalid percent encoding. |
Template Parameters
Name |
Description |
String |
A type convertible to |
Parameters
Name |
Description |
s |
The string to construct from. |
Constructor
Synopsis
Declared in <boost/url/pct_string_view.hpp>
pct_string_view(
char const* s,
std::size_t len);Description
The newly constructed string references the specified character buffer. Ownership is not transferred.
Postconditions
this->data() == s && this->size() == lenComplexity
Linear in len.
Exception Safety
Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The string contains an invalid percent encoding. |
Parameters
Name |
Description |
s |
The string to construct from. |
len |
The length of the string. |
Assignment
Synopsis
Declared in <boost/url/pct_string_view.hpp>
constexpr
pct_string_view&
operator=(pct_string_view const& other) = default;Description
The copy references the same underlying character buffer. Ownership is not transferred.
Postconditions
this->data() == other.data()Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
A reference to this object.
Parameters
Name |
Description |
other |
The string to copy. |
Return the string with percent‐decoding
Synopsis
Declared in <boost/url/pct_string_view.hpp>
template<string_token::StringToken StringToken = string_token::return_string>
StringToken::result_type
decode(
encoding_opts opt = {},
StringToken&& token) const;Description
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.
Example
assert( pct_string_view( "Program%20Files" ).decode() == "Program Files" );Complexity
Linear in this‐>size().
Exception Safety
Calls to allocate may throw. String tokens may throw exceptions.
Return Value
The decoded string.
Parameters
Name |
Description |
opt |
The options for encoding. If this parameter is omitted, the default options are used. |
token |
An optional string token. If this parameter is omitted, then a new |
See Also
Return the decoded size
Synopsis
Declared in <boost/url/pct_string_view.hpp>
constexpr
std::size_t
decoded_size() const noexcept;Description
This function returns the number of characters in the resulting string if percent escapes were converted into ordinary characters.
Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
The number of characters in the decoded string.
Return the string as a range of decoded characters
Synopsis
Declared in <boost/url/pct_string_view.hpp>
decode_view
operator*() const noexcept;Description
Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
A range of decoded characters.
See Also
Arrow support
Synopsis
Declared in <boost/url/pct_string_view.hpp>
pct_string_view const*
operator‐>() const noexcept;Return Value
A pointer to this object.
Swap
Synopsis
Declared in <boost/url/pct_string_view.hpp>
void
swap(pct_string_view& s) noexcept;Parameters
Name |
Description |
s |
The object to swap with |
Common functionality for containers
Synopsis
Declared in <boost/url/segments_base.hpp>
class segments_base;Types
Name |
Description |
A Bidirectional iterator to a path segment |
|
A Bidirectional iterator to a path segment |
|
The reference type |
|
A signed integer type used to represent differences. |
|
The reference type |
|
An unsigned integer type used to represent size. |
|
The value type |
Member Functions
Name |
Description |
Return the last segment |
|
Return an iterator to the beginning |
|
Return the referenced character buffer. |
|
Return true if there are no segments |
|
Return an iterator to the end |
|
Return the first segment |
|
Returns true if this references an absolute path. |
|
Return the number of segments |
Static Member Functions
Name |
Description |
Return the maximum number of characters possible |
Friends
Name |
Description |
A view representing path segments in a URL |
|
A view representing path segments in a URL |
|
Common functionality for containers |
Derived Classes
Name |
Description |
A view representing path segments in a URL |
|
A view representing path segments in a URL |
Description
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:
Containers
-
segments_ref -
segments_view -
segments_encoded_ref -
segments_encoded_view
A Bidirectional iterator to a path segment
Synopsis
Declared in <boost/url/segments_base.hpp>
using const_iterator = iterator;Description
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 reference type
Synopsis
Declared in <boost/url/segments_base.hpp>
using const_reference = std::string;Description
This is the type of value returned when iterators of the view are dereferenced.
A signed integer type used to represent differences.
Synopsis
Declared in <boost/url/segments_base.hpp>
using difference_type = std::ptrdiff_t;The reference type
Synopsis
Declared in <boost/url/segments_base.hpp>
using reference = std::string;Description
This is the type of value returned when iterators of the view are dereferenced.
An unsigned integer type used to represent size.
Synopsis
Synopsis
Declared in <boost/url/segments_base.hpp>
using value_type = std::string;Description
Values of this type represent a segment where unique ownership is retained by making a copy.
Example
segments_base::value_type ps( url_view( "/path/to/file.txt" ).segments().back() );A Bidirectional iterator to a path segment
Synopsis
Declared in <boost/url/impl/segments_base.hpp>
class iterator { /* see-below */ };Friends
Name |
Description |
A view representing path segments in a URL |
|
Common functionality for containers |
Description
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.
Return the last segment
Synopsis
Declared in <boost/url/segments_base.hpp>
std::string
back() const noexcept;Description
Preconditions
this->empty() == falseExample
assert( url_view( "/path/to/file.txt" ).segments().back() == "file.txt" );Preconditions
this->empty() == falseEffects
return *--end();Complexity
Linear in this‐>back().size().
Exception Safety
Calls to allocate may throw.
Return Value
The last segment.
Return an iterator to the beginning
Synopsis
Declared in <boost/url/segments_base.hpp>
iterator
begin() const noexcept;Description
Complexity
Linear in this‐>front().size() or constant if this‐>empty().
Exception Safety
Throws nothing.
Return Value
An iterator to the first segment.
Return the referenced character buffer.
Synopsis
Declared in <boost/url/segments_base.hpp>
pct_string_view
buffer() const noexcept;Description
This function returns the character buffer referenced by the view. The returned string may contain percent escapes.
Example
assert( url_view( "/path/to/file.txt" ).segments().buffer() == "/path/to/file.txt" );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
A string containing the path.
Return true if there are no segments
Synopsis
Declared in <boost/url/segments_base.hpp>
bool
empty() const noexcept;Description
Example
assert( ! url_view( "/index.htm" ).segments().empty() );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
true if there are no segments, otherwise false.
Return an iterator to the end
Synopsis
Declared in <boost/url/segments_base.hpp>
iterator
end() const noexcept;Description
Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
An iterator to one past the last segment.
Return the first segment
Synopsis
Declared in <boost/url/segments_base.hpp>
std::string
front() const noexcept;Description
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.
Preconditions
this->empty() == falseEffects
return *begin();Example
assert( url_view( "/path/to/file.txt" ).segments().front() == "path" );Complexity
Linear in this‐>front().size().
Exception Safety
Calls to allocate may throw.
Return Value
The first segment.
Returns true if this references an absolute path.
Synopsis
Declared in <boost/url/segments_base.hpp>
bool
is_absolute() const noexcept;Description
Absolute paths always start with a forward slash ('/').
Example
assert( url_view( "/path/to/file.txt" ).segments().is_absolute() == true );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
true if the path is absolute, otherwise false.
Return the number of segments
Synopsis
Declared in <boost/url/segments_base.hpp>
std::size_t
size() const noexcept;Description
Example
assert( url_view( "/path/to/file.txt" ).segments().size() == 3 );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
The number of segments.
Return the maximum number of characters possible
Synopsis
Declared in <boost/url/segments_base.hpp>
constexpr
static
std::size_t
max_size() noexcept;Description
This represents the largest number of characters that are possible in a path, not including any null terminator.
Exception Safety
Throws nothing.
Return Value
The maximum number of characters possible.
Common functionality for containers
Synopsis
Declared in <boost/url/segments_encoded_base.hpp>
class segments_encoded_base;Types
Name |
Description |
A Bidirectional iterator to a path segment |
|
A Bidirectional iterator to a path segment |
|
The reference type |
|
A signed integer type used to represent differences. |
|
The reference type |
|
An unsigned integer type used to represent size. |
|
The value type |
Member Functions
Name |
Description |
Return the last segment |
|
Return an iterator to the beginning |
|
Return the referenced character buffer. |
|
Return true if there are no segments |
|
Return an iterator to the end |
|
Return the first segment |
|
Returns true if this references an absolute path. |
|
Return the number of segments |
Static Member Functions
Name |
Description |
Return the maximum number of characters possible |
Friends
Name |
Description |
A view representing path segments in a URL |
|
A view representing path segments in a URL |
|
Common functionality for containers |
Derived Classes
Name |
Description |
A view representing path segments in a URL |
|
A view representing path segments in a URL |
Description
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:
Containers
-
segments_ref -
segments_view -
segments_encoded_ref -
segments_encoded_view
A Bidirectional iterator to a path segment
Synopsis
Declared in <boost/url/segments_encoded_base.hpp>
using const_iterator = iterator;Description
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 reference type
Synopsis
Declared in <boost/url/segments_encoded_base.hpp>
using const_reference = pct_string_view;Description
This is the type of value returned when iterators of the view are dereferenced.
A signed integer type used to represent differences.
Synopsis
Declared in <boost/url/segments_encoded_base.hpp>
using difference_type = std::ptrdiff_t;The reference type
Synopsis
Declared in <boost/url/segments_encoded_base.hpp>
using reference = pct_string_view;Description
This is the type of value returned when iterators of the view are dereferenced.
An unsigned integer type used to represent size.
Synopsis
Synopsis
Declared in <boost/url/segments_encoded_base.hpp>
using value_type = std::string;Description
Values of this type represent a segment where unique ownership is retained by making a copy.
Example
segments_encoded_base::value_type ps( url_view( "/path/to/file.txt" ).encoded_segments().back() );A Bidirectional iterator to a path segment
Synopsis
Declared in <boost/url/segments_encoded_base.hpp>
class iterator { /* see-below */ };Friends
Name |
Description |
A view representing path segments in a URL |
|
Common functionality for containers |
|
Common functionality for containers |
Description
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.
Return the last segment
Synopsis
Declared in <boost/url/segments_encoded_base.hpp>
pct_string_view
back() const noexcept;Description
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.
Preconditions
this->empty() == falseExample
assert( url_view( "/path/to/file.txt" ).encoded_segments().back() == "file.txt" );Preconditions
this->empty() == falseEffects
return *--end();Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
The last segment.
Return an iterator to the beginning
Synopsis
Declared in <boost/url/segments_encoded_base.hpp>
iterator
begin() const noexcept;Description
Complexity
Linear in this‐>front().size() or constant if this‐>empty().
Exception Safety
Throws nothing.
Return Value
An iterator to the first segment.
Return the referenced character buffer.
Synopsis
Declared in <boost/url/segments_encoded_base.hpp>
pct_string_view
buffer() const noexcept;Description
This function returns the character buffer referenced by the view. The returned string may contain percent escapes.
Example
assert( url_view( "/path/to/file.txt" ).encoded_segments().buffer() == "/path/to/file.txt" );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
A string view of the buffer.
Return true if there are no segments
Synopsis
Declared in <boost/url/segments_encoded_base.hpp>
bool
empty() const noexcept;Description
Example
assert( ! url_view( "/index.htm" ).encoded_segments().empty() );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
true if there are no segments, otherwise false.
Return an iterator to the end
Synopsis
Declared in <boost/url/segments_encoded_base.hpp>
iterator
end() const noexcept;Description
Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
An iterator to one past the last segment.
Return the first segment
Synopsis
Declared in <boost/url/segments_encoded_base.hpp>
pct_string_view
front() const noexcept;Description
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.
Preconditions
this->empty() == falseEffects
return *begin();Example
assert( url_view( "/path/to/file.txt" ).encoded_segments().front() == "path" );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
The first segment.
Returns true if this references an absolute path.
Synopsis
Declared in <boost/url/segments_encoded_base.hpp>
bool
is_absolute() const noexcept;Description
Absolute paths always start with a forward slash ('/').
Example
assert( url_view( "/path/to/file.txt" ).encoded_segments().is_absolute() == true );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
true if the path is absolute, otherwise false.
Return the number of segments
Synopsis
Declared in <boost/url/segments_encoded_base.hpp>
std::size_t
size() const noexcept;Description
Example
assert( url_view( "/path/to/file.txt" ).encoded_segments().size() == 3 );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
The number of segments.
Return the maximum number of characters possible
Synopsis
Declared in <boost/url/segments_encoded_base.hpp>
constexpr
static
std::size_t
max_size() noexcept;Description
This represents the largest number of characters that are possible in a path, not including any null terminator.
Exception Safety
Throws nothing.
Return Value
The maximum number of characters possible.
A view representing path segments in a URL
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
class segments_encoded_ref
: public segments_encoded_baseBase Classes
Name |
Description |
Common functionality for containers |
Types
Name |
Description |
A Bidirectional iterator to a path segment |
|
A Bidirectional iterator to a path segment |
|
The reference type |
|
A signed integer type used to represent differences. |
|
The reference type |
|
An unsigned integer type used to represent size. |
|
The value type |
Member Functions
Name |
Description |
|
Constructor |
Assignment |
|
Assign segments |
|
Return the last segment |
|
Return an iterator to the beginning |
|
Return the referenced character buffer. |
|
Clear the contents of the container |
|
Return true if there are no segments |
|
Return an iterator to the end |
|
Erase segments |
|
Return the first segment |
|
Insert segments |
|
Returns true if this references an absolute path. |
|
Remove the last segment |
|
Append a segment |
|
Replace segments |
|
Return the number of segments |
|
Return the referenced url |
|
Conversion |
Static Member Functions
Name |
Description |
Return the maximum number of characters possible |
Friends
Name |
Description |
Common functionality for containers |
Description
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.
Example
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.
Iterator Invalidation
Changes to the underlying character buffer can invalidate iterators which reference it. Modifications made through the container invalidate some or all iterators:
-
push_back: Onlyend(). -
assign,clear,operator=: All elements. -
erase: Erased elements and all elements after (includingend()). -
insert: All elements at or after the insertion point (includingend()). -
replace: Modified elements and all elements after (includingend()).
See Also
Constructor
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
constexpr
segments_encoded_ref(segments_encoded_ref const& other) = default;Description
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.
Postconditions
&this->url() == &other.url();Complexity
Constant.
Exception Safety
Throws nothing.
Parameters
Name |
Description |
other |
The other view. |
Assignment
Synopses
Declared in <boost/url/segments_encoded_ref.hpp>
Assignment
segments_encoded_ref&
operator=(segments_encoded_ref const& other);Assignment
segments_encoded_ref&
operator=(std::initializer_list<pct_string_view> init);Assignment
segments_encoded_ref&
operator=(segments_encoded_view const& other);Exceptions
Name |
Thrown on |
|
The list contains an invalid percent‐encoding. |
Return Value
-
A reference to this object.
-
A reference to this.
Parameters
Name |
Description |
other |
The segments to assign. |
init |
The list of segments to assign. |
Assignment
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
segments_encoded_ref&
operator=(segments_encoded_ref const& other);Description
The existing contents are replaced by a copy of the other segments.
All iterators are invalidated.
|
Note
|
None of the character buffers referenced by other may overlap the buffer of the underlying url, or else the behavior is undefined.
|
Effects
this->assign( other.begin(), other.end() );Complexity
Linear in other.buffer().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
A reference to this object.
Parameters
Name |
Description |
other |
The segments to assign. |
Assignment
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
segments_encoded_ref&
operator=(std::initializer_list<pct_string_view> init);Description
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.
Example
url u;
u.encoded_segments() = {"path", "to", "file.txt"};Preconditions
None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.
Effects
this->assign( init.begin(), init.end() );Complexity
Linear in init.size() + this‐>url().encoded_query().size() + this‐>url().encoded_fragment().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The list contains an invalid percent‐encoding. |
Return Value
A reference to this.
Parameters
Name |
Description |
init |
The list of segments to assign. |
Assignment
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
segments_encoded_ref&
operator=(segments_encoded_view const& other);Description
The existing contents are replaced by a copy of the other segments.
All iterators are invalidated.
|
Note
|
None of the character buffers referenced by other may overlap the buffer of the underlying url, or else the behavior is undefined.
|
Effects
this->assign( other.begin(), other.end() );Complexity
Linear in other.buffer().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
A reference to this object.
Parameters
Name |
Description |
other |
The segments to assign. |
Assign segments
Synopses
Declared in <boost/url/segments_encoded_ref.hpp>
Assign segments
void
assign(std::initializer_list<pct_string_view> init);Assign segments
template<class FwdIt>
void
assign(
FwdIt first,
FwdIt last);Exceptions
Name |
Thrown on |
|
The list contains an invalid percent‐encoding. |
Parameters
Name |
Description |
init |
The list of segments to assign. |
first |
The first element in the range. |
last |
One past the last element in the range. |
Assign segments
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
void
assign(std::initializer_list<pct_string_view> init);Description
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.
|
Note
|
None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined. |
Example
url u;
u.segments().assign( {"path", "to", "file.txt"} );Complexity
Linear in init.size() + this‐>url().encoded_query().size() + this‐>url().encoded_fragment().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The list contains an invalid percent‐encoding. |
Parameters
Name |
Description |
init |
The list of segments to assign. |
Assign segments
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
template<class FwdIt>
void
assign(
FwdIt first,
FwdIt last);Description
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.
|
Note
|
None of the character buffers referenced by the range may overlap the character buffer of the underlying url, or else the behavior is undefined. |
Mandates
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, pct_string_view >::value == trueComplexity
Linear in std::distance( first, last ) + this‐>url().encoded_query().size() + this‐>url().encoded_fragment().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The range contains an invalid percent‐encoding. |
Parameters
Name |
Description |
first |
The first element in the range. |
last |
One past the last element in the range. |
Clear the contents of the container
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
void
clear() noexcept;Description
All iterators are invalidated.
Effects
this->url().set_encoded_path( "" );Postconditions
this->empty() == trueComplexity
Linear in this‐>url().encoded_query().size() + this‐>url().encoded_fragment().size().
Exception Safety
Throws nothing.
Erase segments
Synopses
Return Value
-
An iterator to one past the removed segment.
-
An iterator to one past the removed range.
Parameters
Name |
Description |
pos |
An iterator to the element. |
first |
The first element in the range to erase. |
last |
One past the last element in the range to erase. |
Erase segments
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
Description
This function removes a segment.
All iterators that are equal to pos or come after are invalidated.
Complexity
Linear in this‐>url().encoded_resource().size().
Exception Safety
Throws nothing.
Return Value
An iterator to one past the removed segment.
Parameters
Name |
Description |
pos |
An iterator to the element. |
Erase segments
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
Description
This function removes a range of segments from the container.
All iterators that are equal to first or come after are invalidated.
Complexity
Linear in this‐>url().encoded_resource().size().
Exception Safety
Throws nothing.
Return Value
An iterator to one past the removed range.
Parameters
Name |
Description |
first |
The first element in the range to erase. |
last |
One past the last element in the range to erase. |
Insert segments
Synopses
Declared in <boost/url/segments_encoded_ref.hpp>
Insert segments
iterator
insert(
iterator before,
pct_string_view s);Insert segments
Insert segments
Exceptions
Name |
Thrown on |
|
The segment contains an invalid percent‐encoding. |
Return Value
-
An iterator to the inserted segment.
-
An iterator to the first element inserted, or
beforeifinit.size() == 0. -
An iterator to the first segment inserted, or
beforeifinit.empty().
Parameters
Name |
Description |
before |
An iterator before which the segment is inserted. This may be equal to |
s |
The segment to insert. |
init |
The list of segments to insert. |
first |
The first element in the range to insert. |
last |
One past the last element in the range to insert. |
Insert segments
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
iterator
insert(
iterator before,
pct_string_view s);Description
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.
Complexity
Linear in s.size() + this‐>url().encoded_resource().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The segment contains an invalid percent‐encoding. |
Return Value
An iterator to the inserted segment.
Parameters
Name |
Description |
before |
An iterator before which the segment is inserted. This may be equal to |
s |
The segment to insert. |
Insert segments
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
Description
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.
|
Note
|
None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined. |
Example
url u( "/file.txt" );
u.encoded_segments().insert( u.encoded_segments().begin(), { "path", "to" } );Complexity
Linear in init.size() + this‐>url().encoded_resource().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The list contains an invalid percent‐encoding. |
Return Value
An iterator to the first element inserted, or before if init.size() == 0.
Parameters
Name |
Description |
before |
An iterator before which the list is inserted. This may be equal to |
init |
The list of segments to insert. |
Insert segments
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
Description
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.
|
Note
|
None of the character buffers referenced by the range may overlap the character buffer of the underlying url, or else the behavior is undefined. |
Mandates
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, pct_string_view >::value == trueComplexity
Linear in std::distance( first, last ) + this‐>url().encoded_resource().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The range contains an invalid percent‐encoding. |
Return Value
An iterator to the first segment inserted, or before if init.empty().
Parameters
Name |
Description |
before |
An iterator before which the range is inserted. This may be equal to |
first |
The first element in the range to insert. |
last |
One past the last element in the range to insert. |
Remove the last segment
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
void
pop_back() noexcept;Description
This function removes the last segment from the container.
Iterators to the last segment as well as all end iterators are invalidated.
Preconditions
!this->empty()Exception Safety
Throws nothing.
Append a segment
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
void
push_back(pct_string_view s);Description
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.
Postconditions
this->back() == sException Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The string contains an invalid percent‐encoding. |
Parameters
Name |
Description |
s |
The segment to append. |
Replace segments
Synopses
Declared in <boost/url/segments_encoded_ref.hpp>
Replace segments
iterator
replace(
iterator pos,
pct_string_view s);Replace segments
iterator
replace(
iterator from,
iterator to,
pct_string_view s);Replace segments
Replace segments
Exceptions
Name |
Thrown on |
|
The string contains an invalid percent‐encoding. |
Return Value
-
An iterator to the replaced segment.
-
An iterator to the new segment.
-
An iterator to the first segment inserted, or one past
toifinit.size() == 0.
Parameters
Name |
Description |
pos |
An iterator to the segment. |
s |
The string to assign. |
from |
The first element in the range of segments to replace. |
to |
One past the last element in the range of segments to replace. |
init |
The list of segments to assign. |
first |
The first element in the new range of segments. |
last |
One past the last element in the new range of segments. |
Replace segments
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
iterator
replace(
iterator pos,
pct_string_view s);Description
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.
Complexity
Linear in s.size() + this‐>url().encoded_resouce().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
An iterator to the replaced segment.
Parameters
Name |
Description |
pos |
An iterator to the segment. |
s |
The string to assign. |
Replace segments
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
iterator
replace(
iterator from,
iterator to,
pct_string_view s);Description
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.
Complexity
Linear in s.size() + this‐>url().encoded_resouce().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The string contains an invalid percent‐encoding. |
Return Value
An iterator to the new segment.
Parameters
Name |
Description |
from |
The first element in the range of segments to replace. |
to |
One past the last element in the range of segments to replace. |
s |
The string to assign. |
Replace segments
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
Description
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.
Preconditions
None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.
Complexity
Linear in init.size() + this‐>url().encoded_resouce().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The list contains an invalid percent‐encoding. |
Return Value
An iterator to the first segment inserted, or one past to if init.size() == 0.
Parameters
Name |
Description |
from |
The first element in the range of segments to replace. |
to |
One past the last element in the range of segments to replace. |
init |
The list of segments to assign. |
Replace segments
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
Description
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.
Preconditions
None of the character buffers referenced by the new range may overlap the character buffer of the underlying url, or else the behavior is undefined.
Complexity
Linear in std::distance( first, last ) + this‐>url().encoded_resouce().size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The range contains an invalid percent‐encoding. |
Return Value
An iterator to the first segment inserted, or one past to if init.size() == 0.
Parameters
Name |
Description |
from |
The first element in the range of segments to replace. |
to |
One past the last element in the range of segments to replace. |
first |
The first element in the new range of segments. |
last |
One past the last element in the new range of segments. |
Return the referenced url
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
url_base&
url() const noexcept;Description
This function returns the url referenced by the view.
Example
url u( "/path/to/file.txt" );
assert( &u.encoded_segments().url() == &u );Exception Safety
Throws nothing.
Return Value
A reference to the url.
Conversion
Synopsis
Declared in <boost/url/segments_encoded_ref.hpp>
operator segments_encoded_view() const noexcept;Return Value
A view of the segments.
See Also
A view representing path segments in a URL
Synopsis
Declared in <boost/url/segments_encoded_view.hpp>
class segments_encoded_view
: public segments_encoded_baseBase Classes
Name |
Description |
Common functionality for containers |
Types
Name |
Description |
A Bidirectional iterator to a path segment |
|
A Bidirectional iterator to a path segment |
|
The reference type |
|
A signed integer type used to represent differences. |
|
The reference type |
|
An unsigned integer type used to represent size. |
|
The value type |
Member Functions
Name |
Description |
|
Constructor |
Assignment |
|
Return the last segment |
|
Return an iterator to the beginning |
|
Return the referenced character buffer. |
|
Return true if there are no segments |
|
Return an iterator to the end |
|
Return the first segment |
|
Returns true if this references an absolute path. |
|
Return the number of segments |
|
Conversion |
Static Member Functions
Name |
Description |
Return the maximum number of characters possible |
Friends
Name |
Description |
Parse a string and return an encoded segment view |
|
A view representing path segments in a URL |
|
Common functionality for containers |
Description
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.
Example
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.
Iterator Invalidation
Changes to the underlying character buffer can invalidate iterators which reference it.
See Also
Constructor
Synopses
Declared in <boost/url/segments_encoded_view.hpp>
Constructor
constexpr
segments_encoded_view() = default;Constructor
constexpr
segments_encoded_view(segments_encoded_view const& other) noexcept = default;Constructor
segments_encoded_view(core::string_view s);Exceptions
Name |
Thrown on |
|
|
Parameters
Name |
Description |
s |
The string to parse. |
Constructor
Synopsis
Declared in <boost/url/segments_encoded_view.hpp>
constexpr
segments_encoded_view() = default;Description
Default‐constructed segments have zero elements.
Example
segments_encoded_view ps;Effects
return segments_encoded_view( "" );Complexity
Constant.
Exception Safety
Throws nothing.
Constructor
Synopsis
Declared in <boost/url/segments_encoded_view.hpp>
constexpr
segments_encoded_view(segments_encoded_view const& other) noexcept = default;Description
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.
Postconditions
this->buffer().data() == other.buffer().data()Complexity
Constant.
Exception Safety
Throws nothing
Parameters
Name |
Description |
other |
The object to copy construct from |
Constructor
Synopsis
Declared in <boost/url/segments_encoded_view.hpp>
segments_encoded_view(core::string_view s);Description
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.
Example
segments_encoded_view ps( "/path/to/file.txt" );Effects
return parse_path( s ).value();Postconditions
this->buffer().data() == s.data()Complexity
Linear in s.
Exception Safety
Exceptions thrown on invalid input.
BNF
path = [ "/" ] [ segment *( "/" segment ) ]
segment = *pcharExceptions
Name |
Thrown on |
|
|
Parameters
Name |
Description |
s |
The string to parse. |
Assignment
Synopsis
Declared in <boost/url/segments_encoded_view.hpp>
constexpr
segments_encoded_view&
operator=(segments_encoded_view const& other) = default;Description
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.
Postconditions
this->buffer().data() == other.buffer().data()Complexity
Constant
Exception Safety
Throws nothing
Return Value
Reference to this object
Parameters
Name |
Description |
other |
The segments to copy. |
Conversion
Synopsis
Declared in <boost/url/segments_encoded_view.hpp>
operator segments_view() const noexcept;Description
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.
Example
segments_view ps = parse_path( "/path/to/file.txt" ).value();Postconditions
segments_view( *this ).buffer().data() == this->buffer().data()Complexity
Constant
Exception Safety
Throws nothing
Return Value
A view of the segments.
A view representing path segments in a URL
Synopsis
Declared in <boost/url/segments_ref.hpp>
class segments_ref
: public segments_baseBase Classes
Name |
Description |
Common functionality for containers |
Types
Name |
Description |
A Bidirectional iterator to a path segment |
|
A Bidirectional iterator to a path segment |
|
The reference type |
|
A signed integer type used to represent differences. |
|
The reference type |
|
An unsigned integer type used to represent size. |
|
The value type |
Member Functions
Name |
Description |
|
Constructor |
Assignment |
|
Assign segments |
|
Return the last segment |
|
Return an iterator to the beginning |
|
Return the referenced character buffer. |
|
Clear the contents of the container |
|
Return true if there are no segments |
|
Return an iterator to the end |
|
Erase segments |
|
Return the first segment |
|
Insert segments |
|
Returns true if this references an absolute path. |
|
Remove the last segment |
|
Append a segment |
|
Replace segments |
|
Return the number of segments |
|
Return the referenced url |
|
Conversion |
Static Member Functions
Name |
Description |
Return the maximum number of characters possible |
Friends
Name |
Description |
A view representing path segments in a URL |
|
Common functionality for containers |
Description
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.
Example
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.
Iterator Invalidation
Changes to the underlying character buffer can invalidate iterators which reference it. Modifications made through the container invalidate some or all iterators:
-
push_back: Onlyend(). -
assign,clear,operator=: All elements. -
erase: Erased elements and all elements after (includingend()). -
insert: All elements at or after the insertion point (includingend()). -
replace: Modified elements and all elements after (includingend()).
See Also
Constructor
Synopsis
Declared in <boost/url/segments_ref.hpp>
constexpr
segments_ref(segments_ref const& other) = default;Description
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.
Postconditions
&this->url() == &other.url();Complexity
Constant.
Exception Safety
Throws nothing.
Parameters
Name |
Description |
other |
The other view. |
Assignment
Synopses
Declared in <boost/url/segments_ref.hpp>
Assignment
segments_ref&
operator=(segments_ref const& other);Assignment
segments_ref&
operator=(std::initializer_list<core::string_view> init);Assignment
segments_ref&
operator=(segments_view const& other);Return Value
A reference to this object.
Parameters
Name |
Description |
other |
The segments to assign. |
init |
The list of segments to assign. |
Assignment
Synopsis
Declared in <boost/url/segments_ref.hpp>
segments_ref&
operator=(segments_ref const& other);Description
The existing contents are replaced by a copy of the other segments.
All iterators are invalidated.
|
Note
|
None of the character buffers referenced by other may overlap the buffer of the underlying url, or else the behavior is undefined.
|
Effects
this->assign( other.begin(), other.end() );Complexity
Linear in other.buffer().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
A reference to this object.
Parameters
Name |
Description |
other |
The segments to assign. |
Assignment
Synopsis
Declared in <boost/url/segments_ref.hpp>
segments_ref&
operator=(std::initializer_list<core::string_view> init);Description
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.
Example
url u;
u.segments() = { "path", "to", "file.txt" };Preconditions
None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.
Effects
this->assign( init.begin(), init.end() );Complexity
Linear in init.size() + this‐>url().encoded_query().size() + this‐>url().encoded_fragment().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
A reference to this object.
Parameters
Name |
Description |
init |
The list of segments to assign. |
Assignment
Synopsis
Declared in <boost/url/segments_ref.hpp>
segments_ref&
operator=(segments_view const& other);Description
The existing contents are replaced by a copy of the other segments.
All iterators are invalidated.
|
Note
|
None of the character buffers referenced by other may overlap the buffer of the underlying url, or else the behavior is undefined.
|
Effects
this->assign( other.begin(), other.end() );Complexity
Linear in other.buffer().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
A reference to this object.
Parameters
Name |
Description |
other |
The segments to assign. |
Assign segments
Synopses
Declared in <boost/url/segments_ref.hpp>
Assign segments
void
assign(std::initializer_list<core::string_view> init);Assign segments
template<class FwdIt>
void
assign(
FwdIt first,
FwdIt last);Parameters
Name |
Description |
init |
The list of segments to assign. |
first |
The beginning of the range of segments to assign. |
last |
The end of the range of segments to assign. |
Assign segments
Synopsis
Declared in <boost/url/segments_ref.hpp>
void
assign(std::initializer_list<core::string_view> init);Description
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.
|
Note
|
None of the character buffers referenced by init may overlap the character buffer of the underlying url, or else the behavior is undefined.
|
Example
url u;
u.segments().assign( { "path", "to", "file.txt" } );Complexity
Linear in init.size() + this‐>url().encoded_query().size() + this‐>url().encoded_fragment().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Parameters
Name |
Description |
init |
The list of segments to assign. |
Assign segments
Synopsis
Declared in <boost/url/segments_ref.hpp>
template<class FwdIt>
void
assign(
FwdIt first,
FwdIt last);Description
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.
|
Note
|
None of the character buffers referenced by the range may overlap the character buffer of the underlying url, or else the behavior is undefined. |
Mandates
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, core::string_view >::value == trueComplexity
Linear in std::distance( first, last ) + this‐>url().encoded_query().size() + this‐>url().encoded_fragment().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Parameters
Name |
Description |
first |
The beginning of the range of segments to assign. |
last |
The end of the range of segments to assign. |
Clear the contents of the container
Synopsis
Declared in <boost/url/segments_ref.hpp>
void
clear() noexcept;Description
All iterators are invalidated.
Effects
this->url().set_encoded_path( "" );Postconditions
this->empty() == trueComplexity
Linear in this‐>url().encoded_query().size() + this‐>url().encoded_fragment().size().
Exception Safety
Throws nothing.
Erase segments
Synopses
Return Value
-
An iterator to one past the removed segment.
-
An iterator to one past the removed range.
Parameters
Name |
Description |
pos |
An iterator to the segment. |
first |
The beginning of the range to remove. |
last |
The end of the range to remove. |
Erase segments
Synopsis
Declared in <boost/url/segments_ref.hpp>
Description
This function removes a segment.
All iterators that are equal to pos or come after are invalidated.
Complexity
Linear in this‐>url().encoded_resource().size().
Exception Safety
Throws nothing.
Return Value
An iterator to one past the removed segment.
Parameters
Name |
Description |
pos |
An iterator to the segment. |
Erase segments
Synopsis
Declared in <boost/url/segments_ref.hpp>
Description
This function removes a range of segments.
All iterators that are equal to first or come after are invalidated.
Complexity
Linear in this‐>url().encoded_resource().size().
Exception Safety
Throws nothing.
Return Value
An iterator to one past the removed range.
Parameters
Name |
Description |
first |
The beginning of the range to remove. |
last |
The end of the range to remove. |
Insert segments
Synopses
Return Value
-
An iterator to the inserted segment.
-
An iterator to the first element inserted, or
beforeifinit.size() == 0. -
An iterator to the first segment inserted, or
beforeifinit.empty().
Parameters
Name |
Description |
before |
An iterator before which the segment is inserted. This may be equal to |
s |
The segment to insert. |
init |
The list of segments to insert. |
first |
The beginning of the range of segments to insert. |
last |
The end of the range of segments to insert. |
Insert segments
Synopsis
Declared in <boost/url/segments_ref.hpp>
Description
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.
Complexity
Linear in s.size() + this‐>url().encoded_resource().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
An iterator to the inserted segment.
Parameters
Name |
Description |
before |
An iterator before which the segment is inserted. This may be equal to |
s |
The segment to insert. |
Insert segments
Synopsis
Declared in <boost/url/segments_ref.hpp>
Description
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.
|
Note
|
None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined. |
Example
url u( "/file.txt" );
u.segments().insert( u.segments().begin(), { "path", "to" } );Complexity
Linear in init.size() + this‐>url().encoded_resource().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
An iterator to the first element inserted, or before if init.size() == 0.
Parameters
Name |
Description |
before |
An iterator before which the list is inserted. This may be equal to |
init |
The list of segments to insert. |
Insert segments
Synopsis
Declared in <boost/url/segments_ref.hpp>
Description
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.
|
Note
|
None of the character buffers referenced by the range may overlap the character buffer of the underlying url, or else the behavior is undefined. |
Mandates
std::is_convertible< std::iterator_traits< FwdIt >::reference_type, core::string_view >::value == trueComplexity
Linear in std::distance( first, last ) + this‐>url().encoded_resource().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
An iterator to the first segment inserted, or before if init.empty().
Parameters
Name |
Description |
before |
An iterator before which the range is inserted. This may be equal to |
first |
The beginning of the range of segments to insert. |
last |
The end of the range of segments to insert. |
Remove the last segment
Synopsis
Declared in <boost/url/segments_ref.hpp>
void
pop_back() noexcept;Description
This function removes the last segment from the container.
Iterators to the last segment as well as all end iterators are invalidated.
Preconditions
not this->empty()Exception Safety
Throws nothing.
Append a segment
Synopsis
Declared in <boost/url/segments_ref.hpp>
void
push_back(core::string_view s);Description
This function appends a segment to the end of the path. Reserved characters in the string are automatically escaped.
All end iterators are invalidated.
Postconditions
this->back() == sException Safety
Strong guarantee. Calls to allocate may throw.
Parameters
Name |
Description |
s |
The segment to append. |
Replace segments
Synopses
Declared in <boost/url/segments_ref.hpp>
Replace segments
Replace segments
Replace segments
Replace segments
Return Value
-
An iterator to the replaced segment.
-
An iterator to the new segment.
-
An iterator to the first segment inserted, or one past
toifinit.size() == 0.
Parameters
Name |
Description |
pos |
An iterator to the segment. |
s |
The string to assign. |
from |
The beginning of the range of segments to replace. |
to |
The end of the range of segments to replace. |
init |
The list of segments to assign. |
first |
The beginning of the range of segments to assign. |
last |
The end of the range of segments to assign. |
Replace segments
Synopsis
Declared in <boost/url/segments_ref.hpp>
Description
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.
Complexity
Linear in s.size() + this‐>url().encoded_resouce().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
An iterator to the replaced segment.
Parameters
Name |
Description |
pos |
An iterator to the segment. |
s |
The string to assign. |
Replace segments
Synopsis
Declared in <boost/url/segments_ref.hpp>
Description
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.
Complexity
Linear in s.size() + this‐>url().encoded_resouce().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
An iterator to the new segment.
Parameters
Name |
Description |
from |
The beginning of the range of segments to replace. |
to |
The end of the range of segments to replace. |
s |
The string to assign. |
Replace segments
Synopsis
Declared in <boost/url/segments_ref.hpp>
Description
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.
Preconditions
None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.
Complexity
Linear in init.size() + this‐>url().encoded_resouce().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
An iterator to the first segment inserted, or one past to if init.size() == 0.
Parameters
Name |
Description |
from |
The beginning of the range of segments to replace. |
to |
The end of the range of segments to replace. |
init |
The list of segments to assign. |
Replace segments
Synopsis
Declared in <boost/url/segments_ref.hpp>
Description
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.
Preconditions
None of the character buffers referenced by the new range may overlap the character buffer of the underlying url, or else the behavior is undefined.
Complexity
Linear in std::distance( first, last ) + this‐>url().encoded_resouce().size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
An iterator to the first segment inserted, or one past to if init.size() == 0.
Parameters
Name |
Description |
from |
The beginning of the range of segments to replace. |
to |
The end of the range of segments to replace. |
first |
The beginning of the range of segments to assign. |
last |
The end of the range of segments to assign. |
Return the referenced url
Synopsis
Declared in <boost/url/segments_ref.hpp>
url_base&
url() const noexcept;Description
This function returns the url referenced by the view.
Example
url u( "/path/to/file.txt" );
assert( &u.segments().url() == &u );Exception Safety
Throws nothing.
Return Value
A reference to the url.
Conversion
Synopsis
Declared in <boost/url/segments_ref.hpp>
operator segments_view() const noexcept;Return Value
A view of the segments.
See Also
A view representing path segments in a URL
Synopsis
Declared in <boost/url/segments_view.hpp>
class segments_view
: public segments_baseBase Classes
Name |
Description |
Common functionality for containers |
Types
Name |
Description |
A Bidirectional iterator to a path segment |
|
A Bidirectional iterator to a path segment |
|
The reference type |
|
A signed integer type used to represent differences. |
|
The reference type |
|
An unsigned integer type used to represent size. |
|
The value type |
Member Functions
Name |
Description |
|
Constructor |
Assignment |
|
Return the last segment |
|
Return an iterator to the beginning |
|
Return the referenced character buffer. |
|
Return true if there are no segments |
|
Return an iterator to the end |
|
Return the first segment |
|
Returns true if this references an absolute path. |
|
Return the number of segments |
Static Member Functions
Name |
Description |
Return the maximum number of characters possible |
Friends
Name |
Description |
A view representing path segments in a URL |
|
A view representing path segments in a URL |
|
Common functionality for containers |
Description
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.
Example
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.
Iterator Invalidation
Changes to the underlying character buffer can invalidate iterators which reference it.
See Also
Constructor
Synopses
Declared in <boost/url/segments_view.hpp>
Constructor
constexpr
segments_view() = default;Constructor
constexpr
segments_view(segments_view const& other) = default;Constructor
segments_view(core::string_view s);Exceptions
Name |
Thrown on |
|
|
Parameters
Name |
Description |
other |
The other view. |
s |
The string to parse. |
Constructor
Synopsis
Declared in <boost/url/segments_view.hpp>
constexpr
segments_view() = default;Description
Default‐constructed segments have zero elements.
Example
segments_view ps;Effects
return segments_view( "" );Complexity
Constant.
Exception Safety
Throws nothing.
Constructor
Synopsis
Declared in <boost/url/segments_view.hpp>
constexpr
segments_view(segments_view const& other) = default;Description
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.
Postconditions
this->buffer().data() == other.buffer().data()Complexity
Constant
Exception Safety
Throws nothing
Parameters
Name |
Description |
other |
The other view. |
Constructor
Synopsis
Declared in <boost/url/segments_view.hpp>
segments_view(core::string_view s);Description
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.
Example
segments_view ps( "/path/to/file.txt" );Effects
return parse_path( s ).value();Postconditions
this->buffer().data() == s.data()Complexity
Linear in s.
Exception Safety
Exceptions thrown on invalid input.
BNF
path = [ "/" ] [ segment *( "/" segment ) ]
segment = *pcharExceptions
Name |
Thrown on |
|
|
Parameters
Name |
Description |
s |
The string to parse. |
Assignment
Synopsis
Declared in <boost/url/segments_view.hpp>
constexpr
segments_view&
operator=(segments_view const& other) = default;Description
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.
Postconditions
this->buffer().data() == other.buffer().data()Complexity
Constant
Exception Safety
Throws nothing
Return Value
A reference to this object.
Parameters
Name |
Description |
other |
The other view. |
A modifiable container for a URL.
Synopsis
Declared in <boost/url/static_url.hpp>
template<std::size_t Capacity>
class static_url
: public static_url_baseBase Classes
Name |
Description |
Common implementation for all static URLs |
Member Functions
Name |
Description |
|
Constructor |
|
Destructor |
Assignment |
|
Return the authority |
|
Return the url string |
|
Return the url as a null‐terminated string |
|
Return the number of characters that can be stored without reallocating |
|
Clear the contents while preserving the capacity |
|
Return the result of comparing this with another url |
|
Return a pointer to the url's character buffer |
|
Return true if the url is empty |
|
Return the authority. |
|
Return the fragment |
|
Return the host |
|
Return the host |
|
Return the host and port |
|
Return the host name |
|
Return the origin |
|
Return the query as a container of parameters |
|
Return the password |
|
Return the path |
|
Return the query |
|
Return the resource |
|
Return the path as a container of segments |
|
Return the target |
|
Return the user |
|
Return the userinfo |
|
Return the IPv6 Zone ID |
|
Return the fragment |
|
Return true if an authority is present |
|
Return true if a fragment is present |
|
Return true if a password is present |
|
Return true if a port is present |
|
Return true if a query is present |
|
Return true a scheme is present |
|
Return true if a userinfo is present |
|
Return the host |
|
Return the host |
|
Return the host IPv4 address |
|
Return the host IPv6 address |
|
Return the host IPvFuture address |
|
Return the host name |
|
Return the host type |
|
Return true if the path is absolute |
|
Normalize the URL components |
|
Normalize the URL authority |
|
Normalize the URL fragment |
|
Normalize the URL path |
|
Normalize the URL query |
|
Normalize the URL scheme |
|
Return the query as a container of parameters |
|
Return the password |
|
Return the path |
|
Return a shared, persistent copy of the url |
|
Return the port |
|
Return the port |
|
Return the query |
|
Remove the authority |
|
Remove the fragment |
|
Remove the origin component |
|
Remove the password |
|
Remove the port |
|
Remove the query |
|
Remove the scheme |
|
Remove the userinfo |
|
Adjust the capacity without changing the size |
|
Resolve a URL reference against this base URL |
|
Return the scheme |
|
Return the scheme |
|
Return the path as a container of segments |
|
Set the authority |
|
Set the fragment. |
|
Set the host |
|
Set the host to an address |
|
Set the host to a name |
|
Set the query params |
|
Set the password. |
|
Set the path. |
|
Set the query |
|
Set the user |
|
Set the userinfo. |
|
Set the zone ID for an IPv6 address (percent‐encoded). |
|
Set the fragment. |
|
Set the host |
|
Set the host to an address |
|
Set the host to an address |
|
Set the host to an address |
|
Set the host to an address |
|
Set the host to a name |
|
Set the query params |
|
Set the password. |
|
Set the path. |
|
Set if the path is absolute |
|
Set the port |
|
Set the port |
|
Set the query |
|
Set the scheme |
|
Set the scheme |
|
Set the user |
|
Set the userinfo |
|
Set the zone ID for an IPv6 address. |
|
Return the number of characters in the url |
|
Return the user |
|
Return the userinfo |
|
Return the IPv6 Zone ID |
|
Return the URL as a core::string_view |
Static Member Functions
Name |
Description |
Return the maximum number of characters possible |
Protected Member Functions
Name |
Description |
Calculate a hash of the url |
Friends
Name |
Description |
|
Non-Member Functions
Name |
Description |
Format arguments into a URL |
|
Format arguments into a URL |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Resolve a URL reference against a base URL |
Description
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.
Example
static_url< 1024 > u( "https://www.example.com" );Invariants
this->capacity() == Capacity + 1Template Parameters
Name |
Description |
Capacity |
The maximum capacity in characters, not including the null terminator. |
Synopses
Declared in <boost/url/static_url.hpp>
Constructor
static_url() noexcept;Constructor
static_url(static_url const& u) noexcept;Constructor
explicit
static_url(core::string_view s);Constructor
static_url(url_view_base const& u);Exceptions
Name |
Thrown on |
|
The input does not contain a valid url. |
Parameters
Name |
Description |
u |
The url to copy. |
s |
The string to parse. |
Constructor
Synopsis
Declared in <boost/url/static_url.hpp>
static_url() noexcept;Description
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.
Example
static_url< 1024 > u;Postconditions
this->empty() == trueComplexity
Constant.
Exception Safety
Throws nothing.
BNF
relative-ref = relative-part [ "?" query ] [ "#" fragment ]Specification
Synopsis
Declared in <boost/url/static_url.hpp>
static_url(static_url const& u) noexcept;Description
The newly constructed object contains a copy of u.
Postconditions
this->buffer() == u.buffer() && this->buffer.data() != u.buffer().data()Complexity
Linear in u.size().
Exception Safety
Throws nothing.
Parameters
Name |
Description |
u |
The url to copy. |
Constructor
Synopsis
Declared in <boost/url/static_url.hpp>
explicit
static_url(core::string_view s);Description
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.
Example
static_url< 1024 > u( "https://www.example.com" );Effects
return static_url( parse_uri_reference( s ).value() );Postconditions
this->buffer().data() != s.data()Complexity
Linear in s.size().
Exception Safety
Exceptions thrown on invalid input.
BNF
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
relative-ref = relative-part [ "?" query ] [ "#" fragment ]Exceptions
Name |
Thrown on |
|
The input does not contain a valid url. |
Parameters
Name |
Description |
s |
The string to parse. |
Constructor
Synopsis
Declared in <boost/url/static_url.hpp>
static_url(url_view_base const& u);Description
The newly constructed object contains a copy of u.
Postconditions
this->buffer() == u.buffer() && this->buffer.data() != u.buffer().data()Complexity
Linear in u.size().
Exception Safety
Exception thrown if capacity exceeded.
Exceptions
Name |
Thrown on |
|
Capacity would be exceeded. |
Parameters
Name |
Description |
u |
The url to copy. |
Destructor
Synopsis
Declared in <boost/url/static_url.hpp>
virtual
~static_url() = default;Description
Any params, segments, iterators, or views which reference this object are invalidated. The underlying character buffer is destroyed, invalidating all references to it.
Assignment
Synopses
Declared in <boost/url/static_url.hpp>
Assignment
static_url&
operator=(static_url const& u) noexcept;Assignment
static_url&
operator=(url_view_base const& u);Exceptions
Name |
Thrown on |
|
Capacity would be exceeded. |
Return Value
A reference to this object.
Parameters
Name |
Description |
u |
The url to copy. |
Assignment
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
operator=(static_url const& u) noexcept;Description
The contents of u are copied and the previous contents of this are discarded. Capacity remains unchanged.
Postconditions
this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()Complexity
Linear in u.size().
Exception Safety
Throws nothing.
Return Value
A reference to this object.
Parameters
Name |
Description |
u |
The url to copy. |
Assignment
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
operator=(url_view_base const& u);Description
The contents of u are copied and the previous contents of this are discarded.
Postconditions
this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()Complexity
Linear in u.size().
Exception Safety
Strong guarantee. Exception thrown if capacity exceeded.
Exceptions
Name |
Thrown on |
|
Capacity would be exceeded. |
Return Value
A reference to this object.
Parameters
Name |
Description |
u |
The url to copy. |
Normalize the URL components
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
normalize();Description
Applies Syntax‐based normalization to all components of the URL.
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Normalize the URL authority
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
normalize_authority();Description
Applies Syntax‐based normalization to the URL authority.
Percent‐encoding triplets are normalized to uppercase letters. Percent‐encoded octets that correspond to unreserved characters are decoded.
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Normalize the URL fragment
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
normalize_fragment();Description
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.
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Normalize the URL path
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
normalize_path();Description
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.
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Normalize the URL query
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
normalize_query();Description
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.
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Normalize the URL scheme
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
normalize_scheme();Description
Applies Syntax‐based normalization to the URL scheme.
The scheme is normalized to lowercase.
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Remove the authority
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
remove_authority();Description
This function removes the authority, which includes the userinfo, host, and a port if present.
Example
assert( url( "http://example.com/echo.cgi" ).remove_authority().buffer() == "http:/echo.cgi" );Postconditions
this->has_authority() == false && this->has_userinfo() == false && this->has_port() == falseComplexity
Linear in this‐>size().
Exception Safety
Throws nothing.
BNF
authority = [ userinfo "@" ] host [ ":" port ]
userinfo = *( unreserved / pct-encoded / sub-delims / ":" )
host = IP-literal / IPv4address / reg-name
port = *DIGITReturn Value
*this
See Also
Remove the fragment
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
remove_fragment() noexcept;Description
This function removes the fragment. An empty fragment is distinct from having no fragment.
Example
assert( url( "?first=john&last=doe#anchor" ).remove_fragment().buffer() == "?first=john&last=doe" );Postconditions
this->has_fragment() == false && this->encoded_fragment() == ""Complexity
Constant.
Exception Safety
Throws nothing.
BNF
fragment = *( pchar / "/" / "?" )Return Value
*this
See Also
Remove the origin component
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
remove_origin();Description
This function removes the origin, which consists of the scheme and authority.
Example
assert( url( "http://www.example.com/index.htm" ).remove_origin().buffer() == "/index.htm" );Postconditions
this->scheme_id() == scheme::none && this->has_authority() == falseComplexity
Linear in this‐>size().
Exception Safety
Throws nothing.
Return Value
*this
Remove the password
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
remove_password() noexcept;Description
This function removes the password from the userinfo if a password exists. If there is no userinfo or no authority, the call has no effect.
|
Note
|
The interpretation of the userinfo as individual user and password components is scheme‐dependent. Transmitting passwords in URLs is deprecated. |
Example
assert( url( "http://user:pass@example.com" ).remove_password().authority().buffer() == "user@example.com" );Postconditions
this->has_password() == false && this->encoded_password().empty() == trueComplexity
Linear in this‐>size().
Exception Safety
Throws nothing.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
See Also
Remove the port
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
remove_port() noexcept;Description
If a port exists, it is removed. The rest of the authority is unchanged.
Example
assert( url( "http://www.example.com:80" ).remove_port().authority().buffer() == "www.example.com" );Postconditions
this->has_port() == false && this->port_number() == 0 && this->port() == ""Complexity
Linear in this‐>size().
Exception Safety
Throws nothing.
BNF
authority = [ userinfo "@" ] host [ ":" port ]
port = *DIGITReturn Value
*this
See Also
Remove the query
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
remove_query() noexcept;Description
If a query is present, it is removed. An empty query is distinct from having no query.
Example
assert( url( "http://www.example.com?id=42" ).remove_query().buffer() == "http://www.example.com" );Postconditions
this->has_query() == false && this->params().empty()Exception Safety
Throws nothing.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Return Value
*this
See Also
Remove the scheme
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
remove_scheme();Description
This function removes the scheme if it is present.
Example
assert( url("http://www.example.com/index.htm" ).remove_scheme().buffer() == "//www.example.com/index.htm" );Postconditions
this->has_scheme() == false && this->scheme_id() == scheme::noneComplexity
Linear in this‐>size().
Exception Safety
Throws nothing.
BNF
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]Return Value
*this
See Also
Remove the userinfo
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
remove_userinfo() noexcept;Description
This function removes the userinfo if present, without removing any authority.
Example
assert( url( "http://user@example.com" ).remove_userinfo().has_userinfo() == false );Postconditions
this->has_userinfo() == false && this->encoded_userinfo().empty == trueComplexity
Linear in this‐>size().
Exception Safety
Throws nothing.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
See Also
Set the authority
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_encoded_authority(pct_string_view s);Description
This function sets the authority to the specified string. The string may contain percent‐escapes.
Example
assert( url().set_encoded_authority( "My%20Computer" ).has_authority() );Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
authority = [ userinfo "@" ] host [ ":" port ]
userinfo = *( unreserved / pct-encoded / sub-delims / ":" )
host = IP-literal / IPv4address / reg-name
port = *DIGITReturn Value
*this
Parameters
Name |
Description |
s |
The authority string to set. |
See Also
Set the fragment.
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_encoded_fragment(pct_string_view s);Description
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.
Example
assert( url("?first=john&last=doe" ).set_encoded_fragment( "john%2Ddoe" ).fragment() == "john-doe" );Postconditions
this->has_fragment() == true && this->fragment() == decode_view( s )Complexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
fragment = *( pchar / "/" / "?" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the host
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_encoded_host(pct_string_view s);Description
Depending on the contents of the passed string, this function sets the host:
-
If the string is a valid IPv4 address, then the host is set to the address. The host type is
host_type::ipv4. -
If the string is a valid IPv6 address enclosed in square brackets, then the host is set to that address. The host type is
host_type::ipv6. -
If the string is a valid IPvFuture address enclosed in square brackets, then the host is set to that address. The host type is
host_type::ipvfuture. -
Otherwise, the host name is set to the string. This string can contain percent escapes, or can be empty. Escapes in the string are preserved, and reserved characters in the string are percent‐escaped in the result. The host type is
host_type::name.
In all cases, when this function returns, the URL contains an authority.
Example
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );Postconditions
this->has_authority() == trueComplexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")Specification
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host_address, set_encoded_host_name, set_host, set_host_address, set_host_ipv4, set_host_ipv6, set_host_ipvfuture, set_host_name.
Set the host to an address
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_encoded_host_address(pct_string_view s);Description
Depending on the contents of the passed string, this function sets the host:
-
If the string is a valid IPv4 address, then the host is set to the address. The host type is
host_type::ipv4. -
If the string is a valid IPv6 address, then the host is set to that address. The host type is
host_type::ipv6. -
If the string is a valid IPvFuture, then the host is set to that address. The host type is
host_type::ipvfuture. -
Otherwise, the host name is set to the string. This string can contain percent escapes, or can be empty. Escapes in the string are preserved, and reserved characters in the string are percent‐escaped in the result. The host type is
host_type::name.
In all cases, when this function returns, the URL contains an authority.
Example
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );Postconditions
this->has_authority() == trueComplexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
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 / "-" / ".")Specification
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host, set_encoded_host_name, set_host, set_host_address, set_host_ipv4, set_host_ipv6, set_host_ipvfuture, set_host_name.
Set the host to a name
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_encoded_host_name(pct_string_view s);Description
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.
Example
assert( url( "http://www.example.com/index.htm").set_encoded_host_name( "localhost" ).host_address() == "localhost" );Postconditions
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::nameException Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
reg-name = *( unreserved / pct-encoded / "-" / ".")Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host, set_encoded_host_address, set_host, set_host_address, set_host_ipv4, set_host_ipv6, set_host_ipvfuture, set_host_name.
Set the password.
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_encoded_password(pct_string_view s);Description
This function sets the password in the userinfo to the string, which may contain percent‐escapes. Escapes in the string are preserved, and reserved characters in the string are percent‐escaped in the result.
|
Note
|
The interpretation of the userinfo as individual user and password components is scheme‐dependent. Transmitting passwords in URLs is deprecated. |
Example
assert( url("http://user@example.com").set_encoded_password( "pass" ).encoded_userinfo() == "user:pass" );Postconditions
this->has_password() == trueException Safety
Strong guarantee. Calls to allocate may throw.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. This string may contain any characters, including nulls. |
See Also
Set the path.
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_encoded_path(pct_string_view s);Description
This function sets the path to the string, which may contain percent‐escapes and can be empty. Escapes in the string are preserved, and reserved characters in the string are percent‐escaped in the result.
|
Note
|
The library may adjust the final result to ensure that no other parts of the url is semantically affected. |
Example
url u( "http://www.example.com" );
u.set_encoded_path( "path/to/file.txt" );
assert( u.encoded_path() == "/path/to/file.txt" );Complexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the query
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_encoded_query(pct_string_view s);Description
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.
Example
assert( url( "http://example.com" ).set_encoded_query( "id=42" ).encoded_query() == "id=42" );Postconditions
this->has_query() == true && this->query() == decode_view( s );Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the user
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_encoded_user(pct_string_view s);Description
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.
Example
assert( url().set_encoded_user("john%20doe").userinfo() == "john doe" );Postconditions
this->has_authority() == true && this->has_userinfo() == trueComplexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the userinfo.
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_encoded_userinfo(pct_string_view s);Description
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:
-
If an unescaped colon exists, the characters up to the colon become the user and the rest of the characters after the colon become the password. In this case
has_passwordreturns true. Otherwise, -
If there is no colon, the user is set to the string. The function
has_passwordreturns false.
|
Note
|
The interpretation of the userinfo as individual user and password components is scheme‐dependent. Transmitting passwords in URLs is deprecated. |
Example
assert( url( "http://example.com" ).set_encoded_userinfo( "john%20doe" ).user() == "john doe" );Complexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the zone ID for an IPv6 address (percent‐encoded).
Synopses
Declared in <boost/url/url_base.hpp>
Set the zone ID for an IPv6 address (percent‐encoded).
Set the zone ID for an IPv6 address (percent‐encoded).
static_url&
set_encoded_zone_id(pct_string_view const& s);Exceptions
Name |
Thrown on |
|
|
Return Value
*this
Parameters
Name |
Description |
s |
The zone ID to set. |
Set the zone ID for an IPv6 address (percent‐encoded).
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_encoded_zone_id(pct_string_view s);Description
This function sets the zone ID for the host if the host is an IPv6 address. Escapes in the string are preserved, and reserved characters in the string are percent‐escaped in the result.
Example
assert( u.set_host_ipv6( ipv6_address( "fe80::1" ) ).set_encoded_zone_id( "eth0" ).buffer() == "https://[fe80::1%25eth0]" );Complexity
Linear in this‐>size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Specification
Exceptions
Name |
Thrown on |
|
|
Return Value
*this
Parameters
Name |
Description |
s |
The zone ID to set. |
Set the zone ID for an IPv6 address (percent‐encoded).
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_encoded_zone_id(pct_string_view const& s);Description
This function sets the zone ID for the host if the host is an IPv6 address. Escapes in the string are preserved, and reserved characters in the string are percent‐escaped in the result.
Example
assert( u.set_host_ipv6( ipv6_address( "fe80::1" ) ).set_encoded_zone_id( "eth0" ).buffer() == "https://[fe80::1%25eth0]" );Complexity
Linear in this‐>size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Specification
Return Value
*this
Parameters
Name |
Description |
s |
The zone ID to set. |
Set the fragment.
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_fragment(core::string_view s);Description
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.
Example
assert( url("?first=john&last=doe" ).set_encoded_fragment( "john doe" ).encoded_fragment() == "john%20doe" );Postconditions
this->has_fragment() == true && this->fragment() == sComplexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
fragment = *( pchar / "/" / "?" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the host
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_host(core::string_view s);Description
Depending on the contents of the passed string, this function sets the host:
-
If the string is a valid IPv4 address, then the host is set to the address. The host type is
host_type::ipv4. -
If the string is a valid IPv6 address enclosed in square brackets, then the host is set to that address. The host type is
host_type::ipv6. -
If the string is a valid IPvFuture address enclosed in square brackets, then the host is set to that address. The host type is
host_type::ipvfuture. -
Otherwise, the host name is set to the string, which may be empty. Reserved characters in the string are percent‐escaped in the result. The host type is
host_type::name.
In all cases, when this function returns, the URL contains an authority.
Example
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );Postconditions
this->has_authority() == trueComplexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")Specification
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host, set_encoded_host_address, set_encoded_host_name, set_host_address, set_host_ipv4, set_host_ipv6, set_host_ipvfuture, set_host_name.
Set the host to an address
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_host_address(core::string_view s);Description
Depending on the contents of the passed string, this function sets the host:
-
If the string is a valid IPv4 address, then the host is set to the address. The host type is
host_type::ipv4. -
If the string is a valid IPv6 address, then the host is set to that address. The host type is
host_type::ipv6. -
If the string is a valid IPvFuture, then the host is set to that address. The host type is
host_type::ipvfuture. -
Otherwise, the host name is set to the string, which may be empty. Reserved characters in the string are percent‐escaped in the result. The host type is
host_type::name.
In all cases, when this function returns, the URL contains an authority.
Example
assert( url( "http://www.example.com" ).set_host_address( "127.0.0.1" ).buffer() == "http://127.0.0.1" );Postconditions
this->has_authority() == trueComplexity
Linear in s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
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 / "-" / ".")Specification
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host, set_encoded_host_address, set_encoded_host_name, set_host, set_host_address, set_host_ipv4, set_host_ipv6, set_host_ipvfuture, set_host_name.
Set the host to an address
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_host_ipv4(ipv4_address const& addr);Description
The host is set to the specified IPv4 address. The host type is host_type::ipv4.
Example
assert( url("http://www.example.com").set_host_ipv4( ipv4_address( "127.0.0.1" ) ).buffer() == "http://127.0.0.1" );Complexity
Linear in this‐>size().
Postconditions
this->has_authority() == true && this->host_ipv4_address() == addr && this->host_type() == host_type::ipv4Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
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-255Specification
Return Value
*this
Parameters
Name |
Description |
addr |
The address to set. |
See Also
set_encoded_host, set_encoded_host_address, set_encoded_host_name, set_host, set_host_address, set_host_ipv6, set_host_ipvfuture, set_host_name.
Set the host to an address
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_host_ipv6(ipv6_address const& addr);Description
The host is set to the specified IPv6 address. The host type is host_type::ipv6.
Example
assert( url().set_host_ipv6( ipv6_address( "1::6:c0a8:1" ) ).authority().buffer() == "[1::6:c0a8:1]" );Postconditions
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::ipv6Complexity
Linear in this‐>size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
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 hexadecimalSpecification
Return Value
*this
Parameters
Name |
Description |
addr |
The address to set. |
See Also
set_encoded_host, set_encoded_host_address, set_encoded_host_name, set_host, set_host_address, set_host_ipv4, set_host_ipvfuture, set_host_name.
Set the host to an address
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_host_ipvfuture(core::string_view s);Description
The host is set to the specified IPvFuture string. The host type is host_type::ipvfuture.
Example
assert( url().set_host_ipvfuture( "v42.bis" ).buffer() == "//[v42.bis]" );Complexity
Linear in this‐>size() + s.size().
Postconditions
this->has_authority() == true && this->host_ipvfuture) == s && this->host_type() == host_type::ipvfutureException Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host, set_encoded_host_address, set_encoded_host_name, set_host, set_host_address, set_host_ipv4, set_host_ipv6, set_host_name.
Set the host to a name
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_host_name(core::string_view s);Description
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.
Example
assert( url( "http://www.example.com/index.htm").set_host_name( "localhost" ).host_address() == "localhost" );Postconditions
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::nameException Safety
Strong guarantee. Calls to allocate may throw.
BNF
reg-name = *( unreserved / pct-encoded / "-" / ".")Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host, set_encoded_host_address, set_encoded_host_name, set_host, set_host_address, set_host_ipv4, set_host_ipv6, set_host_ipvfuture.
Set the query params
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_params(
std::initializer_list<param_view> ps,
encoding_opts opts = {});Description
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.
Example
assert( url( "http://example.com" ).set_params( {"id", "42"} ).query() == "id=42" );Postconditions
this->has_query() == trueException Safety
Strong guarantee. Calls to allocate may throw.
Complexity
Linear.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
-
https://datatracker.ietf.org/doc/html/rfc3986#section-3.4 >3.4. Query (rfc3986)</a> @li <a href=[]
Return Value
*this
Parameters
Name |
Description |
ps |
The params to set. |
opts |
The options for encoding. |
See Also
Set the password.
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_password(core::string_view s);Description
This function sets the password in the userinfo to the string. Reserved characters in the string are percent‐escaped in the result.
|
Note
|
The interpretation of the userinfo as individual user and password components is scheme‐dependent. Transmitting passwords in URLs is deprecated. |
Example
assert( url("http://user@example.com").set_password( "pass" ).encoded_userinfo() == "user:pass" );Postconditions
this->has_password() == true && this->password() == sException Safety
Strong guarantee. Calls to allocate may throw.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. This string may contain any characters, including nulls. |
See Also
Set the path.
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_path(core::string_view s);Description
This function sets the path to the string, which may be empty. Reserved characters in the string are percent‐escaped in the result.
|
Note
|
The library may adjust the final result to ensure that no other parts of the URL are semantically affected. |
|
Note
|
This function does not encode '/' chars, which are unreserved for paths but reserved for path segments. If a path segment should include encoded '/'s to differentiate it from path separators, the functions set_encoded_path or segments should be used instead.
|
Example
url u( "http://www.example.com" );
u.set_path( "path/to/file.txt" );
assert( u.path() == "/path/to/file.txt" );Complexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the port
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_port(core::string_view s);Description
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.
Example
assert( url( "http://www.example.com" ).set_port( "8080" ).authority().buffer() == "www.example.com:8080" );Postconditions
this->has_port() == true && this->port_number() == n && this->port() == std::to_string(n)Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
port = *DIGITReturn Value
*this
Parameters
Name |
Description |
s |
The port string to set. |
See Also
Set the port
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_port_number(uint16_t n);Description
The port is set to the specified integer.
Example
assert( url( "http://www.example.com" ).set_port_number( 8080 ).authority().buffer() == "www.example.com:8080" );Postconditions
this->has_authority() == true && this->has_port() == true && this->port_number() == nComplexity
Linear in this‐>size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
authority = [ userinfo "@" ] host [ ":" port ]
port = *DIGITReturn Value
*this
Parameters
Name |
Description |
n |
The port number to set. |
See Also
Set the query
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_query(core::string_view s);Description
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.
Example
assert( url( "http://example.com" ).set_query( "id=42" ).query() == "id=42" );Postconditions
this->has_query() == true && this->query() == sException Safety
Strong guarantee. Calls to allocate may throw.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the scheme
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_scheme(core::string_view s);Description
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.
Example
assert( url( "http://www.example.com" ).set_scheme( "https" ).scheme_id() == scheme::https );Complexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )Return Value
*this
Parameters
Name |
Description |
s |
The scheme to set. |
See Also
Set the scheme
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_scheme_id(urls::scheme id);Description
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.
Example
assert( url( "http://example.com/echo.cgi" ).set_scheme_id( scheme::wss ).buffer() == "wss://example.com/echo.cgi" );Complexity
Linear in this‐>size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Return Value
*this
Parameters
Name |
Description |
id |
The scheme to set. |
Set the user
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_user(core::string_view s);Description
This function sets the user part of the userinfo to the string. Any special or reserved characters in the string are automatically percent‐encoded.
Example
assert( url().set_user("john doe").encoded_userinfo() == "john%20doe" );Postconditions
this->has_authority() == true && this->has_userinfo() == trueComplexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the userinfo
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_userinfo(core::string_view s);Description
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:
-
If an unescaped colon exists, the characters up to the colon become the user and the rest of the characters after the colon become the password. In this case
has_passwordreturns true. Otherwise, -
If there is no colon, the user is set to the string. The function
has_passwordreturns false.
|
Note
|
The interpretation of the userinfo as individual user and password components is scheme‐dependent. Transmitting passwords in URLs is deprecated. |
Example
assert( url( "http://example.com" ).set_userinfo( "user:pass" ).encoded_user() == "user" );Complexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the zone ID for an IPv6 address.
Synopsis
Declared in <boost/url/static_url.hpp>
static_url&
set_zone_id(core::string_view s);Description
This function sets the zone ID for the host if the host is an IPv6 address. Reserved characters in the string are percent‐escaped in the result.
Example
assert( u.set_host_ipv6( ipv6_address( "fe80::1" ) ).set_zone_id( "eth0" ).buffer() == "https://[fe80::1%25eth0]" );Complexity
Linear in this‐>size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Specification
Return Value
*this
Parameters
Name |
Description |
s |
The zone ID to set. |
Common implementation for all static URLs
Synopsis
Declared in <boost/url/static_url.hpp>
class static_url_base
: public url_baseBase Classes
Name |
Description |
Common functionality for containers |
Member Functions
Name |
Description |
Return the authority |
|
Return the url string |
|
Return the url as a null‐terminated string |
|
Return the number of characters that can be stored without reallocating |
|
Clear the contents while preserving the capacity |
|
Return the result of comparing this with another url |
|
Return a pointer to the url's character buffer |
|
Return true if the url is empty |
|
Return the authority. |
|
Return the fragment |
|
Return the host |
|
Return the host |
|
Return the host and port |
|
Return the host name |
|
Return the origin |
|
Return the query as a container of parameters |
|
Return the password |
|
Return the path |
|
Return the query |
|
Return the resource |
|
Return the path as a container of segments |
|
Return the target |
|
Return the user |
|
Return the userinfo |
|
Return the IPv6 Zone ID |
|
Return the fragment |
|
Return true if an authority is present |
|
Return true if a fragment is present |
|
Return true if a password is present |
|
Return true if a port is present |
|
Return true if a query is present |
|
Return true a scheme is present |
|
Return true if a userinfo is present |
|
Return the host |
|
Return the host |
|
Return the host IPv4 address |
|
Return the host IPv6 address |
|
Return the host IPvFuture address |
|
Return the host name |
|
Return the host type |
|
Return true if the path is absolute |
|
Normalize the URL components |
|
Normalize the URL authority |
|
Normalize the URL fragment |
|
Normalize the URL path |
|
Normalize the URL query |
|
Normalize the URL scheme |
|
Return the query as a container of parameters |
|
Return the password |
|
Return the path |
|
Return a shared, persistent copy of the url |
|
Return the port |
|
Return the port |
|
Return the query |
|
Remove the authority |
|
Remove the fragment |
|
Remove the origin component |
|
Remove the password |
|
Remove the port |
|
Remove the query |
|
Remove the scheme |
|
Remove the userinfo |
|
Adjust the capacity without changing the size |
|
Resolve a URL reference against this base URL |
|
Return the scheme |
|
Return the scheme |
|
Return the path as a container of segments |
|
Set the authority |
|
Set the fragment. |
|
Set the host |
|
Set the host to an address |
|
Set the host to a name |
|
Set the query params |
|
Set the password. |
|
Set the path. |
|
Set the query |
|
Set the user |
|
Set the userinfo. |
|
Set the zone ID for an IPv6 address (percent‐encoded). |
|
Set the fragment. |
|
Set the host |
|
Set the host to an address |
|
Set the host to an address |
|
Set the host to an address |
|
Set the host to an address |
|
Set the host to a name |
|
Set the query params |
|
Set the password. |
|
Set the path. |
|
Set if the path is absolute |
|
Set the port |
|
Set the port |
|
Set the query |
|
Set the scheme |
|
Set the scheme |
|
Set the user |
|
Set the userinfo |
|
Set the zone ID for an IPv6 address. |
|
Return the number of characters in the url |
|
Return the user |
|
Return the userinfo |
|
Return the IPv6 Zone ID |
|
Return the URL as a core::string_view |
Static Member Functions
Name |
Description |
Return the maximum number of characters possible |
Protected Member Functions
Name |
Description |
Calculate a hash of the url |
Friends
Name |
Description |
A modifiable container for a URL. |
Non-Member Functions
Name |
Description |
Format arguments into a URL |
|
Format arguments into a URL |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Resolve a URL reference against a base URL |
Derived Classes
Name |
Description |
A modifiable container for a URL. |
Description
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.
Containers
-
url -
url_view -
static_url
Parsing Functions
-
parse_absolute_uri -
parse_origin_form -
parse_relative_ref -
parse_uri -
parse_uri_reference
A modifiable container for a URL.
Synopsis
Declared in <boost/url/url.hpp>
class url
: public url_baseBase Classes
Name |
Description |
Common functionality for containers |
Member Functions
Name |
Description |
|
Constructor |
|
Destructor |
Assignment |
|
Return the authority |
|
Return the url string |
|
Return the url as a null‐terminated string |
|
Return the number of characters that can be stored without reallocating |
|
Clear the contents while preserving the capacity |
|
Return the result of comparing this with another url |
|
Return a pointer to the url's character buffer |
|
Return true if the url is empty |
|
Return the authority. |
|
Return the fragment |
|
Return the host |
|
Return the host |
|
Return the host and port |
|
Return the host name |
|
Return the origin |
|
Return the query as a container of parameters |
|
Return the password |
|
Return the path |
|
Return the query |
|
Return the resource |
|
Return the path as a container of segments |
|
Return the target |
|
Return the user |
|
Return the userinfo |
|
Return the IPv6 Zone ID |
|
Return the fragment |
|
Return true if an authority is present |
|
Return true if a fragment is present |
|
Return true if a password is present |
|
Return true if a port is present |
|
Return true if a query is present |
|
Return true a scheme is present |
|
Return true if a userinfo is present |
|
Return the host |
|
Return the host |
|
Return the host IPv4 address |
|
Return the host IPv6 address |
|
Return the host IPvFuture address |
|
Return the host name |
|
Return the host type |
|
Return true if the path is absolute |
|
Normalize the URL components |
|
Normalize the URL authority |
|
Normalize the URL fragment |
|
Normalize the URL path |
|
Normalize the URL query |
|
Normalize the URL scheme |
|
Return the query as a container of parameters |
|
Return the password |
|
Return the path |
|
Return a shared, persistent copy of the url |
|
Return the port |
|
Return the port |
|
Return the query |
|
Remove the authority |
|
Remove the fragment |
|
Remove the origin component |
|
Remove the password |
|
Remove the port |
|
Remove the query |
|
Remove the scheme |
|
Remove the userinfo |
|
Adjust the capacity without changing the size |
|
Resolve a URL reference against this base URL |
|
Return the scheme |
|
Return the scheme |
|
Return the path as a container of segments |
|
Set the authority |
|
Set the fragment. |
|
Set the host |
|
Set the host to an address |
|
Set the host to a name |
|
Set the query params |
|
Set the password. |
|
Set the path. |
|
Set the query |
|
Set the user |
|
Set the userinfo. |
|
Set the zone ID for an IPv6 address (percent‐encoded). |
|
Set the fragment. |
|
Set the host |
|
Set the host to an address |
|
Set the host to an address |
|
Set the host to an address |
|
Set the host to an address |
|
Set the host to a name |
|
Set the query params |
|
Set the password. |
|
Set the path. |
|
Set if the path is absolute |
|
Set the port |
|
Set the port |
|
Set the query |
|
Set the scheme |
|
Set the scheme |
|
Set the user |
|
Set the userinfo |
|
Set the zone ID for an IPv6 address. |
|
Return the number of characters in the url |
|
Swap the contents. |
|
Return the user |
|
Return the userinfo |
|
Return the IPv6 Zone ID |
|
Return the URL as a core::string_view |
Static Member Functions
Name |
Description |
Return the maximum number of characters possible |
Protected Member Functions
Name |
Description |
Calculate a hash of the url |
Friends
Name |
Description |
Swap |
|
|
Non-Member Functions
Name |
Description |
Format arguments into a URL |
|
Format arguments into a URL |
|
Format arguments into a URL |
|
Format arguments into a URL |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Resolve a URL reference against a base URL |
Description
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.
Exception Safety
-
Functions marked
noexceptprovide the no‐throw guarantee, otherwise: -
Functions which throw offer the strong exception safety guarantee.
BNF
URI-reference = URI / relative-ref
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
relative-ref = relative-part [ "?" query ] [ "#" fragment ]
absolute-URI = scheme ":" hier-part [ "?" query ]Specification
See Also
Constructor
Synopses
Exceptions
Name |
Thrown on |
|
|
|
The input does not contain a valid url. |
Parameters
Name |
Description |
u |
The url to copy. |
s |
The string to parse. |
Constructor
Synopsis
Declared in <boost/url/url.hpp>
url() noexcept;Description
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.
Example
url u;Postconditions
this->empty() == trueComplexity
Constant.
Exception Safety
Throws nothing.
BNF
relative-ref = relative-part [ "?" query ] [ "#" fragment ]Specification
Synopsis
Declared in <boost/url/url.hpp>
url(url const& u);Description
The newly constructed object contains a copy of u.
Postconditions
this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()Complexity
Linear in u.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Exceptions
Name |
Thrown on |
|
|
Parameters
Name |
Description |
u |
The url to copy. |
Constructor
Synopsis
Declared in <boost/url/url.hpp>
url(url&& u) noexcept;Description
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.
Postconditions
u.empty() == trueComplexity
Constant.
Exception Safety
Throws nothing.
Parameters
Name |
Description |
u |
The url to move from. |
Constructor
Synopsis
Declared in <boost/url/url.hpp>
explicit
url(core::string_view s);Description
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.
Example
url u( "https://www.example.com" );Effects
return url( parse_uri_reference( s ).value() );Postconditions
this->buffer().data() != s.data()Complexity
Linear in s.size().
Exception Safety
Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
relative-ref = relative-part [ "?" query ] [ "#" fragment ]Exceptions
Name |
Thrown on |
|
The input does not contain a valid url. |
Parameters
Name |
Description |
s |
The string to parse. |
Constructor
Synopsis
Declared in <boost/url/url.hpp>
url(url_view_base const& u);Description
The newly constructed object contains a copy of u.
Postconditions
this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()Complexity
Linear in u.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Exceptions
Name |
Thrown on |
|
|
Parameters
Name |
Description |
u |
The url to copy. |
Destructor
Synopsis
Declared in <boost/url/url.hpp>
virtual
~url();Description
Any params, segments, iterators, or views which reference this object are invalidated. The underlying character buffer is destroyed, invalidating all references to it.
Assignment
Synopses
Exceptions
Name |
Thrown on |
|
|
Return Value
A reference to this object.
Parameters
Name |
Description |
u |
The url to copy. |
Assignment
Synopsis
Declared in <boost/url/url.hpp>
Description
The contents of u are copied and the previous contents of this are destroyed. Capacity is preserved, or increases.
Postconditions
this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()Complexity
Linear in u.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
A reference to this object.
Parameters
Name |
Description |
u |
The url to copy. |
Assignment
Synopsis
Declared in <boost/url/url.hpp>
Description
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.
Postconditions
u.empty() == trueComplexity
Constant.
Exception Safety
Throws nothing.
Return Value
A reference to this object.
Parameters
Name |
Description |
u |
The url to assign from. |
Assignment
Synopsis
Declared in <boost/url/url.hpp>
url&
operator=(url_view_base const& u);Description
The contents of u are copied and the previous contents of this are destroyed. Capacity is preserved, or increases.
Postconditions
this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()Complexity
Linear in u.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Exceptions
Name |
Thrown on |
|
|
Return Value
A reference to this object.
Parameters
Name |
Description |
u |
The url to copy. |
Normalize the URL components
Synopsis
Declared in <boost/url/url.hpp>
url&
normalize();Description
Applies Syntax‐based normalization to all components of the URL.
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Normalize the URL authority
Synopsis
Declared in <boost/url/url.hpp>
url&
normalize_authority();Description
Applies Syntax‐based normalization to the URL authority.
Percent‐encoding triplets are normalized to uppercase letters. Percent‐encoded octets that correspond to unreserved characters are decoded.
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Normalize the URL fragment
Synopsis
Declared in <boost/url/url.hpp>
url&
normalize_fragment();Description
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.
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Normalize the URL path
Synopsis
Declared in <boost/url/url.hpp>
url&
normalize_path();Description
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.
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Normalize the URL query
Synopsis
Declared in <boost/url/url.hpp>
url&
normalize_query();Description
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.
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Normalize the URL scheme
Synopsis
Declared in <boost/url/url.hpp>
url&
normalize_scheme();Description
Applies Syntax‐based normalization to the URL scheme.
The scheme is normalized to lowercase.
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Remove the authority
Synopsis
Declared in <boost/url/url.hpp>
url&
remove_authority();Description
This function removes the authority, which includes the userinfo, host, and a port if present.
Example
assert( url( "http://example.com/echo.cgi" ).remove_authority().buffer() == "http:/echo.cgi" );Postconditions
this->has_authority() == false && this->has_userinfo() == false && this->has_port() == falseComplexity
Linear in this‐>size().
Exception Safety
Throws nothing.
BNF
authority = [ userinfo "@" ] host [ ":" port ]
userinfo = *( unreserved / pct-encoded / sub-delims / ":" )
host = IP-literal / IPv4address / reg-name
port = *DIGITReturn Value
*this
See Also
Remove the fragment
Synopsis
Declared in <boost/url/url.hpp>
url&
remove_fragment() noexcept;Description
This function removes the fragment. An empty fragment is distinct from having no fragment.
Example
assert( url( "?first=john&last=doe#anchor" ).remove_fragment().buffer() == "?first=john&last=doe" );Postconditions
this->has_fragment() == false && this->encoded_fragment() == ""Complexity
Constant.
Exception Safety
Throws nothing.
BNF
fragment = *( pchar / "/" / "?" )Return Value
*this
See Also
Remove the origin component
Synopsis
Declared in <boost/url/url.hpp>
url&
remove_origin();Description
This function removes the origin, which consists of the scheme and authority.
Example
assert( url( "http://www.example.com/index.htm" ).remove_origin().buffer() == "/index.htm" );Postconditions
this->scheme_id() == scheme::none && this->has_authority() == falseComplexity
Linear in this‐>size().
Exception Safety
Throws nothing.
Return Value
*this
Remove the password
Synopsis
Declared in <boost/url/url.hpp>
url&
remove_password() noexcept;Description
This function removes the password from the userinfo if a password exists. If there is no userinfo or no authority, the call has no effect.
|
Note
|
The interpretation of the userinfo as individual user and password components is scheme‐dependent. Transmitting passwords in URLs is deprecated. |
Example
assert( url( "http://user:pass@example.com" ).remove_password().authority().buffer() == "user@example.com" );Postconditions
this->has_password() == false && this->encoded_password().empty() == trueComplexity
Linear in this‐>size().
Exception Safety
Throws nothing.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
See Also
Remove the port
Synopsis
Declared in <boost/url/url.hpp>
url&
remove_port() noexcept;Description
If a port exists, it is removed. The rest of the authority is unchanged.
Example
assert( url( "http://www.example.com:80" ).remove_port().authority().buffer() == "www.example.com" );Postconditions
this->has_port() == false && this->port_number() == 0 && this->port() == ""Complexity
Linear in this‐>size().
Exception Safety
Throws nothing.
BNF
authority = [ userinfo "@" ] host [ ":" port ]
port = *DIGITReturn Value
*this
See Also
Remove the query
Synopsis
Declared in <boost/url/url.hpp>
url&
remove_query() noexcept;Description
If a query is present, it is removed. An empty query is distinct from having no query.
Example
assert( url( "http://www.example.com?id=42" ).remove_query().buffer() == "http://www.example.com" );Postconditions
this->has_query() == false && this->params().empty()Exception Safety
Throws nothing.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Return Value
*this
See Also
Remove the scheme
Synopsis
Declared in <boost/url/url.hpp>
url&
remove_scheme();Description
This function removes the scheme if it is present.
Example
assert( url("http://www.example.com/index.htm" ).remove_scheme().buffer() == "//www.example.com/index.htm" );Postconditions
this->has_scheme() == false && this->scheme_id() == scheme::noneComplexity
Linear in this‐>size().
Exception Safety
Throws nothing.
BNF
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]Return Value
*this
See Also
Remove the userinfo
Synopsis
Declared in <boost/url/url.hpp>
url&
remove_userinfo() noexcept;Description
This function removes the userinfo if present, without removing any authority.
Example
assert( url( "http://user@example.com" ).remove_userinfo().has_userinfo() == false );Postconditions
this->has_userinfo() == false && this->encoded_userinfo().empty == trueComplexity
Linear in this‐>size().
Exception Safety
Throws nothing.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
See Also
Set the authority
Synopsis
Declared in <boost/url/url.hpp>
url&
set_encoded_authority(pct_string_view s);Description
This function sets the authority to the specified string. The string may contain percent‐escapes.
Example
assert( url().set_encoded_authority( "My%20Computer" ).has_authority() );Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
authority = [ userinfo "@" ] host [ ":" port ]
userinfo = *( unreserved / pct-encoded / sub-delims / ":" )
host = IP-literal / IPv4address / reg-name
port = *DIGITReturn Value
*this
Parameters
Name |
Description |
s |
The authority string to set. |
See Also
Set the fragment.
Synopsis
Declared in <boost/url/url.hpp>
url&
set_encoded_fragment(pct_string_view s);Description
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.
Example
assert( url("?first=john&last=doe" ).set_encoded_fragment( "john%2Ddoe" ).fragment() == "john-doe" );Postconditions
this->has_fragment() == true && this->fragment() == decode_view( s )Complexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
fragment = *( pchar / "/" / "?" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the host
Synopsis
Declared in <boost/url/url.hpp>
url&
set_encoded_host(pct_string_view s);Description
Depending on the contents of the passed string, this function sets the host:
-
If the string is a valid IPv4 address, then the host is set to the address. The host type is
host_type::ipv4. -
If the string is a valid IPv6 address enclosed in square brackets, then the host is set to that address. The host type is
host_type::ipv6. -
If the string is a valid IPvFuture address enclosed in square brackets, then the host is set to that address. The host type is
host_type::ipvfuture. -
Otherwise, the host name is set to the string. This string can contain percent escapes, or can be empty. Escapes in the string are preserved, and reserved characters in the string are percent‐escaped in the result. The host type is
host_type::name.
In all cases, when this function returns, the URL contains an authority.
Example
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );Postconditions
this->has_authority() == trueComplexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")Specification
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host_address, set_encoded_host_name, set_host, set_host_address, set_host_ipv4, set_host_ipv6, set_host_ipvfuture, set_host_name.
Set the host to an address
Synopsis
Declared in <boost/url/url.hpp>
url&
set_encoded_host_address(pct_string_view s);Description
Depending on the contents of the passed string, this function sets the host:
-
If the string is a valid IPv4 address, then the host is set to the address. The host type is
host_type::ipv4. -
If the string is a valid IPv6 address, then the host is set to that address. The host type is
host_type::ipv6. -
If the string is a valid IPvFuture, then the host is set to that address. The host type is
host_type::ipvfuture. -
Otherwise, the host name is set to the string. This string can contain percent escapes, or can be empty. Escapes in the string are preserved, and reserved characters in the string are percent‐escaped in the result. The host type is
host_type::name.
In all cases, when this function returns, the URL contains an authority.
Example
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );Postconditions
this->has_authority() == trueComplexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
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 / "-" / ".")Specification
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host, set_encoded_host_name, set_host, set_host_address, set_host_ipv4, set_host_ipv6, set_host_ipvfuture, set_host_name.
Set the host to a name
Synopsis
Declared in <boost/url/url.hpp>
url&
set_encoded_host_name(pct_string_view s);Description
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.
Example
assert( url( "http://www.example.com/index.htm").set_encoded_host_name( "localhost" ).host_address() == "localhost" );Postconditions
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::nameException Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
reg-name = *( unreserved / pct-encoded / "-" / ".")Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host, set_encoded_host_address, set_host, set_host_address, set_host_ipv4, set_host_ipv6, set_host_ipvfuture, set_host_name.
Set the query params
Synopsis
Declared in <boost/url/url.hpp>
url&
set_encoded_params(std::initializer_list<param_pct_view> ps);Description
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.
Example
assert( url( "http://example.com" ).set_encoded_params( {"id", "42"} ).encoded_query() == "id=42" );Postconditions
this->has_query() == trueComplexity
Linear.
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Return Value
*this
Parameters
Name |
Description |
ps |
The params to set. |
See Also
Set the password.
Synopsis
Declared in <boost/url/url.hpp>
url&
set_encoded_password(pct_string_view s);Description
This function sets the password in the userinfo to the string, which may contain percent‐escapes. Escapes in the string are preserved, and reserved characters in the string are percent‐escaped in the result.
|
Note
|
The interpretation of the userinfo as individual user and password components is scheme‐dependent. Transmitting passwords in URLs is deprecated. |
Example
assert( url("http://user@example.com").set_encoded_password( "pass" ).encoded_userinfo() == "user:pass" );Postconditions
this->has_password() == trueException Safety
Strong guarantee. Calls to allocate may throw.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. This string may contain any characters, including nulls. |
See Also
Set the path.
Synopsis
Declared in <boost/url/url.hpp>
url&
set_encoded_path(pct_string_view s);Description
This function sets the path to the string, which may contain percent‐escapes and can be empty. Escapes in the string are preserved, and reserved characters in the string are percent‐escaped in the result.
|
Note
|
The library may adjust the final result to ensure that no other parts of the url is semantically affected. |
Example
url u( "http://www.example.com" );
u.set_encoded_path( "path/to/file.txt" );
assert( u.encoded_path() == "/path/to/file.txt" );Complexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the query
Synopsis
Declared in <boost/url/url.hpp>
url&
set_encoded_query(pct_string_view s);Description
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.
Example
assert( url( "http://example.com" ).set_encoded_query( "id=42" ).encoded_query() == "id=42" );Postconditions
this->has_query() == true && this->query() == decode_view( s );Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the user
Synopsis
Declared in <boost/url/url.hpp>
url&
set_encoded_user(pct_string_view s);Description
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.
Example
assert( url().set_encoded_user("john%20doe").userinfo() == "john doe" );Postconditions
this->has_authority() == true && this->has_userinfo() == trueComplexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the userinfo.
Synopsis
Declared in <boost/url/url.hpp>
url&
set_encoded_userinfo(pct_string_view s);Description
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:
-
If an unescaped colon exists, the characters up to the colon become the user and the rest of the characters after the colon become the password. In this case
has_passwordreturns true. Otherwise, -
If there is no colon, the user is set to the string. The function
has_passwordreturns false.
|
Note
|
The interpretation of the userinfo as individual user and password components is scheme‐dependent. Transmitting passwords in URLs is deprecated. |
Example
assert( url( "http://example.com" ).set_encoded_userinfo( "john%20doe" ).user() == "john doe" );Complexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the zone ID for an IPv6 address (percent‐encoded).
Synopses
Declared in <boost/url/url_base.hpp>
Set the zone ID for an IPv6 address (percent‐encoded).
Set the zone ID for an IPv6 address (percent‐encoded).
url&
set_encoded_zone_id(pct_string_view const& s);Exceptions
Name |
Thrown on |
|
|
Return Value
*this
Parameters
Name |
Description |
s |
The zone ID to set. |
Set the zone ID for an IPv6 address (percent‐encoded).
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_encoded_zone_id(pct_string_view s);Description
This function sets the zone ID for the host if the host is an IPv6 address. Escapes in the string are preserved, and reserved characters in the string are percent‐escaped in the result.
Example
assert( u.set_host_ipv6( ipv6_address( "fe80::1" ) ).set_encoded_zone_id( "eth0" ).buffer() == "https://[fe80::1%25eth0]" );Complexity
Linear in this‐>size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Specification
Exceptions
Name |
Thrown on |
|
|
Return Value
*this
Parameters
Name |
Description |
s |
The zone ID to set. |
Set the zone ID for an IPv6 address (percent‐encoded).
Synopsis
Declared in <boost/url/url.hpp>
url&
set_encoded_zone_id(pct_string_view const& s);Description
This function sets the zone ID for the host if the host is an IPv6 address. Escapes in the string are preserved, and reserved characters in the string are percent‐escaped in the result.
Example
assert( u.set_host_ipv6( ipv6_address( "fe80::1" ) ).set_encoded_zone_id( "eth0" ).buffer() == "https://[fe80::1%25eth0]" );Complexity
Linear in this‐>size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Specification
Return Value
*this
Parameters
Name |
Description |
s |
The zone ID to set. |
Set the fragment.
Synopsis
Declared in <boost/url/url.hpp>
url&
set_fragment(core::string_view s);Description
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.
Example
assert( url("?first=john&last=doe" ).set_encoded_fragment( "john doe" ).encoded_fragment() == "john%20doe" );Postconditions
this->has_fragment() == true && this->fragment() == sComplexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
fragment = *( pchar / "/" / "?" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the host
Synopsis
Declared in <boost/url/url.hpp>
url&
set_host(core::string_view s);Description
Depending on the contents of the passed string, this function sets the host:
-
If the string is a valid IPv4 address, then the host is set to the address. The host type is
host_type::ipv4. -
If the string is a valid IPv6 address enclosed in square brackets, then the host is set to that address. The host type is
host_type::ipv6. -
If the string is a valid IPvFuture address enclosed in square brackets, then the host is set to that address. The host type is
host_type::ipvfuture. -
Otherwise, the host name is set to the string, which may be empty. Reserved characters in the string are percent‐escaped in the result. The host type is
host_type::name.
In all cases, when this function returns, the URL contains an authority.
Example
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );Postconditions
this->has_authority() == trueComplexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")Specification
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host, set_encoded_host_address, set_encoded_host_name, set_host_address, set_host_ipv4, set_host_ipv6, set_host_ipvfuture, set_host_name.
Set the host to an address
Synopsis
Declared in <boost/url/url.hpp>
url&
set_host_address(core::string_view s);Description
Depending on the contents of the passed string, this function sets the host:
-
If the string is a valid IPv4 address, then the host is set to the address. The host type is
host_type::ipv4. -
If the string is a valid IPv6 address, then the host is set to that address. The host type is
host_type::ipv6. -
If the string is a valid IPvFuture, then the host is set to that address. The host type is
host_type::ipvfuture. -
Otherwise, the host name is set to the string, which may be empty. Reserved characters in the string are percent‐escaped in the result. The host type is
host_type::name.
In all cases, when this function returns, the URL contains an authority.
Example
assert( url( "http://www.example.com" ).set_host_address( "127.0.0.1" ).buffer() == "http://127.0.0.1" );Postconditions
this->has_authority() == trueComplexity
Linear in s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
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 / "-" / ".")Specification
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host, set_encoded_host_address, set_encoded_host_name, set_host, set_host_address, set_host_ipv4, set_host_ipv6, set_host_ipvfuture, set_host_name.
Set the host to an address
Synopsis
Declared in <boost/url/url.hpp>
url&
set_host_ipv4(ipv4_address const& addr);Description
The host is set to the specified IPv4 address. The host type is host_type::ipv4.
Example
assert( url("http://www.example.com").set_host_ipv4( ipv4_address( "127.0.0.1" ) ).buffer() == "http://127.0.0.1" );Complexity
Linear in this‐>size().
Postconditions
this->has_authority() == true && this->host_ipv4_address() == addr && this->host_type() == host_type::ipv4Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
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-255Specification
Return Value
*this
Parameters
Name |
Description |
addr |
The address to set. |
See Also
set_encoded_host, set_encoded_host_address, set_encoded_host_name, set_host, set_host_address, set_host_ipv6, set_host_ipvfuture, set_host_name.
Set the host to an address
Synopsis
Declared in <boost/url/url.hpp>
url&
set_host_ipv6(ipv6_address const& addr);Description
The host is set to the specified IPv6 address. The host type is host_type::ipv6.
Example
assert( url().set_host_ipv6( ipv6_address( "1::6:c0a8:1" ) ).authority().buffer() == "[1::6:c0a8:1]" );Postconditions
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::ipv6Complexity
Linear in this‐>size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
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 hexadecimalSpecification
Return Value
*this
Parameters
Name |
Description |
addr |
The address to set. |
See Also
set_encoded_host, set_encoded_host_address, set_encoded_host_name, set_host, set_host_address, set_host_ipv4, set_host_ipvfuture, set_host_name.
Set the host to an address
Synopsis
Declared in <boost/url/url.hpp>
url&
set_host_ipvfuture(core::string_view s);Description
The host is set to the specified IPvFuture string. The host type is host_type::ipvfuture.
Example
assert( url().set_host_ipvfuture( "v42.bis" ).buffer() == "//[v42.bis]" );Complexity
Linear in this‐>size() + s.size().
Postconditions
this->has_authority() == true && this->host_ipvfuture) == s && this->host_type() == host_type::ipvfutureException Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host, set_encoded_host_address, set_encoded_host_name, set_host, set_host_address, set_host_ipv4, set_host_ipv6, set_host_name.
Set the host to a name
Synopsis
Declared in <boost/url/url.hpp>
url&
set_host_name(core::string_view s);Description
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.
Example
assert( url( "http://www.example.com/index.htm").set_host_name( "localhost" ).host_address() == "localhost" );Postconditions
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::nameException Safety
Strong guarantee. Calls to allocate may throw.
BNF
reg-name = *( unreserved / pct-encoded / "-" / ".")Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host, set_encoded_host_address, set_encoded_host_name, set_host, set_host_address, set_host_ipv4, set_host_ipv6, set_host_ipvfuture.
Set the query params
Synopsis
Declared in <boost/url/url.hpp>
url&
set_params(
std::initializer_list<param_view> ps,
encoding_opts opts = {});Description
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.
Example
assert( url( "http://example.com" ).set_params( {"id", "42"} ).query() == "id=42" );Postconditions
this->has_query() == trueException Safety
Strong guarantee. Calls to allocate may throw.
Complexity
Linear.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
-
https://datatracker.ietf.org/doc/html/rfc3986#section-3.4 >3.4. Query (rfc3986)</a> @li <a href=[]
Return Value
*this
Parameters
Name |
Description |
ps |
The params to set. |
opts |
The options for encoding. |
See Also
Set the password.
Synopsis
Declared in <boost/url/url.hpp>
url&
set_password(core::string_view s);Description
This function sets the password in the userinfo to the string. Reserved characters in the string are percent‐escaped in the result.
|
Note
|
The interpretation of the userinfo as individual user and password components is scheme‐dependent. Transmitting passwords in URLs is deprecated. |
Example
assert( url("http://user@example.com").set_password( "pass" ).encoded_userinfo() == "user:pass" );Postconditions
this->has_password() == true && this->password() == sException Safety
Strong guarantee. Calls to allocate may throw.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. This string may contain any characters, including nulls. |
See Also
Set the path.
Synopsis
Declared in <boost/url/url.hpp>
url&
set_path(core::string_view s);Description
This function sets the path to the string, which may be empty. Reserved characters in the string are percent‐escaped in the result.
|
Note
|
The library may adjust the final result to ensure that no other parts of the URL are semantically affected. |
|
Note
|
This function does not encode '/' chars, which are unreserved for paths but reserved for path segments. If a path segment should include encoded '/'s to differentiate it from path separators, the functions set_encoded_path or segments should be used instead.
|
Example
url u( "http://www.example.com" );
u.set_path( "path/to/file.txt" );
assert( u.path() == "/path/to/file.txt" );Complexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the port
Synopsis
Declared in <boost/url/url.hpp>
url&
set_port(core::string_view s);Description
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.
Example
assert( url( "http://www.example.com" ).set_port( "8080" ).authority().buffer() == "www.example.com:8080" );Postconditions
this->has_port() == true && this->port_number() == n && this->port() == std::to_string(n)Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
port = *DIGITReturn Value
*this
Parameters
Name |
Description |
s |
The port string to set. |
See Also
Set the port
Synopsis
Declared in <boost/url/url.hpp>
url&
set_port_number(uint16_t n);Description
The port is set to the specified integer.
Example
assert( url( "http://www.example.com" ).set_port_number( 8080 ).authority().buffer() == "www.example.com:8080" );Postconditions
this->has_authority() == true && this->has_port() == true && this->port_number() == nComplexity
Linear in this‐>size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
authority = [ userinfo "@" ] host [ ":" port ]
port = *DIGITReturn Value
*this
Parameters
Name |
Description |
n |
The port number to set. |
See Also
Set the query
Synopsis
Declared in <boost/url/url.hpp>
url&
set_query(core::string_view s);Description
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.
Example
assert( url( "http://example.com" ).set_query( "id=42" ).query() == "id=42" );Postconditions
this->has_query() == true && this->query() == sException Safety
Strong guarantee. Calls to allocate may throw.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the scheme
Synopsis
Declared in <boost/url/url.hpp>
url&
set_scheme(core::string_view s);Description
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.
Example
assert( url( "http://www.example.com" ).set_scheme( "https" ).scheme_id() == scheme::https );Complexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )Return Value
*this
Parameters
Name |
Description |
s |
The scheme to set. |
See Also
Set the scheme
Synopsis
Declared in <boost/url/url.hpp>
url&
set_scheme_id(urls::scheme id);Description
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.
Example
assert( url( "http://example.com/echo.cgi" ).set_scheme_id( scheme::wss ).buffer() == "wss://example.com/echo.cgi" );Complexity
Linear in this‐>size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Return Value
*this
Parameters
Name |
Description |
id |
The scheme to set. |
Set the user
Synopsis
Declared in <boost/url/url.hpp>
url&
set_user(core::string_view s);Description
This function sets the user part of the userinfo to the string. Any special or reserved characters in the string are automatically percent‐encoded.
Example
assert( url().set_user("john doe").encoded_userinfo() == "john%20doe" );Postconditions
this->has_authority() == true && this->has_userinfo() == trueComplexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the userinfo
Synopsis
Declared in <boost/url/url.hpp>
url&
set_userinfo(core::string_view s);Description
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:
-
If an unescaped colon exists, the characters up to the colon become the user and the rest of the characters after the colon become the password. In this case
has_passwordreturns true. Otherwise, -
If there is no colon, the user is set to the string. The function
has_passwordreturns false.
|
Note
|
The interpretation of the userinfo as individual user and password components is scheme‐dependent. Transmitting passwords in URLs is deprecated. |
Example
assert( url( "http://example.com" ).set_userinfo( "user:pass" ).encoded_user() == "user" );Complexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the zone ID for an IPv6 address.
Synopsis
Declared in <boost/url/url.hpp>
url&
set_zone_id(core::string_view s);Description
This function sets the zone ID for the host if the host is an IPv6 address. Reserved characters in the string are percent‐escaped in the result.
Example
assert( u.set_host_ipv6( ipv6_address( "fe80::1" ) ).set_zone_id( "eth0" ).buffer() == "https://[fe80::1%25eth0]" );Complexity
Linear in this‐>size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Specification
Return Value
*this
Parameters
Name |
Description |
s |
The zone ID to set. |
Swap the contents.
Synopsis
Declared in <boost/url/url.hpp>
void
swap(url& other) noexcept;Description
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.
Example
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" );Complexity
Constant
Exception Safety
Throws nothing.
Parameters
Name |
Description |
other |
The object to swap with |
Common functionality for containers
Synopsis
Declared in <boost/url/url_base.hpp>
class url_base
: public url_view_baseBase Classes
Name |
Description |
Common functionality for containers |
Member Functions
Name |
Description |
Return the authority |
|
Return the url string |
|
Return the url as a null‐terminated string |
|
Return the number of characters that can be stored without reallocating |
|
Clear the contents while preserving the capacity |
|
Return the result of comparing this with another url |
|
Return a pointer to the url's character buffer |
|
Return true if the url is empty |
|
Return the authority. |
|
Return the fragment |
|
Return the host |
|
Return the host |
|
Return the host and port |
|
Return the host name |
|
Return the origin |
|
Return the query as a container of parameters |
|
Return the password |
|
Return the path |
|
Return the query |
|
Return the resource |
|
Return the path as a container of segments |
|
Return the target |
|
Return the user |
|
Return the userinfo |
|
Return the IPv6 Zone ID |
|
Return the fragment |
|
Return true if an authority is present |
|
Return true if a fragment is present |
|
Return true if a password is present |
|
Return true if a port is present |
|
Return true if a query is present |
|
Return true a scheme is present |
|
Return true if a userinfo is present |
|
Return the host |
|
Return the host |
|
Return the host IPv4 address |
|
Return the host IPv6 address |
|
Return the host IPvFuture address |
|
Return the host name |
|
Return the host type |
|
Return true if the path is absolute |
|
Normalize the URL components |
|
Normalize the URL authority |
|
Normalize the URL fragment |
|
Normalize the URL path |
|
Normalize the URL query |
|
Normalize the URL scheme |
|
Return the query as a container of parameters |
|
Return the password |
|
Return the path |
|
Return a shared, persistent copy of the url |
|
Return the port |
|
Return the port |
|
Return the query |
|
Remove the authority |
|
Remove the fragment |
|
Remove the origin component |
|
Remove the password |
|
Remove the port |
|
Remove the query |
|
Remove the scheme |
|
Remove the userinfo |
|
Adjust the capacity without changing the size |
|
Resolve a URL reference against this base URL |
|
Return the scheme |
|
Return the scheme |
|
Return the path as a container of segments |
|
Set the authority |
|
Set the fragment. |
|
Set the host |
|
Set the host to an address |
|
Set the host to a name |
|
Set the query params |
|
Set the password. |
|
Set the path. |
|
Set the query |
|
Set the user |
|
Set the userinfo. |
|
Set the zone ID for an IPv6 address (percent‐encoded). |
|
Set the fragment. |
|
Set the host |
|
Set the host to an address |
|
Set the host to an address |
|
Set the host to an address |
|
Set the host to an address |
|
Set the host to a name |
|
Set the query params |
|
Set the password. |
|
Set the path. |
|
Set if the path is absolute |
|
Set the port |
|
Set the port |
|
Set the query |
|
Set the scheme |
|
Set the scheme |
|
Set the user |
|
Set the userinfo |
|
Set the zone ID for an IPv6 address. |
|
Return the number of characters in the url |
|
Return the user |
|
Return the userinfo |
|
Return the IPv6 Zone ID |
|
Return the URL as a core::string_view |
Static Member Functions
Name |
Description |
Return the maximum number of characters possible |
Protected Member Functions
Name |
Description |
Calculate a hash of the url |
Friends
Name |
Description |
Resolve a URL reference against a base URL |
|
A view representing query parameters in a URL |
|
A view representing path segments in a URL |
|
A view representing path segments in a URL |
|
A view representing query parameters in a URL |
|
Common implementation for all static URLs |
|
A modifiable container for a URL. |
Non-Member Functions
Name |
Description |
Format arguments into a URL |
|
Format arguments into a URL |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
Derived Classes
Name |
Description |
Common implementation for all static URLs |
|
A modifiable container for a URL. |
Description
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:
Containers
-
url -
url_view -
static_url
Functions
-
parse_absolute_uri -
parse_origin_form -
parse_relative_ref -
parse_uri -
parse_uri_reference
Return the url as a null‐terminated string
Synopsis
Declared in <boost/url/url_base.hpp>
char const*
c_str() const noexcept;Description
This function returns a pointer to a null terminated string representing the url, which may contain percent escapes.
Example
assert( std::strlen( url( "http://www.example.com" ).c_str() ) == 22 );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
A pointer to a null‐terminated string containing the URL.
Return the number of characters that can be stored without reallocating
Synopsis
Declared in <boost/url/url_base.hpp>
std::size_t
capacity() const noexcept;Description
This does not include the null terminator, which is always present.
Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
*this
Clear the contents while preserving the capacity
Synopsis
Declared in <boost/url/url_base.hpp>
void
clear() noexcept;Description
Postconditions
this->empty() == trueComplexity
Constant.
Exception Safety
No‐throw guarantee.
Return the query as a container of parameters
Synopses
Declared in <boost/url/url_base.hpp>
Return the query as a container of parameters
params_encoded_ref
encoded_params() noexcept;Return the query as a container of parameters
params_encoded_view
encoded_params() const noexcept;Return Value
-
*this -
A bidirectional view of key/value pairs.
See Also
Return the query as a container of parameters
Synopsis
Declared in <boost/url/url_base.hpp>
params_encoded_ref
encoded_params() noexcept;Description
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.
Example
params_encoded_ref pv = url( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_params();Complexity
Constant.
Exception Safety
Throws nothing.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Return Value
*this
See Also
Return the query as a container of parameters
Synopsis
Declared in <boost/url/url_base.hpp>
params_encoded_view
encoded_params() const noexcept;Description
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.
Example
params_encoded_view pv = url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_params();Complexity
Constant.
Exception Safety
Throws nothing.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Return Value
A bidirectional view of key/value pairs.
See Also
Return the path as a container of segments
Synopses
Declared in <boost/url/url_base.hpp>
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;Return Value
-
*this -
A bidirectional view of encoded segments.
See Also
Return the path as a container of segments
Synopsis
Declared in <boost/url/url_base.hpp>
segments_encoded_ref
encoded_segments() noexcept;Description
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.
Example
url u( "http://example.com/path/to/file.txt" );
segments_encoded_ref sv = u.encoded_segments();Complexity
Constant.
Exception Safety
Throws nothing.
BNF
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>Return Value
*this
See Also
Return the path as a container of segments
Synopsis
Declared in <boost/url/url_base.hpp>
segments_encoded_view
encoded_segments() const noexcept;Description
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.
Example
segments_encoded_view sv = url_view( "/path/to/file.txt" ).encoded_segments();Complexity
Constant.
Exception Safety
Throws nothing.
BNF
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>Return Value
A bidirectional view of encoded segments.
See Also
Normalize the URL components
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
normalize();Description
Applies Syntax‐based normalization to all components of the URL.
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Normalize the URL authority
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
normalize_authority();Description
Applies Syntax‐based normalization to the URL authority.
Percent‐encoding triplets are normalized to uppercase letters. Percent‐encoded octets that correspond to unreserved characters are decoded.
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Normalize the URL fragment
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
normalize_fragment();Description
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.
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Normalize the URL path
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
normalize_path();Description
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.
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Normalize the URL query
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
normalize_query();Description
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.
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Normalize the URL scheme
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
normalize_scheme();Description
Applies Syntax‐based normalization to the URL scheme.
The scheme is normalized to lowercase.
Exception Safety
Strong guarantee. Calls to allocate may throw.
Return Value
*this
Return the query as a container of parameters
Synopses
Declared in <boost/url/url_base.hpp>
Return the query as a container of parameters
params_ref
params() noexcept;Return the query as a container of parameters
params_view
params() const noexcept;Return the query as a container of parameters
params_ref
params(encoding_opts opt) noexcept;params_view
params(encoding_opts opt) const noexcept;Return Value
-
*this -
A bidirectional view of key/value pairs.
-
A range of references to the parameters.
Parameters
Name |
Description |
opt |
The options for decoding. If this parameter is omitted, the |
See Also
Return the query as a container of parameters
Synopsis
Declared in <boost/url/url_base.hpp>
params_ref
params() noexcept;Description
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.
Example
params_ref pv = url( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).params();Complexity
Constant.
Exception Safety
Throws nothing.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Return Value
*this
See Also
Return the query as a container of parameters
Synopsis
Declared in <boost/url/url_base.hpp>
params_view
params() const noexcept;Return Value
A bidirectional view of key/value pairs.
See Also
Return the query as a container of parameters
Synopsis
Declared in <boost/url/url_base.hpp>
params_ref
params(encoding_opts opt) noexcept;Description
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.
Example
encoding_opts opt;
opt.space_as_plus = true;
params_ref pv = url( "/sql?id=42&name=jane+doe&page+size=20" ).params(opt);Complexity
Constant.
Exception Safety
Throws nothing.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Return Value
A range of references to the parameters.
Parameters
Name |
Description |
opt |
The options for decoding. If this parameter is omitted, the |
See Also
Synopsis
Declared in <boost/url/url_view_base.hpp>
params_view
params(encoding_opts opt) const noexcept;Remove the authority
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
remove_authority();Description
This function removes the authority, which includes the userinfo, host, and a port if present.
Example
assert( url( "http://example.com/echo.cgi" ).remove_authority().buffer() == "http:/echo.cgi" );Postconditions
this->has_authority() == false && this->has_userinfo() == false && this->has_port() == falseComplexity
Linear in this‐>size().
Exception Safety
Throws nothing.
BNF
authority = [ userinfo "@" ] host [ ":" port ]
userinfo = *( unreserved / pct-encoded / sub-delims / ":" )
host = IP-literal / IPv4address / reg-name
port = *DIGITReturn Value
*this
See Also
Remove the fragment
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
remove_fragment() noexcept;Description
This function removes the fragment. An empty fragment is distinct from having no fragment.
Example
assert( url( "?first=john&last=doe#anchor" ).remove_fragment().buffer() == "?first=john&last=doe" );Postconditions
this->has_fragment() == false && this->encoded_fragment() == ""Complexity
Constant.
Exception Safety
Throws nothing.
BNF
fragment = *( pchar / "/" / "?" )Return Value
*this
See Also
Remove the origin component
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
remove_origin();Description
This function removes the origin, which consists of the scheme and authority.
Example
assert( url( "http://www.example.com/index.htm" ).remove_origin().buffer() == "/index.htm" );Postconditions
this->scheme_id() == scheme::none && this->has_authority() == falseComplexity
Linear in this‐>size().
Exception Safety
Throws nothing.
Return Value
*this
Remove the password
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
remove_password() noexcept;Description
This function removes the password from the userinfo if a password exists. If there is no userinfo or no authority, the call has no effect.
|
Note
|
The interpretation of the userinfo as individual user and password components is scheme‐dependent. Transmitting passwords in URLs is deprecated. |
Example
assert( url( "http://user:pass@example.com" ).remove_password().authority().buffer() == "user@example.com" );Postconditions
this->has_password() == false && this->encoded_password().empty() == trueComplexity
Linear in this‐>size().
Exception Safety
Throws nothing.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
See Also
Remove the port
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
remove_port() noexcept;Description
If a port exists, it is removed. The rest of the authority is unchanged.
Example
assert( url( "http://www.example.com:80" ).remove_port().authority().buffer() == "www.example.com" );Postconditions
this->has_port() == false && this->port_number() == 0 && this->port() == ""Complexity
Linear in this‐>size().
Exception Safety
Throws nothing.
BNF
authority = [ userinfo "@" ] host [ ":" port ]
port = *DIGITReturn Value
*this
See Also
Remove the query
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
remove_query() noexcept;Description
If a query is present, it is removed. An empty query is distinct from having no query.
Example
assert( url( "http://www.example.com?id=42" ).remove_query().buffer() == "http://www.example.com" );Postconditions
this->has_query() == false && this->params().empty()Exception Safety
Throws nothing.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Return Value
*this
See Also
Remove the scheme
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
remove_scheme();Description
This function removes the scheme if it is present.
Example
assert( url("http://www.example.com/index.htm" ).remove_scheme().buffer() == "//www.example.com/index.htm" );Postconditions
this->has_scheme() == false && this->scheme_id() == scheme::noneComplexity
Linear in this‐>size().
Exception Safety
Throws nothing.
BNF
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]Return Value
*this
See Also
Remove the userinfo
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
remove_userinfo() noexcept;Description
This function removes the userinfo if present, without removing any authority.
Example
assert( url( "http://user@example.com" ).remove_userinfo().has_userinfo() == false );Postconditions
this->has_userinfo() == false && this->encoded_userinfo().empty == trueComplexity
Linear in this‐>size().
Exception Safety
Throws nothing.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
See Also
Adjust the capacity without changing the size
Synopsis
Declared in <boost/url/url_base.hpp>
void
reserve(std::size_t n);Description
This function adjusts the capacity of the container in characters, without affecting the current contents. Has no effect if n <= this‐>capacity().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Exceptions
Name |
Thrown on |
|
Allocation failure |
Parameters
Name |
Description |
n |
The capacity in characters, excluding any null terminator. |
Resolve a URL reference against this base URL
Synopsis
Declared in <boost/url/url_base.hpp>
system::result<void>
resolve(url_view_base const& ref);Description
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:
-
Ensure the base URI has at least a scheme
-
Normalizing the reference path
-
Merge base and reference paths
-
Normalize the merged path
This function places the result of the resolution into this URL in place.
If an error occurs, the contents of this URL are unspecified and a boost::system::result with an system::error_code is returned.
|
Note
|
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 https://www.rfc-editor.org/errata/eid4547. |
Example
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" );BNF
absolute-URI = scheme ":" hier-part [ "?" query ]Exception Safety
Basic guarantee. Calls to allocate may throw.
Specification
Return Value
An empty boost::system::result upon success, otherwise an error code if !base.has_scheme().
Parameters
Name |
Description |
ref |
The URL reference to resolve. |
Synopses
Declared in <boost/url/url_base.hpp>
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 Value
-
*this -
A bidirectional view of segments.
See Also
Return the path as a container of segments
Synopsis
Declared in <boost/url/url_base.hpp>
urls::segments_ref
segments() noexcept;Description
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.
Example
url u( "http://example.com/path/to/file.txt" );
segments sv = u.segments();Complexity
Constant.
Exception Safety
Throws nothing.
BNF
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>Return Value
*this
See Also
Return the path as a container of segments
Synopsis
Declared in <boost/url/url_base.hpp>
segments_view
segments() const noexcept;Description
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.
Example
segments_view sv = url_view( "/path/to/file.txt" ).segments();Complexity
Constant.
Exception Safety
Throws nothing.
BNF
path = [ "/" ] segment *( "/" segment )Return Value
A bidirectional view of segments.
See Also
Set the authority
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_encoded_authority(pct_string_view s);Description
This function sets the authority to the specified string. The string may contain percent‐escapes.
Example
assert( url().set_encoded_authority( "My%20Computer" ).has_authority() );Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
authority = [ userinfo "@" ] host [ ":" port ]
userinfo = *( unreserved / pct-encoded / sub-delims / ":" )
host = IP-literal / IPv4address / reg-name
port = *DIGITExceptions
Name |
Thrown on |
|
The string contains an invalid percent‐encoding. |
Return Value
*this
Parameters
Name |
Description |
s |
The authority string to set. |
See Also
Set the fragment.
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_encoded_fragment(pct_string_view s);Description
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.
Example
assert( url("?first=john&last=doe" ).set_encoded_fragment( "john%2Ddoe" ).fragment() == "john-doe" );Postconditions
this->has_fragment() == true && this->fragment() == decode_view( s )Complexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
fragment = *( pchar / "/" / "?" )Exceptions
Name |
Thrown on |
|
|
Return Value
-
*this -
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the host
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_encoded_host(pct_string_view s);Description
Depending on the contents of the passed string, this function sets the host:
-
If the string is a valid IPv4 address, then the host is set to the address. The host type is
host_type::ipv4. -
If the string is a valid IPv6 address enclosed in square brackets, then the host is set to that address. The host type is
host_type::ipv6. -
If the string is a valid IPvFuture address enclosed in square brackets, then the host is set to that address. The host type is
host_type::ipvfuture. -
Otherwise, the host name is set to the string. This string can contain percent escapes, or can be empty. Escapes in the string are preserved, and reserved characters in the string are percent‐escaped in the result. The host type is
host_type::name.
In all cases, when this function returns, the URL contains an authority.
Example
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );Postconditions
this->has_authority() == trueComplexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")Specification
Exceptions
Name |
Thrown on |
|
|
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host_address, set_encoded_host_name, set_host, set_host_address, set_host_ipv4, set_host_ipv6, set_host_ipvfuture, set_host_name.
Set the host to an address
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_encoded_host_address(pct_string_view s);Description
Depending on the contents of the passed string, this function sets the host:
-
If the string is a valid IPv4 address, then the host is set to the address. The host type is
host_type::ipv4. -
If the string is a valid IPv6 address, then the host is set to that address. The host type is
host_type::ipv6. -
If the string is a valid IPvFuture, then the host is set to that address. The host type is
host_type::ipvfuture. -
Otherwise, the host name is set to the string. This string can contain percent escapes, or can be empty. Escapes in the string are preserved, and reserved characters in the string are percent‐escaped in the result. The host type is
host_type::name.
In all cases, when this function returns, the URL contains an authority.
Example
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );Postconditions
this->has_authority() == trueComplexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
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 / "-" / ".")Specification
Exceptions
Name |
Thrown on |
|
|
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host, set_encoded_host_name, set_host, set_host_address, set_host_ipv4, set_host_ipv6, set_host_ipvfuture, set_host_name.
Set the host to a name
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_encoded_host_name(pct_string_view s);Description
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.
Example
assert( url( "http://www.example.com/index.htm").set_encoded_host_name( "localhost" ).host_address() == "localhost" );Postconditions
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::nameException Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
reg-name = *( unreserved / pct-encoded / "-" / ".")Exceptions
Name |
Thrown on |
|
|
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host, set_encoded_host_address, set_host, set_host_address, set_host_ipv4, set_host_ipv6, set_host_ipvfuture, set_host_name.
Set the query params
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_encoded_params(std::initializer_list<param_pct_view> ps) noexcept;Description
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.
Example
assert( url( "http://example.com" ).set_encoded_params( {"id", "42"} ).encoded_query() == "id=42" );Postconditions
this->has_query() == trueComplexity
Linear.
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Exceptions
Name |
Thrown on |
|
some element in |
Return Value
*this
Parameters
Name |
Description |
ps |
The params to set. |
See Also
Set the password.
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_encoded_password(pct_string_view s);Description
This function sets the password in the userinfo to the string, which may contain percent‐escapes. Escapes in the string are preserved, and reserved characters in the string are percent‐escaped in the result.
|
Note
|
The interpretation of the userinfo as individual user and password components is scheme‐dependent. Transmitting passwords in URLs is deprecated. |
Example
assert( url("http://user@example.com").set_encoded_password( "pass" ).encoded_userinfo() == "user:pass" );Postconditions
this->has_password() == trueException Safety
Strong guarantee. Calls to allocate may throw.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Exceptions
Name |
Thrown on |
|
|
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. This string may contain any characters, including nulls. |
See Also
Set the path.
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_encoded_path(pct_string_view s);Description
This function sets the path to the string, which may contain percent‐escapes and can be empty. Escapes in the string are preserved, and reserved characters in the string are percent‐escaped in the result.
|
Note
|
The library may adjust the final result to ensure that no other parts of the url is semantically affected. |
Example
url u( "http://www.example.com" );
u.set_encoded_path( "path/to/file.txt" );
assert( u.encoded_path() == "/path/to/file.txt" );Complexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>Exceptions
Name |
Thrown on |
|
|
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the query
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_encoded_query(pct_string_view s);Description
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.
Example
assert( url( "http://example.com" ).set_encoded_query( "id=42" ).encoded_query() == "id=42" );Postconditions
this->has_query() == true && this->query() == decode_view( s );Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Exceptions
Name |
Thrown on |
|
|
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the user
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_encoded_user(pct_string_view s);Description
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.
Example
assert( url().set_encoded_user("john%20doe").userinfo() == "john doe" );Postconditions
this->has_authority() == true && this->has_userinfo() == trueComplexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Exceptions
Name |
Thrown on |
|
|
Return Value
-
*this -
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the userinfo.
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_encoded_userinfo(pct_string_view s);Description
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:
-
If an unescaped colon exists, the characters up to the colon become the user and the rest of the characters after the colon become the password. In this case
has_passwordreturns true. Otherwise, -
If there is no colon, the user is set to the string. The function
has_passwordreturns false.
|
Note
|
The interpretation of the userinfo as individual user and password components is scheme‐dependent. Transmitting passwords in URLs is deprecated. |
Example
assert( url( "http://example.com" ).set_encoded_userinfo( "john%20doe" ).user() == "john doe" );Complexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Exceptions
Name |
Thrown on |
|
|
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the zone ID for an IPv6 address (percent‐encoded).
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_encoded_zone_id(pct_string_view s);Description
This function sets the zone ID for the host if the host is an IPv6 address. Escapes in the string are preserved, and reserved characters in the string are percent‐escaped in the result.
Example
assert( u.set_host_ipv6( ipv6_address( "fe80::1" ) ).set_encoded_zone_id( "eth0" ).buffer() == "https://[fe80::1%25eth0]" );Complexity
Linear in this‐>size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Specification
Exceptions
Name |
Thrown on |
|
|
Return Value
*this
Parameters
Name |
Description |
s |
The zone ID to set. |
Set the fragment.
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_fragment(core::string_view s);Description
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.
Example
assert( url("?first=john&last=doe" ).set_encoded_fragment( "john doe" ).encoded_fragment() == "john%20doe" );Postconditions
this->has_fragment() == true && this->fragment() == sComplexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
fragment = *( pchar / "/" / "?" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the host
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_host(core::string_view s);Description
Depending on the contents of the passed string, this function sets the host:
-
If the string is a valid IPv4 address, then the host is set to the address. The host type is
host_type::ipv4. -
If the string is a valid IPv6 address enclosed in square brackets, then the host is set to that address. The host type is
host_type::ipv6. -
If the string is a valid IPvFuture address enclosed in square brackets, then the host is set to that address. The host type is
host_type::ipvfuture. -
Otherwise, the host name is set to the string, which may be empty. Reserved characters in the string are percent‐escaped in the result. The host type is
host_type::name.
In all cases, when this function returns, the URL contains an authority.
Example
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );Postconditions
this->has_authority() == trueComplexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")Specification
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host, set_encoded_host_address, set_encoded_host_name, set_host_address, set_host_ipv4, set_host_ipv6, set_host_ipvfuture, set_host_name.
Set the host to an address
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_host_address(core::string_view s);Description
Depending on the contents of the passed string, this function sets the host:
-
If the string is a valid IPv4 address, then the host is set to the address. The host type is
host_type::ipv4. -
If the string is a valid IPv6 address, then the host is set to that address. The host type is
host_type::ipv6. -
If the string is a valid IPvFuture, then the host is set to that address. The host type is
host_type::ipvfuture. -
Otherwise, the host name is set to the string, which may be empty. Reserved characters in the string are percent‐escaped in the result. The host type is
host_type::name.
In all cases, when this function returns, the URL contains an authority.
Example
assert( url( "http://www.example.com" ).set_host_address( "127.0.0.1" ).buffer() == "http://127.0.0.1" );Postconditions
this->has_authority() == trueComplexity
Linear in s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
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 / "-" / ".")Specification
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host, set_encoded_host_address, set_encoded_host_name, set_host, set_host_address, set_host_ipv4, set_host_ipv6, set_host_ipvfuture, set_host_name.
Set the host to an address
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_host_ipv4(ipv4_address const& addr);Description
The host is set to the specified IPv4 address. The host type is host_type::ipv4.
Example
assert( url("http://www.example.com").set_host_ipv4( ipv4_address( "127.0.0.1" ) ).buffer() == "http://127.0.0.1" );Complexity
Linear in this‐>size().
Postconditions
this->has_authority() == true && this->host_ipv4_address() == addr && this->host_type() == host_type::ipv4Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
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-255Specification
Return Value
*this
Parameters
Name |
Description |
addr |
The address to set. |
See Also
set_encoded_host, set_encoded_host_address, set_encoded_host_name, set_host, set_host_address, set_host_ipv6, set_host_ipvfuture, set_host_name.
Set the host to an address
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_host_ipv6(ipv6_address const& addr);Description
The host is set to the specified IPv6 address. The host type is host_type::ipv6.
Example
assert( url().set_host_ipv6( ipv6_address( "1::6:c0a8:1" ) ).authority().buffer() == "[1::6:c0a8:1]" );Postconditions
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::ipv6Complexity
Linear in this‐>size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
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 hexadecimalSpecification
Return Value
*this
Parameters
Name |
Description |
addr |
The address to set. |
See Also
set_encoded_host, set_encoded_host_address, set_encoded_host_name, set_host, set_host_address, set_host_ipv4, set_host_ipvfuture, set_host_name.
Set the host to an address
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_host_ipvfuture(core::string_view s);Description
The host is set to the specified IPvFuture string. The host type is host_type::ipvfuture.
Example
assert( url().set_host_ipvfuture( "v42.bis" ).buffer() == "//[v42.bis]" );Complexity
Linear in this‐>size() + s.size().
Postconditions
this->has_authority() == true && this->host_ipvfuture) == s && this->host_type() == host_type::ipvfutureException Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )Exceptions
Name |
Thrown on |
|
|
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host, set_encoded_host_address, set_encoded_host_name, set_host, set_host_address, set_host_ipv4, set_host_ipv6, set_host_name.
Set the host to a name
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_host_name(core::string_view s);Description
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.
Example
assert( url( "http://www.example.com/index.htm").set_host_name( "localhost" ).host_address() == "localhost" );Postconditions
this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::nameException Safety
Strong guarantee. Calls to allocate may throw.
BNF
reg-name = *( unreserved / pct-encoded / "-" / ".")Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
set_encoded_host, set_encoded_host_address, set_encoded_host_name, set_host, set_host_address, set_host_ipv4, set_host_ipv6, set_host_ipvfuture.
Set the query params
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_params(
std::initializer_list<param_view> ps,
encoding_opts opts = {}) noexcept;Description
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.
Example
assert( url( "http://example.com" ).set_params( {"id", "42"} ).query() == "id=42" );Postconditions
this->has_query() == trueException Safety
Strong guarantee. Calls to allocate may throw.
Complexity
Linear.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
-
https://datatracker.ietf.org/doc/html/rfc3986#section-3.4 >3.4. Query (rfc3986)</a> @li <a href=[]
Return Value
*this
Parameters
Name |
Description |
ps |
The params to set. |
opts |
The options for encoding. |
See Also
Set the password.
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_password(core::string_view s);Description
This function sets the password in the userinfo to the string. Reserved characters in the string are percent‐escaped in the result.
|
Note
|
The interpretation of the userinfo as individual user and password components is scheme‐dependent. Transmitting passwords in URLs is deprecated. |
Example
assert( url("http://user@example.com").set_password( "pass" ).encoded_userinfo() == "user:pass" );Postconditions
this->has_password() == true && this->password() == sException Safety
Strong guarantee. Calls to allocate may throw.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. This string may contain any characters, including nulls. |
See Also
Set the path.
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_path(core::string_view s);Description
This function sets the path to the string, which may be empty. Reserved characters in the string are percent‐escaped in the result.
|
Note
|
The library may adjust the final result to ensure that no other parts of the URL are semantically affected. |
|
Note
|
This function does not encode '/' chars, which are unreserved for paths but reserved for path segments. If a path segment should include encoded '/'s to differentiate it from path separators, the functions set_encoded_path or segments should be used instead.
|
Example
url u( "http://www.example.com" );
u.set_path( "path/to/file.txt" );
assert( u.path() == "/path/to/file.txt" );Complexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set if the path is absolute
Synopsis
Declared in <boost/url/url_base.hpp>
bool
set_path_absolute(bool absolute);Description
This function adjusts the path to make it absolute or not, depending on the parameter.
|
Note
|
If an authority is present, the path is always absolute. In this case, the function has no effect. |
Example
url u( "path/to/file.txt" );
assert( u.set_path_absolute( true ) );
assert( u.buffer() == "/path/to/file.txt" );Postconditions
this->is_path_absolute() == true && this->encoded_path().front() == '/'Complexity
Linear in this‐>size().
BNF
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>Return Value
true on success.
Parameters
Name |
Description |
absolute |
If |
See Also
Set the port
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_port(core::string_view s);Description
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.
Example
assert( url( "http://www.example.com" ).set_port( "8080" ).authority().buffer() == "www.example.com:8080" );Postconditions
this->has_port() == true && this->port_number() == n && this->port() == std::to_string(n)Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
port = *DIGITExceptions
Name |
Thrown on |
|
|
Return Value
*this
Parameters
Name |
Description |
s |
The port string to set. |
See Also
Set the port
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_port_number(uint16_t n);Description
The port is set to the specified integer.
Example
assert( url( "http://www.example.com" ).set_port_number( 8080 ).authority().buffer() == "www.example.com:8080" );Postconditions
this->has_authority() == true && this->has_port() == true && this->port_number() == nComplexity
Linear in this‐>size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
authority = [ userinfo "@" ] host [ ":" port ]
port = *DIGITReturn Value
*this
Parameters
Name |
Description |
n |
The port number to set. |
See Also
Set the query
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_query(core::string_view s);Description
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.
Example
assert( url( "http://example.com" ).set_query( "id=42" ).query() == "id=42" );Postconditions
this->has_query() == true && this->query() == sException Safety
Strong guarantee. Calls to allocate may throw.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the scheme
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_scheme(core::string_view s);Description
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.
Example
assert( url( "http://www.example.com" ).set_scheme( "https" ).scheme_id() == scheme::https );Complexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
BNF
scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )Exceptions
Name |
Thrown on |
|
|
Return Value
*this
Parameters
Name |
Description |
s |
The scheme to set. |
See Also
Set the scheme
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_scheme_id(urls::scheme id);Description
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.
Example
assert( url( "http://example.com/echo.cgi" ).set_scheme_id( scheme::wss ).buffer() == "wss://example.com/echo.cgi" );Complexity
Linear in this‐>size().
Exception Safety
Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.
Exceptions
Name |
Thrown on |
|
The scheme is invalid. |
Return Value
*this
Parameters
Name |
Description |
id |
The scheme to set. |
Set the user
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_user(core::string_view s);Description
This function sets the user part of the userinfo to the string. Any special or reserved characters in the string are automatically percent‐encoded.
Example
assert( url().set_user("john doe").encoded_userinfo() == "john%20doe" );Postconditions
this->has_authority() == true && this->has_userinfo() == trueComplexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the userinfo
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_userinfo(core::string_view s);Description
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:
-
If an unescaped colon exists, the characters up to the colon become the user and the rest of the characters after the colon become the password. In this case
has_passwordreturns true. Otherwise, -
If there is no colon, the user is set to the string. The function
has_passwordreturns false.
|
Note
|
The interpretation of the userinfo as individual user and password components is scheme‐dependent. Transmitting passwords in URLs is deprecated. |
Example
assert( url( "http://example.com" ).set_userinfo( "user:pass" ).encoded_user() == "user" );Complexity
Linear in this‐>size() + s.size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
BNF
userinfo = [ [ user ] [ ':' password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
*this
Parameters
Name |
Description |
s |
The string to set. |
See Also
Set the zone ID for an IPv6 address.
Synopsis
Declared in <boost/url/url_base.hpp>
url_base&
set_zone_id(core::string_view s);Description
This function sets the zone ID for the host if the host is an IPv6 address. Reserved characters in the string are percent‐escaped in the result.
Example
assert( u.set_host_ipv6( ipv6_address( "fe80::1" ) ).set_zone_id( "eth0" ).buffer() == "https://[fe80::1%25eth0]" );Complexity
Linear in this‐>size().
Exception Safety
Strong guarantee. Calls to allocate may throw.
Specification
Return Value
*this
Parameters
Name |
Description |
s |
The zone ID to set. |
A non‐owning reference to a valid URL
Synopsis
Declared in <boost/url/url_view.hpp>
class url_view
: public url_view_baseBase Classes
Name |
Description |
Common functionality for containers |
Member Functions
Name |
Description |
|
Constructor |
|
Destructor |
Assignment |
|
Return the authority |
|
Return the url string |
|
Return the result of comparing this with another url |
|
Return a pointer to the url's character buffer |
|
Return true if the url is empty |
|
Return the authority. |
|
Return the fragment |
|
Return the host |
|
Return the host |
|
Return the host and port |
|
Return the host name |
|
Return the origin |
|
Return the query as a container of parameters |
|
Return the password |
|
Return the path |
|
Return the query |
|
Return the resource |
|
Return the path as a container of segments |
|
Return the target |
|
Return the user |
|
Return the userinfo |
|
Return the IPv6 Zone ID |
|
Return the fragment |
|
Return true if an authority is present |
|
Return true if a fragment is present |
|
Return true if a password is present |
|
Return true if a port is present |
|
Return true if a query is present |
|
Return true a scheme is present |
|
Return true if a userinfo is present |
|
Return the host |
|
Return the host |
|
Return the host IPv4 address |
|
Return the host IPv6 address |
|
Return the host IPvFuture address |
|
Return the host name |
|
Return the host type |
|
Return true if the path is absolute |
|
Return the query as a container of parameters |
|
Return the password |
|
Return the path |
|
Return a shared, persistent copy of the url |
|
Return the port |
|
Return the port |
|
Return the query |
|
Return the scheme |
|
Return the scheme |
|
Return the path as a container of segments |
|
Return the number of characters in the url |
|
Return the user |
|
Return the userinfo |
|
Return the IPv6 Zone ID |
|
Return the URL as a core::string_view |
Static Member Functions
Name |
Description |
Return the maximum number of characters possible |
Protected Member Functions
Name |
Description |
Calculate a hash of the url |
Friends
Name |
Description |
Common functionality for containers |
|
Common functionality for query parameter containers |
|
Common functionality for containers |
|
|
Non-Member Functions
Name |
Description |
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return a reference to a parsed URL string |
|
Return a reference to a parsed URL string |
|
Return a reference to a parsed URL string |
|
Return a reference to a parsed URL string |
|
Return a reference to a parsed URL string |
|
Resolve a URL reference against a base URL |
Description
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.
Example 1
Construction from a string parses the input 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" );Example 2
Parsing functions like parse_uri_reference return a boost::system::result containing either a valid url_view upon success, 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" );BNF
URI-reference = URI / relative-ref
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
relative-ref = relative-part [ "?" query ] [ "#" fragment ]Specification
See Also
Constructor
Synopses
Declared in <boost/url/url_view.hpp>
Constructor
url_view() noexcept;Constructor
Constructor
url_view(core::string_view s);Constructor
url_view(url_view_base const& other) noexcept;Constructor
template<class String>
requires std::is_convertible<
String,
core::string_view
>::value &&
!std::is_convertible<
String*,
url_view_base*
>::value
url_view(String const& s);Exceptions
Name |
Thrown on |
|
The input failed to parse correctly. |
Parameters
Name |
Description |
other |
The other view. |
s |
The string to parse. |
See Also
Constructor
Synopsis
Declared in <boost/url/url_view.hpp>
url_view() noexcept;Description
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.
Example
url_view u;Postconditions
this->empty() == trueComplexity
Constant.
Exception Safety
Throws nothing.
BNF
relative-ref = relative-part [ "?" query ] [ "#" fragment ]Specification
Synopsis
Declared in <boost/url/url_view.hpp>
url_view(url_view const& other) noexcept;Description
After construction, both views reference the same underlying character buffer. Ownership is not transferred.
Postconditions
this->buffer().data() == other.buffer().data()Complexity
Constant.
Exception Safety
Throws nothing.
Parameters
Name |
Description |
other |
The other view. |
Constructor
Synopsis
Declared in <boost/url/url_view.hpp>
url_view(core::string_view s);Description
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.
Example
url_view u( "http://www.example.com/index.htm" );Effects
return parse_uri_reference( s ).value();Complexity
Linear in s.size().
Exception Safety
Exceptions thrown on invalid input.
BNF
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
relative-ref = relative-part [ "?" query ] [ "#" fragment ]Exceptions
Name |
Thrown on |
|
The input failed to parse correctly. |
Parameters
Name |
Description |
s |
The string to parse. |
See Also
Constructor
Synopsis
Declared in <boost/url/url_view.hpp>
url_view(url_view_base const& other) noexcept;Description
After construction, both views reference the same underlying character buffer. Ownership is not transferred.
Postconditions
this->buffer().data() == other.buffer().data()Complexity
Constant.
Exception Safety
Throws nothing.
Parameters
Name |
Description |
other |
The other view. |
Constructor
Synopsis
Declared in <boost/url/url_view.hpp>
template<class String>
requires std::is_convertible<
String,
core::string_view
>::value &&
!std::is_convertible<
String*,
url_view_base*
>::value
url_view(String const& s);Description
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.
Example
url_view u( "http://www.example.com/index.htm" );Effects
return parse_uri_reference( s ).value();Complexity
Linear in s.size().
Exception Safety
Exceptions thrown on invalid input.
BNF
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
relative-ref = relative-part [ "?" query ] [ "#" fragment ]Parameters
Name |
Description |
s |
The string to parse. |
See Also
Destructor
Synopsis
Declared in <boost/url/url_view.hpp>
constexpr
~url_view() = default;Description
Any params, segments, iterators, or other views which reference the same underlying character buffer remain valid.
Assignment
Synopses
Declared in <boost/url/url_view.hpp>
Assignment
Assignment
url_view&
operator=(url_view_base const& other) noexcept;Return Value
A reference to this object.
Parameters
Name |
Description |
other |
The other view. |
Assignment
Synopsis
Declared in <boost/url/url_view.hpp>
Description
After assignment, both views reference the same underlying character buffer. Ownership is not transferred.
Postconditions
this->buffer().data() == other.buffer().data()Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
A reference to this object.
Parameters
Name |
Description |
other |
The other view. |
Assignment
Synopsis
Declared in <boost/url/url_view.hpp>
url_view&
operator=(url_view_base const& other) noexcept;Description
After assignment, both views reference the same underlying character buffer. Ownership is not transferred.
Postconditions
this->buffer().data() == other.buffer().data()Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
A reference to this object.
Parameters
Name |
Description |
other |
The other view. |
Return the maximum number of characters possible
Synopsis
Declared in <boost/url/url_view.hpp>
constexpr
static
std::size_t
max_size() noexcept;Description
This represents the largest number of characters that are possible in a url, not including any null terminator.
Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
The maximum number of characters possible.
Common functionality for containers
Synopsis
Declared in <boost/url/url_view_base.hpp>
class url_view_base;Member Functions
Name |
Description |
Return the authority |
|
Return the url string |
|
Return the result of comparing this with another url |
|
Return a pointer to the url's character buffer |
|
Return true if the url is empty |
|
Return the authority. |
|
Return the fragment |
|
Return the host |
|
Return the host |
|
Return the host and port |
|
Return the host name |
|
Return the origin |
|
Return the query as a container of parameters |
|
Return the password |
|
Return the path |
|
Return the query |
|
Return the resource |
|
Return the path as a container of segments |
|
Return the target |
|
Return the user |
|
Return the userinfo |
|
Return the IPv6 Zone ID |
|
Return the fragment |
|
Return true if an authority is present |
|
Return true if a fragment is present |
|
Return true if a password is present |
|
Return true if a port is present |
|
Return true if a query is present |
|
Return true a scheme is present |
|
Return true if a userinfo is present |
|
Return the host |
|
Return the host |
|
Return the host IPv4 address |
|
Return the host IPv6 address |
|
Return the host IPvFuture address |
|
Return the host name |
|
Return the host type |
|
Return true if the path is absolute |
|
Return the query as a container of parameters |
|
Return the password |
|
Return the path |
|
Return a shared, persistent copy of the url |
|
Return the port |
|
Return the port |
|
Return the query |
|
Return the scheme |
|
Return the scheme |
|
Return the path as a container of segments |
|
Return the number of characters in the url |
|
Return the user |
|
Return the userinfo |
|
Return the IPv6 Zone ID |
|
Return the URL as a core::string_view |
Static Member Functions
Name |
Description |
Return the maximum number of characters possible |
Protected Member Functions
Name |
Description |
Calculate a hash of the url |
Friends
Name |
Description |
Format the url to the output stream |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
Return the result of comparing two URLs |
|
A view representing path segments in a URL |
|
A view representing path segments in a URL |
|
A view representing path segments in a URL |
|
A view representing path segments in a URL |
|
Common functionality for containers |
|
Common functionality for containers |
|
A view representing query parameters in a URL |
|
A view representing query parameters in a URL |
|
A view representing query parameters in a URL |
|
A view representing query parameters in a URL |
|
Common functionality for containers |
|
Common functionality for query parameter containers |
|
Common implementation for all static URLs |
|
A non‐owning reference to a valid URL |
|
Common functionality for containers |
|
A modifiable container for a URL. |
Non-Member Functions
Name |
Description |
Resolve a URL reference against a base URL |
Derived Classes
Description
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:
Containers
-
url -
url_view -
static_url
Functions
-
parse_absolute_uri -
parse_origin_form -
parse_relative_ref -
parse_uri -
parse_uri_reference
Return the authority
Synopsis
Declared in <boost/url/url_view_base.hpp>
authority_view
authority() const noexcept;Description
This function returns the authority as an authority_view.
Example
authority_view a = url_view( "https://www.example.com:8080/index.htm" ).authority();Complexity
Constant.
Exception Safety
Throws nothing.
BNF
authority = [ userinfo "@" ] host [ ":" port ]Return Value
An authority_view representing the authority.
See Also
Return the url string
Synopsis
Declared in <boost/url/url_view_base.hpp>
core::string_view
buffer() const noexcept;Description
This function returns the entire url, which may contain percent escapes.
Example
assert( url_view( "http://www.example.com" ).buffer() == "http://www.example.com" );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
The url as a string.
Return the result of comparing this with another url
Synopsis
Declared in <boost/url/url_view_base.hpp>
int
compare(url_view_base const& other) const noexcept;Description
This function compares two URLs according to Syntax‐Based comparison algorithm.
Complexity
Linear in min( u0.size(), u1.size() )
Exception Safety
Throws nothing.
Return Value
‐1 if *this < other, 0 if this == other, and 1 if this > other.
Parameters
Name |
Description |
other |
The url to compare |
Return a pointer to the url's character buffer
Synopsis
Declared in <boost/url/url_view_base.hpp>
char const*
data() const noexcept;Description
This function returns a pointer to the first character of the url, which is not guaranteed to be null‐terminated.
Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
A pointer to the first character.
Return true if the url is empty
Synopsis
Declared in <boost/url/url_view_base.hpp>
bool
empty() const noexcept;Description
The empty string matches the relative‐ref grammar.
Example
assert( url_view( "" ).empty() );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
relative-ref = relative-part [ "?" query ] [ "#" fragment ]
relative-part = "//" authority path-abempty
/ path-absolute
/ path-noscheme
/ path-emptyReturn Value
true if the url is empty.
Return the authority.
Synopsis
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_authority() const noexcept;Description
If present, this function returns a string representing the authority (which may be empty). Otherwise it returns an empty string. The returned string may contain percent escapes.
Example
assert( url_view( "file://Network%20Drive/My%2DFiles" ).encoded_authority() == "Network%20Drive" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
authority = [ userinfo "@" ] host [ ":" port ]Return Value
The authority as a string.
See Also
Return the fragment
Synopsis
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_fragment() const noexcept;Description
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.
Example
assert( url_view( "http://www.example.com/index.htm#a%2D1" ).encoded_fragment() == "a%2D1" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
fragment = *( pchar / "/" / "?" )
pchar = unreserved / pct-encoded / sub-delims / ":" / "@"Return Value
The fragment portion of the url.
See Also
Return the host
Synopsis
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_host() const noexcept;Description
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.
Example
assert( url_view( "https://www%2droot.example.com/" ).encoded_host() == "www%2droot.example.com" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")Return Value
The host address as a string.
Return the host
Synopsis
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_host_address() const noexcept;Description
The value returned by this function depends on the type of host returned from the function host_type.
-
If the type is
host_type::ipv4, then the IPv4 address string is returned. -
If the type is
host_type::ipv6, then the IPv6 address string is returned, without any enclosing brackets. -
If the type is
host_type::ipvfuture, then the IPvFuture address string is returned, without any enclosing brackets. -
If the type is
host_type::name, then the host name string is returned. Any percent‐escapes in the string are decoded first. -
If the type is
host_type::none, then an empty string is returned. The returned string may contain percent escapes.
Example
assert( url_view( "https://www%2droot.example.com/" ).encoded_host_address() == "www%2droot.example.com" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")Return Value
The host address as a string.
Return the host and port
Synopsis
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_host_and_port() const noexcept;Description
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.
Example
assert( url_view( "http://www.example.com:8080/index.htm" ).encoded_host_and_port() == "www.example.com:8080" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
authority = [ userinfo "@" ] host [ ":" port ]Specification
Return Value
The host and port portion of the url.
See Also
Return the host name
Synopsis
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_host_name() const noexcept;Description
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.
Example
assert( url_view( "https://www%2droot.example.com/" ).encoded_host_name() == "www%2droot.example.com" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")Return Value
The host name as a percent‐encoded string.
Return the origin
Synopsis
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_origin() const noexcept;Description
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.
Example
assert( url_view( "http://www.example.com:8080/index.htm?text=none#h1" ).encoded_origin() == "http://www.example.com:8080" );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
The origin portion of the url.
See Also
Return the query as a container of parameters
Synopsis
Declared in <boost/url/url_view_base.hpp>
params_encoded_view
encoded_params() const noexcept;Description
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.
Example
params_encoded_view pv = url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_params();Complexity
Constant.
Exception Safety
Throws nothing.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Return Value
A bidirectional view of key/value pairs.
See Also
Return the password
Synopsis
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_password() const noexcept;Description
This function returns the password portion of the userinfo as a percent‐encoded string.
Example
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_password() == "pass" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
userinfo = user [ ":" [ password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
The password as a string.
See Also
Return the path
Synopsis
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_path() const noexcept;Description
This function returns the path as a string. The path may be empty. Any percent‐escapes in the string are decoded first.
Example
assert( url_view( "file:///Program%20Files/Games/config.ini" ).encoded_path() == "/Program%20Files/Games/config.ini" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>Return Value
The path as a string.
See Also
Return the query
Synopsis
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_query() const noexcept;Description
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.
Example
assert( url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_query() == "id=42&name=jane%2Ddoe&page+size=20" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Return Value
The query as a string.
See Also
Return the resource
Synopsis
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_resource() const noexcept;Description
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.
Example
assert( url_view( "http://www.example.com/index.html?query#frag" ).encoded_resource() == "/index.html?query#frag" );Complexity
Constant.
Exception Safety
Throws nothing.
Specification
Return Value
The resource portion of the url.
See Also
Return the path as a container of segments
Synopsis
Declared in <boost/url/url_view_base.hpp>
segments_encoded_view
encoded_segments() const noexcept;Description
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.
Example
segments_encoded_view sv = url_view( "/path/to/file.txt" ).encoded_segments();Complexity
Constant.
Exception Safety
Throws nothing.
BNF
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>Return Value
A bidirectional view of encoded segments.
See Also
Return the target
Synopsis
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_target() const noexcept;Description
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.
Example
assert( url_view( "http://www.example.com/index.html?query#frag" ).encoded_target() == "/index.html?query" );Complexity
Constant.
Exception Safety
Throws nothing.
Specification
Return Value
The target portion of the url.
See Also
Return the user
Synopsis
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_user() const noexcept;Description
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.
Example
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_user() == "jane%2Ddoe" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
userinfo = user [ ":" [ password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
The user as a string.
See Also
Return the userinfo
Synopsis
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_userinfo() const noexcept;Description
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.
Example
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_userinfo() == "jane%2Ddoe:pass" );Complexity
Constant.
Exception Safety
Throws nothing
BNF
userinfo = user [ ":" [ password ] ]
authority = [ userinfo "@" ] host [ ":" port ]Return Value
The userinfo as a string.
See Also
Return the IPv6 Zone ID
Synopsis
Declared in <boost/url/url_view_base.hpp>
pct_string_view
encoded_zone_id() const noexcept;Description
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.
Example
assert( url_view( "http://[fe80::1%25eth0]/" ).encoded_zone_id() == "eth0" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPv6addrz / IPvFuture ) "]"
ZoneID = 1*( unreserved / pct-encoded )
IPv6addrz = IPv6address "%25" ZoneIDSpecification
Return Value
The Zone ID as a percent‐encoded string.
Return the fragment
Synopsis
Declared in <boost/url/url_view_base.hpp>
template<string_token::StringToken StringToken = string_token::return_string>
StringToken::result_type
fragment(StringToken&& token = {}) const;Description
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:
-
When called with no arguments, the return type of the function is
std::string. Otherwise -
When called with a string token, the behavior and return type of the function depends on the type of string token being passed.
Example
assert( url_view( "http://www.example.com/index.htm#a%2D1" ).fragment() == "a-1" );Complexity
Linear in this‐>fragment().size().
Exception Safety
Calls to allocate may throw. String tokens may throw exceptions.
BNF
fragment = *( pchar / "/" / "?" )
fragment-part = [ "#" fragment ]Return Value
The fragment portion of the url.
Parameters
Name |
Description |
token |
An optional string token to use. If this parameter is omitted, the function returns a new |
See Also
Return true if an authority is present
Synopsis
Declared in <boost/url/url_view_base.hpp>
bool
has_authority() const noexcept;Description
This function returns true if the url contains an authority. The presence of an authority is denoted by a double slash ("//") at the beginning or after the scheme.
Example
assert( url_view( "http://www.example.com/index.htm" ).has_authority() );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
authority = [ userinfo "@" ] host [ ":" port ]
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
absolute-URI = scheme ":" hier-part [ "?" query ]
URI-reference = URI / relative-ref
relative-ref = relative-part [ "?" query ] [ "#" fragment ]
hier-part = "//" authority path-abempty
; (more...)
relative-part = "//" authority path-abempty
; (more...)Return Value
true if the url contains an authority.
See Also
Return true if a fragment is present
Synopsis
Declared in <boost/url/url_view_base.hpp>
bool
has_fragment() const noexcept;Description
This function returns true if the url contains a fragment. An empty fragment is distinct from no fragment.
Example
assert( url_view( "http://www.example.com/index.htm#anchor" ).has_fragment() );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
relative-ref = relative-part [ "?" query ] [ "#" fragment ]Return Value
true if the url contains a fragment.
See Also
Return true if a password is present
Synopsis
Declared in <boost/url/url_view_base.hpp>
bool
has_password() const noexcept;Description
This function returns true if the userinfo is present and contains a password.
Example
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_password() );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
userinfo = user [ ":" [ password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
true if the userinfo contains a password.
See Also
Return true if a port is present
Synopsis
Declared in <boost/url/url_view_base.hpp>
bool
has_port() const noexcept;Description
This function returns true if an authority is present and contains a port.
Example
assert( url_view( "wss://www.example.com:443" ).has_port() );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
authority = [ userinfo "@" ] host [ ":" port ]
port = *DIGITReturn Value
true if a port is present, false otherwise.
See Also
Return true if a query is present
Synopsis
Declared in <boost/url/url_view_base.hpp>
bool
has_query() const noexcept;Description
This function returns true if this contains a query. An empty query is distinct from having no query.
Example
assert( url_view( "/sql?id=42&col=name&page-size=20" ).has_query() );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Return Value
true if a query is present.
See Also
Return true a scheme is present
Synopsis
Declared in <boost/url/url_view_base.hpp>
bool
has_scheme() const noexcept;Description
This function returns true if this contains a scheme.
Example
assert( url_view( "http://www.example.com" ).has_scheme() );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
absolute-URI = scheme ":" hier-part [ "?" query ]
scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )Return Value
true if the url contains a scheme.
Synopsis
Declared in <boost/url/url_view_base.hpp>
bool
has_userinfo() const noexcept;Description
This function returns true if this contains a userinfo.
Example
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_userinfo() );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
userinfo = user [ ":" [ password ] ]
authority = [ userinfo "@" ] host [ ":" port ]Return Value
true if the userinfo is present.
See Also
Return the host
Synopsis
Declared in <boost/url/url_view_base.hpp>
template<string_token::StringToken StringToken = string_token::return_string>
StringToken::result_type
host(StringToken&& token = {}) const;Description
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.
Example
assert( url_view( "https://www%2droot.example.com/" ).host() == "www-root.example.com" );Complexity
Linear in this‐>host().size().
Exception Safety
Calls to allocate may throw.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")Return Value
The host address as a string.
Parameters
Name |
Description |
token |
A string token customization |
Return the host
Synopsis
Declared in <boost/url/url_view_base.hpp>
template<string_token::StringToken StringToken = string_token::return_string>
StringToken::result_type
host_address(StringToken&& token = {}) const;Description
The value returned by this function depends on the type of host returned from the function host_type.
-
If the type is
host_type::ipv4, then the IPv4 address string is returned. -
If the type is
host_type::ipv6, then the IPv6 address string is returned, without any enclosing brackets. -
If the type is
host_type::ipvfuture, then the IPvFuture address string is returned, without any enclosing brackets. -
If the type is
host_type::name, then the host name string is returned. Any percent‐escapes in the string are decoded first. -
If the type is
host_type::none, then an empty string is returned.
Example
assert( url_view( "https://[1::6:c0a8:1]/" ).host_address() == "1::6:c0a8:1" );Complexity
Linear in this‐>host_address().size().
Exception Safety
Calls to allocate may throw.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")Return Value
The host address as a string.
Parameters
Name |
Description |
token |
A string token customization |
Return the host IPv4 address
Synopsis
Declared in <boost/url/url_view_base.hpp>
ipv4_address
host_ipv4_address() const noexcept;Description
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".
Example
assert( url_view( "http://127.0.0.1/index.htm?user=win95" ).host_ipv4_address() == ipv4_address( "127.0.0.1" ) );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
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-255Return Value
The IPv4 address as a value of type ipv4_address.
Return the host IPv6 address
Synopsis
Declared in <boost/url/url_view_base.hpp>
ipv6_address
host_ipv6_address() const noexcept;Description
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".
Example
assert( url_view( "ftp://[::1]/" ).host_ipv6_address() == ipv6_address( "::1" ) );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
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 hexadecimalReturn Value
The IPv6 address as a value of type ipv6_address.
Return the host IPvFuture address
Synopsis
Declared in <boost/url/url_view_base.hpp>
core::string_view
host_ipvfuture() const noexcept;Description
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.
Example
assert( url_view( "http://[v1fe.d:9]/index.htm" ).host_ipvfuture() == "v1fe.d:9" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )Return Value
The IPvFuture address as a string.
Return the host name
Synopsis
Declared in <boost/url/url_view_base.hpp>
template<string_token::StringToken StringToken = string_token::return_string>
StringToken::result_type
host_name(StringToken&& token = {}) const;Description
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.
Example
assert( url_view( "https://www%2droot.example.com/" ).host_name() == "www-root.example.com" );Complexity
Linear in this‐>host_name().size().
Exception Safety
Calls to allocate may throw.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPvFuture ) "]"
reg-name = *( unreserved / pct-encoded / "-" / ".")Return Value
The host name as a string.
Parameters
Name |
Description |
token |
A string token customization. |
Return the host type
Synopsis
Declared in <boost/url/url_view_base.hpp>
urls::host_type
host_type() const noexcept;Description
This function returns one of the following constants representing the type of host present.
-
host_type::ipv4 -
host_type::ipv6 -
host_type::ipvfuture -
host_type::name -
host_type::none
When has_authority is false, the host type is host_type::none.
Example
assert( url_view( "https://192.168.0.1/local.htm" ).host_type() == host_type::ipv4 );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
The type of host present.
Return true if the path is absolute
Synopsis
Declared in <boost/url/url_view_base.hpp>
bool
is_path_absolute() const noexcept;Description
This function returns true if the path begins with a forward slash ('/').
Example
assert( url_view( "/path/to/file.txt" ).is_path_absolute() );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>Return Value
true if the path is absolute, false otherwise.
See Also
Return the query as a container of parameters
Synopses
Declared in <boost/url/url_view_base.hpp>
Return the query as a container of parameters
params_view
params() const noexcept;params_view
params(encoding_opts opt) const noexcept;Return Value
A bidirectional view of key/value pairs.
See Also
Return the query as a container of parameters
Synopsis
Declared in <boost/url/url_view_base.hpp>
params_view
params() const noexcept;Description
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.
Example
params_view pv = url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).params();Complexity
Constant.
Exception Safety
Throws nothing.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Return Value
A bidirectional view of key/value pairs.
See Also
Synopsis
Declared in <boost/url/url_view_base.hpp>
params_view
params(encoding_opts opt) const noexcept;Return the password
Synopsis
Declared in <boost/url/url_view_base.hpp>
template<string_token::StringToken StringToken = string_token::return_string>
StringToken::result_type
password(StringToken&& token = {}) const;Description
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.
Example
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).password() == "pass" );Complexity
Linear in this‐>password().size().
Exception Safety
Calls to allocate may throw.
BNF
userinfo = user [ ":" [ password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
The password as a string.
Parameters
Name |
Description |
token |
The string token to use. |
See Also
Return the path
Synopsis
Declared in <boost/url/url_view_base.hpp>
template<string_token::StringToken StringToken = string_token::return_string>
StringToken::result_type
path(StringToken&& token = {}) const;Description
This function returns the path as a string. The path may be empty. Any percent‐escapes in the string are decoded first.
Example
assert( url_view( "file:///Program%20Files/Games/config.ini" ).path() == "/Program Files/Games/config.ini" );Complexity
Linear in this‐>path().size().
Exception Safety
Calls to allocate may throw.
BNF
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>Return Value
The path as a string.
Parameters
Name |
Description |
token |
A string token to use for the result. |
See Also
Return a shared, persistent copy of the url
Synopsis
Declared in <boost/url/url_view_base.hpp>
std::shared_ptr<url_view const>
persist() const;Description
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.
Example
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.
}Complexity
Linear in this‐>size().
Exception Safety
Calls to allocate may throw.
Return Value
A shared pointer to a read‐only url_view.
Return the port
Synopsis
Declared in <boost/url/url_view_base.hpp>
core::string_view
port() const noexcept;Description
If present, this function returns a string representing the port (which may be empty). Otherwise it returns an empty string.
Example
assert( url_view( "http://localhost.com:8080" ).port() == "8080" );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
port = *DIGITReturn Value
The port as a string.
See Also
Return the port
Synopsis
Declared in <boost/url/url_view_base.hpp>
uint16_t
port_number() const noexcept;Description
If a port is present and the numerical value is representable, it is returned as an unsigned integer. Otherwise, the number zero is returned.
Example
assert( url_view( "http://localhost.com:8080" ).port_number() == 8080 );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
port = *DIGITReturn Value
The port number as an unsigned integer.
See Also
Return the query
Synopsis
Declared in <boost/url/url_view_base.hpp>
template<string_token::StringToken StringToken = string_token::return_string>
StringToken::result_type
query(StringToken&& token = {}) const;Description
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.
Example
assert( url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).query() == "id=42&name=jane-doe&page size=20" );Complexity
Linear in this‐>query().size().
Exception Safety
Calls to allocate may throw.
BNF
query = *( pchar / "/" / "?" )
query-param = key [ "=" value ]
query-params = [ query-param ] *( "&" query-param )Specification
Return Value
The query as a string.
Parameters
Name |
Description |
token |
A token to use for the returned string. |
See Also
Return the scheme
Synopsis
Declared in <boost/url/url_view_base.hpp>
core::string_view
scheme() const noexcept;Description
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.
Example
assert( url_view( "http://www.example.com" ).scheme() == "http" );Exception Safety
Throws nothing.
BNF
scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
absolute-URI = scheme ":" hier-part [ "?" query ]Return Value
The scheme as a string.
See Also
Return the scheme
Synopsis
Declared in <boost/url/url_view_base.hpp>
urls::scheme
scheme_id() const noexcept;Description
This function returns a value which depends on the scheme in the url:
-
If the scheme is a well‐known scheme, corresponding value from the enumeration
urls::schemeis returned. -
If a scheme is present but is not a well‐known scheme, the value returned is
urls::scheme::unknown. -
Otherwise, if the scheme is absent the value returned is
urls::scheme::none.
Example
assert( url_view( "wss://www.example.com/crypto.cgi" ).scheme_id() == scheme::wss );Complexity
Constant.
Exception Safety
Throws nothing.
BNF
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
absolute-URI = scheme ":" hier-part [ "?" query ]
scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )Return Value
The scheme as an enumeration value.
See Also
Return the path as a container of segments
Synopsis
Declared in <boost/url/url_view_base.hpp>
segments_view
segments() const noexcept;Description
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.
Example
segments_view sv = url_view( "/path/to/file.txt" ).segments();Complexity
Constant.
Exception Safety
Throws nothing.
BNF
path = [ "/" ] segment *( "/" segment )Return Value
A bidirectional view of segments.
See Also
Return the number of characters in the url
Synopsis
Declared in <boost/url/url_view_base.hpp>
std::size_t
size() const noexcept;Description
This function returns the number of characters in the url's encoded string, not including any null terminator, if present.
Example
assert( url_view( "file:///Program%20Files" ).size() == 23 );Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
The number of characters in the url.
Return the user
Synopsis
Declared in <boost/url/url_view_base.hpp>
template<string_token::StringToken StringToken = string_token::return_string>
StringToken::result_type
user(StringToken&& token = {}) const;Description
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.
Example
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).user() == "jane-doe" );Complexity
Linear in this‐>user().size().
Exception Safety
Calls to allocate may throw.
BNF
userinfo = user [ ":" [ password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )Return Value
The user as a string.
Parameters
Name |
Description |
token |
The string token to use. |
See Also
Return the userinfo
Synopsis
Declared in <boost/url/url_view_base.hpp>
template<string_token::StringToken StringToken = string_token::return_string>
StringToken::result_type
userinfo(StringToken&& token = {}) const;Description
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.
|
Note
|
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.
|
Example
assert( url_view( "http://jane%2Ddoe:pass@example.com" ).userinfo() == "jane-doe:pass" );Complexity
Linear in this‐>userinfo().size().
Exception Safety
Calls to allocate may throw.
BNF
userinfo = user [ ":" [ password ] ]
authority = [ userinfo "@" ] host [ ":" port ]Return Value
-
When called with no arguments, a value of type
std::stringis returned. Otherwise, the return type and meaning depends on the string token passed to the function. -
The userinfo as a string.
Parameters
Name |
Description |
token |
The string token to use. |
See Also
Return the IPv6 Zone ID
Synopsis
Declared in <boost/url/url_view_base.hpp>
template<string_token::StringToken StringToken = string_token::return_string>
StringToken::result_type
zone_id(StringToken&& token = {}) const;Description
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.
Example
assert( url_view( "http://[fe80::1%25eth0]/" ).zone_id() == "eth0" );Complexity
Linear in this‐>encoded_zone_id().size().
Exception Safety
Calls to allocate may throw.
BNF
host = IP-literal / IPv4address / reg-name
IP-literal = "[" ( IPv6address / IPv6addrz / IPvFuture ) "]"
ZoneID = 1*( unreserved / pct-encoded )
IPv6addrz = IPv6address "%25" ZoneIDSpecification
Return Value
The Zone ID as a string.
Parameters
Name |
Description |
token |
A string token customization. |
Return the URL as a core::string_view
Synopsis
Declared in <boost/url/url_view_base.hpp>
operator core::string_view() const noexcept;Description
Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
A string view of the URL.
Return the maximum number of characters possible
Synopsis
Declared in <boost/url/url_view_base.hpp>
constexpr
static
std::size_t
max_size() noexcept;Description
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.
Complexity
Constant.
Exception Safety
Throws nothing.
Return Value
The maximum number of characters.
Calculate a hash of the url
Synopsis
Declared in <boost/url/url_view_base.hpp>
std::size_t
digest(std::size_t salt = 0) const noexcept;Description
This function calculates a hash of the url as if it were always normalized.
Complexity
Linear in this‐>size().
Exception Safety
Throws nothing.
Return Value
A hash value suitable for use in hash‐based containers.
Parameters
Name |
Description |
salt |
An initial value to add to the hash |
Error codes returned the library
Synopsis
Declared in <boost/url/error.hpp>
enum class error : int;Members
Name |
Description |
|
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. |
|
The percent‐encoded sequence is incomplete. |
|
Missing hexadecimal digit. |
|
No space in output buffer |
|
The URL is not a base URL |
Identifies the type of host in a URL.
Synopsis
Declared in <boost/url/host_type.hpp>
enum class host_type : int;Members
Name |
Description |
|
No host is specified. |
|
A host is specified by reg‐name. |
|
A host is specified by |
|
A host is specified by |
|
A host is specified by IPvFuture. |
Description
Values of this type are returned by URL views and containers to indicate the type of host present in a URL.
Identifies a known URL scheme
Synopsis
Declared in <boost/url/scheme.hpp>
enum class scheme : unsigned short;Members
Name |
Description |
|
Indicates that no scheme is present |
|
Indicates the scheme is not a well‐known scheme |
|
File Transfer Protocol (FTP) |
|
File URI Scheme |
|
The Hypertext Transfer Protocol URI Scheme |
|
The Secure Hypertext Transfer Protocol URI Scheme |
|
The WebSocket URI Scheme |
|
The Secure WebSocket URI Scheme |
Non-Member Functions
Name |
Description |
Return the default port for a known scheme |
|
Return the known scheme for a non‐normalized string, if known |
|
Return the normalized string for a known scheme |
Description
Specification
Designate a named argument for a replacement field
Synopsis
Declared in <boost/url/format.hpp>
template<class T>
named_arg<T>
arg(
core::string_view name,
T const& arg);Description
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.
Example
The function should be used to designate a named argument for a replacement field in a format URL string.
assert(format("user/{id}", arg("id", 1)).buffer() == "user/1");Return Value
A temporary object with reference semantics for a named argument
Parameters
Name |
Description |
name |
The format argument name |
arg |
The format argument value |
Synopsis
Declared in <boost/url/scheme.hpp>
uint16_t
default_port(scheme s) noexcept;Description
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:
-
scheme::ftp= 21 -
scheme::http,scheme::ws= 80 -
scheme::https,scheme::wss= 443
Return Value
An integer with the default port number
Parameters
Name |
Description |
s |
The known scheme constant |
encode overloads
Synopses
Declared in <boost/url/encode.hpp>
Return a percent‐encoded string
template<
string_token::StringToken StringToken = string_token::return_string,
grammar::CharSet CS>
StringToken::result_type
encode(
core::string_view s,
CS const& allowed,
encoding_opts opt = {},
StringToken&& token = {}) noexcept;Apply percent‐encoding to a string
template<grammar::CharSet CS>
std::size_t
encode(
char* dest,
std::size_t size,
core::string_view s,
CS const& allowed,
encoding_opts opt = {});Return Value
-
The string
-
The number of characters written to the destination buffer.
Parameters
Name |
Description |
s |
The string to encode. |
allowed |
The set of characters that is not percent‐encoded. |
opt |
The options for encoding. If this parameter is omitted, the default options are used. |
token |
A string token. |
dest |
The destination buffer to write to. |
size |
The number of writable characters pointed to by |
See Also
Return a percent‐encoded string
Synopsis
Declared in <boost/url/encode.hpp>
template<
string_token::StringToken StringToken = string_token::return_string,
grammar::CharSet CS>
StringToken::result_type
encode(
core::string_view s,
CS const& allowed,
encoding_opts opt = {},
StringToken&& token = {}) noexcept;Description
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.
Example
encoding_opts opt;
opt.space_as_plus = true;
std::string s = encode( "My Stuff", opt, pchars );
assert( s == "My+Stuff" );Exception Safety
Calls to allocate may throw.
Return Value
The string
Parameters
Name |
Description |
s |
The string to encode. |
allowed |
The set of characters that is not percent‐encoded. |
opt |
The options for encoding. If this parameter is omitted, the default options are used. |
token |
A string token. |
See Also
Apply percent‐encoding to a string
Synopsis
Declared in <boost/url/encode.hpp>
template<grammar::CharSet CS>
std::size_t
encode(
char* dest,
std::size_t size,
core::string_view s,
CS const& allowed,
encoding_opts opt = {});Description
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.
Example
char buf[100];
assert( encode( buf, sizeof(buf), "Program Files", pchars ) == 15 );Exception Safety
Throws nothing.
Return Value
The number of characters written to the destination buffer.
Parameters
Name |
Description |
dest |
The destination buffer to write to. |
size |
The number of writable characters pointed to by |
s |
The string to encode. |
allowed |
The set of characters that is not percent‐encoded. |
opt |
The options for encoding. If this parameter is omitted, the default options are used. |
See Also
Return the buffer size needed for percent‐encoding
Synopsis
Declared in <boost/url/encode.hpp>
template<grammar::CharSet CS>
std::size_t
encoded_size(
core::string_view s,
CS const& allowed,
encoding_opts opt = {}) noexcept;Description
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.
Example
assert( encoded_size( "My Stuff", pchars ) == 10 );Exception Safety
Throws nothing.
Return Value
The number of bytes needed, excluding any null terminator.
Parameters
Name |
Description |
s |
The string to measure. |
allowed |
The set of characters that is not percent‐encoded. |
opt |
The options for encoding. If this parameter is omitted, the default options are be used. |
See Also
Format arguments into a URL
Synopses
Exceptions
Name |
Thrown on |
|
|
Return Value
A URL holding the formatted result.
Parameters
Name |
Description |
fmt |
The format URL string. |
args |
Arguments to be formatted. |
Synopsis
Declared in <boost/url/format.hpp>
url
format(
core::string_view fmt,
std::initializer_list<format_arg> args);Description
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.
Example
assert(format("user/{id}", {{"id", 1}}).buffer() == "user/1");Preconditions
All replacement fields must be valid and the 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.
BNF
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 | digitSpecification
Exceptions
Name |
Thrown on |
|
|
Return Value
A URL holding the formatted result.
Parameters
Name |
Description |
fmt |
The format URL string. |
args |
Arguments to be formatted. |
See Also
Format arguments into a URL
Synopsis
Declared in <boost/url/format.hpp>
template<std::convertible_to<format_arg>... Args>
url
format(
core::string_view fmt,
Args...&&... args);Description
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.
Example
assert(format("{}", "Hello world!").buffer() == "Hello%20world%21");Preconditions
All replacement fields must be valid and the 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.
BNF
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 | digitSpecification
Exceptions
Name |
Thrown on |
|
|
Return Value
A URL holding the formatted result.
Parameters
Name |
Description |
fmt |
The format URL string. |
args |
Arguments to be formatted. |
Synopses
Exceptions
Name |
Thrown on |
|
|
Parameters
Name |
Description |
u |
An object that derives from |
fmt |
The format URL string. |
args |
Arguments to be formatted. |
See Also
Format arguments into a URL
Synopsis
Declared in <boost/url/format.hpp>
void
format_to(
url_base& u,
core::string_view fmt,
std::initializer_list<format_arg> args);Description
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.
Example
static_url<30> u;
format_to(u, "user/{id}", {{"id", 1}})
assert(u.buffer() == "user/1");Preconditions
All replacement fields must be valid and the 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.
Exception Safety
Strong guarantee.
BNF
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 | digitSpecification
Exceptions
Name |
Thrown on |
|
|
Parameters
Name |
Description |
u |
An object that derives from |
fmt |
The format URL string. |
args |
Arguments to be formatted. |
See Also
Format arguments into a URL
Synopsis
Declared in <boost/url/format.hpp>
template<std::convertible_to<format_arg>... Args>
void
format_to(
url_base& u,
core::string_view fmt,
Args...&&... args);Description
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.
Example
static_url<30> u;
format(u, "{}", "Hello world!");
assert(u.buffer() == "Hello%20world%21");Preconditions
All replacement fields must be valid and the 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.
Exception Safety
Strong guarantee.
BNF
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 | digitSpecification
Exceptions
Name |
Thrown on |
|
|
Parameters
Name |
Description |
u |
An object that derives from |
fmt |
The format URL string. |
args |
Arguments to be formatted. |
See Also
Return a valid percent‐encoded string
Synopsis
Declared in <boost/url/pct_string_view.hpp>
system::result<pct_string_view>
make_pct_string_view(core::string_view s) noexcept;Description
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.
Complexity
Linear in s.size().
Exception Safety
Throws nothing.
Return Value
On success, the valid percent‐encoded string.
Parameters
Name |
Description |
s |
The string to validate. |
Return a reference to a parsed URL string
Synopsis
Declared in <boost/url/parse.hpp>
system::result<url_view>
parse_absolute_uri(core::string_view s);Description
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.
Example
system::result< url_view > rv = parse_absolute_uri( "http://example.com/index.htm?id=1" );BNF
absolute-URI = scheme ":" hier-part [ "?" query ]
hier-part = "//" authority path-abempty
/ path-absolute
/ path-rootless
/ path-emptyExceptions
Name |
Thrown on |
|
|
Return Value
A view to the parsed URL
Parameters
Name |
Description |
s |
The string to parse |
See Also
Parse an authority
Synopsis
Declared in <boost/url/authority_view.hpp>
system::result<authority_view>
parse_authority(core::string_view s) noexcept;Description
This function parses a string according to the authority grammar below, and returns an authority_view referencing the string. Ownership of the string is not transferred; the caller is responsible for ensuring that the lifetime of the string extends until the view is no longer being accessed.
BNF
authority = [ userinfo "@" ] host [ ":" port ]
userinfo = user [ ":" [ password ] ]
user = *( unreserved / pct-encoded / sub-delims )
password = *( unreserved / pct-encoded / sub-delims / ":" )
host = IP-literal / IPv4address / reg-name
port = *DIGITException Safety
Throws nothing.
Return Value
A view to the parsed authority
Parameters
Name |
Description |
s |
The string to parse |
See Also
Return an IPv4 address from an IP address string in dotted decimal form
Synopsis
Declared in <boost/url/ipv4_address.hpp>
system::result<ipv4_address>
parse_ipv4_address(core::string_view s) noexcept;Return Value
The parsed address, or an error code.
Parameters
Name |
Description |
s |
The string to parse. |
Parse a string containing an IPv6 address.
Synopsis
Declared in <boost/url/ipv6_address.hpp>
system::result<ipv6_address>
parse_ipv6_address(core::string_view s) noexcept;Description
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.
Exception Safety
Throws nothing.
Return Value
A result containing the address.
Parameters
Name |
Description |
s |
The string to parse. |
Return a reference to a parsed URL string
Synopsis
Declared in <boost/url/parse.hpp>
system::result<url_view>
parse_origin_form(core::string_view s);Description
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.
Example
system::result< url_view > = parse_origin_form( "/index.htm?layout=mobile" );BNF
origin-form = absolute-path [ "?" query ]
absolute-path = 1*( "/" segment )Exceptions
Name |
Thrown on |
|
|
Return Value
A view to the parsed URL
Parameters
Name |
Description |
s |
The string to parse |
See Also
Parse a string and return an encoded segment view
Synopsis
Declared in <boost/url/parse_path.hpp>
system::result<segments_encoded_view>
parse_path(core::string_view s) noexcept;Description
This function parses the string and returns the corresponding path object if the string is valid, otherwise returns an error.
BNF
path = [ "/" ] segment *( "/" segment )Exception Safety
No‐throw guarantee.
Return Value
A valid view on success, otherwise an error code.
Parameters
Name |
Description |
s |
The string to parse |
See Also
Parse a string and return an encoded params view
Synopsis
Declared in <boost/url/parse_query.hpp>
system::result<params_encoded_view>
parse_query(core::string_view s) noexcept;Description
This function parses the string and returns the corresponding params object if the string is valid, otherwise returns an error.
BNF
query = *( pchar / "/" / "?" )Exception Safety
No‐throw guarantee.
Specification
Return Value
A valid view on success, otherwise an error code.
Parameters
Name |
Description |
s |
The string to parse |
See Also
Return a reference to a parsed URL string
Synopsis
Declared in <boost/url/parse.hpp>
system::result<url_view>
parse_relative_ref(core::string_view s);Description
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.
Example
system::result< url_view > = parse_relative_ref( "images/dot.gif?v=hide#a" );BNF
relative-ref = relative-part [ "?" query ] [ "#" fragment ]
relative-part = "//" authority path-abempty
/ path-absolute
/ path-noscheme
/ path-abempty
/ path-emptySpecification
Exceptions
Name |
Thrown on |
|
|
Return Value
A view to the parsed URL
Parameters
Name |
Description |
s |
The string to parse |
See Also
Return a reference to a parsed URL string
Synopsis
Declared in <boost/url/parse.hpp>
system::result<url_view>
parse_uri(core::string_view s);Description
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.
Example
system::result< url_view > = parse_uri( "https://www.example.com/index.htm?id=guest#s1" );BNF
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
hier-part = "//" authority path-abempty
/ path-absolute
/ path-rootless
/ path-emptySpecification
Exceptions
Name |
Thrown on |
|
|
Return Value
A boost::system::result containing a value or an error
Parameters
Name |
Description |
s |
The string to parse |
See Also
Return a reference to a parsed URL string
Synopsis
Declared in <boost/url/parse.hpp>
system::result<url_view>
parse_uri_reference(core::string_view s);Description
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.
Example
system::result< url_view > = parse_uri_reference( "ws://echo.example.com/?name=boost#demo" );BNF
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-emptySpecification
Exceptions
Name |
Thrown on |
|
|
Return Value
A view to the parsed URL
Parameters
Name |
Description |
s |
The string to parse |
See Also
Rule for a string with percent‐encoded escapes
Synopsis
Declared in <boost/url/rfc/pct_encoded_rule.hpp>
template<grammar::CharSet CS>
constexpr
/* implementation-defined */
pct_encoded_rule(CS const& cs) noexcept;Description
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.
Value Type
using value_type = pct_string_view;Example
Rules are used with the function grammar::parse.
// pchar = unreserved / pct-encoded / sub-delims / ":" / "@"
system::result< pct_string_view > rv = grammar::parse( "Program%20Files", pct_encoded_rule( pchars ) );BNF
pct-encoded = "%" HEXDIG HEXDIGReturn Value
A rule object.
Parameters
Name |
Description |
cs |
The character set indicating which characters are allowed without escapes. Any character which is not in this set must be escaped, or else parsing returns an error. |
See Also
Resolve a URL reference against a base URL
Synopsis
Declared in <boost/url/url_base.hpp>
system::result<void>
resolve(
url_view_base const& base,
url_view_base const& ref,
url_base& dest);Description
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:
-
Ensure the base URI has at least a scheme
-
Normalizing the reference path
-
Merge base and reference paths
-
Normalize the merged path
This function places the result of the resolution into dest, which can be any of the url containers that inherit from url_base.
If an error occurs, the contents of dest is unspecified and ec is set.
|
Note
|
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 https://www.rfc-editor.org/errata/eid4547. |
Example
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" );BNF
absolute-URI = scheme ":" hier-part [ "?" query ]Exception Safety
Basic guarantee. Calls to allocate may throw.
Specification
Return Value
An empty boost::system::result upon success, otherwise an error code if !base.has_scheme().
Parameters
Name |
Description |
base |
The base URL to resolve against. |
ref |
The URL reference to resolve. |
dest |
The container where the result is written, upon success. |
Synopsis
Declared in <boost/url/scheme.hpp>
scheme
string_to_scheme(core::string_view s) noexcept;Description
If the string does not identify a known scheme, the value scheme::unknown is returned.
BNF
scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )Return Value
The known scheme
Parameters
Name |
Description |
s |
The string holding the scheme |
Swap
Synopsis
Declared in <boost/url/url.hpp>
Description
Exchanges the contents of v0 with another v1. All views, iterators and references remain valid.
If &v0 == &v1, this function call has no effect.
Example
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" );Effects
v0.swap( v1 );Complexity
Constant
Exception Safety
Throws nothing
Parameters
Name |
Description |
v0 |
The first object to swap |
v1 |
The second object to swap |
See Also
Return the normalized string for a known scheme
Synopsis
Declared in <boost/url/scheme.hpp>
core::string_view
to_string(scheme s) noexcept;Return Value
A string representing the known scheme
Parameters
Name |
Description |
s |
The known scheme constant |
Stream insertion operators
Synopses
Declared in <boost/url/authority_view.hpp>
Format the address to an output stream
std::ostream&
operator<<(
std::ostream& os,
ipv6_address const& addr);Format the address to an output stream.
std::ostream&
operator<<(
std::ostream& os,
ipv4_address const& addr);Format the string with percent‐decoding applied to the output stream
std::ostream&
operator<<(
std::ostream& os,
decode_view const& s);Format the url to the output stream
std::ostream&
operator<<(
std::ostream& os,
url_view_base const& u);Format the encoded authority to the output stream
std::ostream&
operator<<(
std::ostream& os,
authority_view const& a);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);Return Value
-
The output stream, for chaining.
-
The output stream.
-
A reference to the output stream, for chaining
-
A reference to the output stream.
Parameters
Name |
Description |
os |
The output stream to write to. |
addr |
The address to write. |
s |
The decoded view to write |
u |
The url to write. |
a |
The URL to write |
qp |
The params to write |
ps |
The object to format. |
Format the address to an output stream
Synopsis
Declared in <boost/url/ipv6_address.hpp>
std::ostream&
operator<<(
std::ostream& os,
ipv6_address const& addr);Description
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.
Return Value
The output stream, for chaining.
Parameters
Name |
Description |
os |
The output stream to write to. |
addr |
The address to write. |
Format the address to an output stream.
Synopsis
Declared in <boost/url/ipv4_address.hpp>
std::ostream&
operator<<(
std::ostream& os,
ipv4_address const& addr);Description
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.
Format the address to an output stream.
IPv4 addresses written to output streams are written in their dotted decimal format.
Return Value
The output stream.
Parameters
Name |
Description |
os |
The output stream. |
addr |
The address to format. |
Format the string with percent‐decoding applied to the output stream
Synopsis
Declared in <boost/url/decode_view.hpp>
std::ostream&
operator<<(
std::ostream& os,
decode_view const& s);Description
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.
Return Value
A reference to the output stream, for chaining
Parameters
Name |
Description |
os |
The output stream to write to |
s |
The decoded view to write |
Format the url to the output stream
Synopsis
Declared in <boost/url/url_view_base.hpp>
std::ostream&
operator<<(
std::ostream& os,
url_view_base const& u);Description
This function serializes the url to the specified output stream. Any percent‐escapes are emitted as‐is; no decoding is performed.
Example
url_view u( "http://www.example.com/index.htm" );
std::stringstream ss;
ss << u;
assert( ss.str() == "http://www.example.com/index.htm" );Effects
return os << u.buffer();Complexity
Linear in u.buffer().size()
Exception Safety
Basic guarantee.
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.
Example
url_view u( "http://www.example.com/index.htm" );
std::stringstream ss;
ss << u;
assert( ss.str() == "http://www.example.com/index.htm" );Effects
return os << u.buffer();Complexity
Linear in u.buffer().size()
Exception Safety
Basic guarantee.
Return Value
A reference to the output stream, for chaining
Parameters
Name |
Description |
os |
The output stream to write to. |
u |
The url to write. |
Format the encoded authority to the output stream
Synopsis
Declared in <boost/url/authority_view.hpp>
std::ostream&
operator<<(
std::ostream& os,
authority_view const& a);Description
This hidden friend function serializes the encoded URL to the output stream.
Example
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.
Example
authority_view a( "www.example.com" );
std::cout << a << std::endl;Return Value
A reference to the output stream, for chaining
Parameters
Name |
Description |
os |
The output stream to write to |
a |
The URL to write |
Format to an output stream
Synopsis
Declared in <boost/url/params_encoded_base.hpp>
std::ostream&
operator<<(
std::ostream& os,
params_encoded_base const& qp);Description
Any percent‐escapes are emitted as‐is; no decoding is performed.
Complexity
Linear in ps.buffer().size().
Effects
return os << ps.buffer();Return Value
A reference to the output stream, for chaining
Parameters
Name |
Description |
os |
The output stream to write to |
qp |
The params to write |
Format to an output stream
Synopsis
Declared in <boost/url/params_base.hpp>
std::ostream&
operator<<(
std::ostream& os,
params_base const& qp);Description
Any percent‐escapes are emitted as‐is; no decoding is performed.
Complexity
Linear in ps.buffer().size().
Effects
return os << ps.buffer();Return Value
A reference to the output stream, for chaining
Parameters
Name |
Description |
os |
The output stream to write to |
qp |
The parameters to write |
Format to an output stream
Synopsis
Declared in <boost/url/segments_encoded_base.hpp>
std::ostream&
operator<<(
std::ostream& os,
segments_encoded_base const& ps);Description
Any percent‐escapes are emitted as‐is; no decoding is performed.
Complexity
Linear in ps.buffer().size().
Effects
return os << ps.buffer();Return Value
A reference to the output stream.
Parameters
Name |
Description |
os |
The output stream to write to. |
ps |
The object to format. |
Format to an output stream
Synopsis
Declared in <boost/url/segments_base.hpp>
std::ostream&
operator<<(
std::ostream& os,
segments_base const& ps);Description
Any percent‐escapes are emitted as‐is; no decoding is performed.
Complexity
Linear in ps.buffer().size().
Effects
return os << ps.buffer();Return Value
A reference to the output stream.
Parameters
Name |
Description |
os |
The output stream to write to. |
ps |
The segments to write. |
Equality operators
Synopses
Declared in <boost/url/authority_view.hpp>
Return true if two addresses are equal
bool
operator==(
ipv6_address const& a1,
ipv6_address const& a2) noexcept;Return true if two addresses are equal
bool
operator==(
ipv4_address const& a1,
ipv4_address const& a2) noexcept;Compare two decode views for equality
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator==(
S const& lhs,
decode_view const& rhs) noexcept;Compare two decode views for equality
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator==(
decode_view const& lhs,
S const& rhs) noexcept;Compare two decode views for equality
constexpr
bool
operator==(
decode_view const& lhs,
decode_view const& rhs) noexcept;Return the result of comparing two URLs
bool
operator==(
url_view_base const& u0,
url_view_base const& u1) noexcept;[» more...]
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;Return Value
-
trueif the addresses are equal -
trueif the addresses are equal, otherwisefalse. -
trueif decodedlhsis equal to the decodedrhs -
trueifu0 == u1 -
trueifa0 == a1, otherwisefalse
Parameters
Name |
Description |
a1 |
The first address to compare. |
a2 |
The second address to compare. |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
u0 |
The first url to compare |
u1 |
The second url to compare |
a0 |
The first authority to compare |
Return true if two addresses are equal
Synopsis
Declared in <boost/url/ipv6_address.hpp>
bool
operator==(
ipv6_address const& a1,
ipv6_address const& a2) noexcept;Return Value
true if the addresses are equal
Parameters
Name |
Description |
a1 |
The first address to compare. |
a2 |
The second address to compare. |
Return true if two addresses are equal
Synopsis
Declared in <boost/url/ipv4_address.hpp>
bool
operator==(
ipv4_address const& a1,
ipv4_address const& a2) noexcept;Return Value
true if the addresses are equal, otherwise false.
Parameters
Name |
Description |
a1 |
The first address to compare. |
a2 |
The second address to compare. |
Compare two decode views for equality
Synopsis
Declared in <boost/url/decode_view.hpp>
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator==(
S const& lhs,
decode_view const& rhs) noexcept;Return Value
true if decoded lhs is equal to the decoded rhs
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
Compare two decode views for equality
Synopsis
Declared in <boost/url/decode_view.hpp>
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator==(
decode_view const& lhs,
S const& rhs) noexcept;Return Value
true if decoded lhs is equal to the decoded rhs
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
Compare two decode views for equality
Synopsis
Declared in <boost/url/decode_view.hpp>
constexpr
bool
operator==(
decode_view const& lhs,
decode_view const& rhs) noexcept;Return Value
true if decoded lhs is equal to the decoded rhs
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
Return the result of comparing two URLs
Synopsis
Declared in <boost/url/url_view_base.hpp>
bool
operator==(
url_view_base const& u0,
url_view_base const& u1) noexcept;Description
The URLs are compared component by component as if they were first normalized.
Example
url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.a.com/index.htm" );
assert( u0 == u1 );Effects
url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() == b.buffer();Complexity
Linear in min( u0.size(), u1.size() )
Exception Safety
Throws nothing
Return Value
true if u0 == u1
Parameters
Name |
Description |
u0 |
The first url to compare |
u1 |
The second url to compare |
Return the result of comparing two authorities. The authorities are compared component by component as if they were first normalized.
Synopsis
Declared in <boost/url/authority_view.hpp>
bool
operator==(
authority_view const& a0,
authority_view const& a1) noexcept;Description
Complexity
Linear in min( a0.size(), a1.size() )
Exception Safety
Throws nothing
Return Value
true if a0 == a1, otherwise false
Parameters
Name |
Description |
a0 |
The first authority to compare |
a1 |
The second authority to compare |
Inequality operators
Synopses
Declared in <boost/url/authority_view.hpp>
Return true if two addresses are not equal
bool
operator!=(
ipv6_address const& a1,
ipv6_address const& a2) noexcept;Return true if two addresses are not equal
bool
operator!=(
ipv4_address const& a1,
ipv4_address const& a2) noexcept;Compare two decode views for inequality
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator!=(
S const& lhs,
decode_view const& rhs) noexcept;Compare two decode views for inequality
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator!=(
decode_view const& lhs,
S const& rhs) noexcept;Compare two decode views for inequality
constexpr
bool
operator!=(
decode_view const& lhs,
decode_view const& rhs) noexcept;Return the result of comparing two URLs
bool
operator!=(
url_view_base const& u0,
url_view_base const& u1) noexcept;[» more...]
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;Return Value
-
trueif the addresses are not equal -
trueif the addresses are not equal, otherwisefalse. -
trueif decodedlhsis not equal to the decodedrhs -
trueifu0 != u1 -
trueifa0 != a1, otherwisefalse
Parameters
Name |
Description |
a1 |
The first address to compare. |
a2 |
The second address to compare. |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
u0 |
The first url to compare |
u1 |
The second url to compare |
a0 |
The first authority to compare |
Return true if two addresses are not equal
Synopsis
Declared in <boost/url/ipv6_address.hpp>
bool
operator!=(
ipv6_address const& a1,
ipv6_address const& a2) noexcept;Return Value
true if the addresses are not equal
Parameters
Name |
Description |
a1 |
The first address to compare. |
a2 |
The second address to compare. |
Return true if two addresses are not equal
Synopsis
Declared in <boost/url/ipv4_address.hpp>
bool
operator!=(
ipv4_address const& a1,
ipv4_address const& a2) noexcept;Return Value
true if the addresses are not equal, otherwise false.
Parameters
Name |
Description |
a1 |
The first address to compare. |
a2 |
The second address to compare. |
Compare two decode views for inequality
Synopsis
Declared in <boost/url/decode_view.hpp>
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator!=(
S const& lhs,
decode_view const& rhs) noexcept;Return Value
true if decoded lhs is not equal to the decoded rhs
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
Compare two decode views for inequality
Synopsis
Declared in <boost/url/decode_view.hpp>
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator!=(
decode_view const& lhs,
S const& rhs) noexcept;Return Value
true if decoded lhs is not equal to the decoded rhs
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
Compare two decode views for inequality
Synopsis
Declared in <boost/url/decode_view.hpp>
constexpr
bool
operator!=(
decode_view const& lhs,
decode_view const& rhs) noexcept;Return Value
true if decoded lhs is not equal to the decoded rhs
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
Return the result of comparing two URLs
Synopsis
Declared in <boost/url/url_view_base.hpp>
bool
operator!=(
url_view_base const& u0,
url_view_base const& u1) noexcept;Description
The URLs are compared component by component as if they were first normalized.
Example
url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.b.com/index.htm" );
assert( u0 != u1 );Effects
url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() != b.buffer();Complexity
Linear in min( u0.size(), u1.size() )
Exception Safety
Throws nothing
Return Value
true if u0 != u1
Parameters
Name |
Description |
u0 |
The first url to compare |
u1 |
The second url to compare |
Return the result of comparing two authorities. The authorities are compared component by component as if they were first normalized.
Synopsis
Declared in <boost/url/authority_view.hpp>
bool
operator!=(
authority_view const& a0,
authority_view const& a1) noexcept;Description
Complexity
Linear in min( a0.size(), a1.size() )
Exception Safety
Throws nothing
Return Value
true if a0 != a1, otherwise false
Parameters
Name |
Description |
a0 |
The first authority to compare |
a1 |
The second authority to compare |
Less‐than operators
Synopses
Declared in <boost/url/authority_view.hpp>
Compare two decode views for less than
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator<(
S const& lhs,
decode_view const& rhs) noexcept;Compare two decode views for less than
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator<(
decode_view const& lhs,
S const& rhs) noexcept;Compare two decode views for less than
constexpr
bool
operator<(
decode_view const& lhs,
decode_view const& rhs) 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;Return Value
-
trueif decodedlhsis less than to the decodedrhs -
trueifu0 < u1 -
trueifa0 < a1, otherwisefalse
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
u0 |
The first url to compare |
u1 |
The second url to compare |
a0 |
The first authority to compare |
a1 |
The second authority to compare |
Compare two decode views for less than
Synopsis
Declared in <boost/url/decode_view.hpp>
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator<(
S const& lhs,
decode_view const& rhs) noexcept;Return Value
true if decoded lhs is less than to the decoded rhs
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
Compare two decode views for less than
Synopsis
Declared in <boost/url/decode_view.hpp>
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator<(
decode_view const& lhs,
S const& rhs) noexcept;Return Value
true if decoded lhs is less than to the decoded rhs
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
Compare two decode views for less than
Synopsis
Declared in <boost/url/decode_view.hpp>
constexpr
bool
operator<(
decode_view const& lhs,
decode_view const& rhs) noexcept;Return Value
true if decoded lhs is less than to the decoded rhs
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
Return the result of comparing two URLs
Synopsis
Declared in <boost/url/url_view_base.hpp>
bool
operator<(
url_view_base const& u0,
url_view_base const& u1) noexcept;Description
The URLs are compared component by component as if they were first normalized.
Example
url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.b.com/index.htm" );
assert( u0 < u1 );Effects
url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() < b.buffer();Complexity
Linear in min( u0.size(), u1.size() )
Exception Safety
Throws nothing
Return Value
true if u0 < u1
Parameters
Name |
Description |
u0 |
The first url to compare |
u1 |
The second url to compare |
Return the result of comparing two authorities. The authorities are compared component by component as if they were first normalized.
Synopsis
Declared in <boost/url/authority_view.hpp>
bool
operator<(
authority_view const& a0,
authority_view const& a1) noexcept;Description
Complexity
Linear in min( a0.size(), a1.size() )
Exception Safety
Throws nothing
Return Value
true if a0 < a1, otherwise false
Parameters
Name |
Description |
a0 |
The first authority to compare |
a1 |
The second authority to compare |
Less‐than‐or‐equal operators
Synopses
Declared in <boost/url/authority_view.hpp>
Compare two decode views for less than or equal
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator<=(
S const& lhs,
decode_view const& rhs) noexcept;Compare two decode views for less than or equal
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator<=(
decode_view const& lhs,
S const& rhs) noexcept;Compare two decode views for less than or equal
constexpr
bool
operator<=(
decode_view const& lhs,
decode_view const& rhs) 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;Return Value
-
trueif decodedlhsis less than or equal to the decodedrhs -
trueifu0 <= u1 -
trueifa0 <= a1, otherwisefalse
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
u0 |
The first url to compare |
u1 |
The second url to compare |
a0 |
The first authority to compare |
a1 |
The second authority to compare |
Compare two decode views for less than or equal
Synopsis
Declared in <boost/url/decode_view.hpp>
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator<=(
S const& lhs,
decode_view const& rhs) noexcept;Return Value
true if decoded lhs is less than or equal to the decoded rhs
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
Compare two decode views for less than or equal
Synopsis
Declared in <boost/url/decode_view.hpp>
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator<=(
decode_view const& lhs,
S const& rhs) noexcept;Return Value
true if decoded lhs is less than or equal to the decoded rhs
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
Compare two decode views for less than or equal
Synopsis
Declared in <boost/url/decode_view.hpp>
constexpr
bool
operator<=(
decode_view const& lhs,
decode_view const& rhs) noexcept;Return Value
true if decoded lhs is less than or equal to the decoded rhs
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
Return the result of comparing two URLs
Synopsis
Declared in <boost/url/url_view_base.hpp>
bool
operator<=(
url_view_base const& u0,
url_view_base const& u1) noexcept;Description
The URLs are compared component by component as if they were first normalized.
Example
url_view u0( "http://www.b.com/index.htm" );
url_view u1( "http://www.b.com/index.htm" );
assert( u0 <= u1 );Effects
url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() <= b.buffer();Complexity
Linear in min( u0.size(), u1.size() )
Exception Safety
Throws nothing
Return Value
true if u0 <= u1
Parameters
Name |
Description |
u0 |
The first url to compare |
u1 |
The second url to compare |
Return the result of comparing two authorities. The authorities are compared component by component as if they were first normalized.
Synopsis
Declared in <boost/url/authority_view.hpp>
bool
operator<=(
authority_view const& a0,
authority_view const& a1) noexcept;Description
Complexity
Linear in min( a0.size(), a1.size() )
Exception Safety
Throws nothing
Return Value
true if a0 <= a1, otherwise false
Parameters
Name |
Description |
a0 |
The first authority to compare |
a1 |
The second authority to compare |
Greater‐than operators
Synopses
Declared in <boost/url/authority_view.hpp>
Compare two decode views for greater than
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator>(
S const& lhs,
decode_view const& rhs) noexcept;Compare two decode views for greater than
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator>(
decode_view const& lhs,
S const& rhs) noexcept;Compare two decode views for greater than
constexpr
bool
operator>(
decode_view const& lhs,
decode_view const& rhs) 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;Return Value
-
trueif decodedlhsis greater than to the decodedrhs -
trueifu0 > u1 -
trueifa0 > a1, otherwisefalse
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
u0 |
The first url to compare |
u1 |
The second url to compare |
a0 |
The first authority to compare |
a1 |
The second authority to compare |
Compare two decode views for greater than
Synopsis
Declared in <boost/url/decode_view.hpp>
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator>(
S const& lhs,
decode_view const& rhs) noexcept;Return Value
true if decoded lhs is greater than to the decoded rhs
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
Compare two decode views for greater than
Synopsis
Declared in <boost/url/decode_view.hpp>
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator>(
decode_view const& lhs,
S const& rhs) noexcept;Return Value
true if decoded lhs is greater than to the decoded rhs
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
Compare two decode views for greater than
Synopsis
Declared in <boost/url/decode_view.hpp>
constexpr
bool
operator>(
decode_view const& lhs,
decode_view const& rhs) noexcept;Return Value
true if decoded lhs is greater than to the decoded rhs
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
Return the result of comparing two URLs
Synopsis
Declared in <boost/url/url_view_base.hpp>
bool
operator>(
url_view_base const& u0,
url_view_base const& u1) noexcept;Description
The URLs are compared component by component as if they were first normalized.
Example
url_view u0( "http://www.b.com/index.htm" );
url_view u1( "http://www.a.com/index.htm" );
assert( u0 > u1 );Effects
url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() > b.buffer();Complexity
Linear in min( u0.size(), u1.size() )
Exception Safety
Throws nothing
Return Value
true if u0 > u1
Parameters
Name |
Description |
u0 |
The first url to compare |
u1 |
The second url to compare |
Return the result of comparing two authorities. The authorities are compared component by component as if they were first normalized.
Synopsis
Declared in <boost/url/authority_view.hpp>
bool
operator>(
authority_view const& a0,
authority_view const& a1) noexcept;Description
Complexity
Linear in min( a0.size(), a1.size() )
Exception Safety
Throws nothing
Return Value
true if a0 > a1, otherwise false
Parameters
Name |
Description |
a0 |
The first authority to compare |
a1 |
The second authority to compare |
Greater‐than‐or‐equal operators
Synopses
Declared in <boost/url/authority_view.hpp>
Compare two decode views for greater than or equal
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator>=(
S const& lhs,
decode_view const& rhs) noexcept;Compare two decode views for greater than or equal
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator>=(
decode_view const& lhs,
S const& rhs) noexcept;Compare two decode views for greater than or equal
constexpr
bool
operator>=(
decode_view const& lhs,
decode_view const& rhs) 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;Return Value
-
trueif decodedlhsis greater than or equal to the decodedrhs -
trueifu0 >= u1 -
trueifa0 >= a1, otherwisefalse
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
u0 |
The first url to compare |
u1 |
The second url to compare |
a0 |
The first authority to compare |
a1 |
The second authority to compare |
Compare two decode views for greater than or equal
Synopsis
Declared in <boost/url/decode_view.hpp>
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator>=(
S const& lhs,
decode_view const& rhs) noexcept;Return Value
true if decoded lhs is greater than or equal to the decoded rhs
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
Compare two decode views for greater than or equal
Synopsis
Declared in <boost/url/decode_view.hpp>
template<std::convertible_to<core::string_view> S>
constexpr
bool
operator>=(
decode_view const& lhs,
S const& rhs) noexcept;Return Value
true if decoded lhs is greater than or equal to the decoded rhs
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
Compare two decode views for greater than or equal
Synopsis
Declared in <boost/url/decode_view.hpp>
constexpr
bool
operator>=(
decode_view const& lhs,
decode_view const& rhs) noexcept;Return Value
true if decoded lhs is greater than or equal to the decoded rhs
Parameters
Name |
Description |
lhs |
The left‐hand‐side decode view to compare |
rhs |
The right‐hand‐side decode view to compare |
Return the result of comparing two URLs
Synopsis
Declared in <boost/url/url_view_base.hpp>
bool
operator>=(
url_view_base const& u0,
url_view_base const& u1) noexcept;Description
The URLs are compared component by component as if they were first normalized.
Example
url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.a.com/index.htm" );
assert( u0 >= u1 );Effects
url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() >= b.buffer();Complexity
Linear in min( u0.size(), u1.size() )
Exception Safety
Throws nothing
Return Value
true if u0 >= u1
Parameters
Name |
Description |
u0 |
The first url to compare |
u1 |
The second url to compare |
Return the result of comparing two authorities. The authorities are compared component by component as if they were first normalized.
Synopsis
Declared in <boost/url/authority_view.hpp>
bool
operator>=(
authority_view const& a0,
authority_view const& a1) noexcept;Description
Complexity
Linear in min( a0.size(), a1.size() )
Exception Safety
Throws nothing
Return Value
true if a0 >= a1, otherwise false
Parameters
Name |
Description |
a0 |
The first authority to compare |
a1 |
The second authority to compare |
Rule for absolute‐URI
Synopsis
Declared in <boost/url/rfc/absolute_uri_rule.hpp>
inline constexpr /* implementation-defined */ absolute_uri_rule = {};Description
Value Type
using value_type = url_view;Example
Rules are used with the function grammar::parse.
system::result< url_view > rv = grammar::parse( "http://example.com/index.htm?id=1", absolute_uri_rule );BNF
absolute-URI = scheme ":" hier-part [ "?" query ]
hier-part = "//" authority path-abempty
/ path-absolute
/ path-rootless
/ path-emptySee Also
Rule for authority
Synopsis
Declared in <boost/url/rfc/authority_rule.hpp>
constexpr /* implementation-defined */ authority_rule = {};Description
Value Type
using value_type = authority_view;Example
Rules are used with the function grammar::parse.
system::result< authority_view > rv = grammar::parse( "user:pass@example.com:8080", authority_rule );BNF
authority = [ userinfo "@" ] host [ ":" port ]See Also
The gen‐delims character set
Synopsis
Declared in <boost/url/rfc/gen_delim_chars.hpp>
constexpr grammar::lut_chars gen_delim_chars = ":/?#[]@";Description
Example
Character sets are used with rules and 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 ) );BNF
gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@"See Also
Ignore case when comparing
Synopsis
Declared in <boost/url/ignore_case.hpp>
inline constexpr /* implementation-defined */ ignore_case = {};Description
This value may be optionally passed to functions accepting a parameter of type ignore_case_param to indicate that comparisons should be case‐insensitive.
Rule for an IP version 4 style address
Synopsis
Declared in <boost/url/rfc/ipv4_address_rule.hpp>
constexpr /* implementation-defined */ ipv4_address_rule = {};Description
Value Type
using value_type = ipv4_address;Example
Rules are used with the function grammar::parse.
system::result< ipv4_address > rv = grammar::parse( "192.168.0.1", ipv4_address_rule );BNF
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-255Specification
See Also
Rule for An IP version 6 style address
Synopsis
Declared in <boost/url/rfc/ipv6_address_rule.hpp>
constexpr /* implementation-defined */ ipv6_address_rule = {};Description
Value Type
using value_type = ipv6_address;Example
Rules are used with the function grammar::parse.
system::result< ipv6_address > rv = grammar::parse( "2001:0db8:85a3:0000:0000:8a2e:0370:7334", ipv6_address_rule );BNF
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 hexadecimalSpecification
See Also
Constant indicating no value in a param
Synopsis
Synopsis
Declared in <boost/url/rfc/origin_form_rule.hpp>
inline constexpr /* implementation-defined */ origin_form_rule = {};Description
This appears in the HTTP/1 request‐line grammar.
Value Type
using value_type = url_view;Example
Rules are used with the function grammar::parse.
system::result< url_view > rv = grammar::parse( "/index.htm?layout=mobile", origin_form_rule );BNF
origin-form = absolute-path [ "?" query ]
absolute-path = 1*( "/" segment )See Also
The path character set
Synopsis
Declared in <boost/url/rfc/pchars.hpp>
constexpr auto pchars = unreserved_chars + sub_delim_chars + ':' + '@';Description
Example
Character sets are used with rules and the functions grammar::find_if and grammar::find_if_not.
system::result< decode_view > rv = grammar::parse( "Program%20Files", pchars );BNF
pchar = unreserved / pct-encoded / sub-delims / ":" / "@"See Also
Rule for a query string
Synopsis
Declared in <boost/url/rfc/query_rule.hpp>
constexpr /* implementation-defined */ query_rule = {};Description
Value Type
using value_type = params_encoded_view;Example
Rules are used with the function grammar::parse.
system::result< params_encoded_view > rv = grammar::parse( "format=web&id=42&compact", query_rule );BNF
query = *( pchar / "/" / "?" )
query-params = [ query-param ] *( "&" query-param )
query-param = key [ "=" value ]
key = *qpchar
value = *( qpchar / "=" )
qpchar = unreserved
/ pct-encoded
/ "!" / "$" / "'" / "(" / ")"
/ "*" / "+" / "," / ";"
/ ":" / "@" / "/" / "?"See Also
Rule for relative‐ref
Synopsis
Declared in <boost/url/rfc/relative_ref_rule.hpp>
constexpr /* implementation-defined */ relative_ref_rule = {};Description
Value Type
using value_type = url_view;Example
Rules are used with the function grammar::parse.
system::result< url_view > rv = grammar::parse( "images/dot.gif?v=hide#a", relative_ref_rule );BNF
relative-ref = relative-part [ "?" query ] [ "#" fragment ]See Also
The reserved character set
Synopsis
Declared in <boost/url/rfc/reserved_chars.hpp>
constexpr auto reserved_chars = ~unreserved_chars;Description
Example
Character sets are used with rules and the functions grammar::find_if and grammar::find_if_not.
system::result< decode_view > rv = grammar::parse( "Program%20Files", pct_encoded_rule( reserved_chars ) );See Also
The sub‐delims character set
Synopsis
Declared in <boost/url/rfc/sub_delim_chars.hpp>
constexpr grammar::lut_chars sub_delim_chars = "!$&()*+,;=\x27";Description
Example
Character sets are used with rules and the functions grammar::find_if and grammar::find_if_not.
system::result< decode_view > = grammar::parse( "Program%20Files", pct_encoded_rule( sub_delim_chars ) );BNF
sub-delims = "!" / "$" / "&" / "'" / "(" / ")"
/ "*" / "+" / "," / ";" / "="See Also
The unreserved character set
Synopsis
Declared in <boost/url/rfc/unreserved_chars.hpp>
constexpr grammar::lut_chars unreserved_chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
"abcdefghijklmnopqrstuvwxyz"
"0123456789"
"‐._~";Description
Example
Character sets are used with rules and the functions grammar::find_if and grammar::find_if_not.
system::result< decode_view > rv = grammar::parse( "Program%20Files", pct_encoded_rule( unreserved_chars ) );BNF
unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"See Also
Rule for URI‐reference
Synopsis
Declared in <boost/url/rfc/uri_reference_rule.hpp>
constexpr /* implementation-defined */ uri_reference_rule = {};Description
Value Type
using value_type = url_view;Example
Rules are used with the function grammar::parse.
system::result< url_view > rv = grammar::parse( "ws://echo.example.com/?name=boost#demo", uri_reference_rule );BNF
URI-reference = URI / relative-ref
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
relative-ref = relative-part [ "?" query ] [ "#" fragment ]Specification
See Also
Rule for URI
Synopsis
Declared in <boost/url/rfc/uri_rule.hpp>
constexpr /* implementation-defined */ uri_rule = {};Description
Value Type
using value_type = url_view;Example
Rules are used with the function grammar::parse.
system::result< url_view > rv = grammar::parse( "https://www.example.com/index.htm?id=guest#s1", uri_rule );BNF
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]Specification
See Also
Created with MrDocs