The set of constants used for cross-platform error codes This alias is no longer supported and should not be used in new code. Please use core::string_view instead. This alias is included for backwards compatibility with earlier versions of the library. However, it will be removed in future releases, and using it in new code is not recommended. Please use the updated version instead to ensure compatibility with future versions of the library. The type of error category used by the library This alias is no longer supported and should not be used in new code. Please use system::error_category instead. This alias is included for backwards compatibility with earlier versions of the library. However, it will be removed in future releases, and using it in new code is not recommended. Please use the updated version instead to ensure compatibility with future versions of the library. The type of error code used by the library This alias is no longer supported and should not be used in new code. Please use system::error_code instead. This alias is included for backwards compatibility with earlier versions of the library. However, it will be removed in future releases, and using it in new code is not recommended. Please use the updated version instead to ensure compatibility with future versions of the library. The type of error condition used by the library This alias is no longer supported and should not be used in new code. Please use system::error_condition instead. This alias is included for backwards compatibility with earlier versions of the library. However, it will be removed in future releases, and using it in new code is not recommended. Please use the updated version instead to ensure compatibility with future versions of the library. The type of system error thrown by the library This alias is no longer supported and should not be used in new code. Please use system::system_error instead. This alias is included for backwards compatibility with earlier versions of the library. However, it will be removed in future releases, and using it in new code is not recommended. Please use the updated version instead to ensure compatibility with future versions of the library. A function to return the generic error category used by the library This alias is no longer supported and should not be used in new code. Please use core::string_view instead. This alias is included for backwards compatibility with earlier versions of the library. However, it will be removed in future releases, and using it in new code is not recommended. Please use the updated version instead to ensure compatibility with future versions of the library. A function to return the system error category used by the library This alias is no longer supported and should not be used in new code. Please use core::string_view instead. This alias is included for backwards compatibility with earlier versions of the library. However, it will be removed in future releases, and using it in new code is not recommended. Please use the updated version instead to ensure compatibility with future versions of the library. A case-insensitive equals predicate for strings The function object returns true when two strings are equal, ignoring case. This is a suitable equality predicate for unordered containers. The function is defined only for strings containing low-ASCII characters. 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) ci_hash , ci_less . A case-insensitive hash function object for strings The hash function is non-cryptographic and not hardened against algorithmic complexity attacks. This is a suitable hash function for unordered containers. The function is defined only for strings containing low-ASCII characters. 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) ci_equal , ci_less . A case-insensitive less predicate for strings The comparison algorithm implements a case-insensitive total order on the set of all ASCII strings; however, it is not a lexicographical comparison. This is a suitable predicate for ordered containers. The function is defined only for strings containing low-ASCII characters. Example boost::container::map< std::string, std::string, ci_less > m1; std::map< std::string, std::string, ci_less > m2; // (since C++14) ci_equal , ci_hash . Match a string literal exactly 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" ) ); delim_rule , parse . Construct from char The value to construct from A set of characters 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 ) ); find_if , find_if_not , parse , token_rule . Constructor 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. A character. Constructor 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. A null-terminated string. Return true if ch is in the character set. This function returns true if the character ch is in the set, otherwise it returns false. Complexity Constant. Exception Safety Throws nothing. true if ch is in the set. The character to test. Return true if ch is in the character set. This function returns true if the character ch is in the set, otherwise it returns false. Complexity Constant. Exception Safety Throws nothing. true if ch is in the set. The character to test. Return a new character set which is the complement of another character set. 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. The new character set. Common functionality for string views 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 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 Access a character See core::string_view::at The character at the position The position to access Return the last character See core::string_view::back The last character Return an iterator to the beginning See core::string_view::begin An iterator to the beginning Return an iterator to the beginning See core::string_view::cbegin An iterator to the beginning Return an iterator to the end See core::string_view::cend An iterator to the end Return the result of comparing to another string See core::string_view::compare The result of the comparison The string to compare Return the result of comparing to another string See core::string_view::compare The result of the comparison The string to compare Return the result of comparing to another string See core::string_view::compare The result of the comparison The position to start comparing from The number of characters to compare The string to compare Return the result of comparing to another string See core::string_view::compare The result of the comparison The position to start comparing from The number of characters to compare The string to compare Return the result of comparing to another string See core::string_view::compare The result of the comparison The position to start comparing from The number of characters to compare The string to compare The number of characters to compare Return the result of comparing to another string See core::string_view::compare The result of the comparison The position to start comparing from The number of characters to compare The string to compare The position to start comparing from The number of characters to compare Return true if matching characters are found See core::string_view::contains true if the string contains the characters, otherwise false The string to search for Return true if matching characters are found See core::string_view::contains true if the string contains the character, otherwise false The character to search for Return true if matching characters are found See core::string_view::contains true if the string contains the characters, otherwise false The string to search for Copy the characters to another buffer See core::string_view::copy The number of characters copied The destination buffer The number of characters to copy The position to start from Return a reverse iterator to the end See core::string_view::crbegin A reverse iterator to the end Return a reverse iterator to the beginning See core::string_view::crend A reverse iterator to the beginning Return a pointer to the character buffer See core::string_view::data A pointer to the character buffer Return true if the string is empty See core::string_view::size true if the string is empty Return an iterator to the end See core::string_view::end An iterator to the end Return true if a matching suffix exists See core::string_view::ends_with true if the suffix matches The string to search for Return true if a matching suffix exists See core::string_view::ends_with true if the suffix matches The character to search for Return true if a matching suffix exists See core::string_view::ends_with true if the suffix matches The string to search for Return the position of matching characters See core::string_view::find The position of the first match The characters to search for The position to start searching from Return the position of matching characters See core::string_view::find The position of the first match The character to search for The position to start searching from Return the position of matching characters See core::string_view::find The position of the first match The characters to search for The position to start searching from Return the position of matching characters See core::string_view::find The position of the first match The characters to search for The position to start searching from The number of characters to search for Return the position of the first non-match See core::string_view::find_first_not_of The position of the first non-match The characters to search for The position to start searching from Return the position of the first non-match See core::string_view::find_first_not_of The position of the first non-match The character to search for The position to start searching from Return the position of the first non-match See core::string_view::find_first_not_of The position of the first non-match The characters to search for The position to start searching from Return the position of the first non-match See core::string_view::find_first_not_of The position of the first non-match The characters to search for The position to start searching from The number of characters to search for Return the position of the first match See core::string_view::find_first_of The position of the first match The characters to search for The position to start searching from Return the position of the first match See core::string_view::find_first_of The position of the first match The character to search for The position to start searching from Return the position of the first match See core::string_view::find_first_of The position of the first match The characters to search for The position to start searching from Return the position of the first match See core::string_view::find_first_of The position of the first match The characters to search for The position to start searching from The number of characters to search for Return the position of the last non-match See core::string_view::find_last_not_of The position of the last non-match The characters to search for The position to start searching from Return the position of the last non-match See core::string_view::find_last_not_of The position of the last non-match The character to search for The position to start searching from Return the position of the last non-match See core::string_view::find_last_not_of The position of the last non-match The characters to search for The position to start searching from Return the position of the last non-match See core::string_view::find_last_not_of The position of the last non-match The characters to search for The position to start searching from The number of characters to search for Return the position of the last match See core::string_view::find_last_of The position of the last match The characters to search for The position to start searching from Return the position of the last match See core::string_view::find_last_of The position of the last match The character to search for The position to start searching from Return the position of the last match See core::string_view::find_last_of The position of the last match The characters to search for The position to start searching from Return the position of the last match See core::string_view::find_last_of The position of the last match The characters to search for The position to start searching from The number of characters to search for Return the first character See core::string_view::front The first character Return the size See core::string_view::length The size Return the maximum allowed size See core::string_view::max_size The maximum allowed size Access a character See core::string_view::operator[] The character at the position The position to access Return a reverse iterator to the end See core::string_view::rbegin A reverse iterator to the end Return a reverse iterator to the beginning See core::string_view::rend A reverse iterator to the beginning Return the position of matching characters See core::string_view::rfind The position of the first match The characters to search for The position to start searching from Return the position of matching characters See core::string_view::rfind The position of the first match The character to search for The position to start searching from Return the position of matching characters See core::string_view::rfind The position of the first match The characters to search for The position to start searching from Return the position of matching characters See core::string_view::rfind The position of the first match The characters to search for The position to start searching from The number of characters to search for Return the size See core::string_view::size The size Return true if a matching prefix exists See core::string_view::starts_with true if the prefix matches The string to search for Return true if a matching prefix exists See core::string_view::starts_with true if the prefix matches The character to search for Return true if a matching prefix exists See core::string_view::starts_with true if the prefix matches The string to search for Return a view to part of the string See core::string_view::substr A view to the substring The position to start from The number of characters Conversion Conversion to std::string is explicit because assigning to string using an implicit constructor does not preserve capacity. A string with the same contents Conversion A string view with the same contents A constant used to represent "no position" Constructor Constructor The object to copy construct from Constructor The string view Constructor The character buffer The number of characters Assignment A reference to this object The object to assign Swap The object to swap with The referenced character buffer Error conditions for errors received from rules error , parse . A fatal error in syntax was encountered. This indicates that parsing cannot continue. Error codes returned when using rules condition , parse . More input is needed to match the rule A rule reached the end of the input, resulting in a partial match. The error is recoverable; the caller may obtain more input if possible and attempt to parse the character buffer again. Custom rules should only return this error if it is completely unambiguous that the rule cannot be matched without more input. The rule did not match the input. This error is returned when a rule fails to match the input. The error is recoverable; the caller may rewind the input pointer and attempt to parse again using a different rule. A rule reached the end of a range This indicates that the input was consumed when parsing a range . The range_rule avoids rewinding the input buffer when this error is returned. Thus the consumed characters are be considered part of the range without contributing additional elements. Leftover input remaining after match. A rule encountered unrecoverable invalid input. This error is returned when input is matching but one of the requirements is violated. For example if a percent escape is found, but one or both characters that follow are not valid hexadecimal digits. This is usually an unrecoverable error. An integer overflowed during parsing. An unspecified syntax error was found. Return the case-insensitive comparison of s0 and s1 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. 0 if the strings are equal, -1 if s0 is less than s1 , or 1 if s0 is greater than s1. The first string The second string ci_is_equal , ci_is_less . Return the case-insensitive digest of a string 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. The digest The string Return true if s0 equals s1 using case-insensitive comparison The function is defined only for strings containing low-ASCII characters. Example assert( ci_is_equal( "Boost", "boost" ) ); true if s0 case-insensitively equals s1 , otherwise false The first string The second string ci_compare , ci_is_less . Return true if s0 is less than s1 using case-insensitive comparison 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" ) ); true if s0 is case-insensitively less than s1 , otherwise false The first string The second string ci_compare , ci_is_equal . Match a character literal 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-FF A rule which matches the character. The character to match parse , squelch . Return the decimal value of a hex character 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" The decimal value or -1 The character to check Return the union of two character sets. 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. The new character set. A character to join A character to join Return a new character set by subtracting 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. The new character set. A character set to join. A character set to join. Return c converted to lowercase This function returns the character, converting it to lowercase if it is uppercase. The function is defined only for low-ASCII characters. Example assert( to_lower( 'A' ) == 'a' ); Exception Safety Throws nothing. The converted character The character to convert to_upper . Return c converted to uppercase This function returns the character, converting it to uppercase if it is lowercase. The function is defined only for low-ASCII characters. Example assert( to_upper( 'a' ) == 'A' ); Exception Safety Throws nothing. The converted character The character to convert to_lower . Format a string to an output stream Format a string to an output stream A reference to the output stream, for chaining The output stream to write to The string to write The set of all characters 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-FF find_if , find_if_not , parse , token_rule . The set of letters and digits 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-9 Specification B.1. Core Rules (rfc5234) find_if , find_if_not , parse , token_rule . The set of all letters 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-z Specification B.1. Core Rules (rfc5234) find_if , find_if_not , parse , token_rule . Match a decimal octet 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-255 Specification 3.2.2. Host (rfc3986) parse . The set of decimal digits 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-9 Specification B.1. Core Rules (rfc5234) find_if , find_if_not , parse , token_rule . The set of hexadecimal digits 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" The RFCs are inconsistent on the case sensitivity of hexadecimal digits. Existing uses suggest case-insensitivity is a de-facto standard. Specification B.1. Core Rules (rfc5234) 1.2. Syntax Notation (rfc7230) 2.3. Uppercase or Lowercase (rfc5952) 4.3. Lowercase (rfc5952) find_if , find_if_not , hexdig_value , parse , token_rule . The set of visible characters 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) characters Specification B.1. Core Rules (rfc5234) find_if , find_if_not , parse , token_rule . A string token for returning a plain string 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 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. Default constructor Deleted copy constructor The object to copy construct from Default move constructor The object to move construct from Virtual destructor Deleted copy assignment Reference to the current object The object to copy assign from Deleted move assignment Reference to the current object The object to move assign from Return a modifiable character buffer This function attempts to obtain a character buffer with space for at least n characters. Upon success, a pointer to the beginning of the buffer is returned. Ownership is not transferred; the caller should not attempt to free the storage. The buffer shall remain valid until this is destroyed. This function may only be called once. After invoking the function, the only valid operation is destruction. A pointer to the buffer The number of characters needed A temporary reference to a formatting argument 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 . format , format_to , arg . The type of string_view used by the library String views are used to pass character buffers into or out of functions. Ownership of the underlying character buffer is not transferred; the caller is responsible for ensuring that the lifetime of character buffer extends until it is no longer referenced. This alias is no longer supported and should not be used in new code. Please use core::string_view instead. This alias is included for backwards compatibility with earlier versions of the library. However, it will be removed in future releases, and using it in new code is not recommended. Please use the updated version instead to ensure compatibility with future versions of the library. A non-owning reference to a valid authority 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 = *DIGIT Specification 3.2. Authority (rfc3986) parse_authority . parse_authority Constructor 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 The object to copy construct from Construct from a string. 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 = *DIGIT Specification 3.2. Authority (rfc3986) The string to parse parse_authority . Destructor Assignment This function assigns the contents of other to this object. Exception Safety Throws nothing. A reference to this object The object to assign Return the complete authority 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. Specification 3.2. Authority (rfc3986) The complete authority Return the result of comparing this with another authority This function compares two authorities according to Syntax-Based comparison algorithm. Exception Safety Throws nothing. Specification 6.2.2 Syntax-Based Normalization (rfc3986) -1 if *this < other , 0 if this == other , and 1 if this > other . The authority to compare Return a pointer to the first character This function returns a pointer to the beginning of the view, which is not guaranteed to be null-terminated. Exception Safety Throws nothing. A pointer to the first character Return true if the authority is empty An empty authority has an empty host, no userinfo, and no port. Example assert( authority_view( "" ).empty() ); Exception Safety Throws nothing. true if the authority is empty Return the host This function returns the host portion of the authority as a string, or the empty string if there is no authority. The returned string may contain percent escapes. 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 / "-" / ".") Specification 3.2.2. Host (rfc3986) The host Return the host 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 / "-" / ".") Specification 3.2.2. Host (rfc3986) The host address Return the host and port 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 3.2.2. Host (rfc3986) 3.2.3. Port (rfc3986) The host and port has_port , port , port_number . Return the host name 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 / "-" / ".") Specification 3.2.2. Host (rfc3986) The host name Return the password 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 / ":" ) Specification 3.2.1. User Information (rfc3986) The password has_password , has_userinfo , encoded_user , encoded_userinfo , password , user , userinfo . Return the user If present, this function returns a string representing the user (which may be empty). Otherwise it returns an empty string. The returned string may contain percent escapes. 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 / ":" ) Specification 3.2.1. User Information (rfc3986) The user has_password , has_userinfo , encoded_password , encoded_userinfo , password , user , userinfo . Return the userinfo 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 ] Specification 3.2.1. User Information (rfc3986) The userinfo has_password , has_userinfo , encoded_password , encoded_user , password , user , userinfo . Return true if a password is present 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 / ":" ) Specification 3.2.1. User Information (rfc3986) true if a password is present has_userinfo , encoded_password , encoded_user , encoded_userinfo , password , user , userinfo . Return true if a port is present 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 = *DIGIT Specification 3.2.3. Port (rfc3986) true if a port is present, otherwise false encoded_host_and_port , port , port_number . Return true if a userinfo is present 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 ] Specification 3.2.1. User Information (rfc3986) true if a userinfo is present has_password , encoded_password , encoded_user , encoded_userinfo , password , user , userinfo . Return the host IPv4 address If the host type is host_type::ipv4 , this function returns the address as a value of type ipv4_address . Otherwise, if the host type is not an IPv4 address, it returns a default-constructed value which is equal to the unspecified address "0.0.0.0". 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-255 Specification 3.2.2. Host (rfc3986) The host IPv4 address Return the host IPv6 address If the host type is host_type::ipv6 , this function returns the address as a value of type ipv6_address . Otherwise, if the host type is not an IPv6 address, it returns a default-constructed value which is equal to the unspecified address "0:0:0:0:0:0:0:0". 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 hexadecimal Specification 3.2.2. Host (rfc3986) The host IPv6 address Return the host IPvFuture address 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 / ":" ) Specification 3.2.2. Host (rfc3986) The host IPvFuture address Return the host type 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. Specification 3.2.2. Host (rfc3986) The host type Return the port 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 = *DIGIT Specification 3.2.3. Port (rfc3986) The port as a string encoded_host_and_port , has_port , port_number . Return the port If a port is present and the numerical value is representable, it is returned as an unsigned integer. Otherwise, the number zero is returned. Example assert( url_view( "http://localhost.com:8080" ).port_number() == 8080 ); Complexity Constant. Exception Safety Throws nothing. BNF port = *DIGIT Specification 3.2.3. Port (rfc3986) The port number encoded_host_and_port , has_port , port . Return the number of characters in the authority 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. The number of characters in the authority A reference to a valid, percent-encoded string 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. 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 The signed integer type The reference type The unsigned integer type The value type An iterator of constant, decoded characters. This iterator is used to access the encoded string as a bidirectional range of characters with percent-decoding applied. Escape sequences are not decoded until the iterator is dereferenced. Constructor Default-constructed views represent empty strings. Example decode_view ds; Postconditions this->empty() == true Complexity Constant. Exception Safety Throws nothing. Constructor 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() == s Complexity 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. A percent-encoded string that has already been validated. Implicit conversion from other string types is supported but may throw exceptions. The options for decoding. If this parameter is omitted, the default options are used. Return the last character Example assert( decode_view( "Program%20Files" ).back() == 's' ); Preconditions not this->empty() Complexity Constant. Exception Safety Throws nothing. The last decoded character Return an iterator to the beginning Example auto it = this->begin(); Complexity Constant. Exception Safety Throws nothing. An iterator to the first decoded character Return the result of comparing to another string The length of the sequences to compare is the smaller of size() and other.size() . The function compares the two strings as if by calling char_traits<char>::compare(to_string().data(), v.to_string().data(), rlen) . This means the comparison is performed with percent-decoding applied to the current string. 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 string to compare Return the result of comparing to another string The length of the sequences to compare is the smaller of size() and other.size() . The function compares the two strings as if by calling char_traits<char>::compare(to_string().data(), v.data(), rlen) . This means the comparison is performed with percent-decoding applied to the current string. 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 string to compare Return true if the string is empty Example assert( decode_view( "" ).empty() ); Complexity Constant. Exception Safety Throws nothing. true if the string is empty Return an iterator to the end Example auto it = this->end(); Complexity Constant. Exception Safety Throws nothing. An iterator to one past the last decoded character Checks if the string ends with the given prefix Example assert( decode_view( "Program%20Files" ).ends_with("Files") ); Complexity Linear. Exception Safety Throws nothing. true if the decoded string ends with s The string to search for Checks if the string ends with the given prefix Example assert( decode_view( "Program%20Files" ).ends_with('s') ); Complexity Constant. Exception Safety Throws nothing. true if the decoded string ends with ch The character to search for Finds the first occurrence of character in this view Complexity Linear. Exception Safety Throws nothing. An iterator to the first decoded occurrence of ch or end() The character to search for Return the first character Example assert( decode_view( "Program%20Files" ).front() == 'P' ); Preconditions not this->empty() Complexity Constant. Exception Safety Throws nothing. The first decoded character Return the decoding options The decoding options used by this view Remove the first characters Example decode_view d( "Program%20Files" ); d.remove_prefix( 8 ); assert( d == "Files" ); Preconditions not this->empty() Complexity Linear. The number of characters to remove Remove the last characters Example decode_view d( "Program%20Files" ); d.remove_prefix( 6 ); assert( d == "Program" ); Preconditions not this->empty() Complexity Linear. The number of characters to remove Finds the first occurrence of character in this view Complexity Linear. Exception Safety Throws nothing. An iterator to the last occurrence of ch or end() The character to search for Return the number of decoded characters Example assert( decode_view( "Program%20Files" ).size() == 13 ); Effects return std::distance( this->begin(), this->end() ); Complexity Constant. Exception Safety Throws nothing. The number of decoded characters Checks if the string begins with the given prefix Example assert( decode_view( "Program%20Files" ).starts_with("Program") ); Complexity Linear. Exception Safety Throws nothing. true if the decoded string starts with s The string to search for Checks if the string begins with the given prefix Example assert( decode_view( "Program%20Files" ).starts_with('P') ); Complexity Constant. Exception Safety Throws nothing. true if the decoded string starts with ch The character to search for Percent-encoding options These options are used to customize the behavior of algorithms which use percent escapes, such as encoding or decoding. encode , encoded_size , pct_string_view . Constructs an encoding_opts object with the specified options. If true, spaces will be encoded as plus signs. If true, hexadecimal digits will be emitted as lower case. If true, null characters will not be allowed. True if nulls are not allowed Normally all possible character values (from 0 to 255) are allowed, with reserved characters being replaced with escapes upon encoding. When this option is true, attempting to decode a null will result in an error. True if hexadecimal digits are emitted as lower case By default, percent-encoding algorithms emit hexadecimal digits A through F as uppercase letters. When this option is true , lowercase letters are used. True if spaces encode to and from plus signs 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 application/x-www-form-urlencoded (w3.org) The form-urlencoded Media Type (RFC 1866) Section 6.2.2.2. Percent-Encoding Normalization (RFC 3986) An optional parameter to determine case-sensitivity 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. params_ref Constructor By default, comparisons are case-sensitive. Example This function performs case-sensitive comparisons when called with no arguments: void f( ignore_case_param = {} ); Constructor 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) ); The object to construct from True if an algorithm should ignore case Values of type ignore_case_param evaluate to true when constructed with the constant ignore_case . Otherwise, they are default-constructed and evaluate to false . true if case should be ignored An IP version 4 style address. 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-255 Specification IPv4 (Wikipedia) 3.2.2. Host (rfc3986) parse_ipv4_address , ipv6_address . parse_ipv4_address The type used to represent an address as an array of bytes The type used to represent an address as an unsigned integer Constructor. Constructor. The object to copy construct from Construct from a string. This function constructs an address from the string s , which must contain a valid IPv4 address string or else an exception is thrown. For a non-throwing parse function, use parse_ipv4_address . Exception Safety Exceptions thrown on invalid input. Specification 3.2.2. Host (rfc3986) The string to parse. The input failed to parse correctly. parse_ipv4_address . Construct from an unsigned integer. This function constructs an address from the unsigned integer u , where the most significant byte forms the first octet of the resulting address. The integer to construct from. Construct from an array of bytes. This function constructs an address from the array in bytes , which is interpreted in big-endian. The value to construct from. Copy Assignment. A reference to this object. The object to copy. Return true if the address is a loopback address true if the address is a loopback address Return true if the address is a multicast address true if the address is a multicast address Return true if the address is unspecified true if the address is unspecified Write a dotted decimal string representing the address to a buffer The resulting buffer is not null-terminated. The formatted string The buffer in which to write, which must have at least dest_size space. The size of the output buffer. dest_size < ipv4_address::max_str_len Return the address as bytes, in network byte order. The address as an array of bytes. Return the address as an unsigned integer. The address as an unsigned integer. Return an address object that represents any address The any address. Return an address object that represents the broadcast address The broadcast address. Return an address object that represents the loopback address The loopback address. The number of characters in the longest possible IPv4 string. The longest ipv4 address string is "255.255.255.255". An IP version 6 style address. 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 hexadecimal Specification IP Version 6 Addressing Architecture (rfc4291) 3.2.2. Host (rfc3986) ipv4_address , parse_ipv6_address . parse_ipv6_address The type used to represent an address as an array of bytes. Octets are stored in network byte order. Constructor. Default constructed objects represent the unspecified address. 2.5.2. The Unspecified Address is_unspecified Constructor. The object to copy construct from Construct from a string. This function constructs an address from the string s , which must contain a valid IPv6 address string or else an exception is thrown. For a non-throwing parse function, use parse_ipv6_address . Exception Safety Exceptions thrown on invalid input. Specification 3.2.2. Host (rfc3986) The string to parse. The input failed to parse correctly. parse_ipv6_address . Construct from an array of bytes. This function constructs an address from the array in bytes , which is interpreted in big-endian. The value to construct from. Construct from an IPv4 address. This function constructs an IPv6 address from the IPv4 address addr . The resulting address is an IPv4-Mapped IPv6 Address. Specification 2.5.5.2. IPv4-Mapped IPv6 Address (rfc4291) The address to construct from. Copy Assignment *this The object to copy assign from Return true if the address is a loopback address The unicast address 0:0:0:0:0:0:0:1 is called the loopback address. It may be used by a node to send an IPv6 packet to itself. Specification 2.5.3. The Loopback Address (rfc4291) true if the address is a loopback address Return true if the address is unspecified The address 0:0:0:0:0:0:0:0 is called the unspecified address. It indicates the absence of an address. Specification 2.5.2. The Unspecified Address (rfc4291) true if the address is unspecified Return true if the address is a mapped IPv4 address This address type is used to represent the addresses of IPv4 nodes as IPv6 addresses. Specification 2.5.5.2. IPv4-Mapped IPv6 Address (rfc4291) true if the address is a mapped IPv4 address Write a dotted decimal string representing the address to a buffer The resulting buffer is not null-terminated. The formatted string The buffer in which to write, which must have at least dest_size space. The size of the output buffer. dest_size < ipv6_address::max_str_len Return the address as bytes, in network byte order The address as an array of bytes. Return an address object that represents the loopback address The unicast address 0:0:0:0:0:0:0:1 is called the loopback address. It may be used by a node to send an IPv6 packet to itself. Specification 2.5.3. The Loopback Address (rfc4291) The loopback address. The number of characters in the longest possible IPv6 string. The longest IPv6 address is: ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff to_buffer . The type of no_value A query parameter 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 Query string (Wikipedia) param_view , param_pct_view . Constructor Default constructed query parameters have an empty key and no value. Example param qp; Postconditions this->key == "" && this->value == "" && this->has_value == false Complexity Constant. Exception Safety Throws nothing. Constructor Upon construction, this becomes a copy of other . Postconditions this->key == other.key && this->value == other.value && this->has_value == other.has_value Complexity Linear in other.key.size() + other.value.size() . Exception Safety Calls to allocate may throw. A reference to this object. The object to construct from. Constructor 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. The object to construct from. Aggregate construction The key to set. The value to set. True if a value is present. Assignment Upon assignment, this becomes a copy of other . Postconditions this->key == other.key && this->value == other.value && this->has_value == other.has_value Complexity Linear in other.key.size() + other.value.size() . Exception Safety Calls to allocate may throw. A reference to this object. The object to assign from. Assignment 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. A reference to this object. The object to assign from. Assignment 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_value Complexity Linear in other.key.size() + other.value.size() . Exception Safety Calls to allocate may throw. A reference to this object. The parameter to copy. Assignment 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_value Complexity Linear in other.key.size() + other.value.size() . Exception Safety Calls to allocate may throw. A reference to this object. The parameter to copy. Arrow support This operator returns the address of the object so that it can be used in pointer contexts. A pointer to the object. True if a value is present The presence of a value is indicated by has_value == true . An empty value is distinct from no value. The key For most usages, key comparisons are case-sensitive and duplicate keys in a query are possible. However, it is the authority that has final control over how the query is interpreted. The value The presence of a value is indicated by has_value equal to true. An empty value is distinct from no value. A view of a percent-encoded query parameter 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 Query string (Wikipedia) param , param_view . Constructor Default constructed query parameters have an empty key and no value. Example param_pct_view qp; Postconditions this->key == "" && this->value == "" && this->has_value == false Complexity Constant. Exception Safety Throws nothing. Construction This converts a param which may contain unvalidated percent-escapes into a param whose key and value are guaranteed to contain strings with no invalid percent-escapes, otherwise an exception is thrown. The new key and value reference the same corresponding underlying character buffers. Ownership of the buffers is not transferred; the caller is responsible for ensuring that the assigned buffers remain valid until they are no longer referenced. Example param_pct_view qp( param_view( "key", "value" ) ); Complexity Linear in key.size() + value.size() . Exception Safety Exceptions thrown on invalid input. The param to construct from. key or value contains an invalid percent escape. Constructor 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 == true Complexity Linear in key.size() + value.size() . Exception Safety Exceptions thrown on invalid input. The key to set. The value to set. key or value contains an invalid percent-encoding. Aggregate construction The key The value True if a value is present Arrow support This operator returns the address of the object so that it can be used in pointer contexts. A pointer to this object Conversion 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. A param object Conversion to param_view 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. A param_view object True if a value is present The presence of a value is indicated by has_value == true . An empty value is distinct from no value. The key For most usages, key comparisons are case-sensitive and duplicate keys in a query are possible. However, it is the authority that has final control over how the query is interpreted. The value The presence of a value is indicated by has_value equal to true. An empty value is distinct from no value. A view of a query parameter 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 Query string (Wikipedia) param , param_pct_view . Constructor Default constructed query parameters have an empty key and no value. Example param_view qp; Postconditions this->key == "" && this->value == "" && this->has_value == false Complexity Constant. Exception Safety Throws nothing. Constructor This function constructs a param which references the character buffers representing the key and value in another container. Ownership of the buffers is not transferred; the caller is responsible for ensuring that the assigned buffers remain valid until they are no longer referenced. Example param qp( "key", "value" ); param_view qpv( qp ); Postconditions this->key == key && this->value == value && this->has_value == other.has_value Complexity Constant. Exception Safety Throws nothing. The param to reference Aggregate construction The key to set. The value to set. True if a value is present. Arrow support This operator returns the address of the object so that it can be used in pointer contexts. A pointer to the object. Conversion This function performs a conversion from a reference-like query parameter to one retaining ownership of the strings by making a copy. No validation is performed on the strings. Complexity Linear in this->key.size() + this->value.size() . Exception Safety Calls to allocate may throw. A new query parameter. True if a value is present The presence of a value is indicated by has_value == true . An empty value is distinct from no value. The key For most usages, key comparisons are case-sensitive and duplicate keys in a query are possible. However, it is the authority that has final control over how the query is interpreted. The value The presence of a value is indicated by has_value equal to true. An empty value is distinct from no value. Common functionality for query parameter containers 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 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 This is the type of value returned when iterators of the view are dereferenced. param_view . A signed integer type used to represent differences. The reference type This is the type of value returned when iterators of the view are dereferenced. param_view . An unsigned integer type to represent sizes. The value type 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" ) ); param . A Bidirectional iterator to a query parameter Objects of this type allow iteration through the parameters in the query. Any percent-escapes in returned strings are decoded first. The values returned are read-only; changes to parameters must be made through the container instead, if the container supports modification. The strings produced when iterators are dereferenced belong to the iterator and become invalidated when that particular iterator is incremented, decremented, or destroyed. The implementation may use temporary, recycled storage to store decoded strings. These iterators are meant to be used ephemerally. That is, for short durations such as within a function scope. Do not store iterators with static storage duration or as long-lived objects. Return an iterator to the beginning Complexity Linear in the size of the first param. Exception Safety Throws nothing. An iterator to the beginning. Return the referenced character buffer. 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. The buffer. Return true if a matching key exists 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. true if a matching key exists. The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Return the number of matching keys 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. The number of matching keys. The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Return true if there are no params Example assert( ! url_view( "?key=value" ).params().empty() ); Complexity Constant. Exception Safety Throws nothing. true if there are no params. Return an iterator to the end Complexity Constant. Exception Safety Throws nothing. An iterator to the end. Find a matching key 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() . an iterator to the param The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Find a matching key 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() . an iterator to the param The position to begin the search from. This can be end() . The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Find a matching key 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() . an iterator to the param The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Find a matching key 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() . an iterator to the param One past the position to begin the search from. This can be end() . The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Return the number of params Example assert( url_view( "?key=value").params().size() == 1 ); Complexity Constant. Exception Safety Throws nothing. The number of params. Return the maximum number of characters possible This represents the largest number of characters that are possible in a path, not including any null terminator. Exception Safety Throws nothing. The maximum number of characters possible. Common functionality for containers This base class is used by the library to provide common member functions for containers. This cannot be instantiated directly; Instead, use one of the containers or functions: Containers params_ref params_view params_encoded_ref params_encoded_view A Bidirectional iterator to a query parameter Objects of this type allow iteration through the parameters in the query. Strings returned by iterators may contain percent escapes. The values returned are read-only; changes to parameters must be made through the container instead, if the container supports modification. The strings produced when iterators are dereferenced refer to the underlying character buffer. Ownership is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced by any container or iterator. The reference type This is the type of value returned when iterators of the view are dereferenced. param_view . A signed integer type used to represent differences. The reference type This is the type of value returned when iterators of the view are dereferenced. param_view . An unsigned integer type to represent sizes. The value type 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" ) ); param . A Bidirectional iterator to a query parameter Objects of this type allow iteration through the parameters in the query. Strings returned by iterators may contain percent escapes. The values returned are read-only; changes to parameters must be made through the container instead, if the container supports modification. The strings produced when iterators are dereferenced refer to the underlying character buffer. Ownership is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced by any container or iterator. Return an iterator to the beginning Complexity Linear in the size of the first param. Exception Safety Throws nothing. An iterator to the beginning. Return the query corresponding to these params 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 Query string (Wikipedia) The query string. Return true if a matching key exists 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. true if a matching key exists. The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. key contains an invalid percent-encoding. Return the number of matching keys 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. The number of matching keys. The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. key contains an invalid percent-encoding. Return true if there are no params Example assert( ! url_view( "?key=value" ).encoded_params().empty() ); Complexity Constant. Exception Safety Throws nothing. true if there are no params. Return an iterator to the end Complexity Constant. Exception Safety Throws nothing. An iterator to the end. Find a matching key 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. an iterator to the param The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. key contains an invalid percent-encoding. Find a matching key 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. an iterator to the param The position to begin the search from. This can be end() . The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. key contains an invalid percent-encoding. Find a matching key 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. an iterator to the param The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. key contains an invalid percent-encoding. Find a matching key 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() . an iterator to the param One past the position to begin the search from. This can be end() . The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Return the number of params Example assert( url_view( "?key=value").encoded_params().size() == 1 ); Complexity Constant. Exception Safety Throws nothing. The number of params. Return the maximum number of characters possible This represents the largest number of characters that are possible in a path, not including any null terminator. Exception Safety Throws nothing. The maximum number of characters possible. A view representing query parameters in a URL 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 : Only `end()`. assign , clear , `operator=` : All params. erase : Erased params and all params after (including `end()`). insert : All params at or after the insertion point (including `end()`). replace , set : Modified params and all params after (including `end()`). A Bidirectional iterator to a query parameter Objects of this type allow iteration through the parameters in the query. Strings returned by iterators may contain percent escapes. The values returned are read-only; changes to parameters must be made through the container instead, if the container supports modification. The strings produced when iterators are dereferenced refer to the underlying character buffer. Ownership is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced by any container or iterator. The reference type This is the type of value returned when iterators of the view are dereferenced. param_view . A signed integer type used to represent differences. The reference type This is the type of value returned when iterators of the view are dereferenced. param_view . An unsigned integer type to represent sizes. The value type 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" ) ); param . A Bidirectional iterator to a query parameter Objects of this type allow iteration through the parameters in the query. Strings returned by iterators may contain percent escapes. The values returned are read-only; changes to parameters must be made through the container instead, if the container supports modification. The strings produced when iterators are dereferenced refer to the underlying character buffer. Ownership is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced by any container or iterator. Constructor 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. The other view. Assignment The previous contents of this are replaced by the contents of `other. All iterators are invalidated. The strings referenced by other must not come from the underlying url, or else the behavior is undefined. Effects this->assign( other.begin(), other.end() ); Complexity Linear in other.buffer().size() . Exception Safety Strong guarantee. Calls to allocate may throw. *this The params to assign. Assignment 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. *this The list of params to assign. init contains an invalid percent-encoding. Append params 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. An iterator to the first new element. The list of params to append. init contains an invalid percent-encoding. Append params 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. An iterator to the new element. The param to append. p contains an invalid percent-encoding. Assign params This function replaces the entire contents of the view with the params in the initializer-list . All iterators are invalidated. The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. 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. The list of params to assign. init contains an invalid percent-encoding. Return an iterator to the beginning Complexity Linear in the size of the first param. Exception Safety Throws nothing. An iterator to the beginning. Return the query corresponding to these params 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 Query string (Wikipedia) The query string. Clear the contents of the container All iterators are invalidated. Effects this->url().remove_query(); Postconditions this->empty() == true && this->url().has_query() == false Complexity Constant. Exception Safety Throws nothing. Return true if a matching key exists 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. true if a matching key exists. The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. key contains an invalid percent-encoding. Return the number of matching keys 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. The number of matching keys. The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. key contains an invalid percent-encoding. Return true if there are no params Example assert( ! url_view( "?key=value" ).encoded_params().empty() ); Complexity Constant. Exception Safety Throws nothing. true if there are no params. Return an iterator to the end Complexity Constant. Exception Safety Throws nothing. An iterator to the end. Erase params 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. An iterator to one past the removed element. An iterator to the element. Erase params 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. An iterator to one past the removed range. An iterator to one past the removed range. The first element to remove. One past the last element to remove. Erase params All iterators are invalidated. Postconditions this->count( key, ic ) == 0 Complexity Linear in this->url().encoded_query().size() . Exception Safety Exceptions thrown on invalid input. The number of params removed from the container. The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. key contains an invalid percent-encoding. Find a matching key 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. an iterator to the param The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. key contains an invalid percent-encoding. Find a matching key 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. an iterator to the param The position to begin the search from. This can be end() . The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. key contains an invalid percent-encoding. Find a matching key 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. an iterator to the param The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. key contains an invalid percent-encoding. Find a matching key 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() . an iterator to the param One past the position to begin the search from. This can be end() . The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Insert params This function inserts the params in an initializer-list before the specified position. All iterators that are equal to before or come after are invalidated. The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. Complexity Linear in this->url().encoded_query().size() . Exception Safety Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input. An iterator to the first element inserted, or before if init.size() == 0 . An iterator before which the element is inserted. This may be equal to end() . The list of params to insert. init contains an invalid percent-encoding. Insert params 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. An iterator to the inserted element. An iterator before which the param is inserted. This may be equal to end() . The param to insert. p contains an invalid percent-encoding. Replace params This function replaces the contents of the element at pos with the specified param. All iterators that are equal to pos or come after are invalidated. The strings passed in must not come from the element being replaced, or else the behavior is undefined. 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. An iterator to the element. An iterator to the element. The param to assign. p contains an invalid percent-encoding. Replace params This function replaces a range of params with the params in an initializer-list . All iterators that are equal to from or come after are invalidated. The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. Complexity Linear in this->url().encoded_query().size() . Exception Safety Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input. An iterator to the first element inserted, or one past to if init.size() == 0 . The range of params to replace. The list of params to assign. init contains an invalid percent-encoding. Set a value This function replaces the value of an element at the specified position. All iterators that are equal to pos or come after are invalidated. The string passed in must not come from the element being replaced, or else the behavior is undefined. 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. An iterator to the element. An iterator to the element. The value to assign. The empty string still counts as a value. That is, has_value for the element is true. value contains an invalid percent-encoding. Set a value 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 `key` is not contained in the view, then the function apppends the param `{ key, value }`. All iterators are invalidated. 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 == value Complexity Linear in this->url().encoded_query().size() . Exception Safety Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input. An iterator to the appended or modified element. The key to match. By default, a case-sensitive comparison is used. The value to assign. The empty string still counts as a value. That is, has_value for the element is true. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. key or value contain an invalid percent-encoding. Return the number of params Example assert( url_view( "?key=value").encoded_params().size() == 1 ); Complexity Constant. Exception Safety Throws nothing. The number of params. Remove the value on an element This function removes the value of an element at the specified position. After the call returns, has_value for the element is false. All iterators that are equal to pos or come after are invalidated. 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. An iterator to the element. An iterator to the element. Return the referenced url This function returns the url referenced by the view. Example url u( "?key=value" ); assert( &u.encoded_params().url() == &u ); Exception Safety Throws nothing. A reference to the url. Conversion Complexity Constant. Exception Safety Throws nothing. A view of the params. Return the maximum number of characters possible This represents the largest number of characters that are possible in a path, not including any null terminator. Exception Safety Throws nothing. The maximum number of characters possible. A view representing query parameters in a URL 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. A Bidirectional iterator to a query parameter Objects of this type allow iteration through the parameters in the query. Strings returned by iterators may contain percent escapes. The values returned are read-only; changes to parameters must be made through the container instead, if the container supports modification. The strings produced when iterators are dereferenced refer to the underlying character buffer. Ownership is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced by any container or iterator. The reference type This is the type of value returned when iterators of the view are dereferenced. param_view . A signed integer type used to represent differences. The reference type This is the type of value returned when iterators of the view are dereferenced. param_view . An unsigned integer type to represent sizes. The value type 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" ) ); param . A Bidirectional iterator to a query parameter Objects of this type allow iteration through the parameters in the query. Strings returned by iterators may contain percent escapes. The values returned are read-only; changes to parameters must be made through the container instead, if the container supports modification. The strings produced when iterators are dereferenced refer to the underlying character buffer. Ownership is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced by any container or iterator. Constructor Default-constructed params have zero elements. Example params_encoded_view qp; Effects return params_encoded_view( "" ); Complexity Constant. Exception Safety Throws nothing. Constructor 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 The object to copy Constructor This function constructs params from a valid query parameter string, which can contain percent escapes. Unlike the parameters in URLs, the string passed here should not start with "?". Upon construction, the view references the character buffer pointed to by s . The caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced. 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 ] Specification 3.4. Query The string to parse. s contains an invalid query parameter string. Assignment 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 *this The object to assign Return an iterator to the beginning Complexity Linear in the size of the first param. Exception Safety Throws nothing. An iterator to the beginning. Return the query corresponding to these params 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 Query string (Wikipedia) The query string. Return true if a matching key exists 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. true if a matching key exists. The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. key contains an invalid percent-encoding. Return the number of matching keys 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. The number of matching keys. The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. key contains an invalid percent-encoding. Return true if there are no params Example assert( ! url_view( "?key=value" ).encoded_params().empty() ); Complexity Constant. Exception Safety Throws nothing. true if there are no params. Return an iterator to the end Complexity Constant. Exception Safety Throws nothing. An iterator to the end. Find a matching key 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. an iterator to the param The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. key contains an invalid percent-encoding. Find a matching key 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. an iterator to the param The position to begin the search from. This can be end() . The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. key contains an invalid percent-encoding. Find a matching key 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. an iterator to the param The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. key contains an invalid percent-encoding. Find a matching key 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() . an iterator to the param One past the position to begin the search from. This can be end() . The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Return the number of params Example assert( url_view( "?key=value").encoded_params().size() == 1 ); Complexity Constant. Exception Safety Throws nothing. The number of params. Conversion This conversion returns a new view which references the same underlying character buffer, and whose iterators and members return ordinary strings with decoding applied to any percent escapes. Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced. 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 A new view with percent escapes decoded. Return the maximum number of characters possible This represents the largest number of characters that are possible in a path, not including any null terminator. Exception Safety Throws nothing. The maximum number of characters possible. A view representing query parameters in a URL 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 : Only `end()`. assign , clear , `operator=` : All elements. erase : Erased elements and all elements after (including `end()`). insert : All elements at or after the insertion point (including `end()`). replace , set : Modified elements and all elements after (including `end()`). A Bidirectional iterator to a query parameter Objects of this type allow iteration through the parameters in the query. Any percent-escapes in returned strings are decoded first. The values returned are read-only; changes to parameters must be made through the container instead, if the container supports modification. The strings produced when iterators are dereferenced belong to the iterator and become invalidated when that particular iterator is incremented, decremented, or destroyed. The implementation may use temporary, recycled storage to store decoded strings. These iterators are meant to be used ephemerally. That is, for short durations such as within a function scope. Do not store iterators with static storage duration or as long-lived objects. The reference type This is the type of value returned when iterators of the view are dereferenced. param_view . A signed integer type used to represent differences. The reference type This is the type of value returned when iterators of the view are dereferenced. param_view . An unsigned integer type to represent sizes. The value type 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" ) ); param . A Bidirectional iterator to a query parameter Objects of this type allow iteration through the parameters in the query. Any percent-escapes in returned strings are decoded first. The values returned are read-only; changes to parameters must be made through the container instead, if the container supports modification. The strings produced when iterators are dereferenced belong to the iterator and become invalidated when that particular iterator is incremented, decremented, or destroyed. The implementation may use temporary, recycled storage to store decoded strings. These iterators are meant to be used ephemerally. That is, for short durations such as within a function scope. Do not store iterators with static storage duration or as long-lived objects. Constructor 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. The other view. Constructor 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. The other view. The options for decoding. If this parameter is omitted, space_as_plus is used. Assignment The previous contents of this are replaced by the contents of `other. All iterators are invalidated. The strings referenced by other must not come from the underlying url, or else the behavior is undefined. Effects this->assign( other.begin(), other.end() ); Complexity Linear in other.buffer().size() . Exception Safety Strong guarantee. Calls to allocate may throw. *this The params to assign. Assignment 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. *this The list of params to assign. Append elements 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. An iterator to the first new element. The list of params to append. Append elements 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. An iterator to the new element. The param to append. Assign elements This function replaces the entire contents of the view with the params in the initializer-list . All iterators are invalidated. The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. Example url u; u.params().assign( {{ "first", "John" }, { "last", "Doe" }} ); Complexity Linear in init.size() . Exception Safety Strong guarantee. Calls to allocate may throw. The list of params to assign. Return an iterator to the beginning Complexity Linear in the size of the first param. Exception Safety Throws nothing. An iterator to the beginning. Return the referenced character buffer. 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. The buffer. Clear the contents of the container All iterators are invalidated. Effects this->url().remove_query(); Postconditions this->empty() == true && this->url().has_query() == false Complexity Constant. Exception Safety Throws nothing. Return true if a matching key exists 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. true if a matching key exists. The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Return the number of matching keys 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. The number of matching keys. The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Return true if there are no params Example assert( ! url_view( "?key=value" ).params().empty() ); Complexity Constant. Exception Safety Throws nothing. true if there are no params. Return an iterator to the end Complexity Constant. Exception Safety Throws nothing. An iterator to the end. Erase elements 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. An iterator to one past the removed element. An iterator to the element. Erase elements 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. An iterator to one past the removed range. The first element to remove. One past the last element to remove. Erase elements All iterators are invalidated. Postconditions this->count( key, ic ) == 0 Complexity Linear in this->url().encoded_query().size() . Exception Safety Throws nothing. The number of elements removed from the container. The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Find a matching key 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() . an iterator to the param The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Find a matching key 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() . an iterator to the param The position to begin the search from. This can be end() . The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Find a matching key 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() . an iterator to the param The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Find a matching key 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() . an iterator to the param One past the position to begin the search from. This can be end() . The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Insert elements This function inserts the params in an initializer-list before the specified position. All iterators that are equal to before or come after are invalidated. The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. Complexity Linear in this->url().encoded_query().size() . Exception Safety Strong guarantee. Calls to allocate may throw. An iterator to the first element inserted, or before if init.size() == 0 . An iterator before which the element is inserted. This may be equal to end() . The list of params to insert. Insert elements 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. An iterator to the inserted element. An iterator before which the param is inserted. This may be equal to end() . The param to insert. Replace elements 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. An iterator to the element. An iterator to the element. The param to assign. Replace elements This function replaces a range of elements with the params in an initializer-list . All iterators that are equal to from or come after are invalidated. The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined. Complexity Linear in this->url().encoded_query().size() . Exception Safety Strong guarantee. Calls to allocate may throw. An iterator to the first element inserted, or one past to if init.size() == 0 . The range of elements to replace. The list of params to assign. Set a value This function replaces the value of an element at the specified position. All iterators that are equal to pos or come after are invalidated. 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. An iterator to the element. An iterator to the element. The value to assign. The empty string still counts as a value. That is, has_value for the element is true. Set a value 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 `key` is 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 == value Complexity Linear in this->url().encoded_query().size() . Exception Safety Strong guarantee. Calls to allocate may throw. An iterator to the appended or modified element. The key to match. By default, a case-sensitive comparison is used. The value to assign. The empty string still counts as a value. That is, has_value for the element is true. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Return the number of params Example assert( url_view( "?key=value").params().size() == 1 ); Complexity Constant. Exception Safety Throws nothing. The number of params. Remove the value on an element This function removes the value of an element at the specified position. After the call returns, has_value for the element is false. All iterators that are equal to pos or come after are invalidated. 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. An iterator to the element. An iterator to the element. Return the referenced url This function returns the url referenced by the view. Example url u( "?key=value" ); assert( &u.segments().url() == &u ); Exception Safety Throws nothing. A reference to the url. Conversion A view of the query parameters. Return the maximum number of characters possible This represents the largest number of characters that are possible in a path, not including any null terminator. Exception Safety Throws nothing. The maximum number of characters possible. A view representing query parameters in a URL 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. A Bidirectional iterator to a query parameter Objects of this type allow iteration through the parameters in the query. Any percent-escapes in returned strings are decoded first. The values returned are read-only; changes to parameters must be made through the container instead, if the container supports modification. The strings produced when iterators are dereferenced belong to the iterator and become invalidated when that particular iterator is incremented, decremented, or destroyed. The implementation may use temporary, recycled storage to store decoded strings. These iterators are meant to be used ephemerally. That is, for short durations such as within a function scope. Do not store iterators with static storage duration or as long-lived objects. The reference type This is the type of value returned when iterators of the view are dereferenced. param_view . A signed integer type used to represent differences. The reference type This is the type of value returned when iterators of the view are dereferenced. param_view . An unsigned integer type to represent sizes. The value type 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" ) ); param . A Bidirectional iterator to a query parameter Objects of this type allow iteration through the parameters in the query. Any percent-escapes in returned strings are decoded first. The values returned are read-only; changes to parameters must be made through the container instead, if the container supports modification. The strings produced when iterators are dereferenced belong to the iterator and become invalidated when that particular iterator is incremented, decremented, or destroyed. The implementation may use temporary, recycled storage to store decoded strings. These iterators are meant to be used ephemerally. That is, for short durations such as within a function scope. Do not store iterators with static storage duration or as long-lived objects. Constructor Default-constructed params have zero elements. Example params_view qp; Effects return params_view( "" ); Complexity Constant. Exception Safety Throws nothing. Constructor 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 The object to copy Constructor This function constructs params from a valid query parameter string, which can contain percent escapes. Unlike the parameters in URLs, the string passed here should not start with "?". Upon construction, the view references the character buffer pointed to by s . The caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced. 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 ] Specification 3.4. Query The string to parse. s contains an invalid query parameter string. Constructor 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 ] Specification 3.4. Query The string to parse. The options for decoding. If this parameter is omitted, space_as_plus is used. s contains an invalid query parameter string. Constructor 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 The object to copy The options for decoding Assignment 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 A reference to this object The object to assign Return an iterator to the beginning Complexity Linear in the size of the first param. Exception Safety Throws nothing. An iterator to the beginning. Return the referenced character buffer. 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. The buffer. Return true if a matching key exists 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. true if a matching key exists. The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Return the number of matching keys 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. The number of matching keys. The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Return true if there are no params Example assert( ! url_view( "?key=value" ).params().empty() ); Complexity Constant. Exception Safety Throws nothing. true if there are no params. Return an iterator to the end Complexity Constant. Exception Safety Throws nothing. An iterator to the end. Find a matching key 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() . an iterator to the param The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Find a matching key 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() . an iterator to the param The position to begin the search from. This can be end() . The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Find a matching key 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() . an iterator to the param The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Find a matching key 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() . an iterator to the param One past the position to begin the search from. This can be end() . The key to match. By default, a case-sensitive comparison is used. An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive. Return the number of params Example assert( url_view( "?key=value").params().size() == 1 ); Complexity Constant. Exception Safety Throws nothing. The number of params. Return the maximum number of characters possible This represents the largest number of characters that are possible in a path, not including any null terminator. Exception Safety Throws nothing. The maximum number of characters possible. A reference to a valid percent-encoded string 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. 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 Constructor Default constructed string are empty. Complexity Constant. Exception Safety Throws nothing. Constructor The copy references the same underlying character buffer. Ownership is not transferred. Postconditions this->data() == other.data() Complexity Constant. Exception Safety Throws nothing. The string to copy. Constructor (deleted) The object to construct from Constructor 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. The string to construct from. The string contains an invalid percent encoding. Constructor The newly constructed string references the specified character buffer. Ownership is not transferred. Postconditions this->data() == s && this->size() == len Complexity Linear in len . Exception Safety Exceptions thrown on invalid input. The string to construct from. The length of the string. The string contains an invalid percent encoding. Assignment The copy references the same underlying character buffer. Ownership is not transferred. Postconditions this->data() == other.data() Complexity Constant. Exception Safety Throws nothing. A reference to this object. The string to copy. Access a character See core::string_view::at The character at the position The position to access Return the last character See core::string_view::back The last character Return an iterator to the beginning See core::string_view::begin An iterator to the beginning Return an iterator to the beginning See core::string_view::cbegin An iterator to the beginning Return an iterator to the end See core::string_view::cend An iterator to the end Return the result of comparing to another string See core::string_view::compare The result of the comparison The string to compare Return the result of comparing to another string See core::string_view::compare The result of the comparison The string to compare Return the result of comparing to another string See core::string_view::compare The result of the comparison The position to start comparing from The number of characters to compare The string to compare Return the result of comparing to another string See core::string_view::compare The result of the comparison The position to start comparing from The number of characters to compare The string to compare Return the result of comparing to another string See core::string_view::compare The result of the comparison The position to start comparing from The number of characters to compare The string to compare The number of characters to compare Return the result of comparing to another string See core::string_view::compare The result of the comparison The position to start comparing from The number of characters to compare The string to compare The position to start comparing from The number of characters to compare Return true if matching characters are found See core::string_view::contains true if the string contains the characters, otherwise false The string to search for Return true if matching characters are found See core::string_view::contains true if the string contains the character, otherwise false The character to search for Return true if matching characters are found See core::string_view::contains true if the string contains the characters, otherwise false The string to search for Copy the characters to another buffer See core::string_view::copy The number of characters copied The destination buffer The number of characters to copy The position to start from Return a reverse iterator to the end See core::string_view::crbegin A reverse iterator to the end Return a reverse iterator to the beginning See core::string_view::crend A reverse iterator to the beginning Return a pointer to the character buffer See core::string_view::data A pointer to the character buffer Return the decoded size 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. The number of characters in the decoded string. Return true if the string is empty See core::string_view::size true if the string is empty Return an iterator to the end See core::string_view::end An iterator to the end Return true if a matching suffix exists See core::string_view::ends_with true if the suffix matches The string to search for Return true if a matching suffix exists See core::string_view::ends_with true if the suffix matches The character to search for Return true if a matching suffix exists See core::string_view::ends_with true if the suffix matches The string to search for Return the position of matching characters See core::string_view::find The position of the first match The characters to search for The position to start searching from Return the position of matching characters See core::string_view::find The position of the first match The character to search for The position to start searching from Return the position of matching characters See core::string_view::find The position of the first match The characters to search for The position to start searching from Return the position of matching characters See core::string_view::find The position of the first match The characters to search for The position to start searching from The number of characters to search for Return the position of the first non-match See core::string_view::find_first_not_of The position of the first non-match The characters to search for The position to start searching from Return the position of the first non-match See core::string_view::find_first_not_of The position of the first non-match The character to search for The position to start searching from Return the position of the first non-match See core::string_view::find_first_not_of The position of the first non-match The characters to search for The position to start searching from Return the position of the first non-match See core::string_view::find_first_not_of The position of the first non-match The characters to search for The position to start searching from The number of characters to search for Return the position of the first match See core::string_view::find_first_of The position of the first match The characters to search for The position to start searching from Return the position of the first match See core::string_view::find_first_of The position of the first match The character to search for The position to start searching from Return the position of the first match See core::string_view::find_first_of The position of the first match The characters to search for The position to start searching from Return the position of the first match See core::string_view::find_first_of The position of the first match The characters to search for The position to start searching from The number of characters to search for Return the position of the last non-match See core::string_view::find_last_not_of The position of the last non-match The characters to search for The position to start searching from Return the position of the last non-match See core::string_view::find_last_not_of The position of the last non-match The character to search for The position to start searching from Return the position of the last non-match See core::string_view::find_last_not_of The position of the last non-match The characters to search for The position to start searching from Return the position of the last non-match See core::string_view::find_last_not_of The position of the last non-match The characters to search for The position to start searching from The number of characters to search for Return the position of the last match See core::string_view::find_last_of The position of the last match The characters to search for The position to start searching from Return the position of the last match See core::string_view::find_last_of The position of the last match The character to search for The position to start searching from Return the position of the last match See core::string_view::find_last_of The position of the last match The characters to search for The position to start searching from Return the position of the last match See core::string_view::find_last_of The position of the last match The characters to search for The position to start searching from The number of characters to search for Return the first character See core::string_view::front The first character Return the size See core::string_view::length The size Return the maximum allowed size See core::string_view::max_size The maximum allowed size Return the string as a range of decoded characters Complexity Constant. Exception Safety Throws nothing. A range of decoded characters. decode_view . Arrow support A pointer to this object. Access a character See core::string_view::operator[] The character at the position The position to access Return a reverse iterator to the end See core::string_view::rbegin A reverse iterator to the end Return a reverse iterator to the beginning See core::string_view::rend A reverse iterator to the beginning Return the position of matching characters See core::string_view::rfind The position of the first match The characters to search for The position to start searching from Return the position of matching characters See core::string_view::rfind The position of the first match The character to search for The position to start searching from Return the position of matching characters See core::string_view::rfind The position of the first match The characters to search for The position to start searching from Return the position of matching characters See core::string_view::rfind The position of the first match The characters to search for The position to start searching from The number of characters to search for Return the size See core::string_view::size The size Return true if a matching prefix exists See core::string_view::starts_with true if the prefix matches The string to search for Return true if a matching prefix exists See core::string_view::starts_with true if the prefix matches The character to search for Return true if a matching prefix exists See core::string_view::starts_with true if the prefix matches The string to search for Return a view to part of the string See core::string_view::substr A view to the substring The position to start from The number of characters Swap The object to swap with Conversion Conversion to std::string is explicit because assigning to string using an implicit constructor does not preserve capacity. A string with the same contents Conversion A string view with the same contents A constant used to represent "no position" Assignment A reference to this object The object to assign Swap The object to swap with The referenced character buffer Common functionality for containers This base class is used by the library to provide common member functions for containers. This cannot be instantiated directly; Instead, use one of the containers or functions: Containers segments_ref segments_view segments_encoded_ref segments_encoded_view A Bidirectional iterator to a path segment Objects of this type allow iteration through the segments in the path. Any percent-escapes in returned strings are decoded first. The values returned are read-only; changes to segments must be made through the container instead, if the container supports modification. The strings produced when iterators are dereferenced belong to the iterator and become invalidated when that particular iterator is incremented, decremented, or destroyed. The reference type This is the type of value returned when iterators of the view are dereferenced. A signed integer type used to represent differences. The reference type This is the type of value returned when iterators of the view are dereferenced. An unsigned integer type used to represent size. The value type 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 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 Preconditions this->empty() == false Example assert( url_view( "/path/to/file.txt" ).segments().back() == "file.txt" ); Preconditions this->empty() == false Effects return *--end(); Complexity Linear in this->back().size() . Exception Safety Calls to allocate may throw. The last segment. Return an iterator to the beginning Complexity Linear in this->front().size() or constant if this->empty() . Exception Safety Throws nothing. An iterator to the first segment. Return the referenced character buffer. 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. A string containing the path. Return true if there are no segments Example assert( ! url_view( "/index.htm" ).segments().empty() ); Complexity Constant. Exception Safety Throws nothing. true if there are no segments, otherwise false . Return an iterator to the end Complexity Constant. Exception Safety Throws nothing. An iterator to one past the last segment. Return the first segment This function returns a string with the first segment of the path without any leading or trailing '/' separators. Any percent-escapes in the string are decoded first. Preconditions this->empty() == false Effects 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. The first segment. Returns true if this references an absolute path. 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. true if the path is absolute, otherwise false . Return the number of segments Example assert( url_view( "/path/to/file.txt" ).segments().size() == 3 ); Complexity Constant. Exception Safety Throws nothing. The number of segments. Return the maximum number of characters possible This represents the largest number of characters that are possible in a path, not including any null terminator. Exception Safety Throws nothing. The maximum number of characters possible. Common functionality for containers This base class is used by the library to provide common member functions for containers. This cannot be instantiated directly; Instead, use one of the containers or functions: Containers segments_ref segments_view segments_encoded_ref segments_encoded_view A Bidirectional iterator to a path segment Objects of this type allow iteration through the segments in the path. Strings returned by iterators may contain percent escapes. The values returned are read-only; changes to segments must be made through the container instead, if the container supports modification. The strings produced when iterators are dereferenced refer to the underlying character buffer. Ownership is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced by any container or iterator. The reference type This is the type of value returned when iterators of the view are dereferenced. A signed integer type used to represent differences. The reference type This is the type of value returned when iterators of the view are dereferenced. An unsigned integer type used to represent size. The value type 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 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 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() == false Example assert( url_view( "/path/to/file.txt" ).encoded_segments().back() == "file.txt" ); Preconditions this->empty() == false Effects return *--end(); Complexity Constant. Exception Safety Throws nothing. The last segment. Return an iterator to the beginning Complexity Linear in this->front().size() or constant if this->empty() . Exception Safety Throws nothing. An iterator to the first segment. Return the referenced character buffer. 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. A string view of the buffer. Return true if there are no segments Example assert( ! url_view( "/index.htm" ).encoded_segments().empty() ); Complexity Constant. Exception Safety Throws nothing. true if there are no segments, otherwise false . Return an iterator to the end Complexity Constant. Exception Safety Throws nothing. An iterator to one past the last segment. Return the first segment This function returns a string with the first segment of the path without any leading or trailing '/' separators. The returned string may contain percent escapes. Preconditions this->empty() == false Effects return *begin(); Example assert( url_view( "/path/to/file.txt" ).encoded_segments().front() == "path" ); Complexity Constant. Exception Safety Throws nothing. The first segment. Returns true if this references an absolute path. 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. true if the path is absolute, otherwise false . Return the number of segments Example assert( url_view( "/path/to/file.txt" ).encoded_segments().size() == 3 ); Complexity Constant. Exception Safety Throws nothing. The number of segments. Return the maximum number of characters possible This represents the largest number of characters that are possible in a path, not including any null terminator. Exception Safety Throws nothing. The maximum number of characters possible. A view representing path segments in a URL 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 : Only `end()`. assign , clear , operator= : All elements. erase : Erased elements and all elements after (including `end()`). insert : All elements at or after the insertion point (including `end()`). replace : Modified elements and all elements after (including `end()`). segments_encoded_view , segments_view , segments_ref . A Bidirectional iterator to a path segment Objects of this type allow iteration through the segments in the path. Strings returned by iterators may contain percent escapes. The values returned are read-only; changes to segments must be made through the container instead, if the container supports modification. The strings produced when iterators are dereferenced refer to the underlying character buffer. Ownership is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced by any container or iterator. The reference type This is the type of value returned when iterators of the view are dereferenced. A signed integer type used to represent differences. The reference type This is the type of value returned when iterators of the view are dereferenced. An unsigned integer type used to represent size. The value type 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 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. Constructor 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. The other view. Assignment The existing contents are replaced by a copy of the other segments. All iterators are invalidated. None of the character buffers referenced by other may overlap the buffer of the underlying url, or else the behavior is undefined. Effects this->assign( other.begin(), other.end() ); Complexity Linear in other.buffer().size() . Exception Safety Strong guarantee. Calls to allocate may throw. A reference to this object. The segments to assign. Assignment 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. A reference to this. The list of segments to assign. The list contains an invalid percent-encoding. Assignment The existing contents are replaced by a copy of the other segments. All iterators are invalidated. None of the character buffers referenced by other may overlap the buffer of the underlying url, or else the behavior is undefined. Effects this->assign( other.begin(), other.end() ); Complexity Linear in other.buffer().size() . Exception Safety Strong guarantee. Calls to allocate may throw. A reference to this object. The segments to assign. Assign segments The existing contents are replaced by a copy of the contents of the initializer list. Reserved characters in the list are automatically escaped. Escapes in the list are preserved. All iterators are invalidated. None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined. 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. The list of segments to assign. The list contains an invalid percent-encoding. Return the last segment This function returns a string with the last segment of the path without any leading or trailing '/' separators. The returned string may contain percent escapes. Preconditions this->empty() == false Example assert( url_view( "/path/to/file.txt" ).encoded_segments().back() == "file.txt" ); Preconditions this->empty() == false Effects return *--end(); Complexity Constant. Exception Safety Throws nothing. The last segment. Return an iterator to the beginning Complexity Linear in this->front().size() or constant if this->empty() . Exception Safety Throws nothing. An iterator to the first segment. Return the referenced character buffer. 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. A string view of the buffer. Clear the contents of the container All iterators are invalidated. Effects this->url().set_encoded_path( "" ); Postconditions this->empty() == true Complexity Linear in this->url().encoded_query().size() + this->url().encoded_fragment().size() . Exception Safety Throws nothing. Return true if there are no segments Example assert( ! url_view( "/index.htm" ).encoded_segments().empty() ); Complexity Constant. Exception Safety Throws nothing. true if there are no segments, otherwise false . Return an iterator to the end Complexity Constant. Exception Safety Throws nothing. An iterator to one past the last segment. Erase segments 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. An iterator to one past the removed segment. An iterator to the element. Erase segments 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. An iterator to one past the removed range. The first element in the range to erase. One past the last element in the range to erase. Return the first segment This function returns a string with the first segment of the path without any leading or trailing '/' separators. The returned string may contain percent escapes. Preconditions this->empty() == false Effects return *begin(); Example assert( url_view( "/path/to/file.txt" ).encoded_segments().front() == "path" ); Complexity Constant. Exception Safety Throws nothing. The first segment. Insert segments 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. An iterator to the inserted segment. An iterator before which the segment is inserted. This may be equal to end() . The segment to insert. The segment contains an invalid percent-encoding. Insert segments This function inserts the segments in an initializer list before the specified position. Reserved characters in the list are automatically escaped. Escapes in the list are preserved. All iterators that are equal to before or come after are invalidated. None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined. 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. An iterator to the first element inserted, or before if init.size() == 0 . An iterator before which the list is inserted. This may be equal to end() . The list of segments to insert. The list contains an invalid percent-encoding. Returns true if this references an absolute path. 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. true if the path is absolute, otherwise false . Remove the last segment This function removes the last segment from the container. Iterators to the last segment as well as all end iterators are invalidated. Preconditions !this->empty() Exception Safety Throws nothing. Append a segment This function appends a segment to the end of the path. Reserved characters in the string are automatically escaped. Escapes in the string are preserved. All end iterators are invalidated. Postconditions this->back() == s Exception Safety Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input. The segment to append. The string contains an invalid percent-encoding. Replace segments 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. An iterator to the replaced segment. An iterator to the segment. The string to assign. Replace segments 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. An iterator to the new segment. The first element in the range of segments to replace. One past the last element in the range of segments to replace. The string to assign. The string contains an invalid percent-encoding. Replace segments 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. An iterator to the first segment inserted, or one past to if init.size() == 0 . The first element in the range of segments to replace. One past the last element in the range of segments to replace. The list of segments to assign. The list contains an invalid percent-encoding. Return the number of segments Example assert( url_view( "/path/to/file.txt" ).encoded_segments().size() == 3 ); Complexity Constant. Exception Safety Throws nothing. The number of segments. Return the referenced url 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. A reference to the url. Conversion A view of the segments. segments_encoded_view . Return the maximum number of characters possible This represents the largest number of characters that are possible in a path, not including any null terminator. Exception Safety Throws nothing. The maximum number of characters possible. A view representing path segments in a URL 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. segments_view , segments_encoded_ref , segments_ref . A Bidirectional iterator to a path segment Objects of this type allow iteration through the segments in the path. Strings returned by iterators may contain percent escapes. The values returned are read-only; changes to segments must be made through the container instead, if the container supports modification. The strings produced when iterators are dereferenced refer to the underlying character buffer. Ownership is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced by any container or iterator. The reference type This is the type of value returned when iterators of the view are dereferenced. A signed integer type used to represent differences. The reference type This is the type of value returned when iterators of the view are dereferenced. An unsigned integer type used to represent size. The value type 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 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. Constructor Default-constructed segments have zero elements. Example segments_encoded_view ps; Effects return segments_encoded_view( "" ); Complexity Constant. Exception Safety Throws nothing. Constructor 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 The object to copy construct from Constructor This function constructs segments from a valid path string, which can contain percent escapes. Upon construction, the view references the character buffer pointed to by s . caller is responsible for ensuring that the lifetime of the buffer extends until the view is destroyed. 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 = *pchar Specification 3.3. Path The string to parse. s contains an invalid path. Constructor This function creates a new segments_encoded_view from a pair of iterators referring to elements of another encoded segments view. The resulting view references the same underlying character buffer as the original. The caller is responsible for ensuring that the lifetime of the original buffer extends until the constructed view is no longer referenced. Example segments_encoded_view ps( "/path/to/file.txt" ); segments_encoded_view sub( std::next(ps.begin()), ps.end()); // sub represents "to/file.txt" Preconditions The iterators must be valid and belong to the same segments_encoded_view . Postconditions sub.buffer() references characters in the original ps.buffer() . Complexity Linear in sub.buffer() Exception Safety Throws nothing. The beginning iterator. The ending iterator. Assignment 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 Reference to this object The segments to copy. Return the last segment This function returns a string with the last segment of the path without any leading or trailing '/' separators. The returned string may contain percent escapes. Preconditions this->empty() == false Example assert( url_view( "/path/to/file.txt" ).encoded_segments().back() == "file.txt" ); Preconditions this->empty() == false Effects return *--end(); Complexity Constant. Exception Safety Throws nothing. The last segment. Return an iterator to the beginning Complexity Linear in this->front().size() or constant if this->empty() . Exception Safety Throws nothing. An iterator to the first segment. Return the referenced character buffer. 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. A string view of the buffer. Return true if there are no segments Example assert( ! url_view( "/index.htm" ).encoded_segments().empty() ); Complexity Constant. Exception Safety Throws nothing. true if there are no segments, otherwise false . Return an iterator to the end Complexity Constant. Exception Safety Throws nothing. An iterator to one past the last segment. Return the first segment This function returns a string with the first segment of the path without any leading or trailing '/' separators. The returned string may contain percent escapes. Preconditions this->empty() == false Effects return *begin(); Example assert( url_view( "/path/to/file.txt" ).encoded_segments().front() == "path" ); Complexity Constant. Exception Safety Throws nothing. The first segment. Returns true if this references an absolute path. 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. true if the path is absolute, otherwise false . Return the number of segments Example assert( url_view( "/path/to/file.txt" ).encoded_segments().size() == 3 ); Complexity Constant. Exception Safety Throws nothing. The number of segments. Conversion This conversion returns a new view which references the same underlying character buffer, and whose iterators and members return ordinary strings with decoding applied to any percent escapes. Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced. 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 A view of the segments. Return the maximum number of characters possible This represents the largest number of characters that are possible in a path, not including any null terminator. Exception Safety Throws nothing. The maximum number of characters possible. A view representing path segments in a URL 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 : Only `end()`. assign , clear , operator= : All elements. erase : Erased elements and all elements after (including `end()`). insert : All elements at or after the insertion point (including `end()`). replace : Modified elements and all elements after (including `end()`). segments_encoded_ref , segments_encoded_view , segments_view . A Bidirectional iterator to a path segment Objects of this type allow iteration through the segments in the path. Any percent-escapes in returned strings are decoded first. The values returned are read-only; changes to segments must be made through the container instead, if the container supports modification. The strings produced when iterators are dereferenced belong to the iterator and become invalidated when that particular iterator is incremented, decremented, or destroyed. The reference type This is the type of value returned when iterators of the view are dereferenced. A signed integer type used to represent differences. The reference type This is the type of value returned when iterators of the view are dereferenced. An unsigned integer type used to represent size. The value type 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 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. Constructor 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. The other view. Assignment The existing contents are replaced by a copy of the other segments. All iterators are invalidated. None of the character buffers referenced by other may overlap the buffer of the underlying url, or else the behavior is undefined. Effects this->assign( other.begin(), other.end() ); Complexity Linear in other.buffer().size() . Exception Safety Strong guarantee. Calls to allocate may throw. A reference to this object. The segments to assign. Assignment 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. A reference to this object. The list of segments to assign. Assignment The existing contents are replaced by a copy of the other segments. All iterators are invalidated. None of the character buffers referenced by other may overlap the buffer of the underlying url, or else the behavior is undefined. Effects this->assign( other.begin(), other.end() ); Complexity Linear in other.buffer().size() . Exception Safety Strong guarantee. Calls to allocate may throw. A reference to this object. The segments to assign. Assign segments The existing contents are replaced by a copy of the contents of the initializer list. Reserved characters in the list are automatically escaped. All iterators are invalidated. None of the character buffers referenced by init may overlap the character buffer of the underlying url, or else the behavior is undefined. 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. The list of segments to assign. Return the last segment Preconditions this->empty() == false Example assert( url_view( "/path/to/file.txt" ).segments().back() == "file.txt" ); Preconditions this->empty() == false Effects return *--end(); Complexity Linear in this->back().size() . Exception Safety Calls to allocate may throw. The last segment. Return an iterator to the beginning Complexity Linear in this->front().size() or constant if this->empty() . Exception Safety Throws nothing. An iterator to the first segment. Return the referenced character buffer. 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. A string containing the path. Clear the contents of the container All iterators are invalidated. Effects this->url().set_encoded_path( "" ); Postconditions this->empty() == true Complexity Linear in this->url().encoded_query().size() + this->url().encoded_fragment().size() . Exception Safety Throws nothing. Return true if there are no segments Example assert( ! url_view( "/index.htm" ).segments().empty() ); Complexity Constant. Exception Safety Throws nothing. true if there are no segments, otherwise false . Return an iterator to the end Complexity Constant. Exception Safety Throws nothing. An iterator to one past the last segment. Erase segments 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. An iterator to one past the removed segment. An iterator to the segment. Erase segments 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. An iterator to one past the removed range. The beginning of the range to remove. The end of the range to remove. Return the first segment This function returns a string with the first segment of the path without any leading or trailing '/' separators. Any percent-escapes in the string are decoded first. Preconditions this->empty() == false Effects 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. The first segment. Insert segments 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. An iterator to the inserted segment. An iterator before which the segment is inserted. This may be equal to end() . The segment to insert. Insert segments This function inserts the segments in an initializer list before the specified position. Reserved characters in the list are percent-escaped in the result. All iterators that are equal to before or come after are invalidated. None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined. 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. An iterator to the first element inserted, or before if init.size() == 0 . An iterator before which the list is inserted. This may be equal to end() . The list of segments to insert. Returns true if this references an absolute path. 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. true if the path is absolute, otherwise false . Remove the last segment This function removes the last segment from the container. Iterators to the last segment as well as all end iterators are invalidated. Preconditions not this->empty() Exception Safety Throws nothing. Append a segment This function appends a segment to the end of the path. Reserved characters in the string are automatically escaped. All end iterators are invalidated. Postconditions this->back() == s Exception Safety Strong guarantee. Calls to allocate may throw. The segment to append. Replace segments 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. An iterator to the replaced segment. An iterator to the segment. The string to assign. Replace segments 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. An iterator to the new segment. The beginning of the range of segments to replace. The end of the range of segments to replace. The string to assign. Replace segments 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. An iterator to the first segment inserted, or one past to if init.size() == 0 . The beginning of the range of segments to replace. The end of the range of segments to replace. The list of segments to assign. Return the number of segments Example assert( url_view( "/path/to/file.txt" ).segments().size() == 3 ); Complexity Constant. Exception Safety Throws nothing. The number of segments. Return the referenced url 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. A reference to the url. Conversion A view of the segments. segments_view . Return the maximum number of characters possible This represents the largest number of characters that are possible in a path, not including any null terminator. Exception Safety Throws nothing. The maximum number of characters possible. A view representing path segments in a URL 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. segments_encoded_view , segments_encoded_ref , segments_ref . A Bidirectional iterator to a path segment Objects of this type allow iteration through the segments in the path. Any percent-escapes in returned strings are decoded first. The values returned are read-only; changes to segments must be made through the container instead, if the container supports modification. The strings produced when iterators are dereferenced belong to the iterator and become invalidated when that particular iterator is incremented, decremented, or destroyed. The reference type This is the type of value returned when iterators of the view are dereferenced. A signed integer type used to represent differences. The reference type This is the type of value returned when iterators of the view are dereferenced. An unsigned integer type used to represent size. The value type 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 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. Constructor Default-constructed segments have zero elements. Example segments_view ps; Effects return segments_view( "" ); Complexity Constant. Exception Safety Throws nothing. Constructor 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 The other view. Constructor This function constructs segments from a valid path string, which can contain percent escapes. Upon construction, the view references the character buffer pointed to by s . caller is responsible for ensuring that the lifetime of the buffer extends until the view is destroyed. 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 = *pchar Specification 3.3. Path The string to parse. s contains an invalid path. Constructor This function creates a new segments_view from a pair of iterators referring to elements of another segments view. The resulting view references the same underlying character buffer as the original. The caller is responsible for ensuring that the lifetime of the original buffer extends until the constructed view is no longer referenced. Example segments_view ps( "/path/to/file.txt" ); segments_view sub( std::next(ps.begin()), ps.end()); // sub represents "to/file.txt" Preconditions The iterators must be valid and belong to the same segments_view . Postconditions sub.buffer() references characters in the original ps.buffer() . Complexity Linear in sub.buffer() Exception Safety Throws nothing. The beginning iterator. The ending iterator. Assignment 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 A reference to this object. The other view. Return the last segment Preconditions this->empty() == false Example assert( url_view( "/path/to/file.txt" ).segments().back() == "file.txt" ); Preconditions this->empty() == false Effects return *--end(); Complexity Linear in this->back().size() . Exception Safety Calls to allocate may throw. The last segment. Return an iterator to the beginning Complexity Linear in this->front().size() or constant if this->empty() . Exception Safety Throws nothing. An iterator to the first segment. Return the referenced character buffer. 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. A string containing the path. Return true if there are no segments Example assert( ! url_view( "/index.htm" ).segments().empty() ); Complexity Constant. Exception Safety Throws nothing. true if there are no segments, otherwise false . Return an iterator to the end Complexity Constant. Exception Safety Throws nothing. An iterator to one past the last segment. Return the first segment This function returns a string with the first segment of the path without any leading or trailing '/' separators. Any percent-escapes in the string are decoded first. Preconditions this->empty() == false Effects 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. The first segment. Returns true if this references an absolute path. 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. true if the path is absolute, otherwise false . Return the number of segments Example assert( url_view( "/path/to/file.txt" ).segments().size() == 3 ); Complexity Constant. Exception Safety Throws nothing. The number of segments. Return the maximum number of characters possible This represents the largest number of characters that are possible in a path, not including any null terminator. Exception Safety Throws nothing. The maximum number of characters possible. Common implementation for all static URLs 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 format_to format_to operator!= operator< operator<= operator== operator> operator>= resolve Return the authority 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 ] Specification 3.2. Authority (rfc3986) An authority_view representing the authority. encoded_authority , has_authority . Return the url string 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. The url as a string. Return the url as a null-terminated string This function returns a pointer to a null terminated string representing the url, which may contain percent escapes. Example assert( std::strlen( url( "http://www.example.com" ).c_str() ) == 22 ); Complexity Constant. Exception Safety Throws nothing. A pointer to a null-terminated string containing the URL. Return the number of characters that can be stored without reallocating This does not include the null terminator, which is always present. Complexity Constant. Exception Safety Throws nothing. *this Clear the contents while preserving the capacity Postconditions this->empty() == true Complexity Constant. Exception Safety No-throw guarantee. Return the result of comparing this with another url This function compares two URLs according to Syntax-Based comparison algorithm. Complexity Linear in min( u0.size(), u1.size() ) Exception Safety Throws nothing. Specification 6.2.2 Syntax-Based Normalization (rfc3986) -1 if *this < other , 0 if this == other , and 1 if this > other . The url to compare Return a pointer to the url's character buffer This function returns a pointer to the first character of the url, which is not guaranteed to be null-terminated. Complexity Constant. Exception Safety Throws nothing. A pointer to the first character. Return true if the url is empty 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-empty Specification 4.2. Relative Reference (rfc3986) true if the url is empty. Return the authority. 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 ] Specification 3.2. Authority (rfc3986) The authority as a string. authority , has_authority . Return the fragment 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 / ":" / "@" Specification 3.5. Fragment (rfc3986) The fragment portion of the url. fragment , has_fragment . Return the host This function returns the host portion of the authority as a string, or the empty string if there is no authority. The returned string may contain percent escapes. 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 / "-" / ".") Specification 3.2.2. Host (rfc3986) The host address as a string. Return the host 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 / "-" / ".") Specification 3.2.2. Host (rfc3986) The host address as a string. Return the host and port 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 3.2.2. Host (rfc3986) 3.2.3. Port (rfc3986) The host and port portion of the url. has_port , port , port_number . Return the host name 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 / "-" / ".") Specification 3.2.2. Host (rfc3986) The host name as a percent-encoded string. Return the origin If an authority is present, this function returns the scheme and authority portion of the url. Otherwise, an empty string is returned. The returned string may contain percent escapes. 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. The origin portion of the url. encoded_resource , encoded_target . Return the query as a container of parameters This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Strings returned when iterating the range may contain percent escapes. The container is modifiable; changes to the container are reflected in the underlying URL. 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 3.4. Query (rfc3986) Query string (Wikipedia) *this params , remove_query , set_encoded_query , set_query . Return the query as a container of parameters This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Strings returned when iterating the range may contain percent escapes. 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 3.4. Query (rfc3986) Query string (Wikipedia) A bidirectional view of key/value pairs. encoded_query , has_query , params , query . Return the password 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 / ":" ) Specification 3.2.1. User Information (rfc3986) The password as a string. has_password , has_userinfo , encoded_user , encoded_userinfo , password , user , userinfo . Return the path This function returns the path as a string. The path may be empty. Any percent-escapes in the string are decoded first. 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> Specification 3.3. Path (rfc3986) The path as a string. is_path_absolute , encoded_segments . path , segments . Return the query If this contains a query, it is returned as a string (which may be empty). Otherwise, an empty string is returned. The returned string may contain percent escapes. 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 3.4. Query (rfc3986) Query string (Wikipedia) The query as a string. encoded_params , has_query , params , query . Return the resource 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 3.3. Path (rfc3986) 3.4. Query (rfc3986) The resource portion of the url. encoded_origin , encoded_target . Return the path as a container of segments This function returns a bidirectional view of segments over the path. The returned view references the same underlying character buffer; ownership is not transferred. Strings returned when iterating the range may contain percent escapes. The container is modifiable; changes to the container are reflected in the underlying URL. 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> Specification 3.3. Path (rfc3986) *this encoded_segments , set_encoded_path , set_path , set_path_absolute . Return the path as a container of segments This function returns a bidirectional view of strings over the path. The returned view references the same underlying character buffer; ownership is not transferred. 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> Specification 3.3. Path (rfc3986) A bidirectional view of encoded segments. is_path_absolute , encoded_path , path , segments , segments_encoded_view . Return the target This function returns the target, which is the portion of the url that includes only the path and query. The returned string may contain percent escapes. Example assert( url_view( "http://www.example.com/index.html?query#frag" ).encoded_target() == "/index.html?query" ); Complexity Constant. Exception Safety Throws nothing. Specification 3.3. Path (rfc3986) 3.4. Query (rfc3986) The target portion of the url. encoded_origin , encoded_resource . Return the user If present, this function returns a string representing the user (which may be empty). Otherwise it returns an empty string. The returned string may contain percent escapes. 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 / ":" ) Specification 3.2.1. User Information (rfc3986) The user as a string. has_password , has_userinfo , encoded_password , encoded_userinfo , password , user , userinfo . Return the userinfo 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 ] Specification 3.2.1. User Information (rfc3986) The userinfo as a string. has_password , has_userinfo , encoded_password , encoded_user , password , user , userinfo . Return the IPv6 Zone ID 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" ZoneID Specification Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers The Zone ID as a percent-encoded string. Return true if an authority is present 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...) Specification 3.2. Authority (rfc3986) true if the url contains an authority. authority , encoded_authority . Return true if a fragment is present This function returns true if the url contains a fragment. An empty fragment is distinct from no fragment. 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 ] Specification 3.5. Fragment (rfc3986) true if the url contains a fragment. encoded_fragment , fragment . Return true if a password is present 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 / ":" ) Specification 3.2.1. User Information (rfc3986) true if the userinfo contains a password. has_userinfo , encoded_password , encoded_user , encoded_userinfo , password , user , userinfo . Return true if a port is present 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 = *DIGIT Specification 3.2.3. Port (rfc3986) true if a port is present, false otherwise. encoded_host_and_port , port , port_number . Return true if a query is present This function returns true if this contains a query. An empty query is distinct from having no query. 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 3.4. Query (rfc3986) Query string (Wikipedia) true if a query is present. encoded_params , encoded_query , params , query . Return true a scheme is present 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 / "+" / "-" / "." ) Specification 3.1. Scheme (rfc3986) true if the url contains a scheme. scheme , scheme_id . Return true if a userinfo is present 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 ] Specification 3.2.1. User Information (rfc3986) true if the userinfo is present. has_password , encoded_password , encoded_user , encoded_userinfo , password , user , userinfo . Return the host IPv4 address If the host type is host_type::ipv4 , this function returns the address as a value of type ipv4_address . Otherwise, if the host type is not an IPv4 address, it returns a default-constructed value which is equal to the unspecified address "0.0.0.0". 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-255 Specification 3.2.2. Host (rfc3986) The IPv4 address as a value of type ipv4_address . Return the host IPv6 address If the host type is host_type::ipv6 , this function returns the address as a value of type ipv6_address . Otherwise, if the host type is not an IPv6 address, it returns a default-constructed value which is equal to the unspecified address "0:0:0:0:0:0:0:0". 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 hexadecimal Specification 3.2.2. Host (rfc3986) The IPv6 address as a value of type ipv6_address . Return the host IPvFuture address 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 / ":" ) Specification 3.2.2. Host (rfc3986) The IPvFuture address as a string. Return the host type 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. Specification 3.2.2. Host (rfc3986) The type of host present. Return true if the path is absolute 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> Specification 3.3. Path (rfc3986) true if the path is absolute, false otherwise. encoded_path , encoded_segments . path , segments . Normalize the URL components Applies Syntax-based normalization to all components of the URL. Exception Safety Strong guarantee. Calls to allocate may throw. Specification 6.2.2 Syntax-Based Normalization (rfc3986) *this Normalize the URL authority Applies Syntax-based normalization to the URL authority. Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded. Exception Safety Strong guarantee. Calls to allocate may throw. Specification 6.2.2 Syntax-Based Normalization (rfc3986) *this Normalize the URL fragment Applies Syntax-based normalization to the URL fragment. Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded. Exception Safety Strong guarantee. Calls to allocate may throw. Specification 6.2.2 Syntax-Based Normalization (rfc3986) *this Normalize the URL path Applies Syntax-based normalization to the URL path. Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded. Redundant path-segments are removed. Exception Safety Strong guarantee. Calls to allocate may throw. Specification 6.2.2 Syntax-Based Normalization (rfc3986) *this Normalize the URL query Applies Syntax-based normalization to the URL query. Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded. Exception Safety Strong guarantee. Calls to allocate may throw. Specification 6.2.2 Syntax-Based Normalization (rfc3986) *this Normalize the URL scheme Applies Syntax-based normalization to the URL scheme. The scheme is normalized to lowercase. Exception Safety Strong guarantee. Calls to allocate may throw. Specification 6.2.2 Syntax-Based Normalization (rfc3986) *this Return the query as a container of parameters This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first. The container is modifiable; changes to the container are reflected in the underlying URL. 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 3.4. Query (rfc3986) Query string (Wikipedia) *this encoded_params , remove_query , set_encoded_query , set_query . Return the query as a container of parameters A bidirectional view of key/value pairs. encoded_params , encoded_query , has_query , query . Return the query as a container of parameters This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first. The container is modifiable; changes to the container are reflected in the underlying URL. 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 3.4. Query (rfc3986) Query string (Wikipedia) A range of references to the parameters. The options for decoding. If this parameter is omitted, the space_as_plus is used. encoded_params , remove_query , set_encoded_query , set_query . Return a shared, persistent copy of the url This function returns a read-only copy of the url, with shared lifetime. The returned value owns (persists) the underlying string. The algorithm used to create the value minimizes the number of individual memory allocations, making it more efficient than when using direct standard library functions. 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. A shared pointer to a read-only url_view. Return the port 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 = *DIGIT Specification 3.2.3. Port (rfc3986) The port as a string. encoded_host_and_port , has_port , port_number . Return the port If a port is present and the numerical value is representable, it is returned as an unsigned integer. Otherwise, the number zero is returned. Example assert( url_view( "http://localhost.com:8080" ).port_number() == 8080 ); Complexity Constant. Exception Safety Throws nothing. BNF port = *DIGIT Specification 3.2.3. Port (rfc3986) The port number as an unsigned integer. encoded_host_and_port , has_port , port . Remove the authority 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() == false Complexity 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 = *DIGIT Specification 3.2. Authority (rfc3986) *this set_encoded_authority . Remove the fragment 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 / "/" / "?" ) Specification 3.5. Fragment *this remove_fragment , set_encoded_fragment , set_fragment . Remove the origin component 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() == false Complexity Linear in this->size() . Exception Safety Throws nothing. *this Remove the password This function removes the password from the userinfo if a password exists. If there is no userinfo or no authority, the call has no effect. The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated. Example assert( url( "http://user:pass@example.com" ).remove_password().authority().buffer() == "user@example.com" ); Postconditions this->has_password() == false && this->encoded_password().empty() == true Complexity Linear in this->size() . Exception Safety Throws nothing. BNF userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" ) Specification 3.2.1. User Information (rfc3986) *this set_encoded_password , set_encoded_user , set_password , set_user . Remove the port 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 = *DIGIT Specification 3.2.3. Port (rfc3986) *this set_port . Remove the query 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 3.4. Query (rfc3986) Query string (Wikipedia) *this encoded_params , params , set_encoded_query , set_query . Remove the scheme 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::none Complexity Linear in this->size() . Exception Safety Throws nothing. BNF URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] Specification 3.1. Scheme (rfc3986) *this set_scheme . Remove the userinfo 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 == true Complexity Linear in this->size() . Exception Safety Throws nothing. BNF userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" ) Specification 3.2.1. User Information (rfc3986) *this set_encoded_userinfo , set_userinfo . Adjust the capacity without changing the size This function adjusts the capacity of the container in characters, without affecting the current contents. Has no effect if n <= this->capacity() . Exception Safety Strong guarantee. Calls to allocate may throw. The capacity in characters, excluding any null terminator. Allocation failure Resolve a URL reference against this base URL This function attempts to resolve a URL reference ref against this base URL in a manner similar to that of a web browser resolving an anchor tag. This URL must satisfy the URI grammar. In other words, it must contain a scheme. Relative references are only usable when in the context of a base absolute URI. This process of resolving a relative reference within the context of a base URI is defined in detail in rfc3986 (see below). The resolution process works as if the relative reference is appended to the base URI and the result is normalized. Given the input base URL, this function resolves the relative reference as if performing the following steps: 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. Abnormal hrefs where the number of ".." segments exceeds the number of segments in the base path are handled by including the unmatched ".." segments in the result, as described in Errata 4547 . 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 An empty boost::system::result upon success, otherwise an error code if !base.has_scheme() . The URL reference to resolve. url , url_view . Return the scheme This function returns the scheme if it exists, without a trailing colon (':'). Otherwise it returns an empty string. Note that schemes are case-insensitive, and the canonical form is lowercased. 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 ] Specification 3.1. Scheme (rfc3986) The scheme as a string. has_scheme , scheme_id . Return the scheme 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::scheme is 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 / "+" / "-" / "." ) Specification 3.1. Scheme (rfc3986) The scheme as an enumeration value. has_scheme , scheme . Return the path as a container of segments This function returns a bidirectional view of segments over the path. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first. The container is modifiable; changes to the container are reflected in the underlying URL. 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> Specification 3.3. Path (rfc3986) *this encoded_segments , set_encoded_path , set_path , set_path_absolute . Return the path as a container of segments This function returns a bidirectional view of strings over the path. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first. Example segments_view sv = url_view( "/path/to/file.txt" ).segments(); Complexity Constant. Exception Safety Throws nothing. BNF path = [ "/" ] segment *( "/" segment ) Specification 3.3. Path (rfc3986) A bidirectional view of segments. is_path_absolute , encoded_path , encoded_segments . path , segments_view . Set the authority 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 = *DIGIT Specification 3.2. Authority (rfc3986) *this The authority string to set. The string contains an invalid percent-encoding. remove_authority . Set the fragment. This function sets the fragment to the specified string, which may contain percent-escapes and which may be empty. An empty fragment is distinct from having no fragment. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. 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 / "/" / "?" ) Specification 3.5. Fragment *this *this The string to set. s contains an invalid percent-encoding. remove_fragment , set_fragment . Set the host 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() == true Complexity 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 IPv4 (Wikipedia) IP Version 6 Addressing Architecture (rfc4291) 3.2.2. Host (rfc3986) *this The string to set. s contains an invalid percent-encoding. 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 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() == true Complexity 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 IPv4 (Wikipedia) IP Version 6 Addressing Architecture (rfc4291) 3.2.2. Host (rfc3986) *this The string to set. s contains an invalid percent-encoding. 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 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::name Exception Safety Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input. BNF reg-name = *( unreserved / pct-encoded / "-" / ".") Specification 3.2.2. Host (rfc3986) *this The string to set. s contains an invalid percent-encoding. 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 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() == true Complexity 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 3.4. Query (rfc3986) Query string (Wikipedia) *this The params to set. some element in ps contains an invalid percent-encoding. set_params , params , remove_query , set_encoded_query , set_query . Set the password. This function sets the password in the userinfo to the string, which may contain percent-escapes. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated. Example assert( url("http://user@example.com").set_encoded_password( "pass" ).encoded_userinfo() == "user:pass" ); Postconditions this->has_password() == true 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 / ":" ) Specification 3.2.1. User Information (rfc3986) *this The string to set. This string may contain any characters, including nulls. s contains an invalid percent-encoding. remove_password , set_encoded_password , set_encoded_user , set_user . Set the path. This function sets the path to the string, which may contain percent-escapes and can be empty. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. The library may adjust the final result to ensure that no other parts of the url is semantically affected. 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> Specification 3.3. Path (rfc3986) *this The string to set. s contains an invalid percent-encoding. encoded_segments , segments , set_path , set_path_absolute . Set the query This sets the query to the string, which may contain percent-escapes and can be empty. An empty query is distinct from having no query. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. 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 3.4. Query (rfc3986) Query string (Wikipedia) *this The string to set. s contains an invalid percent-encoding. encoded_params , params , remove_query , set_query . Set the user This function sets the user part of the userinfo the the string, which may contain percent-escapes. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. Example assert( url().set_encoded_user("john%20doe").userinfo() == "john doe" ); Postconditions this->has_authority() == true && this->has_userinfo() == true 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 / ":" ) Specification 3.2.1. User Information (rfc3986) *this *this The string to set. s contains an invalid percent-encoding. remove_password , set_encoded_password , set_password , set_user . Set the userinfo. The userinfo is set to the given string, which may contain percent-escapes. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. The effects on the user and password depend on the presence of a colon (':') in the string: 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_password returns true. Otherwise, If there is no colon, the user is set to the string. The function has_password returns false. 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 / ":" ) Specification 3.2.1. User Information (rfc3986) *this The string to set. s contains an invalid percent-encoding. remove_userinfo , set_userinfo . Set the zone ID for an IPv6 address (percent-encoded). 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 RFC 6874 *this The zone ID to set. s contains an invalid percent-encoding. Set the fragment. This function sets the fragment to the specified string, which may be empty. An empty fragment is distinct from having no fragment. Reserved characters in the string are percent-escaped in the result. Example assert( url("?first=john&last=doe" ).set_encoded_fragment( "john doe" ).encoded_fragment() == "john%20doe" ); Postconditions this->has_fragment() == true && this->fragment() == s Complexity Linear in this->size() + s.size() . Exception Safety Strong guarantee. Calls to allocate may throw. BNF fragment = *( pchar / "/" / "?" ) Specification 3.5. Fragment *this The string to set. remove_fragment , set_encoded_fragment . Set the host 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() == true Complexity 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 IPv4 (Wikipedia) IP Version 6 Addressing Architecture (rfc4291) 3.2.2. Host (rfc3986) *this The string to set. 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 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() == true Complexity 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 IPv4 (Wikipedia) IP Version 6 Addressing Architecture (rfc4291) 3.2.2. Host (rfc3986) *this The string to set. 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 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::ipv4 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 Specification IPv4 (Wikipedia) 3.2.2. Host (rfc3986) *this The address to set. 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 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::ipv6 Complexity 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 hexadecimal Specification IP Version 6 Addressing Architecture (rfc4291) 3.2.2. Host (rfc3986) *this The address to set. 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 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::ipvfuture Exception Safety Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input. BNF IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" ) Specification 3.2.2. Host (rfc3986) *this The string to set. s contains an invalid percent-encoding. 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 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::name Exception Safety Strong guarantee. Calls to allocate may throw. BNF reg-name = *( unreserved / pct-encoded / "-" / ".") Specification 3.2.2. Host (rfc3986) *this The string to set. 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 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() == true Exception Safety Strong guarantee. Calls to allocate may throw. Complexity Linear. BNF query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param ) Specification ://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia) *this The params to set. The options for encoding. encoded_params , remove_query , set_encoded_query , set_query . Set the password. This function sets the password in the userinfo to the string. Reserved characters in the string are percent-escaped in the result. The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated. Example assert( url("http://user@example.com").set_password( "pass" ).encoded_userinfo() == "user:pass" ); Postconditions this->has_password() == true && this->password() == s 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 / ":" ) Specification 3.2.1. User Information (rfc3986) *this The string to set. This string may contain any characters, including nulls. remove_password , set_encoded_password , set_encoded_user , set_user . Set the path. This function sets the path to the string, which may be empty. Reserved characters in the string are percent-escaped in the result. The library may adjust the final result to ensure that no other parts of the URL are semantically affected. This function does not encode '/' chars, which are unreserved for paths but reserved for path segments. If a path segment should include encoded '/'s to differentiate it from path separators, the functions set_encoded_path or segments should be used instead. 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> Specification 3.3. Path (rfc3986) *this The string to set. encoded_segments , segments , set_encoded_path , set_path_absolute . Set if the path is absolute This function adjusts the path to make it absolute or not, depending on the parameter. If an authority is present, the path is always absolute. In this case, the function has no effect. 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> Specification 3.3. Path (rfc3986) true on success. If true , the path is made absolute. encoded_segments , segments , set_encoded_path , set_path . Set the port This port is set to the string, which must contain only digits or be empty. An empty port string is distinct from having no port. 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 = *DIGIT Specification 3.2.3. Port (rfc3986) *this The port string to set. s does not contain a valid port. remove_port , set_port . Set the port 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() == n Complexity Linear in this->size() . Exception Safety Strong guarantee. Calls to allocate may throw. BNF authority = [ userinfo "@" ] host [ ":" port ] port = *DIGIT Specification 3.2.3. Port (rfc3986) *this The port number to set. remove_port , set_port . Set the query This sets the query to the string, which can be empty. An empty query is distinct from having no query. Reserved characters in the string are percent-escaped in the result. Example assert( url( "http://example.com" ).set_query( "id=42" ).query() == "id=42" ); Postconditions this->has_query() == true && this->query() == s Exception Safety Strong guarantee. Calls to allocate may throw. BNF query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param ) Specification 3.4. Query (rfc3986) Query string (Wikipedia) *this The string to set. encoded_params , params , remove_query , set_encoded_query . Set the scheme The scheme is set to the specified string, which must contain a valid scheme without any trailing colon (':'). Note that schemes are case-insensitive, and the canonical form is lowercased. 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 / "+" / "-" / "." ) Specification 3.1. Scheme (rfc3986) *this The scheme to set. s contains an invalid scheme. remove_scheme . Set the scheme This function sets the scheme to the specified known urls::scheme id, which may not be scheme::unknown or else an exception is thrown. If the id is scheme::none , this function behaves as if remove_scheme were called. 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. Specification 3.1. Scheme (rfc3986) *this The scheme to set. The scheme is invalid. Set the user This function sets the user part of the userinfo to the string. Any special or reserved characters in the string are automatically percent-encoded. Example assert( url().set_user("john doe").encoded_userinfo() == "john%20doe" ); Postconditions this->has_authority() == true && this->has_userinfo() == true 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 / ":" ) Specification 3.2.1. User Information (rfc3986) *this The string to set. remove_password , set_encoded_password , set_encoded_user , set_password . Set the userinfo The userinfo is set to the given string, which may contain percent-escapes. Any special or reserved characters in the string are automatically percent-encoded. The effects on the user and password depend on the presence of a colon (':') in the string: 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_password returns true. Otherwise, If there is no colon, the user is set to the string. The function has_password returns false. 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 / ":" ) Specification 3.2.1. User Information (rfc3986) *this The string to set. remove_userinfo , set_encoded_userinfo . Set the zone ID for an IPv6 address. 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 RFC 6874 *this The zone ID to set. Return the number of characters in the url This function returns the number of characters in the url's encoded string, not including any null terminator, if present. Example assert( url_view( "file:///Program%20Files" ).size() == 23 ); Complexity Constant. Exception Safety Throws nothing. The number of characters in the url. Return the URL as a core::string_view Complexity Constant. Exception Safety Throws nothing. A string view of the URL. Return the maximum number of characters possible 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. The maximum number of characters. Calculate a hash of the url This function calculates a hash of the url as if it were always normalized. Complexity Linear in this->size() . Exception Safety Throws nothing. A hash value suitable for use in hash-based containers. An initial value to add to the hash A modifiable container for a URL. 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 `noexcept` provide 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 Uniform Resource Identifier (URI): Generic Syntax (rfc3986) parse_absolute_uri , parse_relative_ref , parse_uri , parse_uri_reference , resolve . format format format_to format_to operator!= operator< operator<= operator== operator> operator>= resolve Constructor Default constructed urls contain a zero-length string. This matches the grammar for a relative-ref with an empty path and no query or fragment. Example url u; Postconditions this->empty() == true Complexity Constant. Exception Safety Throws nothing. BNF relative-ref = relative-part [ "?" query ] [ "#" fragment ] Specification Constructor 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. The url to copy. u.size() > max_size() . Constructor The contents of u are transferred to the newly constructed object, which includes the underlying character buffer. After construction, the moved-from object is as if default constructed. Postconditions u.empty() == true Complexity Constant. Exception Safety Throws nothing. The url to move from. Constructor This function constructs a URL from the string s , which must contain a valid URI or relative-ref or else an exception is thrown. The new url retains ownership by allocating a copy of the passed string. 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 ] Specification 4.1. URI Reference The string to parse. The input does not contain a valid url. Constructor 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. The url to copy. u.size() > max_size() . Destructor Any params, segments, iterators, or views which reference this object are invalidated. The underlying character buffer is destroyed, invalidating all references to it. Assignment 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. A reference to this object. The url to copy. Assignment The contents of u are transferred to this , including the underlying character buffer. The previous contents of this are destroyed. After assignment, the moved-from object is as if default constructed. Postconditions u.empty() == true Complexity Constant. Exception Safety Throws nothing. A reference to this object. The url to assign from. Assignment 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. A reference to this object. The url to copy. u.size() > max_size() . Return the authority 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 ] Specification 3.2. Authority (rfc3986) An authority_view representing the authority. encoded_authority , has_authority . Return the url string 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. The url as a string. Return the url as a null-terminated string This function returns a pointer to a null terminated string representing the url, which may contain percent escapes. Example assert( std::strlen( url( "http://www.example.com" ).c_str() ) == 22 ); Complexity Constant. Exception Safety Throws nothing. A pointer to a null-terminated string containing the URL. Return the number of characters that can be stored without reallocating This does not include the null terminator, which is always present. Complexity Constant. Exception Safety Throws nothing. *this Clear the contents while preserving the capacity Postconditions this->empty() == true Complexity Constant. Exception Safety No-throw guarantee. Return the result of comparing this with another url This function compares two URLs according to Syntax-Based comparison algorithm. Complexity Linear in min( u0.size(), u1.size() ) Exception Safety Throws nothing. Specification 6.2.2 Syntax-Based Normalization (rfc3986) -1 if *this < other , 0 if this == other , and 1 if this > other . The url to compare Return a pointer to the url's character buffer This function returns a pointer to the first character of the url, which is not guaranteed to be null-terminated. Complexity Constant. Exception Safety Throws nothing. A pointer to the first character. Return true if the url is empty 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-empty Specification 4.2. Relative Reference (rfc3986) true if the url is empty. Return the authority. 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 ] Specification 3.2. Authority (rfc3986) The authority as a string. authority , has_authority . Return the fragment 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 / ":" / "@" Specification 3.5. Fragment (rfc3986) The fragment portion of the url. fragment , has_fragment . Return the host This function returns the host portion of the authority as a string, or the empty string if there is no authority. The returned string may contain percent escapes. 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 / "-" / ".") Specification 3.2.2. Host (rfc3986) The host address as a string. Return the host 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 / "-" / ".") Specification 3.2.2. Host (rfc3986) The host address as a string. Return the host and port 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 3.2.2. Host (rfc3986) 3.2.3. Port (rfc3986) The host and port portion of the url. has_port , port , port_number . Return the host name 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 / "-" / ".") Specification 3.2.2. Host (rfc3986) The host name as a percent-encoded string. Return the origin If an authority is present, this function returns the scheme and authority portion of the url. Otherwise, an empty string is returned. The returned string may contain percent escapes. 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. The origin portion of the url. encoded_resource , encoded_target . Return the query as a container of parameters This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Strings returned when iterating the range may contain percent escapes. The container is modifiable; changes to the container are reflected in the underlying URL. 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 3.4. Query (rfc3986) Query string (Wikipedia) *this params , remove_query , set_encoded_query , set_query . Return the query as a container of parameters This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Strings returned when iterating the range may contain percent escapes. 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 3.4. Query (rfc3986) Query string (Wikipedia) A bidirectional view of key/value pairs. encoded_query , has_query , params , query . Return the password 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 / ":" ) Specification 3.2.1. User Information (rfc3986) The password as a string. has_password , has_userinfo , encoded_user , encoded_userinfo , password , user , userinfo . Return the path This function returns the path as a string. The path may be empty. Any percent-escapes in the string are decoded first. 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> Specification 3.3. Path (rfc3986) The path as a string. is_path_absolute , encoded_segments . path , segments . Return the query If this contains a query, it is returned as a string (which may be empty). Otherwise, an empty string is returned. The returned string may contain percent escapes. 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 3.4. Query (rfc3986) Query string (Wikipedia) The query as a string. encoded_params , has_query , params , query . Return the resource 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 3.3. Path (rfc3986) 3.4. Query (rfc3986) The resource portion of the url. encoded_origin , encoded_target . Return the path as a container of segments This function returns a bidirectional view of segments over the path. The returned view references the same underlying character buffer; ownership is not transferred. Strings returned when iterating the range may contain percent escapes. The container is modifiable; changes to the container are reflected in the underlying URL. 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> Specification 3.3. Path (rfc3986) *this encoded_segments , set_encoded_path , set_path , set_path_absolute . Return the path as a container of segments This function returns a bidirectional view of strings over the path. The returned view references the same underlying character buffer; ownership is not transferred. 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> Specification 3.3. Path (rfc3986) A bidirectional view of encoded segments. is_path_absolute , encoded_path , path , segments , segments_encoded_view . Return the target This function returns the target, which is the portion of the url that includes only the path and query. The returned string may contain percent escapes. Example assert( url_view( "http://www.example.com/index.html?query#frag" ).encoded_target() == "/index.html?query" ); Complexity Constant. Exception Safety Throws nothing. Specification 3.3. Path (rfc3986) 3.4. Query (rfc3986) The target portion of the url. encoded_origin , encoded_resource . Return the user If present, this function returns a string representing the user (which may be empty). Otherwise it returns an empty string. The returned string may contain percent escapes. 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 / ":" ) Specification 3.2.1. User Information (rfc3986) The user as a string. has_password , has_userinfo , encoded_password , encoded_userinfo , password , user , userinfo . Return the userinfo 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 ] Specification 3.2.1. User Information (rfc3986) The userinfo as a string. has_password , has_userinfo , encoded_password , encoded_user , password , user , userinfo . Return the IPv6 Zone ID 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" ZoneID Specification Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers The Zone ID as a percent-encoded string. Return true if an authority is present 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...) Specification 3.2. Authority (rfc3986) true if the url contains an authority. authority , encoded_authority . Return true if a fragment is present This function returns true if the url contains a fragment. An empty fragment is distinct from no fragment. 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 ] Specification 3.5. Fragment (rfc3986) true if the url contains a fragment. encoded_fragment , fragment . Return true if a password is present 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 / ":" ) Specification 3.2.1. User Information (rfc3986) true if the userinfo contains a password. has_userinfo , encoded_password , encoded_user , encoded_userinfo , password , user , userinfo . Return true if a port is present 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 = *DIGIT Specification 3.2.3. Port (rfc3986) true if a port is present, false otherwise. encoded_host_and_port , port , port_number . Return true if a query is present This function returns true if this contains a query. An empty query is distinct from having no query. 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 3.4. Query (rfc3986) Query string (Wikipedia) true if a query is present. encoded_params , encoded_query , params , query . Return true a scheme is present 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 / "+" / "-" / "." ) Specification 3.1. Scheme (rfc3986) true if the url contains a scheme. scheme , scheme_id . Return true if a userinfo is present 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 ] Specification 3.2.1. User Information (rfc3986) true if the userinfo is present. has_password , encoded_password , encoded_user , encoded_userinfo , password , user , userinfo . Return the host IPv4 address If the host type is host_type::ipv4 , this function returns the address as a value of type ipv4_address . Otherwise, if the host type is not an IPv4 address, it returns a default-constructed value which is equal to the unspecified address "0.0.0.0". 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-255 Specification 3.2.2. Host (rfc3986) The IPv4 address as a value of type ipv4_address . Return the host IPv6 address If the host type is host_type::ipv6 , this function returns the address as a value of type ipv6_address . Otherwise, if the host type is not an IPv6 address, it returns a default-constructed value which is equal to the unspecified address "0:0:0:0:0:0:0:0". 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 hexadecimal Specification 3.2.2. Host (rfc3986) The IPv6 address as a value of type ipv6_address . Return the host IPvFuture address 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 / ":" ) Specification 3.2.2. Host (rfc3986) The IPvFuture address as a string. Return the host type 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. Specification 3.2.2. Host (rfc3986) The type of host present. Return true if the path is absolute 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> Specification 3.3. Path (rfc3986) true if the path is absolute, false otherwise. encoded_path , encoded_segments . path , segments . Normalize the URL components Applies Syntax-based normalization to all components of the URL. Exception Safety Strong guarantee. Calls to allocate may throw. Specification 6.2.2 Syntax-Based Normalization (rfc3986) *this Normalize the URL authority Applies Syntax-based normalization to the URL authority. Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded. Exception Safety Strong guarantee. Calls to allocate may throw. Specification 6.2.2 Syntax-Based Normalization (rfc3986) *this Normalize the URL fragment Applies Syntax-based normalization to the URL fragment. Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded. Exception Safety Strong guarantee. Calls to allocate may throw. Specification 6.2.2 Syntax-Based Normalization (rfc3986) *this Normalize the URL path Applies Syntax-based normalization to the URL path. Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded. Redundant path-segments are removed. Exception Safety Strong guarantee. Calls to allocate may throw. Specification 6.2.2 Syntax-Based Normalization (rfc3986) *this Normalize the URL query Applies Syntax-based normalization to the URL query. Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded. Exception Safety Strong guarantee. Calls to allocate may throw. Specification 6.2.2 Syntax-Based Normalization (rfc3986) *this Normalize the URL scheme Applies Syntax-based normalization to the URL scheme. The scheme is normalized to lowercase. Exception Safety Strong guarantee. Calls to allocate may throw. Specification 6.2.2 Syntax-Based Normalization (rfc3986) *this Return the query as a container of parameters This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first. The container is modifiable; changes to the container are reflected in the underlying URL. 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 3.4. Query (rfc3986) Query string (Wikipedia) *this encoded_params , remove_query , set_encoded_query , set_query . Return the query as a container of parameters A bidirectional view of key/value pairs. encoded_params , encoded_query , has_query , query . Return the query as a container of parameters This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first. The container is modifiable; changes to the container are reflected in the underlying URL. 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 3.4. Query (rfc3986) Query string (Wikipedia) A range of references to the parameters. The options for decoding. If this parameter is omitted, the space_as_plus is used. encoded_params , remove_query , set_encoded_query , set_query . Return a shared, persistent copy of the url This function returns a read-only copy of the url, with shared lifetime. The returned value owns (persists) the underlying string. The algorithm used to create the value minimizes the number of individual memory allocations, making it more efficient than when using direct standard library functions. 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. A shared pointer to a read-only url_view. Return the port 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 = *DIGIT Specification 3.2.3. Port (rfc3986) The port as a string. encoded_host_and_port , has_port , port_number . Return the port If a port is present and the numerical value is representable, it is returned as an unsigned integer. Otherwise, the number zero is returned. Example assert( url_view( "http://localhost.com:8080" ).port_number() == 8080 ); Complexity Constant. Exception Safety Throws nothing. BNF port = *DIGIT Specification 3.2.3. Port (rfc3986) The port number as an unsigned integer. encoded_host_and_port , has_port , port . Remove the authority 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() == false Complexity 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 = *DIGIT Specification 3.2. Authority (rfc3986) *this set_encoded_authority . Remove the fragment 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 / "/" / "?" ) Specification 3.5. Fragment *this remove_fragment , set_encoded_fragment , set_fragment . Remove the origin component 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() == false Complexity Linear in this->size() . Exception Safety Throws nothing. *this Remove the password This function removes the password from the userinfo if a password exists. If there is no userinfo or no authority, the call has no effect. The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated. Example assert( url( "http://user:pass@example.com" ).remove_password().authority().buffer() == "user@example.com" ); Postconditions this->has_password() == false && this->encoded_password().empty() == true Complexity Linear in this->size() . Exception Safety Throws nothing. BNF userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" ) Specification 3.2.1. User Information (rfc3986) *this set_encoded_password , set_encoded_user , set_password , set_user . Remove the port 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 = *DIGIT Specification 3.2.3. Port (rfc3986) *this set_port . Remove the query 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 3.4. Query (rfc3986) Query string (Wikipedia) *this encoded_params , params , set_encoded_query , set_query . Remove the scheme 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::none Complexity Linear in this->size() . Exception Safety Throws nothing. BNF URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] Specification 3.1. Scheme (rfc3986) *this set_scheme . Remove the userinfo 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 == true Complexity Linear in this->size() . Exception Safety Throws nothing. BNF userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" ) Specification 3.2.1. User Information (rfc3986) *this set_encoded_userinfo , set_userinfo . Adjust the capacity without changing the size This function adjusts the capacity of the container in characters, without affecting the current contents. Has no effect if n <= this->capacity() . Exception Safety Strong guarantee. Calls to allocate may throw. The capacity in characters, excluding any null terminator. Allocation failure Resolve a URL reference against this base URL This function attempts to resolve a URL reference ref against this base URL in a manner similar to that of a web browser resolving an anchor tag. This URL must satisfy the URI grammar. In other words, it must contain a scheme. Relative references are only usable when in the context of a base absolute URI. This process of resolving a relative reference within the context of a base URI is defined in detail in rfc3986 (see below). The resolution process works as if the relative reference is appended to the base URI and the result is normalized. Given the input base URL, this function resolves the relative reference as if performing the following steps: 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. Abnormal hrefs where the number of ".." segments exceeds the number of segments in the base path are handled by including the unmatched ".." segments in the result, as described in Errata 4547 . 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 An empty boost::system::result upon success, otherwise an error code if !base.has_scheme() . The URL reference to resolve. url , url_view . Return the scheme This function returns the scheme if it exists, without a trailing colon (':'). Otherwise it returns an empty string. Note that schemes are case-insensitive, and the canonical form is lowercased. 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 ] Specification 3.1. Scheme (rfc3986) The scheme as a string. has_scheme , scheme_id . Return the scheme 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::scheme is 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 / "+" / "-" / "." ) Specification 3.1. Scheme (rfc3986) The scheme as an enumeration value. has_scheme , scheme . Return the path as a container of segments This function returns a bidirectional view of segments over the path. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first. The container is modifiable; changes to the container are reflected in the underlying URL. 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> Specification 3.3. Path (rfc3986) *this encoded_segments , set_encoded_path , set_path , set_path_absolute . Return the path as a container of segments This function returns a bidirectional view of strings over the path. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first. Example segments_view sv = url_view( "/path/to/file.txt" ).segments(); Complexity Constant. Exception Safety Throws nothing. BNF path = [ "/" ] segment *( "/" segment ) Specification 3.3. Path (rfc3986) A bidirectional view of segments. is_path_absolute , encoded_path , encoded_segments . path , segments_view . Set the authority 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 = *DIGIT Specification 3.2. Authority (rfc3986) *this The authority string to set. remove_authority . Set the fragment. This function sets the fragment to the specified string, which may contain percent-escapes and which may be empty. An empty fragment is distinct from having no fragment. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. 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 / "/" / "?" ) Specification 3.5. Fragment *this The string to set. remove_fragment , set_fragment . Set the host 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() == true Complexity 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 IPv4 (Wikipedia) IP Version 6 Addressing Architecture (rfc4291) 3.2.2. Host (rfc3986) *this The string to set. 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 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() == true Complexity 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 IPv4 (Wikipedia) IP Version 6 Addressing Architecture (rfc4291) 3.2.2. Host (rfc3986) *this The string to set. 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 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::name Exception Safety Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input. BNF reg-name = *( unreserved / pct-encoded / "-" / ".") Specification 3.2.2. Host (rfc3986) *this The string to set. 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 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() == true Complexity 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 3.4. Query (rfc3986) Query string (Wikipedia) *this The params to set. set_params , params , remove_query , set_encoded_query , set_query . Set the password. This function sets the password in the userinfo to the string, which may contain percent-escapes. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated. Example assert( url("http://user@example.com").set_encoded_password( "pass" ).encoded_userinfo() == "user:pass" ); Postconditions this->has_password() == true 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 / ":" ) Specification 3.2.1. User Information (rfc3986) *this The string to set. This string may contain any characters, including nulls. remove_password , set_encoded_password , set_encoded_user , set_user . Set the path. This function sets the path to the string, which may contain percent-escapes and can be empty. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. The library may adjust the final result to ensure that no other parts of the url is semantically affected. 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> Specification 3.3. Path (rfc3986) *this The string to set. encoded_segments , segments , set_path , set_path_absolute . Set the query This sets the query to the string, which may contain percent-escapes and can be empty. An empty query is distinct from having no query. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. 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 3.4. Query (rfc3986) Query string (Wikipedia) *this The string to set. encoded_params , params , remove_query , set_query . Set the user This function sets the user part of the userinfo the the string, which may contain percent-escapes. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. Example assert( url().set_encoded_user("john%20doe").userinfo() == "john doe" ); Postconditions this->has_authority() == true && this->has_userinfo() == true 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 / ":" ) Specification 3.2.1. User Information (rfc3986) *this The string to set. remove_password , set_encoded_password , set_password , set_user . Set the userinfo. The userinfo is set to the given string, which may contain percent-escapes. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. The effects on the user and password depend on the presence of a colon (':') in the string: 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_password returns true. Otherwise, If there is no colon, the user is set to the string. The function has_password returns false. 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 / ":" ) Specification 3.2.1. User Information (rfc3986) *this The string to set. remove_userinfo , set_userinfo . Set the zone ID for an IPv6 address (percent-encoded). 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 RFC 6874 *this The zone ID to set. s contains an invalid percent-encoding. Set the zone ID for an IPv6 address (percent-encoded). 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 RFC 6874 *this The zone ID to set. Set the fragment. This function sets the fragment to the specified string, which may be empty. An empty fragment is distinct from having no fragment. Reserved characters in the string are percent-escaped in the result. Example assert( url("?first=john&last=doe" ).set_encoded_fragment( "john doe" ).encoded_fragment() == "john%20doe" ); Postconditions this->has_fragment() == true && this->fragment() == s Complexity Linear in this->size() + s.size() . Exception Safety Strong guarantee. Calls to allocate may throw. BNF fragment = *( pchar / "/" / "?" ) Specification 3.5. Fragment *this The string to set. remove_fragment , set_encoded_fragment . Set the host 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() == true Complexity 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 IPv4 (Wikipedia) IP Version 6 Addressing Architecture (rfc4291) 3.2.2. Host (rfc3986) *this The string to set. 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 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() == true Complexity 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 IPv4 (Wikipedia) IP Version 6 Addressing Architecture (rfc4291) 3.2.2. Host (rfc3986) *this The string to set. 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 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::ipv4 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 Specification IPv4 (Wikipedia) 3.2.2. Host (rfc3986) *this The address to set. 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 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::ipv6 Complexity 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 hexadecimal Specification IP Version 6 Addressing Architecture (rfc4291) 3.2.2. Host (rfc3986) *this The address to set. 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 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::ipvfuture Exception Safety Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input. BNF IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" ) Specification 3.2.2. Host (rfc3986) *this The string to set. 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 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::name Exception Safety Strong guarantee. Calls to allocate may throw. BNF reg-name = *( unreserved / pct-encoded / "-" / ".") Specification 3.2.2. Host (rfc3986) *this The string to set. 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 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() == true Exception Safety Strong guarantee. Calls to allocate may throw. Complexity Linear. BNF query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param ) Specification ://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia) *this The params to set. The options for encoding. encoded_params , remove_query , set_encoded_query , set_query . Set the password. This function sets the password in the userinfo to the string. Reserved characters in the string are percent-escaped in the result. The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated. Example assert( url("http://user@example.com").set_password( "pass" ).encoded_userinfo() == "user:pass" ); Postconditions this->has_password() == true && this->password() == s 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 / ":" ) Specification 3.2.1. User Information (rfc3986) *this The string to set. This string may contain any characters, including nulls. remove_password , set_encoded_password , set_encoded_user , set_user . Set the path. This function sets the path to the string, which may be empty. Reserved characters in the string are percent-escaped in the result. The library may adjust the final result to ensure that no other parts of the URL are semantically affected. This function does not encode '/' chars, which are unreserved for paths but reserved for path segments. If a path segment should include encoded '/'s to differentiate it from path separators, the functions set_encoded_path or segments should be used instead. 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> Specification 3.3. Path (rfc3986) *this The string to set. encoded_segments , segments , set_encoded_path , set_path_absolute . Set if the path is absolute This function adjusts the path to make it absolute or not, depending on the parameter. If an authority is present, the path is always absolute. In this case, the function has no effect. 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> Specification 3.3. Path (rfc3986) true on success. If true , the path is made absolute. encoded_segments , segments , set_encoded_path , set_path . Set the port This port is set to the string, which must contain only digits or be empty. An empty port string is distinct from having no port. 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 = *DIGIT Specification 3.2.3. Port (rfc3986) *this The port string to set. remove_port , set_port . Set the port 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() == n Complexity Linear in this->size() . Exception Safety Strong guarantee. Calls to allocate may throw. BNF authority = [ userinfo "@" ] host [ ":" port ] port = *DIGIT Specification 3.2.3. Port (rfc3986) *this The port number to set. remove_port , set_port . Set the query This sets the query to the string, which can be empty. An empty query is distinct from having no query. Reserved characters in the string are percent-escaped in the result. Example assert( url( "http://example.com" ).set_query( "id=42" ).query() == "id=42" ); Postconditions this->has_query() == true && this->query() == s Exception Safety Strong guarantee. Calls to allocate may throw. BNF query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param ) Specification 3.4. Query (rfc3986) Query string (Wikipedia) *this The string to set. encoded_params , params , remove_query , set_encoded_query . Set the scheme The scheme is set to the specified string, which must contain a valid scheme without any trailing colon (':'). Note that schemes are case-insensitive, and the canonical form is lowercased. 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 / "+" / "-" / "." ) Specification 3.1. Scheme (rfc3986) *this The scheme to set. remove_scheme . Set the scheme This function sets the scheme to the specified known urls::scheme id, which may not be scheme::unknown or else an exception is thrown. If the id is scheme::none , this function behaves as if remove_scheme were called. 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. Specification 3.1. Scheme (rfc3986) *this The scheme to set. Set the user This function sets the user part of the userinfo to the string. Any special or reserved characters in the string are automatically percent-encoded. Example assert( url().set_user("john doe").encoded_userinfo() == "john%20doe" ); Postconditions this->has_authority() == true && this->has_userinfo() == true 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 / ":" ) Specification 3.2.1. User Information (rfc3986) *this The string to set. remove_password , set_encoded_password , set_encoded_user , set_password . Set the userinfo The userinfo is set to the given string, which may contain percent-escapes. Any special or reserved characters in the string are automatically percent-encoded. The effects on the user and password depend on the presence of a colon (':') in the string: 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_password returns true. Otherwise, If there is no colon, the user is set to the string. The function has_password returns false. 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 / ":" ) Specification 3.2.1. User Information (rfc3986) *this The string to set. remove_userinfo , set_encoded_userinfo . Set the zone ID for an IPv6 address. 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 RFC 6874 *this The zone ID to set. Return the number of characters in the url This function returns the number of characters in the url's encoded string, not including any null terminator, if present. Example assert( url_view( "file:///Program%20Files" ).size() == 23 ); Complexity Constant. Exception Safety Throws nothing. The number of characters in the url. Swap the contents. Exchanges the contents of this url with another url. All views, iterators and references remain valid. If this == &other , this function call has no effect. 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. The object to swap with Return the URL as a core::string_view Complexity Constant. Exception Safety Throws nothing. A string view of the URL. Return the maximum number of characters possible 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. The maximum number of characters. Calculate a hash of the url This function calculates a hash of the url as if it were always normalized. Complexity Linear in this->size() . Exception Safety Throws nothing. A hash value suitable for use in hash-based containers. An initial value to add to the hash Common functionality for containers This base class is used by the library to provide common member functions for containers. This cannot be instantiated directly; Instead, use one of the containers or functions: Containers url url_view static_url Functions parse_absolute_uri parse_origin_form parse_relative_ref parse_uri parse_uri_reference format_to format_to operator!= operator< operator<= operator== operator> operator>= Return the authority 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 ] Specification 3.2. Authority (rfc3986) An authority_view representing the authority. encoded_authority , has_authority . Return the url string 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. The url as a string. Return the url as a null-terminated string This function returns a pointer to a null terminated string representing the url, which may contain percent escapes. Example assert( std::strlen( url( "http://www.example.com" ).c_str() ) == 22 ); Complexity Constant. Exception Safety Throws nothing. A pointer to a null-terminated string containing the URL. Return the number of characters that can be stored without reallocating This does not include the null terminator, which is always present. Complexity Constant. Exception Safety Throws nothing. *this Clear the contents while preserving the capacity Postconditions this->empty() == true Complexity Constant. Exception Safety No-throw guarantee. Return the result of comparing this with another url This function compares two URLs according to Syntax-Based comparison algorithm. Complexity Linear in min( u0.size(), u1.size() ) Exception Safety Throws nothing. Specification 6.2.2 Syntax-Based Normalization (rfc3986) -1 if *this < other , 0 if this == other , and 1 if this > other . The url to compare Return a pointer to the url's character buffer This function returns a pointer to the first character of the url, which is not guaranteed to be null-terminated. Complexity Constant. Exception Safety Throws nothing. A pointer to the first character. Return true if the url is empty 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-empty Specification 4.2. Relative Reference (rfc3986) true if the url is empty. Return the authority. 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 ] Specification 3.2. Authority (rfc3986) The authority as a string. authority , has_authority . Return the fragment 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 / ":" / "@" Specification 3.5. Fragment (rfc3986) The fragment portion of the url. fragment , has_fragment . Return the host This function returns the host portion of the authority as a string, or the empty string if there is no authority. The returned string may contain percent escapes. 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 / "-" / ".") Specification 3.2.2. Host (rfc3986) The host address as a string. Return the host 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 / "-" / ".") Specification 3.2.2. Host (rfc3986) The host address as a string. Return the host and port 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 3.2.2. Host (rfc3986) 3.2.3. Port (rfc3986) The host and port portion of the url. has_port , port , port_number . Return the host name 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 / "-" / ".") Specification 3.2.2. Host (rfc3986) The host name as a percent-encoded string. Return the origin If an authority is present, this function returns the scheme and authority portion of the url. Otherwise, an empty string is returned. The returned string may contain percent escapes. 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. The origin portion of the url. encoded_resource , encoded_target . Return the query as a container of parameters This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Strings returned when iterating the range may contain percent escapes. The container is modifiable; changes to the container are reflected in the underlying URL. 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 3.4. Query (rfc3986) Query string (Wikipedia) *this params , remove_query , set_encoded_query , set_query . Return the query as a container of parameters This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Strings returned when iterating the range may contain percent escapes. 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 3.4. Query (rfc3986) Query string (Wikipedia) A bidirectional view of key/value pairs. encoded_query , has_query , params , query . Return the password 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 / ":" ) Specification 3.2.1. User Information (rfc3986) The password as a string. has_password , has_userinfo , encoded_user , encoded_userinfo , password , user , userinfo . Return the path This function returns the path as a string. The path may be empty. Any percent-escapes in the string are decoded first. 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> Specification 3.3. Path (rfc3986) The path as a string. is_path_absolute , encoded_segments . path , segments . Return the query If this contains a query, it is returned as a string (which may be empty). Otherwise, an empty string is returned. The returned string may contain percent escapes. 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 3.4. Query (rfc3986) Query string (Wikipedia) The query as a string. encoded_params , has_query , params , query . Return the resource 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 3.3. Path (rfc3986) 3.4. Query (rfc3986) The resource portion of the url. encoded_origin , encoded_target . Return the path as a container of segments This function returns a bidirectional view of segments over the path. The returned view references the same underlying character buffer; ownership is not transferred. Strings returned when iterating the range may contain percent escapes. The container is modifiable; changes to the container are reflected in the underlying URL. 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> Specification 3.3. Path (rfc3986) *this encoded_segments , set_encoded_path , set_path , set_path_absolute . Return the path as a container of segments This function returns a bidirectional view of strings over the path. The returned view references the same underlying character buffer; ownership is not transferred. 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> Specification 3.3. Path (rfc3986) A bidirectional view of encoded segments. is_path_absolute , encoded_path , path , segments , segments_encoded_view . Return the target This function returns the target, which is the portion of the url that includes only the path and query. The returned string may contain percent escapes. Example assert( url_view( "http://www.example.com/index.html?query#frag" ).encoded_target() == "/index.html?query" ); Complexity Constant. Exception Safety Throws nothing. Specification 3.3. Path (rfc3986) 3.4. Query (rfc3986) The target portion of the url. encoded_origin , encoded_resource . Return the user If present, this function returns a string representing the user (which may be empty). Otherwise it returns an empty string. The returned string may contain percent escapes. 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 / ":" ) Specification 3.2.1. User Information (rfc3986) The user as a string. has_password , has_userinfo , encoded_password , encoded_userinfo , password , user , userinfo . Return the userinfo 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 ] Specification 3.2.1. User Information (rfc3986) The userinfo as a string. has_password , has_userinfo , encoded_password , encoded_user , password , user , userinfo . Return the IPv6 Zone ID 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" ZoneID Specification Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers The Zone ID as a percent-encoded string. Return true if an authority is present 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...) Specification 3.2. Authority (rfc3986) true if the url contains an authority. authority , encoded_authority . Return true if a fragment is present This function returns true if the url contains a fragment. An empty fragment is distinct from no fragment. 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 ] Specification 3.5. Fragment (rfc3986) true if the url contains a fragment. encoded_fragment , fragment . Return true if a password is present 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 / ":" ) Specification 3.2.1. User Information (rfc3986) true if the userinfo contains a password. has_userinfo , encoded_password , encoded_user , encoded_userinfo , password , user , userinfo . Return true if a port is present 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 = *DIGIT Specification 3.2.3. Port (rfc3986) true if a port is present, false otherwise. encoded_host_and_port , port , port_number . Return true if a query is present This function returns true if this contains a query. An empty query is distinct from having no query. 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 3.4. Query (rfc3986) Query string (Wikipedia) true if a query is present. encoded_params , encoded_query , params , query . Return true a scheme is present 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 / "+" / "-" / "." ) Specification 3.1. Scheme (rfc3986) true if the url contains a scheme. scheme , scheme_id . Return true if a userinfo is present 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 ] Specification 3.2.1. User Information (rfc3986) true if the userinfo is present. has_password , encoded_password , encoded_user , encoded_userinfo , password , user , userinfo . Return the host IPv4 address If the host type is host_type::ipv4 , this function returns the address as a value of type ipv4_address . Otherwise, if the host type is not an IPv4 address, it returns a default-constructed value which is equal to the unspecified address "0.0.0.0". 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-255 Specification 3.2.2. Host (rfc3986) The IPv4 address as a value of type ipv4_address . Return the host IPv6 address If the host type is host_type::ipv6 , this function returns the address as a value of type ipv6_address . Otherwise, if the host type is not an IPv6 address, it returns a default-constructed value which is equal to the unspecified address "0:0:0:0:0:0:0:0". 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 hexadecimal Specification 3.2.2. Host (rfc3986) The IPv6 address as a value of type ipv6_address . Return the host IPvFuture address 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 / ":" ) Specification 3.2.2. Host (rfc3986) The IPvFuture address as a string. Return the host type 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. Specification 3.2.2. Host (rfc3986) The type of host present. Return true if the path is absolute 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> Specification 3.3. Path (rfc3986) true if the path is absolute, false otherwise. encoded_path , encoded_segments . path , segments . Normalize the URL components Applies Syntax-based normalization to all components of the URL. Exception Safety Strong guarantee. Calls to allocate may throw. Specification 6.2.2 Syntax-Based Normalization (rfc3986) *this Normalize the URL authority Applies Syntax-based normalization to the URL authority. Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded. Exception Safety Strong guarantee. Calls to allocate may throw. Specification 6.2.2 Syntax-Based Normalization (rfc3986) *this Normalize the URL fragment Applies Syntax-based normalization to the URL fragment. Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded. Exception Safety Strong guarantee. Calls to allocate may throw. Specification 6.2.2 Syntax-Based Normalization (rfc3986) *this Normalize the URL path Applies Syntax-based normalization to the URL path. Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded. Redundant path-segments are removed. Exception Safety Strong guarantee. Calls to allocate may throw. Specification 6.2.2 Syntax-Based Normalization (rfc3986) *this Normalize the URL query Applies Syntax-based normalization to the URL query. Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded. Exception Safety Strong guarantee. Calls to allocate may throw. Specification 6.2.2 Syntax-Based Normalization (rfc3986) *this Normalize the URL scheme Applies Syntax-based normalization to the URL scheme. The scheme is normalized to lowercase. Exception Safety Strong guarantee. Calls to allocate may throw. Specification 6.2.2 Syntax-Based Normalization (rfc3986) *this Return the query as a container of parameters This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first. The container is modifiable; changes to the container are reflected in the underlying URL. 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 3.4. Query (rfc3986) Query string (Wikipedia) *this encoded_params , remove_query , set_encoded_query , set_query . Return the query as a container of parameters A bidirectional view of key/value pairs. encoded_params , encoded_query , has_query , query . Return the query as a container of parameters This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first. The container is modifiable; changes to the container are reflected in the underlying URL. 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 3.4. Query (rfc3986) Query string (Wikipedia) A range of references to the parameters. The options for decoding. If this parameter is omitted, the space_as_plus is used. encoded_params , remove_query , set_encoded_query , set_query . Return a shared, persistent copy of the url This function returns a read-only copy of the url, with shared lifetime. The returned value owns (persists) the underlying string. The algorithm used to create the value minimizes the number of individual memory allocations, making it more efficient than when using direct standard library functions. 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. A shared pointer to a read-only url_view. Return the port 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 = *DIGIT Specification 3.2.3. Port (rfc3986) The port as a string. encoded_host_and_port , has_port , port_number . Return the port If a port is present and the numerical value is representable, it is returned as an unsigned integer. Otherwise, the number zero is returned. Example assert( url_view( "http://localhost.com:8080" ).port_number() == 8080 ); Complexity Constant. Exception Safety Throws nothing. BNF port = *DIGIT Specification 3.2.3. Port (rfc3986) The port number as an unsigned integer. encoded_host_and_port , has_port , port . Remove the authority 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() == false Complexity 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 = *DIGIT Specification 3.2. Authority (rfc3986) *this set_encoded_authority . Remove the fragment 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 / "/" / "?" ) Specification 3.5. Fragment *this remove_fragment , set_encoded_fragment , set_fragment . Remove the origin component 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() == false Complexity Linear in this->size() . Exception Safety Throws nothing. *this Remove the password This function removes the password from the userinfo if a password exists. If there is no userinfo or no authority, the call has no effect. The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated. Example assert( url( "http://user:pass@example.com" ).remove_password().authority().buffer() == "user@example.com" ); Postconditions this->has_password() == false && this->encoded_password().empty() == true Complexity Linear in this->size() . Exception Safety Throws nothing. BNF userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" ) Specification 3.2.1. User Information (rfc3986) *this set_encoded_password , set_encoded_user , set_password , set_user . Remove the port 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 = *DIGIT Specification 3.2.3. Port (rfc3986) *this set_port . Remove the query 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 3.4. Query (rfc3986) Query string (Wikipedia) *this encoded_params , params , set_encoded_query , set_query . Remove the scheme 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::none Complexity Linear in this->size() . Exception Safety Throws nothing. BNF URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] Specification 3.1. Scheme (rfc3986) *this set_scheme . Remove the userinfo 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 == true Complexity Linear in this->size() . Exception Safety Throws nothing. BNF userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" ) Specification 3.2.1. User Information (rfc3986) *this set_encoded_userinfo , set_userinfo . Adjust the capacity without changing the size This function adjusts the capacity of the container in characters, without affecting the current contents. Has no effect if n <= this->capacity() . Exception Safety Strong guarantee. Calls to allocate may throw. The capacity in characters, excluding any null terminator. Allocation failure Resolve a URL reference against this base URL This function attempts to resolve a URL reference ref against this base URL in a manner similar to that of a web browser resolving an anchor tag. This URL must satisfy the URI grammar. In other words, it must contain a scheme. Relative references are only usable when in the context of a base absolute URI. This process of resolving a relative reference within the context of a base URI is defined in detail in rfc3986 (see below). The resolution process works as if the relative reference is appended to the base URI and the result is normalized. Given the input base URL, this function resolves the relative reference as if performing the following steps: 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. Abnormal hrefs where the number of ".." segments exceeds the number of segments in the base path are handled by including the unmatched ".." segments in the result, as described in Errata 4547 . 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 An empty boost::system::result upon success, otherwise an error code if !base.has_scheme() . The URL reference to resolve. url , url_view . Return the scheme This function returns the scheme if it exists, without a trailing colon (':'). Otherwise it returns an empty string. Note that schemes are case-insensitive, and the canonical form is lowercased. 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 ] Specification 3.1. Scheme (rfc3986) The scheme as a string. has_scheme , scheme_id . Return the scheme 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::scheme is 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 / "+" / "-" / "." ) Specification 3.1. Scheme (rfc3986) The scheme as an enumeration value. has_scheme , scheme . Return the path as a container of segments This function returns a bidirectional view of segments over the path. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first. The container is modifiable; changes to the container are reflected in the underlying URL. 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> Specification 3.3. Path (rfc3986) *this encoded_segments , set_encoded_path , set_path , set_path_absolute . Return the path as a container of segments This function returns a bidirectional view of strings over the path. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first. Example segments_view sv = url_view( "/path/to/file.txt" ).segments(); Complexity Constant. Exception Safety Throws nothing. BNF path = [ "/" ] segment *( "/" segment ) Specification 3.3. Path (rfc3986) A bidirectional view of segments. is_path_absolute , encoded_path , encoded_segments . path , segments_view . Set the authority 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 = *DIGIT Specification 3.2. Authority (rfc3986) *this The authority string to set. The string contains an invalid percent-encoding. remove_authority . Set the fragment. This function sets the fragment to the specified string, which may contain percent-escapes and which may be empty. An empty fragment is distinct from having no fragment. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. 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 / "/" / "?" ) Specification 3.5. Fragment *this *this The string to set. s contains an invalid percent-encoding. remove_fragment , set_fragment . Set the host 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() == true Complexity 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 IPv4 (Wikipedia) IP Version 6 Addressing Architecture (rfc4291) 3.2.2. Host (rfc3986) *this The string to set. s contains an invalid percent-encoding. 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 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() == true Complexity 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 IPv4 (Wikipedia) IP Version 6 Addressing Architecture (rfc4291) 3.2.2. Host (rfc3986) *this The string to set. s contains an invalid percent-encoding. 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 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::name Exception Safety Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input. BNF reg-name = *( unreserved / pct-encoded / "-" / ".") Specification 3.2.2. Host (rfc3986) *this The string to set. s contains an invalid percent-encoding. 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 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() == true Complexity 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 3.4. Query (rfc3986) Query string (Wikipedia) *this The params to set. some element in ps contains an invalid percent-encoding. set_params , params , remove_query , set_encoded_query , set_query . Set the password. This function sets the password in the userinfo to the string, which may contain percent-escapes. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated. Example assert( url("http://user@example.com").set_encoded_password( "pass" ).encoded_userinfo() == "user:pass" ); Postconditions this->has_password() == true 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 / ":" ) Specification 3.2.1. User Information (rfc3986) *this The string to set. This string may contain any characters, including nulls. s contains an invalid percent-encoding. remove_password , set_encoded_password , set_encoded_user , set_user . Set the path. This function sets the path to the string, which may contain percent-escapes and can be empty. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. The library may adjust the final result to ensure that no other parts of the url is semantically affected. 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> Specification 3.3. Path (rfc3986) *this The string to set. s contains an invalid percent-encoding. encoded_segments , segments , set_path , set_path_absolute . Set the query This sets the query to the string, which may contain percent-escapes and can be empty. An empty query is distinct from having no query. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. 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 3.4. Query (rfc3986) Query string (Wikipedia) *this The string to set. s contains an invalid percent-encoding. encoded_params , params , remove_query , set_query . Set the user This function sets the user part of the userinfo the the string, which may contain percent-escapes. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. Example assert( url().set_encoded_user("john%20doe").userinfo() == "john doe" ); Postconditions this->has_authority() == true && this->has_userinfo() == true 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 / ":" ) Specification 3.2.1. User Information (rfc3986) *this *this The string to set. s contains an invalid percent-encoding. remove_password , set_encoded_password , set_password , set_user . Set the userinfo. The userinfo is set to the given string, which may contain percent-escapes. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. The effects on the user and password depend on the presence of a colon (':') in the string: 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_password returns true. Otherwise, If there is no colon, the user is set to the string. The function has_password returns false. 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 / ":" ) Specification 3.2.1. User Information (rfc3986) *this The string to set. s contains an invalid percent-encoding. remove_userinfo , set_userinfo . Set the zone ID for an IPv6 address (percent-encoded). 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 RFC 6874 *this The zone ID to set. s contains an invalid percent-encoding. Set the fragment. This function sets the fragment to the specified string, which may be empty. An empty fragment is distinct from having no fragment. Reserved characters in the string are percent-escaped in the result. Example assert( url("?first=john&last=doe" ).set_encoded_fragment( "john doe" ).encoded_fragment() == "john%20doe" ); Postconditions this->has_fragment() == true && this->fragment() == s Complexity Linear in this->size() + s.size() . Exception Safety Strong guarantee. Calls to allocate may throw. BNF fragment = *( pchar / "/" / "?" ) Specification 3.5. Fragment *this The string to set. remove_fragment , set_encoded_fragment . Set the host 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() == true Complexity 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 IPv4 (Wikipedia) IP Version 6 Addressing Architecture (rfc4291) 3.2.2. Host (rfc3986) *this The string to set. 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 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() == true Complexity 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 IPv4 (Wikipedia) IP Version 6 Addressing Architecture (rfc4291) 3.2.2. Host (rfc3986) *this The string to set. 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 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::ipv4 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 Specification IPv4 (Wikipedia) 3.2.2. Host (rfc3986) *this The address to set. 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 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::ipv6 Complexity 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 hexadecimal Specification IP Version 6 Addressing Architecture (rfc4291) 3.2.2. Host (rfc3986) *this The address to set. 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 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::ipvfuture Exception Safety Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input. BNF IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" ) Specification 3.2.2. Host (rfc3986) *this The string to set. s contains an invalid percent-encoding. 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 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::name Exception Safety Strong guarantee. Calls to allocate may throw. BNF reg-name = *( unreserved / pct-encoded / "-" / ".") Specification 3.2.2. Host (rfc3986) *this The string to set. 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 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() == true Exception Safety Strong guarantee. Calls to allocate may throw. Complexity Linear. BNF query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param ) Specification ://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia) *this The params to set. The options for encoding. encoded_params , remove_query , set_encoded_query , set_query . Set the password. This function sets the password in the userinfo to the string. Reserved characters in the string are percent-escaped in the result. The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated. Example assert( url("http://user@example.com").set_password( "pass" ).encoded_userinfo() == "user:pass" ); Postconditions this->has_password() == true && this->password() == s 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 / ":" ) Specification 3.2.1. User Information (rfc3986) *this The string to set. This string may contain any characters, including nulls. remove_password , set_encoded_password , set_encoded_user , set_user . Set the path. This function sets the path to the string, which may be empty. Reserved characters in the string are percent-escaped in the result. The library may adjust the final result to ensure that no other parts of the URL are semantically affected. This function does not encode '/' chars, which are unreserved for paths but reserved for path segments. If a path segment should include encoded '/'s to differentiate it from path separators, the functions set_encoded_path or segments should be used instead. 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> Specification 3.3. Path (rfc3986) *this The string to set. encoded_segments , segments , set_encoded_path , set_path_absolute . Set if the path is absolute This function adjusts the path to make it absolute or not, depending on the parameter. If an authority is present, the path is always absolute. In this case, the function has no effect. 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> Specification 3.3. Path (rfc3986) true on success. If true , the path is made absolute. encoded_segments , segments , set_encoded_path , set_path . Set the port This port is set to the string, which must contain only digits or be empty. An empty port string is distinct from having no port. 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 = *DIGIT Specification 3.2.3. Port (rfc3986) *this The port string to set. s does not contain a valid port. remove_port , set_port . Set the port 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() == n Complexity Linear in this->size() . Exception Safety Strong guarantee. Calls to allocate may throw. BNF authority = [ userinfo "@" ] host [ ":" port ] port = *DIGIT Specification 3.2.3. Port (rfc3986) *this The port number to set. remove_port , set_port . Set the query This sets the query to the string, which can be empty. An empty query is distinct from having no query. Reserved characters in the string are percent-escaped in the result. Example assert( url( "http://example.com" ).set_query( "id=42" ).query() == "id=42" ); Postconditions this->has_query() == true && this->query() == s Exception Safety Strong guarantee. Calls to allocate may throw. BNF query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param ) Specification 3.4. Query (rfc3986) Query string (Wikipedia) *this The string to set. encoded_params , params , remove_query , set_encoded_query . Set the scheme The scheme is set to the specified string, which must contain a valid scheme without any trailing colon (':'). Note that schemes are case-insensitive, and the canonical form is lowercased. 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 / "+" / "-" / "." ) Specification 3.1. Scheme (rfc3986) *this The scheme to set. s contains an invalid scheme. remove_scheme . Set the scheme This function sets the scheme to the specified known urls::scheme id, which may not be scheme::unknown or else an exception is thrown. If the id is scheme::none , this function behaves as if remove_scheme were called. 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. Specification 3.1. Scheme (rfc3986) *this The scheme to set. The scheme is invalid. Set the user This function sets the user part of the userinfo to the string. Any special or reserved characters in the string are automatically percent-encoded. Example assert( url().set_user("john doe").encoded_userinfo() == "john%20doe" ); Postconditions this->has_authority() == true && this->has_userinfo() == true 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 / ":" ) Specification 3.2.1. User Information (rfc3986) *this The string to set. remove_password , set_encoded_password , set_encoded_user , set_password . Set the userinfo The userinfo is set to the given string, which may contain percent-escapes. Any special or reserved characters in the string are automatically percent-encoded. The effects on the user and password depend on the presence of a colon (':') in the string: 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_password returns true. Otherwise, If there is no colon, the user is set to the string. The function has_password returns false. 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 / ":" ) Specification 3.2.1. User Information (rfc3986) *this The string to set. remove_userinfo , set_encoded_userinfo . Set the zone ID for an IPv6 address. 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 RFC 6874 *this The zone ID to set. Return the number of characters in the url This function returns the number of characters in the url's encoded string, not including any null terminator, if present. Example assert( url_view( "file:///Program%20Files" ).size() == 23 ); Complexity Constant. Exception Safety Throws nothing. The number of characters in the url. Return the URL as a core::string_view Complexity Constant. Exception Safety Throws nothing. A string view of the URL. Return the maximum number of characters possible 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. The maximum number of characters. Calculate a hash of the url This function calculates a hash of the url as if it were always normalized. Complexity Linear in this->size() . Exception Safety Throws nothing. A hash value suitable for use in hash-based containers. An initial value to add to the hash A non-owning reference to a valid URL 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 Uniform Resource Identifier (URI): Generic Syntax (rfc3986) parse_absolute_uri , parse_origin_form , parse_relative_ref , parse_uri , parse_uri_reference . operator!= operator< operator<= operator== operator> operator>= parse_absolute_uri parse_origin_form parse_relative_ref parse_uri parse_uri_reference resolve Constructor Default constructed views refer to a string with zero length, which always remains valid. This matches the grammar for a relative-ref with an empty path and no query or fragment. Example url_view u; Postconditions this->empty() == true Complexity Constant. Exception Safety Throws nothing. BNF relative-ref = relative-part [ "?" query ] [ "#" fragment ] Specification Constructor 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. The other view. Constructor This function constructs a URL from the string s , which must contain a valid URI or relative-ref or else an exception is thrown. Upon successful construction, the view refers to the characters in the buffer pointed to by s . Ownership is not transferred; The caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced. 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 ] Specification 4.1. URI Reference The string to parse. The input failed to parse correctly. parse_uri_reference . Constructor 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. The other view. Destructor Any params, segments, iterators, or other views which reference the same underlying character buffer remain valid. Assignment 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. A reference to this object. The other view. Assignment 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. A reference to this object. The other view. Return the authority 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 ] Specification 3.2. Authority (rfc3986) An authority_view representing the authority. encoded_authority , has_authority . Return the url string 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. The url as a string. Return the result of comparing this with another url This function compares two URLs according to Syntax-Based comparison algorithm. Complexity Linear in min( u0.size(), u1.size() ) Exception Safety Throws nothing. Specification 6.2.2 Syntax-Based Normalization (rfc3986) -1 if *this < other , 0 if this == other , and 1 if this > other . The url to compare Return a pointer to the url's character buffer This function returns a pointer to the first character of the url, which is not guaranteed to be null-terminated. Complexity Constant. Exception Safety Throws nothing. A pointer to the first character. Return true if the url is empty 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-empty Specification 4.2. Relative Reference (rfc3986) true if the url is empty. Return the authority. 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 ] Specification 3.2. Authority (rfc3986) The authority as a string. authority , has_authority . Return the fragment 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 / ":" / "@" Specification 3.5. Fragment (rfc3986) The fragment portion of the url. fragment , has_fragment . Return the host This function returns the host portion of the authority as a string, or the empty string if there is no authority. The returned string may contain percent escapes. 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 / "-" / ".") Specification 3.2.2. Host (rfc3986) The host address as a string. Return the host 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 / "-" / ".") Specification 3.2.2. Host (rfc3986) The host address as a string. Return the host and port 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 3.2.2. Host (rfc3986) 3.2.3. Port (rfc3986) The host and port portion of the url. has_port , port , port_number . Return the host name 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 / "-" / ".") Specification 3.2.2. Host (rfc3986) The host name as a percent-encoded string. Return the origin If an authority is present, this function returns the scheme and authority portion of the url. Otherwise, an empty string is returned. The returned string may contain percent escapes. 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. The origin portion of the url. encoded_resource , encoded_target . Return the query as a container of parameters This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Strings returned when iterating the range may contain percent escapes. 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 3.4. Query (rfc3986) Query string (Wikipedia) A bidirectional view of key/value pairs. encoded_query , has_query , params , query . Return the password 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 / ":" ) Specification 3.2.1. User Information (rfc3986) The password as a string. has_password , has_userinfo , encoded_user , encoded_userinfo , password , user , userinfo . Return the path This function returns the path as a string. The path may be empty. Any percent-escapes in the string are decoded first. 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> Specification 3.3. Path (rfc3986) The path as a string. is_path_absolute , encoded_segments . path , segments . Return the query If this contains a query, it is returned as a string (which may be empty). Otherwise, an empty string is returned. The returned string may contain percent escapes. 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 3.4. Query (rfc3986) Query string (Wikipedia) The query as a string. encoded_params , has_query , params , query . Return the resource 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 3.3. Path (rfc3986) 3.4. Query (rfc3986) The resource portion of the url. encoded_origin , encoded_target . Return the path as a container of segments This function returns a bidirectional view of strings over the path. The returned view references the same underlying character buffer; ownership is not transferred. 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> Specification 3.3. Path (rfc3986) A bidirectional view of encoded segments. is_path_absolute , encoded_path , path , segments , segments_encoded_view . Return the target This function returns the target, which is the portion of the url that includes only the path and query. The returned string may contain percent escapes. Example assert( url_view( "http://www.example.com/index.html?query#frag" ).encoded_target() == "/index.html?query" ); Complexity Constant. Exception Safety Throws nothing. Specification 3.3. Path (rfc3986) 3.4. Query (rfc3986) The target portion of the url. encoded_origin , encoded_resource . Return the user If present, this function returns a string representing the user (which may be empty). Otherwise it returns an empty string. The returned string may contain percent escapes. 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 / ":" ) Specification 3.2.1. User Information (rfc3986) The user as a string. has_password , has_userinfo , encoded_password , encoded_userinfo , password , user , userinfo . Return the userinfo 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 ] Specification 3.2.1. User Information (rfc3986) The userinfo as a string. has_password , has_userinfo , encoded_password , encoded_user , password , user , userinfo . Return the IPv6 Zone ID 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" ZoneID Specification Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers The Zone ID as a percent-encoded string. Return true if an authority is present 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...) Specification 3.2. Authority (rfc3986) true if the url contains an authority. authority , encoded_authority . Return true if a fragment is present This function returns true if the url contains a fragment. An empty fragment is distinct from no fragment. 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 ] Specification 3.5. Fragment (rfc3986) true if the url contains a fragment. encoded_fragment , fragment . Return true if a password is present 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 / ":" ) Specification 3.2.1. User Information (rfc3986) true if the userinfo contains a password. has_userinfo , encoded_password , encoded_user , encoded_userinfo , password , user , userinfo . Return true if a port is present 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 = *DIGIT Specification 3.2.3. Port (rfc3986) true if a port is present, false otherwise. encoded_host_and_port , port , port_number . Return true if a query is present This function returns true if this contains a query. An empty query is distinct from having no query. 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 3.4. Query (rfc3986) Query string (Wikipedia) true if a query is present. encoded_params , encoded_query , params , query . Return true a scheme is present 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 / "+" / "-" / "." ) Specification 3.1. Scheme (rfc3986) true if the url contains a scheme. scheme , scheme_id . Return true if a userinfo is present 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 ] Specification 3.2.1. User Information (rfc3986) true if the userinfo is present. has_password , encoded_password , encoded_user , encoded_userinfo , password , user , userinfo . Return the host IPv4 address If the host type is host_type::ipv4 , this function returns the address as a value of type ipv4_address . Otherwise, if the host type is not an IPv4 address, it returns a default-constructed value which is equal to the unspecified address "0.0.0.0". 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-255 Specification 3.2.2. Host (rfc3986) The IPv4 address as a value of type ipv4_address . Return the host IPv6 address If the host type is host_type::ipv6 , this function returns the address as a value of type ipv6_address . Otherwise, if the host type is not an IPv6 address, it returns a default-constructed value which is equal to the unspecified address "0:0:0:0:0:0:0:0". 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 hexadecimal Specification 3.2.2. Host (rfc3986) The IPv6 address as a value of type ipv6_address . Return the host IPvFuture address 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 / ":" ) Specification 3.2.2. Host (rfc3986) The IPvFuture address as a string. Return the host type 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. Specification 3.2.2. Host (rfc3986) The type of host present. Return true if the path is absolute 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> Specification 3.3. Path (rfc3986) true if the path is absolute, false otherwise. encoded_path , encoded_segments . path , segments . Return the query as a container of parameters This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first. 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 3.4. Query (rfc3986) Query string (Wikipedia) A bidirectional view of key/value pairs. encoded_params , encoded_query , has_query , query . Return a shared, persistent copy of the url This function returns a read-only copy of the url, with shared lifetime. The returned value owns (persists) the underlying string. The algorithm used to create the value minimizes the number of individual memory allocations, making it more efficient than when using direct standard library functions. 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. A shared pointer to a read-only url_view. Return the port 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 = *DIGIT Specification 3.2.3. Port (rfc3986) The port as a string. encoded_host_and_port , has_port , port_number . Return the port If a port is present and the numerical value is representable, it is returned as an unsigned integer. Otherwise, the number zero is returned. Example assert( url_view( "http://localhost.com:8080" ).port_number() == 8080 ); Complexity Constant. Exception Safety Throws nothing. BNF port = *DIGIT Specification 3.2.3. Port (rfc3986) The port number as an unsigned integer. encoded_host_and_port , has_port , port . Return the scheme This function returns the scheme if it exists, without a trailing colon (':'). Otherwise it returns an empty string. Note that schemes are case-insensitive, and the canonical form is lowercased. 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 ] Specification 3.1. Scheme (rfc3986) The scheme as a string. has_scheme , scheme_id . Return the scheme 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::scheme is 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 / "+" / "-" / "." ) Specification 3.1. Scheme (rfc3986) The scheme as an enumeration value. has_scheme , scheme . Return the path as a container of segments This function returns a bidirectional view of strings over the path. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first. Example segments_view sv = url_view( "/path/to/file.txt" ).segments(); Complexity Constant. Exception Safety Throws nothing. BNF path = [ "/" ] segment *( "/" segment ) Specification 3.3. Path (rfc3986) A bidirectional view of segments. is_path_absolute , encoded_path , encoded_segments . path , segments_view . Return the number of characters in the url This function returns the number of characters in the url's encoded string, not including any null terminator, if present. Example assert( url_view( "file:///Program%20Files" ).size() == 23 ); Complexity Constant. Exception Safety Throws nothing. The number of characters in the url. Return the URL as a core::string_view Complexity Constant. Exception Safety Throws nothing. A string view of the URL. Return the maximum number of characters possible This represents the largest number of characters that are possible in a url, not including any null terminator. Complexity Constant. Exception Safety Throws nothing. The maximum number of characters possible. Calculate a hash of the url This function calculates a hash of the url as if it were always normalized. Complexity Linear in this->size() . Exception Safety Throws nothing. A hash value suitable for use in hash-based containers. An initial value to add to the hash Common functionality for containers This base class is used by the library to provide common member functions for containers. This cannot be instantiated directly; Instead, use one of the containers or functions: Containers url url_view static_url Functions parse_absolute_uri parse_origin_form parse_relative_ref parse_uri parse_uri_reference resolve Return the authority 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 ] Specification 3.2. Authority (rfc3986) An authority_view representing the authority. encoded_authority , has_authority . Return the url string 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. The url as a string. Return the result of comparing this with another url This function compares two URLs according to Syntax-Based comparison algorithm. Complexity Linear in min( u0.size(), u1.size() ) Exception Safety Throws nothing. Specification 6.2.2 Syntax-Based Normalization (rfc3986) -1 if *this < other , 0 if this == other , and 1 if this > other . The url to compare Return a pointer to the url's character buffer This function returns a pointer to the first character of the url, which is not guaranteed to be null-terminated. Complexity Constant. Exception Safety Throws nothing. A pointer to the first character. Return true if the url is empty 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-empty Specification 4.2. Relative Reference (rfc3986) true if the url is empty. Return the authority. 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 ] Specification 3.2. Authority (rfc3986) The authority as a string. authority , has_authority . Return the fragment 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 / ":" / "@" Specification 3.5. Fragment (rfc3986) The fragment portion of the url. fragment , has_fragment . Return the host This function returns the host portion of the authority as a string, or the empty string if there is no authority. The returned string may contain percent escapes. 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 / "-" / ".") Specification 3.2.2. Host (rfc3986) The host address as a string. Return the host 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 / "-" / ".") Specification 3.2.2. Host (rfc3986) The host address as a string. Return the host and port 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 3.2.2. Host (rfc3986) 3.2.3. Port (rfc3986) The host and port portion of the url. has_port , port , port_number . Return the host name 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 / "-" / ".") Specification 3.2.2. Host (rfc3986) The host name as a percent-encoded string. Return the origin If an authority is present, this function returns the scheme and authority portion of the url. Otherwise, an empty string is returned. The returned string may contain percent escapes. 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. The origin portion of the url. encoded_resource , encoded_target . Return the query as a container of parameters This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Strings returned when iterating the range may contain percent escapes. 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 3.4. Query (rfc3986) Query string (Wikipedia) A bidirectional view of key/value pairs. encoded_query , has_query , params , query . Return the password 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 / ":" ) Specification 3.2.1. User Information (rfc3986) The password as a string. has_password , has_userinfo , encoded_user , encoded_userinfo , password , user , userinfo . Return the path This function returns the path as a string. The path may be empty. Any percent-escapes in the string are decoded first. 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> Specification 3.3. Path (rfc3986) The path as a string. is_path_absolute , encoded_segments . path , segments . Return the query If this contains a query, it is returned as a string (which may be empty). Otherwise, an empty string is returned. The returned string may contain percent escapes. 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 3.4. Query (rfc3986) Query string (Wikipedia) The query as a string. encoded_params , has_query , params , query . Return the resource 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 3.3. Path (rfc3986) 3.4. Query (rfc3986) The resource portion of the url. encoded_origin , encoded_target . Return the path as a container of segments This function returns a bidirectional view of strings over the path. The returned view references the same underlying character buffer; ownership is not transferred. 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> Specification 3.3. Path (rfc3986) A bidirectional view of encoded segments. is_path_absolute , encoded_path , path , segments , segments_encoded_view . Return the target This function returns the target, which is the portion of the url that includes only the path and query. The returned string may contain percent escapes. Example assert( url_view( "http://www.example.com/index.html?query#frag" ).encoded_target() == "/index.html?query" ); Complexity Constant. Exception Safety Throws nothing. Specification 3.3. Path (rfc3986) 3.4. Query (rfc3986) The target portion of the url. encoded_origin , encoded_resource . Return the user If present, this function returns a string representing the user (which may be empty). Otherwise it returns an empty string. The returned string may contain percent escapes. 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 / ":" ) Specification 3.2.1. User Information (rfc3986) The user as a string. has_password , has_userinfo , encoded_password , encoded_userinfo , password , user , userinfo . Return the userinfo 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 ] Specification 3.2.1. User Information (rfc3986) The userinfo as a string. has_password , has_userinfo , encoded_password , encoded_user , password , user , userinfo . Return the IPv6 Zone ID 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" ZoneID Specification Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers The Zone ID as a percent-encoded string. Return true if an authority is present 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...) Specification 3.2. Authority (rfc3986) true if the url contains an authority. authority , encoded_authority . Return true if a fragment is present This function returns true if the url contains a fragment. An empty fragment is distinct from no fragment. 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 ] Specification 3.5. Fragment (rfc3986) true if the url contains a fragment. encoded_fragment , fragment . Return true if a password is present 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 / ":" ) Specification 3.2.1. User Information (rfc3986) true if the userinfo contains a password. has_userinfo , encoded_password , encoded_user , encoded_userinfo , password , user , userinfo . Return true if a port is present 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 = *DIGIT Specification 3.2.3. Port (rfc3986) true if a port is present, false otherwise. encoded_host_and_port , port , port_number . Return true if a query is present This function returns true if this contains a query. An empty query is distinct from having no query. 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 3.4. Query (rfc3986) Query string (Wikipedia) true if a query is present. encoded_params , encoded_query , params , query . Return true a scheme is present 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 / "+" / "-" / "." ) Specification 3.1. Scheme (rfc3986) true if the url contains a scheme. scheme , scheme_id . Return true if a userinfo is present 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 ] Specification 3.2.1. User Information (rfc3986) true if the userinfo is present. has_password , encoded_password , encoded_user , encoded_userinfo , password , user , userinfo . Return the host IPv4 address If the host type is host_type::ipv4 , this function returns the address as a value of type ipv4_address . Otherwise, if the host type is not an IPv4 address, it returns a default-constructed value which is equal to the unspecified address "0.0.0.0". 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-255 Specification 3.2.2. Host (rfc3986) The IPv4 address as a value of type ipv4_address . Return the host IPv6 address If the host type is host_type::ipv6 , this function returns the address as a value of type ipv6_address . Otherwise, if the host type is not an IPv6 address, it returns a default-constructed value which is equal to the unspecified address "0:0:0:0:0:0:0:0". 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 hexadecimal Specification 3.2.2. Host (rfc3986) The IPv6 address as a value of type ipv6_address . Return the host IPvFuture address 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 / ":" ) Specification 3.2.2. Host (rfc3986) The IPvFuture address as a string. Return the host type 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. Specification 3.2.2. Host (rfc3986) The type of host present. Return true if the path is absolute 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> Specification 3.3. Path (rfc3986) true if the path is absolute, false otherwise. encoded_path , encoded_segments . path , segments . Return the query as a container of parameters This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first. 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 3.4. Query (rfc3986) Query string (Wikipedia) A bidirectional view of key/value pairs. encoded_params , encoded_query , has_query , query . Return a shared, persistent copy of the url This function returns a read-only copy of the url, with shared lifetime. The returned value owns (persists) the underlying string. The algorithm used to create the value minimizes the number of individual memory allocations, making it more efficient than when using direct standard library functions. 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. A shared pointer to a read-only url_view. Return the port 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 = *DIGIT Specification 3.2.3. Port (rfc3986) The port as a string. encoded_host_and_port , has_port , port_number . Return the port If a port is present and the numerical value is representable, it is returned as an unsigned integer. Otherwise, the number zero is returned. Example assert( url_view( "http://localhost.com:8080" ).port_number() == 8080 ); Complexity Constant. Exception Safety Throws nothing. BNF port = *DIGIT Specification 3.2.3. Port (rfc3986) The port number as an unsigned integer. encoded_host_and_port , has_port , port . Return the scheme This function returns the scheme if it exists, without a trailing colon (':'). Otherwise it returns an empty string. Note that schemes are case-insensitive, and the canonical form is lowercased. 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 ] Specification 3.1. Scheme (rfc3986) The scheme as a string. has_scheme , scheme_id . Return the scheme 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::scheme is 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 / "+" / "-" / "." ) Specification 3.1. Scheme (rfc3986) The scheme as an enumeration value. has_scheme , scheme . Return the path as a container of segments This function returns a bidirectional view of strings over the path. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first. Example segments_view sv = url_view( "/path/to/file.txt" ).segments(); Complexity Constant. Exception Safety Throws nothing. BNF path = [ "/" ] segment *( "/" segment ) Specification 3.3. Path (rfc3986) A bidirectional view of segments. is_path_absolute , encoded_path , encoded_segments . path , segments_view . Return the number of characters in the url This function returns the number of characters in the url's encoded string, not including any null terminator, if present. Example assert( url_view( "file:///Program%20Files" ).size() == 23 ); Complexity Constant. Exception Safety Throws nothing. The number of characters in the url. Return the URL as a core::string_view Complexity Constant. Exception Safety Throws nothing. A string view of the URL. Return the maximum number of characters possible 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. The maximum number of characters. Calculate a hash of the url This function calculates a hash of the url as if it were always normalized. Complexity Linear in this->size() . Exception Safety Throws nothing. A hash value suitable for use in hash-based containers. An initial value to add to the hash Error codes returned the library The operation completed successfully. Null encountered in pct-encoded. Illegal reserved character in encoded string. A grammar element was not in canonical form. Bad hexadecimal digit. This error condition is fatal. The percent-encoded sequence is incomplete. This error condition is fatal. Missing hexadecimal digit. This error condition is fatal. No space in output buffer This error is returned when a provided output buffer was too small to hold the complete result of an algorithm. The URL is not a base URL Identifies the type of host in a URL. Values of this type are returned by URL views and containers to indicate the type of host present in a URL. No host is specified. A host is specified by reg-name. A host is specified by ipv4_address . A host is specified by ipv6_address . A host is specified by IPvFuture. Identifies a known URL scheme Specification 3.1. Scheme (rfc3986) default_port string_to_scheme to_string Indicates that no scheme is present Indicates the scheme is not a well-known scheme File Transfer Protocol (FTP) FTP is a standard communication protocol used for the transfer of computer files from a server to a client on a computer network. Specification The 'ftp' URI Scheme File URI Scheme The File URI Scheme is typically used to retrieve files from within one's own computer. Specification The "file" URI Scheme (rfc8089) The Hypertext Transfer Protocol URI Scheme URLs of this type indicate a resource which is interacted with using the HTTP protocol. Specification Hypertext Transfer Protocol (HTTP/1.1) (rfc7230) The Secure Hypertext Transfer Protocol URI Scheme URLs of this type indicate a resource which is interacted with using the Secure HTTP protocol. Specification Hypertext Transfer Protocol (HTTP/1.1) (rfc7230) The WebSocket URI Scheme URLs of this type indicate a resource which is interacted with using the WebSocket protocol. Specification The WebSocket Protocol (rfc6455) The Secure WebSocket URI Scheme URLs of this type indicate a resource which is interacted with using the Secure WebSocket protocol. Specification The WebSocket Protocol (rfc6455) Return the default port for a known scheme This function returns the default port for the known schemes. If the value does not represent a known scheme or the scheme does not represent a protocol, the function returns zero. The following ports are returned by the function: scheme::ftp = 21 scheme::http , scheme::ws = 80 scheme::https , scheme::wss = 443 An integer with the default port number The known scheme constant scheme Format arguments into a URL 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 | digit Specification Format String Syntax A URL holding the formatted result. The format URL string. Arguments to be formatted. fmt contains an invalid format string and the result contains an invalid URL after replacements are applied. format_to . url Format arguments into a URL 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 | digit Specification Format String Syntax An object that derives from url_base . The format URL string. Arguments to be formatted. fmt contains an invalid format string and u contains an invalid URL after replacements are applied. format . static_url static_url_base url url_base Return a valid percent-encoded string If s is a valid percent-encoded string, the function returns the buffer as a valid view which may be used to perform decoding or measurements. Otherwise the result contains an error code. Upon success, the returned view references the original character buffer; Ownership is not transferred. Complexity Linear in s.size() . Exception Safety Throws nothing. On success, the valid percent-encoded string. The string to validate. Return a reference to a parsed URL string This function parses a string according to the grammar below and returns a view referencing the passed string upon success, else returns an error. Ownership of the string is not transferred; the caller is responsible for ensuring that the lifetime of the character buffer extends until the view is no longer being accessed. 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-empty Specification 4.3. Absolute URI (rfc3986) A view to the parsed URL The string to parse s.size() > url_view::max_size parse_origin_form , parse_relative_ref , parse_uri , parse_uri_reference , url_view . url_view Parse an authority 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 = *DIGIT Exception Safety Throws nothing. Specification 3.2. Authority (rfc3986) A view to the parsed authority The string to parse authority_view . authority_view Return an IPv4 address from an IP address string in dotted decimal form The parsed address, or an error code. The string to parse. ipv4_address Parse a string containing an IPv6 address. 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. A result containing the address. The string to parse. ipv6_address Return a reference to a parsed URL string This function parses a string according to the grammar below and returns a view referencing the passed string upon success, else returns an error. Ownership of the string is not transferred; the caller is responsible for ensuring that the lifetime of the character buffer extends until the view is no longer being accessed. Example system::result< url_view > = parse_origin_form( "/index.htm?layout=mobile" ); BNF origin-form = absolute-path [ "?" query ] absolute-path = 1*( "/" segment ) Specification 5.3.1. origin-form (rfc7230) A view to the parsed URL The string to parse s.size() > url_view::max_size parse_absolute_uri , parse_relative_ref , parse_uri , parse_uri_reference , url_view . url_view Parse a string and return an encoded segment view This function parses the string and returns the corresponding path object if the string is valid, otherwise returns an error. BNF path = [ "/" ] segment *( "/" segment ) Exception Safety No-throw guarantee. Specification 3.3. Path (rfc3986) A valid view on success, otherwise an error code. The string to parse segments_encoded_view . Parse a string and return an encoded params view This function parses the string and returns the corresponding params object if the string is valid, otherwise returns an error. BNF query = *( pchar / "/" / "?" ) Exception Safety No-throw guarantee. Specification A valid view on success, otherwise an error code. The string to parse params_encoded_view . Return a reference to a parsed URL string This function parses a string according to the grammar below and returns a view referencing the passed string upon success, else returns an error. Ownership of the string is not transferred; the caller is responsible for ensuring that the lifetime of the character buffer extends until the view is no longer being accessed. 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-empty Specification 4.2. Relative Reference (rfc3986) Errata ID: 5428 (rfc3986) A view to the parsed URL The string to parse s.size() > url_view::max_size parse_absolute_uri , parse_origin_form , parse_uri , parse_uri_reference , url_view . url_view Return a reference to a parsed URL string This function parses a string according to the grammar below and returns a view referencing the passed string upon success, else returns an error. Ownership of the string is not transferred; the caller is responsible for ensuring that the lifetime of the character buffer extends until the view is no longer being accessed. 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-empty Specification 3. Syntax Components (rfc3986) A boost::system::result containing a value or an error The string to parse s.size() > url_view::max_size parse_absolute_uri , parse_origin_form , parse_relative_ref , parse_uri_reference , url_view . url_view Return a reference to a parsed URL string This function parses a string according to the grammar below and returns a view referencing the passed string upon success, else returns an error. Ownership of the string is not transferred; the caller is responsible for ensuring that the lifetime of the character buffer extends until the view is no longer being accessed. 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-empty Specification 4.1. URI Reference (rfc3986) Errata ID: 5428 (rfc3986) A view to the parsed URL The string to parse s.size() > url_view::max_size parse_absolute_uri , parse_origin_form , parse_relative_ref , parse_uri , url_view . url_view Resolve a URL reference against a base URL This function attempts to resolve a URL reference ref against the base URL base in a manner similar to that of a web browser resolving an anchor tag. The base URL must satisfy the URI grammar. In other words, it must contain a scheme. Relative references are only usable when in the context of a base absolute URI. This process of resolving a relative reference within the context of a base URI is defined in detail in rfc3986 (see below). The resolution process works as if the relative reference is appended to the base URI and the result is normalized. Given the input base URL, this function resolves the relative reference as if performing the following steps: 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. Abnormal hrefs where the number of ".." segments exceeds the number of segments in the base path are handled by including the unmatched ".." segments in the result, as described in Errata 4547 . 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 An empty boost::system::result upon success, otherwise an error code if !base.has_scheme() . The base URL to resolve against. The URL reference to resolve. The container where the result is written, upon success. url , url_view . static_url static_url_base url url_view url_view_base Return the known scheme for a non-normalized string, if known If the string does not identify a known scheme, the value scheme::unknown is returned. BNF scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ) Specification 3.1. Scheme (rfc3986) The known scheme The string holding the scheme scheme Swap Exchanges the contents of v0 with another v1 . All views, iterators and references remain valid. If &v0 == &v1 , this function call has no effect. 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 The first object to swap The second object to swap url::swap Return the normalized string for a known scheme A string representing the known scheme The known scheme constant scheme Format the address to an output stream This function writes the address to an output stream using standard notation. The output stream, for chaining. The output stream to write to. The address to write. Format the address to an output stream. IPv4 addresses written to output streams are written in their dotted decimal format. The output stream. The output stream. The address to format. Format the string with percent-decoding applied to the output stream 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. A reference to the output stream, for chaining The output stream to write to The decoded view to write 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. 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. A reference to the output stream, for chaining The output stream to write to. The url to write. Format the encoded authority to the output stream 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; A reference to the output stream, for chaining The output stream to write to The URL to write Format to an output stream Any percent-escapes are emitted as-is; no decoding is performed. Complexity Linear in ps.buffer().size() . Effects return os << ps.buffer(); A reference to the output stream, for chaining The output stream to write to The params to write Format to an output stream Any percent-escapes are emitted as-is; no decoding is performed. Complexity Linear in ps.buffer().size() . Effects return os << ps.buffer(); A reference to the output stream, for chaining The output stream to write to The parameters to write Format to an output stream Any percent-escapes are emitted as-is; no decoding is performed. Complexity Linear in ps.buffer().size() . Effects return os << ps.buffer(); A reference to the output stream. The output stream to write to. The object to format. Format to an output stream Any percent-escapes are emitted as-is; no decoding is performed. Complexity Linear in ps.buffer().size() . Effects return os << ps.buffer(); A reference to the output stream. The output stream to write to. The segments to write. Return true if two addresses are equal true if the addresses are equal The first address to compare. The second address to compare. Return true if two addresses are equal true if the addresses are equal, otherwise false . The first address to compare. The second address to compare. Compare two decode views for equality true if decoded lhs is equal to the decoded rhs The left-hand-side decode view to compare The right-hand-side decode view to compare Return the result of comparing two URLs 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 Specification 6.2.2 Syntax-Based Normalization (rfc3986) true if u0 == u1 The first url to compare The second url to compare static_url static_url_base url url_base url_view Return the result of comparing two authorities. The authorities are compared component by component as if they were first normalized. Complexity Linear in min( a0.size(), a1.size() ) Exception Safety Throws nothing true if a0 == a1 , otherwise false The first authority to compare The second authority to compare Return true if two addresses are not equal true if the addresses are not equal The first address to compare. The second address to compare. Return true if two addresses are not equal true if the addresses are not equal, otherwise false . The first address to compare. The second address to compare. Compare two decode views for inequality true if decoded lhs is not equal to the decoded rhs The left-hand-side decode view to compare The right-hand-side decode view to compare Return the result of comparing two URLs 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 Specification 6.2.2 Syntax-Based Normalization (rfc3986) true if u0 != u1 The first url to compare The second url to compare static_url static_url_base url url_base url_view Return the result of comparing two authorities. The authorities are compared component by component as if they were first normalized. Complexity Linear in min( a0.size(), a1.size() ) Exception Safety Throws nothing true if a0 != a1 , otherwise false The first authority to compare The second authority to compare Compare two decode views for less than true if decoded lhs is less than to the decoded rhs The left-hand-side decode view to compare The right-hand-side decode view to compare Return the result of comparing two URLs 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 Specification 6.2.2 Syntax-Based Normalization (rfc3986) true if u0 < u1 The first url to compare The second url to compare static_url static_url_base url url_base url_view Return the result of comparing two authorities. The authorities are compared component by component as if they were first normalized. Complexity Linear in min( a0.size(), a1.size() ) Exception Safety Throws nothing true if a0 < a1 , otherwise false The first authority to compare The second authority to compare Compare two decode views for less than or equal true if decoded lhs is less than or equal to the decoded rhs The left-hand-side decode view to compare The right-hand-side decode view to compare Return the result of comparing two URLs 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 Specification 6.2.2 Syntax-Based Normalization (rfc3986) true if u0 <= u1 The first url to compare The second url to compare static_url static_url_base url url_base url_view Return the result of comparing two authorities. The authorities are compared component by component as if they were first normalized. Complexity Linear in min( a0.size(), a1.size() ) Exception Safety Throws nothing true if a0 <= a1 , otherwise false The first authority to compare The second authority to compare Compare two decode views for greater than true if decoded lhs is greater than to the decoded rhs The left-hand-side decode view to compare The right-hand-side decode view to compare Return the result of comparing two URLs 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 Specification 6.2.2 Syntax-Based Normalization (rfc3986) true if u0 > u1 The first url to compare The second url to compare static_url static_url_base url url_base url_view Return the result of comparing two authorities. The authorities are compared component by component as if they were first normalized. Complexity Linear in min( a0.size(), a1.size() ) Exception Safety Throws nothing true if a0 > a1 , otherwise false The first authority to compare The second authority to compare Compare two decode views for greater than or equal true if decoded lhs is greater than or equal to the decoded rhs The left-hand-side decode view to compare The right-hand-side decode view to compare Return the result of comparing two URLs 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 Specification 6.2.2 Syntax-Based Normalization (rfc3986) true if u0 >= u1 The first url to compare The second url to compare static_url static_url_base url url_base url_view Return the result of comparing two authorities. The authorities are compared component by component as if they were first normalized. Complexity Linear in min( a0.size(), a1.size() ) Exception Safety Throws nothing true if a0 >= a1 , otherwise false The first authority to compare The second authority to compare Rule for absolute-URI 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-empty Specification 4.3. Absolute URI (rfc3986) grammar::parse , parse_absolute_uri , url_view . Rule for authority 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 ] Specification 3.2. Authority (rfc3986) authority_view , grammar::parse , parse_authority . The gen-delims character set 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 = ":" / "/" / "?" / "#" / "[" / "]" / "@" Specification 2.2. Reserved Characters (rfc3986) grammar::find_if , grammar::find_if_not , grammar::parse , pct_encoded_rule . Ignore case when comparing This value may be optionally passed to functions accepting a parameter of type ignore_case_param to indicate that comparisons should be case-insensitive. Rule for an IP version 4 style address 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-255 Specification IPv4 (Wikipedia) 3.2.2. Host (rfc3986) ipv4_address , parse_ipv4_address , grammar::parse . Rule for An IP version 6 style address 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 hexadecimal Specification IP Version 6 Addressing Architecture (rfc4291) 3.2.2. Host (rfc3986) ipv6_address , parse_ipv6_address , grammar::parse . Constant indicating no value in a param Rule for origin-form 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 ) Specification 5.3.1. origin-form (rfc7230) grammar::parse , parse_origin_form , url_view . The path character set 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 / ":" / "@" Specification 3.3. Path (rfc3986) grammar::find_if , grammar::find_if_not , grammar::parse , pct_encoded_rule . Rule for a query string 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 / "!" / "$" / "'" / "(" / ")" / "*" / "+" / "," / ";" / ":" / "@" / "/" / "?" Specification 3.4. Query (rfc3986) grammar::parse , params_encoded_view . Rule for relative-ref 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 ] Specification 4.2. Relative Reference (rfc3986) grammar::parse , parse_relative_ref , url_view . The reserved character set 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 ) ); Specification 2.3. Unreserved Characters (rfc3986) grammar::find_if , grammar::find_if_not , grammar::parse , pct_encoded_rule . The sub-delims character set 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 = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "=" Specification 2.2. Reserved Characters (rfc3986) grammar::find_if , grammar::find_if_not , grammar::parse , pct_encoded_rule . The unreserved character set 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 / "-" / "." / "_" / "~" Specification 2.3. Unreserved Characters (rfc3986) grammar::find_if , grammar::find_if_not , grammar::parse , pct_encoded_rule . Rule for URI-reference 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 3. Syntax Components (rfc3986) grammar::parse , parse_uri_reference , url_view . Rule for URI 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 3. Syntax Components (rfc3986) grammar::parse , parse_uri , url_view .