//
// Copyright (c) 2023 Alan de Freitas (alandefreitas@gmail.com)
//
// Distributed under the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at https://www.boost.org/LICENSE_1_0.txt)
//
// Official repository: https://github.com/boostorg/url
//

= Boost.URL

Boost.URL is a portable C++ library which provides containers and algorithms which model a "URL," more formally described using the
https://datatracker.ietf.org/doc/html/rfc3986[Uniform Resource Identifier (URI),window=blank_]
specification (henceforth referred to as https://tools.ietf.org/html/rfc3986[rfc3986,window=blank_]).
A URL is a compact sequence of characters that identifies an abstract or physical resource.
For example, this is a valid URL:

[source]
----
https://www.example.com/path/to/file.txt?userid=1001&pages=3&results=full#page1
----

This library understands the grammars related to URLs and provides functionality to validate, parse, examine, and modify urls, and apply normalization or resolution algorithms.

== 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 most algorithms have the means to opt-out of dynamic memory allocation.
Another feature of the library is that all modifications leave the URL in a valid state.
Code which uses this library is easy to read, flexible, and performant.

Boost.URL offers these features:

* C++11 as only requirement
* Fast compilation, few templates
* Strict compliance with https://tools.ietf.org/html/rfc3986[rfc3986,window=blank_]
* Containers that maintain valid URLs
* Parsing algorithms that work without exceptions
* Control over storage and allocation for URLs
* Support for `-fno-exceptions`, detected automatically
* Features that work well on embedded devices

[NOTE]
====
Currently the library does not handle
https://www.rfc-editor.org/rfc/rfc3987.html[Internationalized Resource Identifiers,window=blank_] (IRIs).
These are different from URLs, come from Unicode strings instead of low-ASCII strings, and are covered by a separate specification.
====

== Requirements

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

For standard types, such as cpp:std::error_code[] or cpp:std::string_view[], the library uses their Boost equivalents cpp:boost::system::error_code[] and cpp:boost::core::string_view[].

Boost.URL works great on embedded devices.
It can be used in a way that avoids all dynamic memory allocations.
Furthermore it offers alternative interfaces that 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.1, 14.2, 14.3

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

We do not test and support gcc 8.0.1.

== Quality Assurance

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

* Coverage reports
* Compilation and tests on Drone.io and GitHub Actions
* 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 https://tools.ietf.org/html/rfc3986[rfc3986,window=blank_].

== ABNF

This documentation uses the Augmented
https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form[Backus-Naur Form,window=blank_]
(ABNF) notation of
https://datatracker.ietf.org/doc/html/rfc5234[rfc5234,window=blank_]
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 is of interest to users who wish to compose parsing algorithms using the combinators provided by the library.

== Acknowledgments

This library wouldn't be where it is today without the help of
https://github.com/pdimov[Peter Dimov,window=blank_]
for design advice and general assistance.






