uri_create

Name

uri_create_str — parse a URI or IRI

Library

URI parsing library (liburi, -luri)

Synopsis

#include <liburi.h>

URI *uri_create_str( const char *restrict uristr, const URI *restrict base);

Description

The uri_create_str function parses a string in order to produce a URI instance. If the URI to be parsed in uristr is not absolute, and an absolute base URI is supplied as base, the parsed URI will be resolved relative to the base URI and the result will be an absolute URI. If no base URI is supplied, the resulting URI instance may be either absolute or relative, depending upon the contents of uristr.

The resulting instance must be freed later using uri_destroy(3).

URIs are normalised as they are parsed. Normalisation is performed according to section 6.2.2 of RFC3986, and includes adjusting the case of any scheme, hostname and percent-encoded characters so as to be consistent, as well as removing redundant components from the path (for example, a path of /a/b/c/../d/../../e will be normalised to /a/e).

Once parsed, a URI can be resolved against a base URI if it is relative using uri_create_uri(3), and can be recomposed into a string representation using uri_str(3).

Parameters

uristr: A string to parse as a URI or IRI.
base: An optional absolute base URI. If base is supplied but is not an absolute URI, the results are undefined.

Return value

If the URI was parsed successfully, uri_create_str will return a new URI instance. If the URI could not be parsed, or some other error occurs, NULL will be returned and errno set accordingly.

Diagnostics

In the event of an error ocurring, errno may be set to one of the following values:

EINVAL: The URI was not well-formed and could not be parsed.
ENOMEM: A memory allocation operation failed.

Examples

Parsing an absolute URI:

URI *uri;

uri = uri_create_str("http://example.com/sample", NULL);

Parsing a relative URI, and resolving it against an absolute base URI:

URI *base, *uri;

base = uri_create_str("http://example.com/sample", NULL);

/* The result would be as though the string being parsed had been:
 *    http://example.com/switch?toggle=1
 */
uri = uri_create_str("switch?toggle=1", base);