iref 4.0.0

//! This crates provides an implementation of
//! [Uniform Resource Identifiers (URIs, aka URLs)][uri] and [Internationalized
//! Resource Identifiers (IRIs)][iri] following [RFC 3987][uri-rfc] and [RFC
//! 3986][iri-rfc] defined by the [Internet Engineering Task Force
//! (IETF)][ietf] to uniquely identify objects across the web. IRIs are a
//! superclass of URIs accepting international characters defined in the
//! [Unicode][unicode] table.
//!
//! [uri]: <https://en.wikipedia.org/wiki/Uniform_Resource_Identifier>
//! [uri-rfc]: <https://tools.ietf.org/html/rfc3986>
//! [iri]: <https://en.wikipedia.org/wiki/Internationalized_resource_identifier>
//! [iri-rfc]: <https://tools.ietf.org/html/rfc3987>
//! [ietf]: <ietf.org>
//! [unicode]: <https://en.wikipedia.org/wiki/Unicode>
//!
//! URI/IRIs are defined as a sequence of characters with distinguishable
//! components: a scheme, an authority, a path, a query and a fragment.
//!
//! ```text
//!     foo://example.com:8042/over/there?name=ferret#nose
//!     \_/   \______________/\_________/ \_________/ \__/
//!      |           |            |            |        |
//!   scheme     authority       path        query   fragment
//! ```
//!
//! This crate provides types to represent borrowed and owned URIs and IRIs
//! (`Uri`, `Iri`, `UriBuf`, `IriBuf`), borrowed and owned URIs and IRIs
//! references (`UriRef`, `IriRef`, `UriRefBuf`, `IriRefBuf`) and similar
//! types for every part of an URI/IRI. Theses allows the easy access and
//! manipulation of every components.
//! It features:
//!   - borrowed and owned URI/IRIs and URI/IRI-reference;
//!   - mutable URI/IRI buffers (in-place);
//!   - path normalization;
//!   - comparison modulo normalization;
//!   - URI/IRI-reference resolution;
//!   - static URI/IRI parsing using the [`uri!`]/[`iri!`] macros.
//!   - `serde` support (by enabling the `serde` feature).
//!   - `no_std` support (by disabling the default `std` feature).
//!
//! ## Basic usage
//!
//! You can parse an IRI string slice by simply calling [`Iri::new`].
//! No memory allocation occurs using this function, it only borrows the input
//! data, and validates it. Access to each component is done in linear time.
//!
//! ```rust
//! use iref::Iri;
//!
//! # fn main() -> Result<(), iref::IriError<&'static str>> {
//! let iri = Iri::new("https://www.rust-lang.org/foo/bar?query#frag")?;
//!
//! println!("scheme: {}", iri.scheme());
//! println!("authority: {}", iri.authority().unwrap());
//! println!("path: {}", iri.path());
//! println!("query: {}", iri.query().unwrap());
//! println!("fragment: {}", iri.fragment().unwrap());
//! #
//! # Ok(())
//! # }
//! ```
//!
//! IRIs can be created and modified using the `IriBuf` type.
//! With this type, the IRI is held in a single buffer, modified in-place to
//! reduce memory allocations and optimize memory accesses.
//! This also allows the conversion from `IriBuf` into `Iri`.
//!
//! ```rust
//! use iref::IriBuf;
//!
//! # fn main() -> Result<(), iref::IriError<std::borrow::Cow<'static, str>>> {
//! let mut iri = IriBuf::new("https://www.rust-lang.org".to_string())?;
//!
//! iri.authority_mut().unwrap().set_port(Some("40".try_into()?));
//! iri.set_path("/foo".try_into()?);
//! iri.path_mut().push("bar".try_into()?);
//! iri.set_query(Some("query".try_into()?));
//! iri.set_fragment(Some("fragment".try_into()?));
//!
//! assert_eq!(iri, "https://www.rust-lang.org:40/foo/bar?query#fragment");
//! # Ok(())
//! # }
//! ```
//!
//! The `try_into` method is used to ensure that each string is syntactically
//! correct (for instance, it is not possible to replace `"query"` with
//! `"query?"` since `?` is not a valid query character).
//!
//! ## Detailed Usage
//!
//! ### Path manipulation
//!
//! The IRI path is accessed through the `path` or `path_mut` methods.
//! It is possible to access the segments of a path using the iterator returned
//! by the `segments` method.
//!
//! ```rust
//! # use iref::Iri;
//! # fn main() -> Result<(), iref::IriError<&'static str>> {
//! # let iri = Iri::new("https://www.rust-lang.org/foo/bar?query#frag")?;
//! for segment in iri.path().segments() {
//!   println!("{}", segment);
//! }
//! # Ok(())
//! # }
//! ```
//!
//! One can use the `normalized_segments` method to iterate over the normalized
//! version of the path where dot segments (`.` and `..`) are removed.
//! In addition, it is possible to push or pop segments to a path using the
//! corresponding methods:
//! ```rust
//! # use iref::IriBuf;
//! # fn main() -> Result<(), iref::IriError<std::borrow::Cow<'static, str>>> {
//! let mut iri = IriBuf::new("https://rust-lang.org/a/c".to_string())?;
//! let mut path = iri.path_mut();
//!
//! path.pop();
//! path.push("b".try_into()?);
//! path.push("c".try_into()?);
//! path.push("".try_into()?); // the empty segment is valid.
//!
//! assert_eq!(iri.path(), "/a/b/c/");
//! # Ok(())
//! # }
//! ```
//!
//! ### IRI references
//!
//! This crate provides the two types `IriRef` and `IriRefBuf` to represent
//! IRI references. An IRI reference is either an IRI or a relative IRI.
//! Contrarily to regular IRIs, relative IRI references may have no scheme.
//!
//! ```rust
//! # use iref::{Iri, IriRef, IriRefBuf};
//! # fn main() -> Result<(), iref::IriError<&'static str>> {
//! let mut iri_ref = IriRefBuf::default(); // an IRI reference can be empty.
//!
//! // An IRI reference with a scheme is a valid IRI.
//! iri_ref.set_scheme(Some("https".try_into()?));
//! let iri: &Iri = iri_ref.as_iri().unwrap();
//!
//! // An IRI can be safely converted into an IRI reference.
//! let iri_ref: &IriRef = iri.into();
//! # Ok(())
//! # }
//! ```
//!
//! Given a base IRI, references can be resolved into a regular IRI using the
//! [Reference Resolution Algorithm](https://tools.ietf.org/html/rfc3986#section-5)
//! defined in [RFC 3986](https://tools.ietf.org/html/rfc3986).
//! This crate provides a *strict* implementation of this algorithm.
//!
//! ```rust
//! # use iref::{Iri, IriRef, IriRefBuf};
//! # fn main() -> Result<(), iref::IriError<::std::borrow::Cow<'static, str>>> {
//! let base_iri = Iri::new("http://a/b/c/d;p?q")?;
//! let mut iri_ref = IriRefBuf::new("g;x=1/../y".to_string())?;
//!
//! // non mutating resolution.
//! assert_eq!(iri_ref.resolved(base_iri), "http://a/b/c/y");
//!
//! // in-place resolution.
//! iri_ref.resolve(base_iri);
//! assert_eq!(iri_ref, "http://a/b/c/y");
//! # Ok(())
//! # }
//! ```
//!
//! This crate implements
//! [Errata 4547](https://www.rfc-editor.org/errata/eid4547) about the
//! abnormal use of dot segments in relative paths.
//! This means that for instance, the path `a/b/../../../` is normalized into
//! `../`.
//!
//! ### IRI comparison
//!
//! Here are the features of the IRI comparison method implemented in this crate.
//!
//! #### Protocol agnostic
//!
//! This implementation does not know anything about existing protocols.
//! For instance, even if the
//! [HTTP protocol](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol)
//! defines `80` as the default port,
//! the two IRIs `http://example.org` and `http://example.org:80` are **not** equivalent.
//!
//! #### Every `/` counts
//!
//! The path `/foo/bar` is **not** equivalent to `/foo/bar/`.
//!
//! #### Path normalization
//!
//! Paths are normalized during comparison by removing dot segments (`.` and `..`).
//! This means for instance that the paths `a/b/c` and `a/../a/./b/../b/c` **are**
//! equivalent.
//! Note however that this crate implements
//! [Errata 4547](https://www.rfc-editor.org/errata/eid4547) about the
//! abnormal use of dot segments in relative paths.
//! This means that for instance, the IRI `http:a/b/../../../` is equivalent to
//! `http:../` and **not** `http:`.
//!
//! #### Percent-encoded characters
//!
//! Thanks to the [`pct-str` crate](https://crates.io/crates/pct-str),
//! percent encoded characters are correctly handled.
//! The two IRIs `http://example.org` and `http://exa%6dple.org` **are**
//! equivalent.
#![cfg_attr(not(feature = "std"), no_std)]

mod common;
pub mod iri;
pub mod uri;
mod uri_iri;

#[cfg(feature = "url")]
mod url;

#[cfg(feature = "std")]
pub(crate) mod utils;

pub use common::*;

pub use iri::{InvalidIri, Iri, IriError, IriRef};
pub use uri::{InvalidUri, Uri, UriError, UriRef};

#[cfg(feature = "std")]
pub use iri::{IriBuf, IriRefBuf};

#[cfg(feature = "std")]
pub use uri::{UriBuf, UriRefBuf};