fluent_uri/
lib.rs

1#![warn(
2    future_incompatible,
3    missing_debug_implementations,
4    missing_docs,
5    nonstandard_style,
6    rust_2018_idioms,
7    clippy::checked_conversions,
8    clippy::if_not_else,
9    clippy::ignored_unit_patterns,
10    clippy::map_unwrap_or,
11    clippy::missing_errors_doc,
12    clippy::must_use_candidate,
13    // clippy::redundant_closure_for_method_calls,
14    clippy::redundant_else,
15    clippy::semicolon_if_nothing_returned,
16    // clippy::single_match_else,
17    clippy::use_self,
18)]
19#![forbid(unsafe_code)]
20#![cfg_attr(docsrs, feature(doc_cfg))]
21#![no_std]
22
23//! A generic URI/IRI handling library compliant with [RFC 3986] and [RFC 3987].
24//!
25//! [RFC 3986]: https://datatracker.ietf.org/doc/html/rfc3986
26//! [RFC 3987]: https://datatracker.ietf.org/doc/html/rfc3987
27//!
28//! **Examples:** [Parsing](Uri#examples). [Building](build::Builder#examples).
29//! [Reference resolution](UriRef::resolve_against). [Normalization](Uri::normalize).
30//! [Percent-decoding](crate::pct_enc::EStr#examples).
31//! [Percent-encoding](crate::pct_enc::EString#examples).
32//!
33//! # Terminology
34//!
35//! A *[URI reference]* is either a *[URI]* or a *[relative reference]*. If it starts with a *[scheme]*
36//! (like `http`, `ftp`, `mailto`, etc.) followed by a colon (`:`), it is a URI. For example,
37//! `http://example.com/` and `mailto:user@example.com` are URIs. Otherwise, it is
38//! a relative reference. For example, `//example.org/`, `/index.html`, `../`, `foo`,
39//! `?bar`, and `#baz` are relative references.
40//!
41//! An *[IRI]* (reference) is an internationalized version of URI (reference)
42//! which may contain non-ASCII characters.
43//!
44//! [URI]: https://datatracker.ietf.org/doc/html/rfc3986#section-3
45//! [URI reference]: https://datatracker.ietf.org/doc/html/rfc3986#section-4.1
46//! [IRI]: https://datatracker.ietf.org/doc/html/rfc3987#section-2
47//! [relative reference]: https://datatracker.ietf.org/doc/html/rfc3986#section-4.2
48//! [scheme]: https://datatracker.ietf.org/doc/html/rfc3986#section-3.1
49//!
50//! # Guidance for crate users
51//!
52//! Advice for designers of new URI schemes can be found in [RFC 7595].
53//! Guidance on the specification of URI substructure in standards
54//! can be found in [RFC 8820]. The crate author recommends [RFC 9413]
55//! for further reading as the long-term interoperability
56//! of URI schemes may be of concern.
57//!
58//! [RFC 7595]: https://datatracker.ietf.org/doc/html/rfc7595
59//! [RFC 8820]: https://datatracker.ietf.org/doc/html/rfc8820
60//! [RFC 9413]: https://datatracker.ietf.org/doc/html/rfc9413
61//!
62//! # Crate features
63//!
64//! - `std` (default): Implies `alloc` and `impl-error`. Required for [`Authority::socket_addrs`].
65//!
66//! - `alloc`: Required for memory-allocating types and functions.
67//!
68//! - `impl-error`: Required for [`Error`] implementations. Disabling `std`
69//!   while enabling `impl-error` requires a minimum Rust version of 1.81.
70//!
71//! - `net`: Required for IP address fields in [`Host`], for [`Builder::host`] to
72//!   take an IP address as argument, and for [`Authority::socket_addrs`].
73//!   Disabling `std` while enabling `net` requires a minimum Rust version of 1.77.
74//!
75//! - `serde`: Required for [`Serialize`] and [`Deserialize`] implementations.
76//!
77//! [`Host`]: component::Host
78//! [`Builder::host`]: build::Builder::host
79//! [`Authority::socket_addrs`]: component::Authority::socket_addrs
80//! [`Error`]: core::error::Error
81//! [`Serialize`]: serde::Serialize
82//! [`Deserialize`]: serde::Deserialize
83
84#[cfg(feature = "alloc")]
85pub mod build;
86pub mod component;
87mod convert;
88mod fmt;
89mod imp;
90#[cfg(feature = "alloc")]
91pub mod normalize;
92mod parse;
93pub mod pct_enc;
94#[cfg(feature = "alloc")]
95pub mod resolve;
96mod utf8;
97
98pub use convert::ConvertError;
99pub use imp::{Iri, IriRef, Uri, UriRef};
100pub use parse::{ParseError, ParseErrorKind};
101
102#[cfg(feature = "std")]
103extern crate std;
104
105#[cfg(feature = "alloc")]
106extern crate alloc;
107
108#[cfg(all(feature = "net", not(feature = "std")))]
109use core::net;
110#[cfg(all(feature = "net", feature = "std"))]
111use std::net;
112
113#[cfg(all(feature = "impl-error", not(feature = "std")))]
114use core::error::Error;
115#[cfg(all(feature = "impl-error", feature = "std"))]
116use std::error::Error;
fluent_uri/lib.rs

fluent_uri/
lib.rs
