Overview

Boost.URL is a portable C++ library which provides containers and algorithms which model a "URL", more formally described using the Uniform Resource Identifier (URI) specification (henceforth referred to as rfc3986). A URL is a compact sequence of characters that identifies an abstract or physical resource. For example, this is a valid URL which satisfies the absolute-URI grammar:

https://www.example.com/path/to/file.txt?userid=1001&page=2&results=full

This library understands the various grammars related to URLs and provides functionalities for:

Validating and parsing of strings,
Manipulation of URL strings, and
Algorithms such as normalization and resolution.

	Note
	Currently the library does not handle Internationalized Resource Identifiers (IRIs). These are different from URLs, come from Unicode strings instead of low-ASCII strings, and are covered by a separate specification.

Features

While the library is general purpose, special care has been taken to ensure that the implementation and data representation are friendly to network programs which need to handle URLs efficiently and securely, including the case where the inputs come from untrusted sources.

Interfaces are provided for using error codes instead of exceptions as needed, and all algorithms provide a mechanism for avoiding memory allocations entirely if desired. Another feature of the library is that all container mutations leave the URL in a valid state. Code which uses Boost.URL will be easy to read, flexible, and performant.

Boost.URL offers these features:

Require only C++11
Fast compilation, few templates
Strict compliance with rfc3986
Containers always maintain valid URLs
Parsing algorithms work without exceptions
Control over storage and allocation for URLs
Optional header-only, without linking to a library
Supports -fno-exceptions, detected automatically
Link to a built static or dynamic Boost library, or use header-only
Work well on embedded devices

Requirements

The library requires a compiler supporting at least C++11.

Aliases for standard types, such as error_code or string_view, use their Boost equivalents.

Header-Only

To use the library as header-only; that is, to eliminate the requirement to link a program to a static or dynamic Boost.URL library, simply place the following line in exactly one source file in your project.

#include <boost/url/src.hpp>

Embedded

Boost.URL works great on embedded devices. It can be used in a way that avoids all dynamic memory allocations. Furthermore it is designed to work without exceptions if desired.

Tested Compilers

Boost.URL has been tested with the following compilers:

clang: 3.8, 4, 5, 6, 7, 8, 9, 10, 11, 12
gcc: 4.8, 4.9, 5, 6, 7, 8, 9, 10, 11
msvc: 14.0, 14.1, 14.2, 14.3

and these architectures: x86, x64, ARM64, S390x.

Quality Assurance

The development infrastructure for the library includes these per-commit analyses:

Coverage reports
Compilation and tests on Drone.io and GitHub Actions
Fuzzing using clang-llvm and machine learning
Regular code audits for security

Nomenclature

Various names have been used historically to refer to different flavors of resource identifiers, including URI, URL, URN, and even IRI. Over time, the distinction between URIs and URLs has disappeared when discussed in technical documents and informal works. In this library we use the term URL to refer to all strings which are valid according to the top-level grammar rules found in rfc3986.

ABNF

This documentation uses the Augmented Backus-Naur Form (ABNF) notation of rfc5234 to specify particular grammars used by algorithms and containers. While a complete understanding of the notation is not a requirement for using the library, it may help for an understanding of how valid components of URLs are defined. In particular, this will be of interest to users who wish to compose parsing algorithms using the combinators provided by the library.

Security Review (Bishop Fox)

To be announced

Acknowledgments

This library wouldn't be where it is today without the help of Peter Dimov for design advice and general assistance.