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 . True if spaces encode to and from plus signs This option controls whether or not the PLUS character ("+") is used to represent the SP character (" ") when encoding or decoding. Although not prescribed by the RFC, plus signs are commonly treated as spaces upon decoding when used in the query of URLs using well known schemes such as HTTP. Specification application/x-www-form-urlencoded (w3.org) True if hexadecimal digits are emitted as lower case By default, percent-encoding algorithms emit hexadecimal digits A through F as uppercase letters. When this option is `true`, lowercase letters are used. True if nulls are not allowed Normally all possible character values (from 0 to 255) are allowed, with reserved characters being replaced with escapes upon encoding. When this option is true, attempting to decode a null will result in an error. 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. Base class for string tokens, and algorithm parameters This abstract interface provides a means for an algorithm to generically obtain a modifiable, contiguous character buffer of prescribed size. As the author of an algorithm simply declare an rvalue reference as a parameter type. Instances of this type are intended only to be used once and then destroyed. 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. 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. 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 character traits The value type The pointer type The const pointer type The reference type The const reference type The const iterator type The iterator type The const reverse iterator type The reverse iterator type The size type The difference type A constant used to represent "no position" Conversion Conversion Conversion to std::string is explicit because assigning to string using an implicit constructor does not preserve capacity. Return an iterator to the beginning See `core::string_view::begin` Return an iterator to the end See `core::string_view::end` Return an iterator to the beginning See `core::string_view::cbegin` Return an iterator to the end See `core::string_view::cend` Return the size See `core::string_view::size` Return the size See `core::string_view::length` Return the maximum allowed size See `core::string_view::max_size` Return true if the string is empty See `core::string_view::size` Access a character See `core::string_view::operator[]` Access a character See `core::string_view::at` Return the first character See `core::string_view::front` Return the last character See `core::string_view::back` Return a pointer to the character buffer See `core::string_view::data` Copy the characters to another buffer See `core::string_view::copy` Return a view to part of the string See `core::string_view::substr` Return the result of comparing to another string See `core::string_view::compare` Return the result of comparing to another string See `core::string_view::compare` Return the result of comparing to another string See `core::string_view::compare` Return the result of comparing to another string See `core::string_view::compare` Return the result of comparing to another string See `core::string_view::compare` Return the result of comparing to another string See `core::string_view::compare` Return true if a matching prefix exists See `core::string_view::starts_with` Return true if a matching prefix exists See `core::string_view::starts_with` Return true if a matching prefix exists See `core::string_view::starts_with` Return true if a matching suffix exists See `core::string_view::ends_with` Return true if a matching suffix exists See `core::string_view::ends_with` Return true if a matching suffix exists See `core::string_view::ends_with` Return the position of matching characters See `core::string_view::find` Return the position of matching characters See `core::string_view::find` Return the position of matching characters See `core::string_view::find` Return the position of matching characters See `core::string_view::find` Return the position of matching characters See `core::string_view::rfind` Return the position of matching characters See `core::string_view::rfind` Return the position of matching characters See `core::string_view::rfind` Return the position of matching characters See `core::string_view::rfind` Return the position of the first match See `core::string_view::find_first_of` Return the position of the first match See `core::string_view::find_first_of` Return the position of the first match See `core::string_view::find_first_of` Return the position of the first match See `core::string_view::find_first_of` Return the position of the last match See `core::string_view::find_last_of` Return the position of the last match See `core::string_view::find_last_of` Return the position of the last match See `core::string_view::find_last_of` Return the position of the last match See `core::string_view::find_last_of` Return the position of the first non-match See `core::string_view::find_first_not_of` Return the position of the first non-match See `core::string_view::find_first_not_of` Return the position of the first non-match See `core::string_view::find_first_not_of` Return the position of the first non-match See `core::string_view::find_first_not_of` Return the position of the last non-match See `core::string_view::find_last_not_of` Return the position of the last non-match See `core::string_view::find_last_not_of` Return the position of the last non-match See `core::string_view::find_last_not_of` Return the position of the last non-match See `core::string_view::find_last_not_of` Return true if matching characters are found See `core::string_view::contains` Return true if matching characters are found See `core::string_view::contains` Return true if matching characters are found See `core::string_view::contains` Return the hash of this value Return the hash of this value Format a string to an output stream Return true if c is in the character set. 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 character to check The decimal value or -1 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. The character to test. operator()(unsigned char) const 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 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. 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. A character set containing all characters. all_chars_t 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. Error conditions for errors received from rules error , parse . A fatal error in syntax was encountered. This indicates that parsing cannot continue. 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 . 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 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" ) ); ci_compare , ci_is_equal . A character set containing the alphabetical characters. alpha_chars_t 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. Operators The following operators are supported between decode_view and any object that is convertible to `core::string_view` bool operator==( decode_view, decode_view ) noexcept; bool operator!=( decode_view, decode_view ) noexcept; bool operator<=( decode_view, decode_view ) noexcept; bool operator< ( decode_view, decode_view ) noexcept; bool operator> ( decode_view, decode_view ) noexcept; bool operator>=( decode_view, decode_view ) noexcept; The value type The reference type reference The unsigned integer type The signed integer type iterator 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 Exceptions thrown on invalid input. The string contains an invalid percent encoding. A percent-encoded string that has already been validated. The options for decoding. If this parameter is omitted, the default options are used. Return true if the string is empty Example assert( decode_view( "" ).empty() ); Complexity Constant. Exception Safety Throws nothing. 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. Return an iterator to the beginning Example auto it = this->begin(); Complexity Constant. Exception Safety Throws nothing. Return an iterator to the end Example auto it = this->end(); Complexity Constant. Exception Safety Throws nothing. Return the first character Example assert( decode_view( "Program%20Files" ).front() == 'P' ); Preconditions not this->empty() Complexity Constant. Exception Safety Throws nothing. Return the last character Example assert( decode_view( "Program%20Files" ).back() == 's' ); Preconditions not this->empty() Complexity Constant. Exception Safety Throws nothing. Checks if the string begins with the given prefix Example assert( decode_view( "Program%20Files" ).starts_with("Program") ); Complexity Linear. Exception Safety Throws nothing. Checks if the string ends with the given prefix Example assert( decode_view( "Program%20Files" ).ends_with("Files") ); Complexity Linear. Exception Safety Throws nothing. Checks if the string begins with the given prefix Example assert( decode_view( "Program%20Files" ).starts_with('P') ); Complexity Constant. Exception Safety Throws nothing. Checks if the string ends with the given prefix Example assert( decode_view( "Program%20Files" ).ends_with('s') ); Complexity Constant. Exception Safety Throws nothing. Finds the first occurrence of character in this view Complexity Linear. Exception Safety Throws nothing. Finds the first occurrence of character in this view Complexity Linear. Exception Safety Throws nothing. Remove the first characters Example decode_view d( "Program%20Files" ); d.remove_prefix( 8 ); assert( d == "Files" ); Preconditions not this->empty() Complexity Linear. Remove the last characters Example decode_view d( "Program%20Files" ); d.remove_prefix( 6 ); assert( d == "Program" ); Preconditions not this->empty() Complexity Linear. Return the decoding options 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. string to compare 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 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. string to compare 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 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. Operators The following operators are supported between pct_string_view and any object that is convertible to `core::string_view` bool operator==( pct_string_view, pct_string_view ) noexcept; bool operator!=( pct_string_view, pct_string_view ) noexcept; bool operator<=( pct_string_view, pct_string_view ) noexcept; bool operator< ( pct_string_view, pct_string_view ) noexcept; bool operator> ( pct_string_view, pct_string_view ) noexcept; bool operator>=( pct_string_view, pct_string_view ) noexcept; Constructor 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. other The string to copy. Constructor (deleted) 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 contains an invalid percent encoding. len The string 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 contains an invalid percent encoding. The string to construct from. Assignment The copy references the same underlying character buffer. Ownership is not transferred. Postconditions this->data() == other.data() Complexity Constant. Exception Safety Throws nothing. other The string to copy. 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. Return the string as a range of decoded characters Complexity Constant. Exception Safety Throws nothing. decode_view . Swap 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. The string to validate. 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 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 . 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 . 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. 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 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 . The number of characters in the longest possible IPv4 string. The longest ipv4 address string is "255.255.255.255". The type used to represent an address as an unsigned integer The type used to represent an address as an array of bytes Constructor. Constructor. Copy Assignment. 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. 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. The input failed to parse correctly. The string to parse. Specification 3.2.2. Host (rfc3986) parse_ipv4_address . Return the address as bytes, in network byte order. Return the address as an unsigned integer. Write a dotted decimal string representing the address to a buffer The resulting buffer is not null-terminated. `dest_size < ipv4_address::max_str_len` The formatted string The buffer in which to write, which must have at least `dest_size` space. The size of the output buffer. Return true if the address is a loopback address Return true if the address is unspecified Return true if the address is a multicast address Return true if two addresses are equal Return true if two addresses are not equal Return an address object that represents any address Return an address object that represents the loopback address Return an address object that represents the broadcast address Return true if two addresses are equal Return true if two addresses are not equal Format the address to an output stream. IPv4 addresses written to output streams are written in their dotted decimal format. The output stream. The address to format. Return an IPv4 address from an IP address string in dotted decimal form 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 . 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 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. Copy Assignment 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. The address to construct from. Specification 2.5.5.2. IPv4-Mapped IPv6 Address (rfc4291) 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. The input failed to parse correctly. The string to parse. Specification 3.2.2. Host (rfc3986) parse_ipv6_address . Return the address as bytes, in network byte order Write a dotted decimal string representing the address to a buffer The resulting buffer is not null-terminated. `dest_size < ipv6_address::max_str_len` The formatted string The buffer in which to write, which must have at least `dest_size` space. The size of the output buffer. 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) 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) 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) Return true if two addresses are equal Return true if two addresses are not equal 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) Return true if two addresses are equal Return true if two addresses are not equal 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. 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. Identifies a known URL scheme Specification 3.1. Scheme (rfc3986) 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 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 / "+" / "-" / "." ) The known scheme The string holding the scheme Specification 3.1. Scheme (rfc3986) Return the normalized string for a known scheme A string representing the known scheme The known scheme constant 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 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 result containing either a valid url_view upon succcess, otherwise they contain an error. The error can be converted to an exception by the caller if desired: system::result< url_view > rv = parse_uri_reference( "https://www.example.com/index.htm?text=none#a1" ); 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 . Destructor Any params, segments, iterators, or other views which reference the same underlying character buffer remain valid. 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 4.2. Relative Reference (rfc3986) 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. The input failed to parse correctly. The string to parse. BNF URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] relative-ref = relative-part [ "?" query ] [ "#" fragment ] Specification 4.1. URI Reference 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. 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. 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. 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. 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. 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 result containing either a valid authority_view upon succcess, otherwise it contain 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 . Destructor 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 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) parse_authority . Constructor Assignment 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. 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. 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. 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) 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) has_password , encoded_password , encoded_user , 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) has_password , has_userinfo , encoded_password , encoded_user , 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) has_password , has_userinfo , encoded_password , encoded_userinfo , 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) has_userinfo , encoded_password , encoded_user , encoded_userinfo , password , user , userinfo . 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) has_password , has_userinfo , encoded_user , encoded_userinfo , password , user , userinfo . 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) 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) 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) 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) 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) 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) 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) 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) encoded_host_and_port , port , port_number . 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) 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) encoded_host_and_port , has_port , port . 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) has_port , port , port_number . Return the result of comparing this with another authority This function compares two authorities according to Syntax-Based comparison algorithm. Exception Safety Throws nothing. -1 if `*this < other`, 0 if `this == other`, and 1 if `this > other`. Specification 6.2.2 Syntax-Based Normalization (rfc3986) 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 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 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 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 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 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 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 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 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 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 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 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 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 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. A view to the parsed authority The string to parse Specification 3.2. Authority (rfc3986) authority_view . 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. 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. Example When ignore_case is passed as an argument, this function ignores case when performing comparisons: void f( ignore_case_param = {} ); 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`. 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 iterator 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() ); The reference type This is the type of value returned when iterators of the view are dereferenced. reference An unsigned integer type used to represent size. A signed integer type used to represent differences. Return the maximum number of characters possible This represents the largest number of characters that are possible in a path, not including any null terminator. Exception Safety Throws nothing. 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. 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. Return true if there are no segments Example assert( ! url_view( "/index.htm" ).encoded_segments().empty() ); Complexity Constant. Exception Safety Throws nothing. Return the number of segments Example assert( url_view( "/path/to/file.txt" ).encoded_segments().size() == 3 ); Complexity Constant. Exception Safety Throws nothing. 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. 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. Return an iterator to the beginning Complexity Linear in `this->front().size()` or constant if `this->empty()`. Exception Safety Throws nothing. Return an iterator to the end Complexity Constant. Exception Safety Throws nothing. 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(); 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 iterator 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() ); The reference type This is the type of value returned when iterators of the view are dereferenced. reference An unsigned integer type used to represent size. A signed integer type used to represent differences. Return the maximum number of characters possible This represents the largest number of characters that are possible in a path, not including any null terminator. Exception Safety Throws nothing. 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. 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. Return true if there are no segments Example assert( ! url_view( "/index.htm" ).segments().empty() ); Complexity Constant. Exception Safety Throws nothing. Return the number of segments Example assert( url_view( "/path/to/file.txt" ).segments().size() == 3 ); Complexity Constant. Exception Safety Throws nothing. 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. 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. Return an iterator to the beginning Complexity Linear in `this->front().size()` or constant if `this->empty()`. Exception Safety Throws nothing. Return an iterator to the end Complexity Constant. Exception Safety Throws nothing. 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 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 . 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 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. `s` contains an invalid path. The string to parse. BNF path = [ "/" ] [ segment *( "/" segment ) ] segment = *pchar Specification 3.3. Path 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 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 . 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 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. `s` contains an invalid path. The string to parse. BNF path = [ "/" ] [ segment *( "/" segment ) ] segment = *pchar Specification 3.3. Path 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 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 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. A valid view on success, otherwise an error code. The string to parse Specification 3.3. Path (rfc3986) segments_encoded_view . 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. 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 . The key For most usages, key comparisons are case-sensitive and duplicate keys in a query are possible. However, it is the authority that has final control over how the query is interpreted. The value The presence of a value is indicated by has_value equal to true. An empty value is distinct from no value. True if a value is present The presence of a value is indicated by `has_value == true`. An empty value is distinct from no value. Constructor 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. 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. `key` or `value` contains an invalid percent-encoding. value The key and value to set. 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. `key` or `value` contains an invalid percent escape. The param to construct from. 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 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. 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 . The key For most usages, key comparisons are case-sensitive and duplicate keys in a query are possible. However, it is the authority that has final control over how the query is interpreted. The value The presence of a value is indicated by has_value equal to true. An empty value is distinct from no value. True if a value is present The presence of a value is indicated by `has_value == true`. An empty value is distinct from no value. Constructor 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 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. Constant indicating no value in a param 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 . The key For most usages, key comparisons are case-sensitive and duplicate keys in a query are possible. However, it is the authority that has final control over how the query is interpreted. The value The presence of a value is indicated by has_value equal to true. An empty value is distinct from no value. True if a value is present The presence of a value is indicated by `has_value == true`. An empty value is distinct from no value. Constructor 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 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. other The object to construct from. 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. other The object to construct 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. other The object to assign from. 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. other 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. 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. The parameter to copy. 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 iterator 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 . The reference type This is the type of value returned when iterators of the view are dereferenced. param_view . reference An unsigned integer type to represent sizes. A signed integer type used to represent differences. Return the maximum number of characters possible This represents the largest number of characters that are possible in a path, not including any null terminator. Exception Safety Throws nothing. 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) Return true if there are no params Example assert( ! url_view( "?key=value" ).encoded_params().empty() ); Complexity Constant. Exception Safety Throws nothing. Return the number of params Example assert( url_view( "?key=value").encoded_params().size() == 1 ); Complexity Constant. Exception Safety Throws nothing. Return an iterator to the beginning Complexity Linear in the size of the first param. Exception Safety Throws nothing. Return an iterator to the end 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. `key` contains an invalid percent-encoding. 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, 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. `key` contains an invalid percent-encoding. 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, 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. `key` contains an invalid percent-encoding. 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, 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. `key` contains an invalid percent-encoding. 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, 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. `key` contains an invalid percent-encoding. 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, 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. 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 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()`). 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. 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. The list of params to assign. Conversion 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. 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. 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. 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. 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. 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. 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. 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. last The range of elements to erase. 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. 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. 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. 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. 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 iterator 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 . The reference type This is the type of value returned when iterators of the view are dereferenced. param_view . reference An unsigned integer type to represent sizes. A signed integer type used to represent differences. Return the maximum number of characters possible This represents the largest number of characters that are possible in a path, not including any null terminator. Exception Safety Throws nothing. 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. Return true if there are no params Example assert( ! url_view( "?key=value" ).params().empty() ); Complexity Constant. Exception Safety Throws nothing. Return the number of params Example assert( url_view( "?key=value").params().size() == 1 ); Complexity Constant. Exception Safety Throws nothing. Return an iterator to the beginning Complexity Linear in the size of the first param. Exception Safety Throws nothing. Return an iterator to the end 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. 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 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. 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 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. 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 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 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. `s` contains an invalid query parameter string. The string to parse. BNF query-params = [ query-param ] *( "&" query-param ) query-param = key [ "=" value ] Specification 3.4. Query 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. `s` contains an invalid query parameter string. The string to parse. The options for decoding. If this parameter is omitted, `space_as_plus` is used. BNF query-params = [ query-param ] *( "&" query-param ) query-param = key [ "=" value ] Specification 3.4. Query 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 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. 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 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. `s` contains an invalid query parameter string. The string to parse. BNF query-params = [ query-param ] *( "&" query-param ) query-param = key [ "=" value ] Specification 3.4. Query 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 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 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 Exception Safety No-throw guarantee. A valid view on success, otherwise an error code. The string to parse Specification params_encoded_view . 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 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. 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. Clear the contents while preserving the capacity Postconditions this->empty() == true Complexity Constant. Exception Safety No-throw guarantee. 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. Allocation failure The capacity in characters, excluding any null terminator. 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. `s` contains an invalid scheme. The scheme to set. BNF scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ) Specification 3.1. Scheme (rfc3986) remove_scheme . 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) set_scheme . 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. The string contains an invalid percent-encoding. The authority string to set. BNF authority = [ userinfo "@" ] host [ ":" port ] userinfo = *( unreserved / pct-encoded / sub-delims / ":" ) host = IP-literal / IPv4address / reg-name port = *DIGIT Specification 3.2. Authority (rfc3986) remove_authority . 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) set_encoded_authority . 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. The string to set. BNF userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" ) Specification 3.2.1. User Information (rfc3986) remove_userinfo , set_encoded_userinfo . 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. `s` contains an invalid percent-encoding. The string to set. BNF userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" ) Specification 3.2.1. User Information (rfc3986) remove_userinfo , set_userinfo . 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) set_encoded_userinfo , set_userinfo . 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. The string to set. BNF userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" ) Specification 3.2.1. User Information (rfc3986) remove_password , set_encoded_password , set_encoded_user , set_password . 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. `s` contains an invalid percent-encoding. The string to set. BNF userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" ) Specification 3.2.1. User Information (rfc3986) remove_password , set_encoded_password , set_password , set_user . 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. The string to set. This string may contain any characters, including nulls. BNF userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" ) Specification 3.2.1. User Information (rfc3986) remove_password , set_encoded_password , set_encoded_user , set_user . 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. `s` contains an invalid percent-encoding. The string to set. This string may contain any characters, including nulls. BNF userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" ) Specification 3.2.1. User Information (rfc3986) remove_password , set_encoded_password , set_encoded_user , set_user . 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) set_encoded_password , set_encoded_user , set_password , set_user . 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. The string to set. 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) 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 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. `s` contains an invalid percent-encoding. The string to set. 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) 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, 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. The string to set. 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) 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 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. `s` contains an invalid percent-encoding. The string to set. 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) 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 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. The address to set. 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) 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. The address to set. 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) 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. `s` contains an invalid percent-encoding. The string to set. BNF IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" ) Specification 3.2.2. Host (rfc3986) 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. The string to set. BNF reg-name = *( unreserved / pct-encoded / "-" / ".") Specification 3.2.2. Host (rfc3986) 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 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. `s` contains an invalid percent-encoding. The string to set. BNF reg-name = *( unreserved / pct-encoded / "-" / ".") Specification 3.2.2. Host (rfc3986) 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 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. The port number to set. BNF authority = [ userinfo "@" ] host [ ":" port ] port = *DIGIT Specification 3.2.3. Port (rfc3986) remove_port , set_port . 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. `s` does not contain a valid port. The port string to set. BNF port = *DIGIT Specification 3.2.3. Port (rfc3986) remove_port , set_port . 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) set_port . 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() == '/' true on success. 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) encoded_segments , segments , set_encoded_path , set_path . Set the path. This function sets the path to the string, which may be empty. Reserved characters in the string are percent-escaped in the result. The library may adjust the final result to ensure that no other parts of the url is semantically affected. This function does not encode '/' chars, which are unreserved for paths but reserved for path segments. If a path segment should include encoded '/'s to differentiate it from path separators, the functions set_encoded_path or segments should be used instead. 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. The string to set. 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) encoded_segments , segments , set_encoded_path , set_path_absolute . 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. `s` contains an invalid percent-encoding. The string to set. 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) encoded_segments , segments , set_path , set_path_absolute . 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) encoded_segments , set_encoded_path , set_path , set_path_absolute . url_view_base::segments Return the path as a container of segments This function returns a bidirectional view of segments over the path. The returned view references the same underlying character buffer; ownership is not transferred. Strings returned when iterating the range may contain percent escapes. The container is modifiable; changes to the container are reflected in the underlying URL. 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) encoded_segments , set_encoded_path , set_path , set_path_absolute . url_view_base::encoded_segments 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. The string to set. BNF query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param ) Specification 3.4. Query (rfc3986) Query string (Wikipedia) encoded_params , params , remove_query , set_encoded_query . 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. The string to set. `s` contains an invalid percent-encoding. BNF query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param ) Specification 3.4. Query (rfc3986) Query string (Wikipedia) encoded_params , params , remove_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. 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) encoded_params , remove_query , set_encoded_query , set_query . url_view_base::params Return the query as a container of parameters This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first. The container is modifiable; changes to the container are reflected in the underlying URL. 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. The options for decoding. If this parameter is omitted, the `space_as_plus` is used. BNF query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param ) Specification 3.4. Query (rfc3986) Query string (Wikipedia) encoded_params , remove_query , set_encoded_query , set_query . url_view_base::encoded_params Return the query as a container of parameters This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Strings returned when iterating the range may contain percent escapes. The container is modifiable; changes to the container are reflected in the underlying URL. 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) params , remove_query , set_encoded_query , set_query . 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. The params to set. BNF query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param ) Specification ://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia) encoded_params , remove_query , set_encoded_query , set_query . 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. The params to set. some element in `ps` contains an invalid percent-encoding. BNF query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param ) Specification 3.4. Query (rfc3986) Query string (Wikipedia) set_params , params , remove_query , set_encoded_query , set_query . 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) encoded_params , params , set_encoded_query , set_query . 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 remove_fragment , set_encoded_fragment , set_fragment . 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. The string to set. BNF fragment = *( pchar / "/" / "?" ) Specification 3.5. Fragment remove_fragment , set_encoded_fragment . 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. `s` contains an invalid percent-encoding. The string to set. BNF fragment = *( pchar / "/" / "?" ) Specification 3.5. Fragment remove_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. 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) 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) 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) 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) 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) 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) 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 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. An empty result upon success, otherwise an error code if `!base.has_scheme()`. The URL reference to resolve. Specification 5. Reference Resolution (rfc3986) url , url_view . 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()`). 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. 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. `init` contains an invalid percent-encoding. The list of params to assign. Conversion Complexity Constant. Exception Safety Throws nothing. 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. 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. 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. `init` contains an invalid percent-encoding. The list of params to assign. 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. `p` contains an invalid percent-encoding. An iterator to the new element. The param to append. 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. `init` contains an invalid percent-encoding. An iterator to the first new element. The list of params to append. 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. `p` contains an invalid percent-encoding. An iterator to the inserted element. An iterator before which the param is inserted. This may be equal to `end()`. The param to insert. 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. `init` contains an invalid percent-encoding. 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. 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. last The range of params to erase. 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. `key` contains an invalid percent-encoding. 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. 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. `p` contains an invalid percent-encoding. An iterator to the element. An iterator to the element. The param to assign. 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. `init` contains an invalid percent-encoding. 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. 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. 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. `value` contains an invalid percent-encoding. 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 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. `key` or `value` contain an invalid percent-encoding. 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. 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 . 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. 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. The list contains an invalid percent-encoding. The list of segments to assign. Conversion segments_encoded_view . 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. 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. 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 contains an invalid percent-encoding. The list of segments to assign. 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. The segment contains an invalid percent-encoding. 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 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. The list contains an invalid percent-encoding. 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. 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. last The range of segments to erase. 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. The string contains an invalid percent-encoding. An iterator to the new segment. to 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. 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. The list contains an invalid percent-encoding. An iterator to the first segment inserted, or one past `to` if `init.size() == 0`. to The range of segments to replace. The list of segments to assign. 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 string contains an invalid percent-encoding. The segment to append. 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. 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 . 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. 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. The list of segments to assign. Conversion segments_view . 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. 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. 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. 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. 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. last The range of segments to erase. 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. to 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`. to The range of segments to replace. The list of segments to assign. 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. 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. 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 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. 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. 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) 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. 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. Return the URL as a core::string_view Complexity Constant. Exception Safety Throws nothing. 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. 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) scheme , scheme_id . 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) 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) has_scheme , scheme . 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) authority , encoded_authority . 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) encoded_authority , has_authority . 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) authority , has_authority . 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) has_password , encoded_password , encoded_user , encoded_userinfo , 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) has_userinfo , encoded_password , encoded_user , 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) has_password , has_userinfo , encoded_password , encoded_user , 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) has_password , has_userinfo , encoded_password , encoded_userinfo , password , user , userinfo . 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) has_password , has_userinfo , encoded_user , encoded_userinfo , password , user , userinfo . 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) 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) 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) 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) 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) 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) 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) 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 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) encoded_host_and_port , port , port_number . 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) 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) encoded_host_and_port , has_port , port . 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) encoded_path , encoded_segments . path , segments . 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) is_path_absolute , encoded_segments . path , segments . 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) is_path_absolute , encoded_path , encoded_segments . path , segments_view . 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) is_path_absolute , encoded_path , path , segments , segments_encoded_view . 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 ://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia) encoded_params , encoded_query , params , query . 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 ://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia) encoded_params , has_query , params , 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. 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 ://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia) 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. 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. Specification 3.4. Query (rfc3986) BNF query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param ) Specification ://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia) encoded_query , has_query , params , query . 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) encoded_fragment , fragment . 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) fragment , has_fragment . 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) has_port , port , port_number . 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. encoded_resource , encoded_target . 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) encoded_origin , encoded_target . 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) encoded_origin , encoded_resource . 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`. 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 std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) == std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment()); Complexity Linear in `min( u0.size(), u1.size() )` Exception Safety Throws nothing `true` if `u0 == u1` Specification 6.2.2 Syntax-Based Normalization (rfc3986) 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 std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) != std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment()); Complexity Linear in `min( u0.size(), u1.size() )` Exception Safety Throws nothing `true` if `u0 != u1` Specification 6.2.2 Syntax-Based Normalization (rfc3986) 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 std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) < std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment()); Complexity Linear in `min( u0.size(), u1.size() )` Exception Safety Throws nothing `true` if `u0 < u1` Specification 6.2.2 Syntax-Based Normalization (rfc3986) 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 std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) <= std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment()); Complexity Linear in `min( u0.size(), u1.size() )` Exception Safety Throws nothing `true` if `u0 <= u1` Specification 6.2.2 Syntax-Based Normalization (rfc3986) 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 std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) > std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment()); Complexity Linear in `min( u0.size(), u1.size() )` Exception Safety Throws nothing `true` if `u0 > u1` Specification 6.2.2 Syntax-Based Normalization (rfc3986) 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 std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) >= std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment()); Complexity Linear in `min( u0.size(), u1.size() )` Exception Safety Throws nothing `true` if `u0 >= u1` Specification 6.2.2 Syntax-Based Normalization (rfc3986) 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 std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) == std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment()); Complexity Linear in `min( u0.size(), u1.size() )` Exception Safety Throws nothing `true` if `u0 == u1` Specification 6.2.2 Syntax-Based Normalization (rfc3986) 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 std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) != std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment()); Complexity Linear in `min( u0.size(), u1.size() )` Exception Safety Throws nothing `true` if `u0 != u1` Specification 6.2.2 Syntax-Based Normalization (rfc3986) 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 std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) < std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment()); Complexity Linear in `min( u0.size(), u1.size() )` Exception Safety Throws nothing `true` if `u0 < u1` Specification 6.2.2 Syntax-Based Normalization (rfc3986) 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 std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) <= std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment()); Complexity Linear in `min( u0.size(), u1.size() )` Exception Safety Throws nothing `true` if `u0 <= u1` Specification 6.2.2 Syntax-Based Normalization (rfc3986) 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 std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) > std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment()); Complexity Linear in `min( u0.size(), u1.size() )` Exception Safety Throws nothing `true` if `u0 > u1` Specification 6.2.2 Syntax-Based Normalization (rfc3986) 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 std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) >= std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment()); Complexity Linear in `min( u0.size(), u1.size() )` Exception Safety Throws nothing `true` if `u0 >= u1` Specification 6.2.2 Syntax-Based Normalization (rfc3986) 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. 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. An empty 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. Specification 5. Reference Resolution (rfc3986) url , url_view . 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 . Destructor Any params, segments, iterators, or views which reference this object are invalidated. The underlying character buffer is destroyed, invalidating all references to it. Constructor 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 4.2. Relative Reference (rfc3986) 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. The input does not contain a valid url. The string to parse. BNF URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] relative-ref = relative-part [ "?" query ] [ "#" fragment ] Specification 4.1. URI Reference 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 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. `u.size() > max_size()`. The url to copy. 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. `u.size() > max_size()`. 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. 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. `u.size() > max_size()`. The url to copy. 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. The url to copy. 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 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 v1 The objects to swap url::swap url_base::set_scheme url_base::set_scheme_id url_base::remove_scheme url_base::set_encoded_authority url_base::remove_authority url_base::set_userinfo url_base::set_encoded_userinfo url_base::remove_userinfo url_base::set_user url_base::set_encoded_user url_base::set_password url_base::set_encoded_password url_base::remove_password url_base::set_host url_base::set_encoded_host url_base::set_host_address url_base::set_encoded_host_address url_base::set_host_ipv4 url_base::set_host_ipv6 url_base::set_host_ipvfuture url_base::set_host_name url_base::set_encoded_host_name url_base::set_port_number url_base::set_port url_base::remove_port url_base::set_path url_base::set_encoded_path url_base::set_query url_base::set_encoded_query url_base::set_params url_base::set_encoded_params url_base::remove_query url_base::remove_fragment url_base::set_fragment url_base::set_encoded_fragment url_base::remove_origin url_base::normalize url_base::normalize_scheme url_base::normalize_authority url_base::normalize_path url_base::normalize_query url_base::normalize_fragment 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 v1 The objects to swap url::swap 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 `s.size() > url_view::max_size` A result containing a value or an error The string to parse Specification 4.3. Absolute URI (rfc3986) parse_origin_form , parse_relative_ref , parse_uri , parse_uri_reference , 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_origin_form( "/index.htm?layout=mobile" ); BNF origin-form = absolute-path [ "?" query ] absolute-path = 1*( "/" segment ) `s.size() > url_view::max_size` A result containing a value or an error The string to parse Specification 5.3.1. origin-form (rfc7230) parse_absolute_uri , parse_relative_ref , parse_uri , parse_uri_reference , 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_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 A result containing a value or an error The string to parse `s.size() > url_view::max_size` Specification 4.2. Relative Reference (rfc3986) Errata ID: 5428 (rfc3986) parse_absolute_uri , parse_origin_form , parse_uri , parse_uri_reference , 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 `s.size() > url_view::max_size` A result containing a value or an error The string to parse Specification 3. Syntax Components (rfc3986) parse_absolute_uri , parse_origin_form , parse_relative_ref , parse_uri_reference , 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 `s.size() > url_view::max_size` A result containing a value or an error The string to parse Specification 4.1. URI Reference (rfc3986) Errata ID: 5428 (rfc3986) parse_absolute_uri , parse_origin_form , parse_relative_ref , parse_uri , url_view . 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 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. 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. 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. 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 format_to . 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. 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. 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 format . 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 . 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 .