The URI template

In addition to protocol implementations, the cpp-netlib provides a powerful URI template. The URI template implements a parser based on RFC 3986.

Generic URI Syntax Overview

A generic URI will take the form:

[scheme:]scheme-specific-part[#fragment]

A URI is known as absolute if it specifies the scheme. Otherwise, it is known as a relative URI. Currently, basic_uri supports only absolute URIs.

URIs can be further classified according to whether they’re hierarchical or opaque (non-hierarchical).

Some examples of non-hierarchical URIs include:

mailto:john.doe@example.com
news:comp.infosystems.www.servers.unix
tel:+1-816-555-1212

The data following the first ":" is said to be opaque to the URI parser and requires no further parsing. By way of example, the following shows how a non-hierarchical URI is processed by the parser by defining everything after the ":" to be a part of the path:

_images/mailto_uri.png

A hierarchical URI is identified by a double slash ("//") after the scheme and a scheme-specific component, which RFC 3986 defines to be:

[scheme:][//authority][path][?query][#fragment]

The authority component can be further broken down to:

[user_info@]host[:port]

Examples of hierarchical URIs include:

http://www.boost.org/
file:///bin/bash

The following example, describing a complex URI using FTP, shows how a URI is broken down by the parser:

_images/ftp_uri.png

Note that the authority is further subdivided into different elements. Another example, using HTTP is given below:

_images/http_uri.png

The difference here between the path in a hierarchical URI and that in the example above for the non-hierarchical URI.

basic_uri

The basic_uri definition is consistent with that of basic_message:

template <class Tag>
class basic_uri;

As it stands, the template only supplies a URI parser and no builder. To use the parser, it’s as simple as supplying a string to the constructor:

boost::network::uri::uri instance("http://cpp-netlib.github.com/");
assert(boost::is_valid(instance));
std::cout << "scheme: " << boost::network::uri::scheme(instance) << std::endl
          << "host: " << boost::network::uri::host(instance) << std::endl;

The command-line output of this program will be:

scheme: http
host: cpp-netlib.github.com

A future version of basic_uri will provide a full builder API.

URI Concept

Legend

U:The URI type.
u,u_:An instance of M.
S:A string type.
s,v:An instance of S.
T:The Tag type.
Construct Result Description
U(u) Instance of U Copy constructible.
U(s) Instance of U Constructible from string.
u = u_; Reference to u Assignable.
u = s; Reference to u Assignable from string.
swap(u, u_); void Swappable.
scheme(u); Convertible to S Retrieve the URI scheme of u.
user_info(u); Convertible to S Retrieve the user info of u.
host(u); Convertible to S Retrieve the host of u.
port(u); Convertible to H Retrieve the port of u.
path(u); Convertible to S Retrieve the path of u.
query(u); Convertible to S Retrieve the query string of u.
fragment(u); Convertible to S Retrieve the fragment of u.