[/
    Copyright (c) 2021 Vinnie Falco (vinnie.falco@gmail.com)
    Copyright (c) 2022 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 http://www.boost.org/LICENSE_1_0.txt)

    Official repository: https://github.com/boostorg/url
]

[section Overview]
[block'''<?dbhtml stop-chunking?>''']

[/-----------------------------------------------------------------------------]

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)]
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:

[teletype]
```
    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.

[heading 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 __rfc3986__
* 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] (IRIs).
    These are different from URLs, come from Unicode strings instead of
    low-ASCII strings, and are covered by a separate specification.
]

[/-----------------------------------------------------------------------------]

[section 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.

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.

[endsect]

[/-----------------------------------------------------------------------------]

[heading 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.

[heading 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

[/-----------------------------------------------------------------------------]

[section 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__.

[endsect]

[/-----------------------------------------------------------------------------]

[heading ABNF]

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

[/-----------------------------------------------------------------------------]

[heading Acknowledgments]

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

[/-----------------------------------------------------------------------------]

[include 2.0.quicklook.qbk]

[endsect]
