Given the increased importance of being able to develop portable, scalable network-aware applications, C++ developers are at a disavantage in having no standard network implementation to use. One of the fundamental components of any network library is a URI and this proposal is motivated by the desire to introduce a portable, efficient and internationalized implementation of a URI to C++ standard library users.
This proposal is based on original development done in the cpp-netlib project http://cpp-netlib.org/. This implementation is released using the Boost software license and will track the proposed library as it evolves. A standalone project can be found at https://github.com/cpp-netlib/uri/.
The scope of this proposal will include a single uri type, some specifications about how URIs are intended to be processed and extended, including some additional helper types and functions. It will include a type and functions to build a URI from its components. Finally, it will include types and functions for percent encoding, URI references and URI normalization.
#include <experimental/uri>
#include <cassert>
int main() {
std::experimental::uri uri("http://www.example.com/glynos/?key=value#frag");
assert(uri.is_absolute());
assert(!uri.is_opaque());
assert(*uri.scheme() == "http");
assert(*uri.host() == "www.example.com");
assert(*uri.path() == "/glynos/");
assert(*uri.query() == "key=value");
assert(*uri.fragment() == "frag");
return 0;
}
The code excerpt above shows a simple of how the proposed uri class will work. The URI string is parsed during object construction and broken down into its component parts. HTTP URIs are absolute and hierarchical (i.e. not opaque).
#include <experimental/uri>
#include <cassert>
int main() {
std::experimental::uri uri(U"xmpp:example-node@example.com?message;subject=Hello%20World");
assert(uri.is_absolute());
assert(uri.is_opaque());
assert(*uri.scheme() == "xmpp");
assert(*uri.path() == "example-node@example.com");
assert(*uri.query() == "message;subject=Hello%20World");
return 0;
}
The uri in this proposal supports encoded strings and supports encoding conversion. The example above shows a uri object constructed using a std::u32string and allow the parts to be accessed as std::string_view objects.
This proposal is a library extension that adds a header, two classes and some functions. It depends on the acceptance of other proposals (std::optional, std::string_view) for the API.
The uri and uri_builder and all related free functions and operators now belong in the std::experimental namespace.
The input and output stream operators are now template operators and use std::basic_istream and std::basic_ostream.
The assignment operators no longer needs to parse the URI string.
All functions associated with percent encoding and decoding are now static members of the std::experimental::uri class instead of free functions. They also throw exceptions on encoding failures.
absolute and opaque become is_absolute and is_opaque. This is a reversal of a previous revision (see N3484) and brings the uri proposal into line with the file system path (N3505).
Added noexcept overloads that take an additional error_code & argument. This applies to normalize, make_reference and resolve.
Added overloads to the uri constructors and to std::experimental::make_uri to better support allocators.
The authors’ contact details have been updated.
The API has been updated to use the name std::string_view instead of std::string_ref.
The proposed uri class is now in the std namespace, after feedback from the BSI C++ Panel. As a consequence the names of the encode_* and decode free functions have been updated to encode_uri_* and decode_uri.
uri::relativize has been renamed uri::make_reference.
A section describing the impact of the proposal on the standard has been added and the issues section was removed.
The document has been fixed so that query part now starts after the question-mark separator.
All parts accessors (scheme, user_info, host, port, path, query and fragment) now all return std::optional<std::string_view>.
normalize, relativize and resolve all accept as an argument the uri_comparison_level.
The uri(InputIterator, InputIterator) and uri(Source) constructors now can throw a std::system_error exception instead of uri_syntax_error. This makes the constructor exception consistent with the error code set by make_uri.
compare now returns an int instead of a bool. The return value of compare will be -1 if this (normalized) uri is lexographically less than that of the other, 0 if they are equal and 1 if this is greater than the other (see comparison ladder).
The items in the appendix describing the revision history have changed to this section. The appendix now contains a response to questions about existing practice and to the WhatWG URL Standard.
The updated uri class no longer specifies the underlying string type directly; it need not even be a std::basic_string. The std::uri::value_type is now defined as the value of the string iterator. Consequently, the uri class will no longer assume that the underlying string is in a contiguous block of memory, so the c_str() has been removed.
The uri(InputIterator, InputIterator) and uri(Source) constructors now can throw a uri_syntax_error exception. The is_valid member has been removed as it is now redundant.
This proposal in its current form only specifies tests for syntactic validity. To make this more explicit, the test for validity (now an exception) is named uri_syntax_error. This decision will influence others, especially related to normalization and equivalence. Future versions of this proposal may address the question of semantic validity. It would boil down to how complex the implementation of a generic URI class needs to be, and if it can be made extensible in the right ways to test scheme-specific semantics.
The accessors is_absolute and is_opaque have been renamed absolute and opaque in order to be more consistent.
The functions normalize, relativize and resolve have been removed and replaced with member functions in the class.
A function compare is provided which takes as a 3rd argument a uri_comparison_level enum. This can be used to determine the level of the comparison ladder to use when comparing URIs. A more complete description of what comparison and equivalence means can be discussed and elaborated in a future proposal.
The question of semantics of relational operators will also be addressed.
The functions pct_encode and pct_decode have been renamed encode and decode. A few more functions have been added to take into account the different types of encoding for different URI parts.
The changes requires to the uri::builder have been taken into account, including renaming it uri_builder and providing a method uri() that returns a new uri object.
As seems to be inevitable when developing a proposal for a standards committee, there are some differences of opinion regarding the names of certain functions. I will attempt to justify some of them now:
There has been some concern about the ambiguity with this term and with name resolution. Nevertheless, RFC 3986, Section 5 calls this process ‘Reference Resolution’ and existing URI classes in other languages and frameworks also use this term (e.g. Java and Qt).
The names of the query accessors have changed at least twice (once removing the is_ suffix and again to add them). The current revision of the proposal is consistent at least with std::filesystem::path interface.
The current proposal does not provide any way to allow a library implementation or user to extend the API. This would be important to allow scheme or protocol specific implementations of normalize and compare. A future revision should address this.
The generic syntax of a URI is defined in RFC 3986.
All URIs are of the form:
scheme ":" "hierarchical part" [ "?" query ] [ "#" fragment ]
The scheme is used to identify the specification needed to parse the rest of the URI. A generic syntax parser can parse any URI into its main parts. The scheme can then be used to identify whether further scheme-specific parsing can be performed.
The hierarchical part refers to the part of the URI that holds identification information that is hierarchical in nature. This may contain an authority (always prefixed with a double slash "//") and/or a path. The path part is required, thought it may be empty. The authority part holds an optional user info part, ending with an at sign "@"; a host identifier and an optional port number, preceded by a colon ":". The host may be an IP address or domain name. RFC 3986 does not specify the format for IPv6 addresses, though RFC 2732 does.
The query is an optional part following a question mark "?" that contains information that is not hierarchical.
Finally, the fragment is an optional part, prefixed by a hash symbol "#" that is used to identify secondary sources.
RFC 3987 specifies a new protocol element, the Internationalized Resource Identifier (IRI). The IRI complements a URI, and extends it to allow unicode characters.
This proposal will define a uri type that will attempt to encompass all three of these RFCs.
URI percent encoding is described in RFC 3986, section 2.1 and RFC 3986, section 2.4.
Percent encoding is the mechanism used to encode reserved characters in a URI. According to RFC 3986, section 2.2, the set of reserved characters are:
| ! | # | $ | & | ' | ( | ) | * | + | , | / | : | ; | = | ? | @ | [ | ] |
| %21 | %23 | %24 | %26 | %27 | %28 | %29 | %2A | %2B | %2C | %2F | %3A | %3B | %3D | %3F | %40 | %5B | %5D |
Percent encoding is not limited to reserved characters. Any character data may be percent encoded:
| newline | space | " | % | - | . | < | > | \ | ^ | _ | ` | { | | | } | ~ |
| %0A | %20 | %22 | %25 | %2D | %2E | %3C | %3E | %5C | %5E | %5F | %60 | %7B | %7C | %7D | %7E |
URI normalization is described in RFC 3986, Section 6 and in RFC 3987, Section 5. Normalization is the process by which a URI is transformed in order to determine if two URIs are equivalent.
Different types of normalization may preserve semantics, and others may not. Normalization may also depend on the scheme.
The scheme and host are case-insensitive. The proposed normalization solution will convert these to lowercase.
HTTP://Example.com/ --> http://example.com/
The user info, path, query and fragment are case-sensitive and so must not be converted.
Characters in a percent-encoded triplet are case-insensitive. The proposed normalization solution will convert these to lowercase.
http://example.com/%5b%5d --> http://example.com/%5B%5D
Unreserved characters that have been encoded will be decoded.
http://example.com/%7Eglynos/ --> http://example.com/~glynos/
If a path refers to a directory, it should be indicated with a trailing slash.
http://example.com/glynos --> http://example.com/glynos/
But not if the path refers to a file.
http://example.com/glynos/page.html --> http://example.com/glynos/page.html
The segments ”..” and ”.” can be removed according to the algorithm specified in RFC 3986, Section 5.2.4.
http://example.com/glynos/./proposals/../ --> http://example.com/glynos/
Some schemes may have a default port (for HTTP it is 80). The default port can be removed.
http://example.com:80/ --> http://example.com/
http://example.com:/ --> http://example.com/
The Comparison Ladder is described in RFC 3986, Section 6.2. It explains that comparing URIs using normalization can be implemented in different ways according to the complexity of the method and the number of false negatives which may arise.
The final two steps in the Comparison Ladder require more information than can be provided within the limits of the proposal in order to be implemented comprehensively, and will not form part of the proposal at this stage.
URI references are described in RFC 3986, section 4, RFC 3986, section 5 and RFC 3987, section 6.5. URI references are particularly useful when working on the server side when the base URI is always the same, and also when using URIs within the same document.
Two operations related to references are of use: acquiring the relative reference of a URI, and resolving a reference against a base URI.
#include <string> // std::basic_string
#include <system_error> // std::error_code
#include <iosfwd> // std::basic_istream, std::basic_ostream
#include <iterator> // std::iterator_traits
#include <memory> // std::allocator
#include <optional> // std::optional
namespace std {
namespace experimental {
// class declarations
class uri;
class uri_builder;
class uri_syntax_error;
class uri_builder_error;
class uri_encoding_error;
enum class uri_error {
invalid_syntax,
invalid_uri,
invalid_scheme,
invalid_user_info,
invalid_host,
invalid_port,
invalid_path,
invalid_query,
invalid_fragment,
};
enum class uri_comparison_level {
string_comparison,
case_normalization,
percent_encoding_normalization,
path_segment_normalization,
scheme_based_normalization,
protocol_based_normalization,
};
// factory functions
template <class Source>
uri make_uri(const Source &source, std::error_code &e) noexcept;
template <class InputIter>
uri make_uri(InputIter first, InputIter last, std::error_code &e) noexcept;
template <class Source, class Alloc = std::alloc<uri::value_type>>
uri make_uri(const Source &source, const Alloc &alloc, std::error_code &e) noexcept;
template <class InputIter, class Alloc = std::allocator<uri::value_type>>
uri make_uri(InputIter first, InputIter last, const Alloc &alloc, std::error_code &e) noexcept;
// swap functions
void swap(uri &lhs, uri &rhs);
// equality and comparison operators
bool operator == (const uri &lhs, const uri &rhs);
bool operator != (const uri &lhs, const uri &rhs);
bool operator < (const uri &lhs, const uri &rhs);
bool operator <= (const uri &lhs, const uri &rhs);
bool operator > (const uri &lhs, const uri &rhs);
bool operator >= (const uri &lhs, const uri &rhs);
// stream operators
template <typename CharT, class CharTraits = std::char_traits<CharT>>
std::basic_ostream<CharT, CharTraits> &
operator << (std::basic_ostream<CharT, CharTraits> &os, const uri &u);
template <typename CharT, class CharTraits = std::char_traits<CharT>>
std::basic_istream<CharT, CharTraits> &
operator >> (std::basic_istream<CharT, CharTraits> &is, uri &u);
} // namespace experimental
} // namespace std
The <experimental/uri> header contains a declaration for a single uri class in the std::experimental namespace.
Previous revisions of this proposal used the sub-namespace network namespace, but given feedback this is no longer the case.
// factory functions
namespace std {
namespace experimental {
template <class Source>
uri make_uri(const Source &source, std::error_code &e) noexcept;
template <class InputIter>
uri make_uri(InputIter first, InputIter last, std::error_code &e) noexcept;
template <class Source, class Alloc = std::alloc<uri::value_type>>
uri make_uri(const Source &source, const Alloc &alloc, std::error_code &e) noexcept;
template <class InputIter, class Alloc = std::allocator<uri::value_type>>
uri make_uri(InputIter first, InputIter last, const Alloc &alloc, std::error_code &e) noexcept;
} // namespace experimental
} // namespace std
These factory functions are provided in order to be able to construct a uri object without throwing an exception. The error code is stored in the std::error_code object, if the string source is an invalid URI.
namespace std {
namespace experimental {
enum uri_comparison_level { ... };
bool operator == (const uri &lhs, const uri &rhs);
bool operator != (const uri &lhs, const uri &rhs);
bool operator < (const uri &lhs, const uri &rhs);
bool operator <= (const uri &lhs, const uri &rhs);
bool operator > (const uri &lhs, const uri &rhs);
bool operator >= (const uri &lhs, const uri &rhs);
} // namespace experimental
} // namespace std
namespace std {
namespace experimental {
template <typename CharT, class CharTraits = std::char_traits<CharT>>
std::basic_ostream<CharT, CharTraits> &
operator << (std::basic_ostream<CharT, CharTraits> &os, const uri &u);
} // namespace experimental
} // namespace std
Output stream operator for std::experimental::uri.
namespace std {
namespace experimental {
template <typename CharT, class CharTraits = std::char_traits<CharT>>
std::basic_istream<CharT, CharTraits> &
operator >> (std::basic_istream<CharT, CharTraits> &is, uri &u);
} // namespace experimental
} // namespace std
Input stream operator for std::experimental::uri.
The proposed std::experimental::uri class constructor throws a std::experimental::uri_syntax_error exception if the URI string passed as an argument is an invalid URI. A factory function, std::experimental::make_uri is provided that sets an error code to report an error.
The proposed std::experimental::uri::encode_* and std::experimental::uri::decode throw a uri_encoding_error.
The uri member function of std::experimental::uri_builder can also throw a std::experimental::uri_builder_error exception if it is not possible to build a valid URI.
std::experimental::uri_syntax_error, std::uri_encoding_error and std::experimental::uri_builder_error are all subclasses of std::system_error.
An enum class, std::experimental::uri_error, forms a part of this proposal, and its values are used to indicate the type of URI error in a std::error_code object.
std::experimental::uri constructors can throw std::bad_alloc on a failure to allocate storage.
Below is the proposed interface for the uri class:
namespace std {
namespace experimental {
class uri {
public:
// typedefs
typedef ... string_type;
typedef string_type::const_iterator iterator;
typedef string_type::const_iterator const_iterator;
typedef std::iterator_traits<iterator>::value_type value_type;
typedef basic_string_view<value_type> string_view;
// constructors and destructor
uri();
template <typename InputIter, class Alloc = std::allocator<value_type>>
uri(const InputIter &first, const InputIter &last, const Alloc &alloc = Alloc());
template <class Source, class Alloc = std::allocator<value_type>>
explicit uri(const Source &source, const Alloc &alloc = Alloc());
uri(const uri &other);
uri(uri &&other) noexcept;
~uri();
// assignment
uri &operator = (const uri &other);
uri &operator = (uri &&other) noexcept;
// swap
void swap(uri &other) noexcept;
// iterators
const_iterator begin() const;
const_iterator end() const;
// accessors
std::optional<string_view> scheme() const;
std::optional<string_view> user_info() const;
std::optional<string_view> host() const;
std::optional<string_view> port() const;
std::optional<string_view> path() const;
std::optional<string_view> authority() const;
std::optional<string_view> query() const;
std::optional<string_view> fragment() const;
// query
bool empty() const noexcept;
bool is_absolute() const noexcept;
bool is_opaque() const noexcept;
// transformers
uri normalize(uri_comparison_level level) const;
uri normalize(uri_comparison_level level, std::error_code &ec) const noexcept;
uri make_reference(const uri &other, uri_comparison_level level) const;
uri make_reference(const uri &other, uri_comparison_level level,
std::error_code &ec) const noexcept;
uri resolve(const uri &other, uri_comparison_level level) const;
uri resolve(const uri &other, uri_comparison_level level,
std::error_code &ec) const noexcept;
// comparison
int compare(const uri &other, uri_comparison_level level) const noexcept;
// string accessors
template <typename CharT,
class CharTraits = std::char_traits<CharT>,
class Alloc = std::allocator<CharT>>
std::basic_string<CharT, CharTraits, Alloc> string(const Alloc &alloc = Alloc()) const;
std::string string() const;
std::wstring wstring() const;
std::u16string u16string() const;
std::u32string u32string() const;
// percent encoding and decoding
template <typename InputIter, typename OutputIter>
static OutputIter encode_user_info(InputIter first, InputIter last, OutputIter out);
template <typename InputIter, typename OutputIter>
static OutputIter encode_host(InputIter first, InputIter last, OutputIter out);
template <typename InputIter, typename OutputIter>
static OutputIter encode_port(InputIter first, InputIter last, OutputIter out);
template <typename InputIter, typename OutputIter>
static OutputIter encode_path(InputIter first, InputIter last, OutputIter out);
template <typename InputIter, typename OutputIter>
static OutputIter encode_query(InputIter first, InputIter last, OutputIter out);
template <typename InputIter, typename OutputIter>
static OutputIter encode_fragment(InputIter first, InputIter last, OutputIter out);
template <typename InputIter, typename OutputIter>
static OutputIter decode(InputIter first, InputIter last, OutputIter out);
};
} // namespace experimental
} // namespace std
The uri class itself is a little more than a light-weight wrapper around a string, a parser and the uri‘s component parts. Parsing is performed upon construction and, if successfully parsed, the component parts are stored as string_view‘s that reference the original string. For example, consider the following URI:
http://www.example.com/path/?key=value#fragment
^ ^ ^ ^ ^^ ^^ ^
a b c d ef gh i
On parsing, the uri object will contain a set of range types corresponding to the ranges for scheme, user info, host, port, path, query and fragment. So the ranges corresponding to the example above will be:
| URI part | Range | String |
|---|---|---|
| scheme | [a, b) | "http" |
| user_info | nullopt | |
| host | [c, d) | "www.example.com" |
| port | nullopt | |
| path | [d, e) | "/path/" |
| query | [f, g) | "key=value" |
| fragment | [h, i) | "fragment" |
Template parameters named InputIter are required meet the requirements for a C++ standard library RandomIterator compliant iterator. The iterator’s value type is required to be char, wchar_t, char16_t, or char32_t.
Template parameters named Source are required to be one of:
A container with a value type of char, wchar_t, char16_t, or char32_t.
An iterator for a null terminated byte-string. The value type is required to be char, wchar_t, char16_t, or char32_t.
A C-array. The value type is required to be char, wchar_t, char16_t, or char32_t.
This is identical wording to that found in the filesystem proposal (N3365).
typedef ... string_type;
typedef string_type::const_iterator iterator;
typedef string_type::const_iterator const_iterator;
typedef std::iterator_traits<iterator>::value_type value_type;
The string_type is left unspecified in this proposal and is intended to be implementation defined.
uri();
template <typename InputIter, class Alloc = std::allocator<value_type>>
uri(const InputIter &first, const InputIter &last, const Alloc &alloc = Alloc());
template <class Source, class Alloc = std::allocator<value_type>>
uri(const Source &source, const Alloc &alloc = Alloc());
uri(const uri &other);
uri(uri &&other) noexcept;
uri &operator = (const uri &other);
uri &operator = (uri &&other) noexcept;
const_iterator begin() const;
const_iterator end() const;
std::optional<string_view> scheme() const;
std::optional<string_view> user_info() const;
std::optional<string_view> host() const;
std::optional<string_view> port() const;
std::optional<string_view> path() const;
std::optional<string_view> authority() const;
std::optional<string_view> query() const;
std::optional<string_view> fragment() const;
bool empty() const noexcept;
bool is_absolute() const noexcept;
bool is_opaque() const noexcept;
This proposal specifies three transformer functions: normalize, make_reference and resolve.
uri normalize(uri_comparison_level level) const;
uri make_reference(const uri &other, uri_comparison_level level) const;
std::experimental::uri base_uri("http://www.example.com/");
std::experimental::uri uri("http://www.example.com/glynos/?key=value#fragment");
std::experimental::uri rel_uri(base_uri.make_reference(uri,
std::experimental::uri_comparison_level::string_comparison));
assert(rel_uri.string() == "/glynos/?key=value#fragment");
uri resolve(const uri &other, uri_comparison_level level) const;
int compare(const uri &other, uri_comparison_level level) const;
Returns -1 if this is less than other, given the comparison level; 0 if they are considered equal and 1 if this is greater.
template <typename CharT,
class CharTraits = std::char_traits<CharT>,
class Alloc = std::allocator<CharT>>
std::basic_string<CharT, CharTraits, Alloc> string(const Alloc &alloc = Alloc()) const;
std::string string() const;
std::wstring wstring() const;
std::u16string u16string() const;
std::u32string u32string() const;
template <typename InputIter, typename OutputIter>
static OutputIter
encode_user_info(InputIter first, InputIter last, OutputIter out);
template <typename InputIter, typename OutputIter>
static OutputIter
encode_host(InputIter first, InputIter last, OutputIter out);
template <typename InputIter, typename OutputIter>
static OutputIter
encode_port(InputIter first, InputIter last, OutputIter out);
template <typename InputIter, typename OutputIter>
static OutputIter
encode_path(InputIter first, InputIter last, OutputIter out);
template <typename InputIter, typename OutputIter>
static OutputIter
encode_query(InputIter first, InputIter last, OutputIter out);
template <typename InputIter, typename OutputIter>
static OutputIter
encode_fragment(InputIter first, InputIter last, OutputIter out);
template <typename InputIter, typename OutputIter>
static OutputIter
decode(InputIter first, InputIter last, OutputIter out);
The proposed uri_builder class is provided in order to construct uri objects more safely and more productively.
namespace std {
namespace experimental {
class uri_builder {
private:
uri_builder(const uri_builder &) = delete;
uri_builder &operator = uri_builder(const uri_builder &) = delete;
public:
uri_builder();
explicit uri_builder(const uri &base);
template <typename Source>
explicit uri_builder(const Source &base);
~uri_builder();
template <typename Source>
uri_builder &scheme(const Source &scheme);
template <typename Source>
uri_builder &user_info(const Source &user_info);
template <typename Source>
uri_builder &host(const Source &host);
template <typename Source>
uri_builder &port(const Source &port);
template <typename Source>
uri_builder &authority(const Source &authority);
template <typename Source>
uri_builder &authority(const Source &user_info, const Source &host, const Source &port);
template <typename Source>
uri_builder &path(const Source &path);
template <typename Source>
uri_builder &append_path(const Source &path);
template <typename Source>
uri_builder &query(const Source &query);
template <class Key, class Param>
uri_builder &query(const Key &key, const Param ¶m);
template <typename Source>
uri_builder &fragment(const Source &fragment);
std::experimental::uri uri() const;
};
} // namespace experimental
} // namespace std
The builder member functions are templates. This can allow the implementation to provide specializations depending on the argument type in order ensure that resultant URI remains valid and consistent. This could mean performing normalization or percent encoding on input strings where appropriate, and could allow other types to be used. For example, the port could be provided as an integral type.
To build a uri object, invoke the uri_builder::uri() member function. All encoding takes place here, and a std::system_error is thrown in case the uri is invalid.
The first example shows that the uri_builder can build a uri with a port number supplied as an integer. Also, since the uri_builder also handles normalization, a trailing slash is added where a path was not provided.
std::experimental::uri_builder builder;
builder.scheme("http")
.host("example.com")
.port(8080);
assert(builder.uri().string() == "http://example.com:8080/");
The builder should work with any scheme. The second example shows how the uri_builder would be used to create an e-mail address using the mailto scheme.
std::experimental::uri_builder builder;
builder.scheme("mailto")
.path("glynos@example.com");
assert(builder.uri().string() == "mailto:glynos@example.com");
The third example shows how the builder should normalize all parts of the URI.
std::experimental::uri_builder builder;
builder.scheme("http")
.host("Example.com")
.path("%7Eglynos//My Path/");
assert(builder.uri().string() == "http://example.com/~glynos/My%20Path/");
namespace std {
uri_builder::uri_builder();
} // namespace std
Constructs a uri_builder object.
namespace std {
uri_builder::uri_builder(const uri &base);
} // namespace std
Constructs a uri_builder object from a base URI.
namespace std {
template <typename Source>
uri_builder::uri_builder(const Source &base);
} // namespace std
Constructs a uri_builder object from a base URI.
namespace std {
template <typename Source>
uri_builder &uri_builder::scheme(const Source &scheme);
} // namespace std
namespace std {
template <typename Source>
uri_builder &uri_builder::user_info(const Source &user_info);
} // namespace std
namespace std {
template <typename Source>
uri_builder &uri_builder::host(const Source &host);
} // namespace std
namespace std {
template <typename Source>
uri_builder &uri_builder::port(const Source &port);
} // namespace std
namespace std {
template <typename Source>
uri_builder &authority(const Source &authority);
} // namespace std
namespace std {
template <typename Source>
uri_builder &authority(const Source &user_info, const Source &host, const Source &port);
} // namespace std
namespace std {
template <typename Source>
uri_builder &uri_builder::path(const Source &path);
} // namespace std
namespace std {
template <typename Source>
uri_builder &uri_builder::append_path(const Source &path);
} // namespace std
namespace std {
template <typename Source>
uri_builder &uri_builder::query(const Source &query);
} // namespace std
namespace std {
template <class Key, class Param>
uri_builder &uri_builder::query(const Key &key, const Param ¶m);
} // namespace std
namespace std {
template <typename Source>
uri_builder &uri_builder::fragment(const Source &fragment);
} // namespace std
namespace std {
template <typename Source>
uri uri_builder::uri() const;
} // namespace std
There exist several implementations of C++, including (but not limited to):
The cpp-netlib uri is the library that has motivated this proposal. It implements a generic URI, support for percent encoding, normalization and URI resolution. It also currently partially implements a URI builder.
QUrl supports much of the same functionality. It is fully internationalized, supports URI resolution and implicitly normalization. The part accessors differ from cpp-netlib, in that they return copies of the underlying parts, not references.
google-url is another existing library which is fast and robust. Its parsing strategy is such that it never fails (there is no validation), but always tries to find the best fit for the URL components. It supports normalization (but has called it canonicalization).
All of the implementations listed above do effectively the same thing - they parse a string and split it into components, either by storing separate copies of each part or by storing references to sub-strings in the original uri string.
In addition to RFC 3986 and RFC 3987, the WhatWG URL Standard is proposal for a standard that sets out to make URLs more interoperable.
The most important features of this proposed standard seem to be:
It does not explicitly describe operations such as normalization, comparison or resolution.
As this proposal allows the URI parsing to be implementation defined, there is no reason why an implementor could not decide to use this standard. Apart from a few naming differences, the proposed uri interface maps closely to the WhatWG URL JavaScript API. If there is a strong interest in doing so, a future revision of this proposal could rename its class and member functions.
C++ Network Library users and mailing list
Kyle Kloepper and Niklas Gustafsson for providing valuable feedback and encouragement, and for presenting different versions of this proposal at committee meetings.
Beman Dawes and his Filesystem proposal from which I was influenced strongly in the class design.
Wikipedia, for being there.