Struct Builder

struct Builder<'a> { ... }

URI/IRI reference builder.

Usage

  1. Create builder by [Builder::new()]Self::new.
  2. Set (or unset) components and set normalization mode as you wish.
  3. Validate by [Builder::build()]Self::build and get Built value.
  4. Use core::fmt::Display trait to serialize the resulting Built, or use From/Into traits to convert into an allocated string types.
# use iri_string::validate::Error;
use iri_string::build::Builder;
# #[cfg(not(feature = "alloc"))]
# use iri_string::types::IriStr;
# #[cfg(feature = "alloc")]
use iri_string::types::{IriStr, IriString};

// 1. Create builder.
let mut builder = Builder::new();

// 2. Set (or unset) component and normalization mode.
builder.scheme("http");
builder.host("example.com");
builder.path("/foo/../");
builder.normalize();

// 3. Validate and create the result.
let built = builder.build::<IriStr>()?;

# #[cfg(feature = "alloc")] {
// 4a. Serialize by `Display` trait (or `ToString`).
let s = built.to_string();
assert_eq!(s, "http://example.com/");
# }

# #[cfg(feature = "alloc")] {
// 4b. Convert into an allocated string types.
// Thanks to pre-validation by `.build::<IriStr>()`, this conversion is infallible!
let s: IriString = built.into();
assert_eq!(s, "http://example.com/");
# }

# Ok::<_, Error>(())

Implementations

impl<'a> Builder<'a>

fn new() -> Self

Creates a builder with empty data.

Examples

# use iri_string::validate::Error;
use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let builder = Builder::new();

let iri = builder.build::<IriReferenceStr>()?;
# #[cfg(feature = "alloc")] {
assert_eq!(iri.to_string(), "");
# }
# Ok::<_, Error>(())

fn build<T>(self: Self) -> Result<Built<'a, T>, Error>
where
    T: ?Sized + Buildable<'a>

Builds the proxy object that can be converted to the desired IRI string type.

Examples

# use iri_string::validate::Error;
use iri_string::build::Builder;
use iri_string::types::IriStr;
# #[cfg(feature = "alloc")]
use iri_string::types::IriString;

let mut builder = Builder::new();

builder.scheme("http");
builder.host("example.com");
builder.path("/foo/bar");

let built = builder.build::<IriStr>()?;

# #[cfg(feature = "alloc")] {
// The returned value implements `core::fmt::Display` and
// `core::string::ToString`.
assert_eq!(built.to_string(), "http://example.com/foo/bar");

// The returned value implements `Into<{iri_owned_string_type}>`.
let iri = IriString::from(built);
// `let iri: IriString = built.into();` is also OK.
# }
# Ok::<_, Error>(())

impl<'a> Builder<'a>

fn scheme(self: &mut Self, v: &'a str)

Sets the scheme.

Examples

# use iri_string::validate::Error;
use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let mut builder = Builder::new();
builder.scheme("foo");

let iri = builder.build::<IriReferenceStr>()?;
# #[cfg(feature = "alloc")] {
assert_eq!(iri.to_string(), "foo:");
# }
# Ok::<_, Error>(())

fn unset_scheme(self: &mut Self)

Unsets the scheme.

Examples

# use iri_string::validate::Error;
use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let mut builder = Builder::new();
builder.scheme("foo");
builder.unset_scheme();

let iri = builder.build::<IriReferenceStr>()?;
# #[cfg(feature = "alloc")] {
assert_eq!(iri.to_string(), "");
# }
# Ok::<_, Error>(())

fn path(self: &mut Self, v: &'a str)

Sets the path.

Note that no methods are provided to "unset" path since every IRI references has a path component (although it can be empty). If you want to "unset" the path, just set the empty string.

Examples

# use iri_string::validate::Error;
use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let mut builder = Builder::new();
builder.path("foo/bar");

let iri = builder.build::<IriReferenceStr>()?;
# #[cfg(feature = "alloc")] {
assert_eq!(iri.to_string(), "foo/bar");
# }
# Ok::<_, Error>(())

fn unset_authority(self: &mut Self)

Unsets the authority.

Examples

# use iri_string::validate::Error;
use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let mut builder = Builder::new();
builder.host("example.com");
builder.unset_authority();

let iri = builder.build::<IriReferenceStr>()?;
# #[cfg(feature = "alloc")] {
assert_eq!(iri.to_string(), "");
# }
# Ok::<_, Error>(())

fn userinfo<T: Into<UserinfoBuilder<'a>>>(self: &mut Self, v: T)

Sets the userinfo.

userinfo component always have user part (but it can be empty).

Note that ("", None) is considered as an empty userinfo, rather than unset userinfo. Also note that the user part cannot have colon characters.

Examples

# use iri_string::validate::Error;
use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let mut builder = Builder::new();
builder.userinfo("user:pass");

let iri = builder.build::<IriReferenceStr>()?;
# #[cfg(feature = "alloc")] {
assert_eq!(iri.to_string(), "//user:pass@");
# }
# Ok::<_, Error>(())

You can specify (user, password) pair.

# use iri_string::validate::Error;
use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let mut builder = Builder::new();

builder.userinfo(("user", Some("pass")));
# #[cfg(feature = "alloc")] {
assert_eq!(
    builder.clone().build::<IriReferenceStr>()?.to_string(),
    "//user:pass@"
);
# }
# Ok::<_, Error>(())

("", None) is considered as an empty userinfo.

# use iri_string::validate::Error;
use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let mut builder = Builder::new();
builder.userinfo(("", None));

let iri = builder.build::<IriReferenceStr>()?;
# #[cfg(feature = "alloc")] {
assert_eq!(iri.to_string(), "//@");
# }
# Ok::<_, Error>(())

fn unset_userinfo(self: &mut Self)

Unsets the port.

Examples

# use iri_string::validate::Error;
use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let mut builder = Builder::new();
builder.userinfo("user:pass");
// Note that this does not unset the entire authority.
// Now empty authority is set.
builder.unset_userinfo();

let iri = builder.build::<IriReferenceStr>()?;
# #[cfg(feature = "alloc")] {
assert_eq!(iri.to_string(), "//");
# }
# Ok::<_, Error>(())

fn host(self: &mut Self, v: &'a str)

Sets the reg-name or IP address (i.e. host) without port.

Note that no methods are provided to "unset" host. Depending on your situation, set empty string as a reg-name, or unset the authority entirely by [unset_authority]Self::unset_authority method.

Examples

# use iri_string::validate::Error;
use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let mut builder = Builder::new();
builder.host("example.com");

let iri = builder.build::<IriReferenceStr>()?;
# #[cfg(feature = "alloc")] {
assert_eq!(iri.to_string(), "//example.com");
# }
# Ok::<_, Error>(())

fn ip_address<T: Into<std::net::IpAddr>>(self: &mut Self, addr: T)

Sets the IP address as a host.

Note that no methods are provided to "unset" host. Depending on your situation, set empty string as a reg-name, or unset the authority entirely by [unset_authority]Self::unset_authority method.

Examples

# use iri_string::validate::Error;
# #[cfg(feature = "std")] {
use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let mut builder = Builder::new();
builder.ip_address(std::net::Ipv4Addr::new(192, 0, 2, 0));

let iri = builder.build::<IriReferenceStr>()?;
# #[cfg(feature = "alloc")] {
assert_eq!(iri.to_string(), "//192.0.2.0");
# }
# }
# Ok::<_, Error>(())

fn port<T: Into<PortBuilder<'a>>>(self: &mut Self, v: T)

Sets the port.

Examples

# use iri_string::validate::Error;
use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let mut builder = Builder::new();
builder.port(80_u16);
// Accepts other types that implements `Into<PortBuilder<'a>>`.
//builder.port(80_u8);
//builder.port("80");

let iri = builder.build::<IriReferenceStr>()?;
# #[cfg(feature = "alloc")] {
assert_eq!(iri.to_string(), "//:80");
# }
# Ok::<_, Error>(())

fn unset_port(self: &mut Self)

Unsets the port.

Examples

# use iri_string::validate::Error;
use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let mut builder = Builder::new();
builder.port(80_u16);
// Note that this does not unset the entire authority.
// Now empty authority is set.
builder.unset_port();

let iri = builder.build::<IriReferenceStr>()?;
# #[cfg(feature = "alloc")] {
assert_eq!(iri.to_string(), "//");
# }
# Ok::<_, Error>(())

fn query(self: &mut Self, v: &'a str)

Sets the query.

The string after ? should be specified.

Examples

# use iri_string::validate::Error;
use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let mut builder = Builder::new();
builder.query("q=example");

let iri = builder.build::<IriReferenceStr>()?;
# #[cfg(feature = "alloc")] {
assert_eq!(iri.to_string(), "?q=example");
# }
# Ok::<_, Error>(())

fn unset_query(self: &mut Self)

Unsets the query.

Examples

# use iri_string::validate::Error;
use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let mut builder = Builder::new();
builder.query("q=example");
builder.unset_query();

let iri = builder.build::<IriReferenceStr>()?;
# #[cfg(feature = "alloc")] {
assert_eq!(iri.to_string(), "");
# }
# Ok::<_, Error>(())

fn fragment(self: &mut Self, v: &'a str)

Sets the fragment.

The string after # should be specified.

Examples

# use iri_string::validate::Error;
use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let mut builder = Builder::new();
builder.fragment("anchor");

let iri = builder.build::<IriReferenceStr>()?;
# #[cfg(feature = "alloc")] {
assert_eq!(iri.to_string(), "#anchor");
# }
# Ok::<_, Error>(())

fn unset_fragment(self: &mut Self)

Unsets the fragment.

Examples

# use iri_string::validate::Error;
use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let mut builder = Builder::new();
builder.fragment("anchor");
builder.unset_fragment();

let iri = builder.build::<IriReferenceStr>()?;
# #[cfg(feature = "alloc")] {
assert_eq!(iri.to_string(), "");
# }
# Ok::<_, Error>(())

fn unset_normalize(self: &mut Self)

Stop normalizing the result.

Examples

# use iri_string::validate::Error;
use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let mut builder = Builder::new();
builder.scheme("http");
// `%75%73%65%72` is "user".
builder.userinfo("%75%73%65%72");
builder.host("EXAMPLE.COM");
builder.port("");
builder.path("/foo/../%2e%2e/bar/%2e/baz/.");

builder.unset_normalize();

let iri = builder.build::<IriReferenceStr>()?;
# #[cfg(feature = "alloc")] {
assert_eq!(
    iri.to_string(),
    "http://%75%73%65%72@EXAMPLE.COM:/foo/../%2e%2e/bar/%2e/baz/."
);
# }
# Ok::<_, Error>(())

fn normalize(self: &mut Self)

Normalizes the result using RFC 3986 syntax-based normalization and WHATWG URL Standard algorithm.

Normalization

If scheme or authority component is present or the path is absolute, the build result will fully normalized using full syntax-based normalization:

  • case normalization ([RFC 3986 6.2.2.1]),
  • percent-encoding normalization ([RFC 3986 6.2.2.2]), and
  • path segment normalization ([RFC 3986 6.2.2.2]).

However, if both scheme and authority is absent and the path is relative (including empty), i.e. the IRI reference to be built starts with the relative path component, path segment normalization will be omitted. This is because the path segment normalization depends on presence or absense of the authority components, and will remove extra .. segments which should not be ignored.

Note that path must already be empty or start with a slash before the normalizaiton if authority is present.

WHATWG URL Standard

If you need to avoid WHATWG URL Standard serialization, use Built::ensure_rfc3986_normalizable method to test if the result is normalizable without WHATWG spec.

Examples

# use iri_string::validate::Error;
use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let mut builder = Builder::new();
builder.scheme("http");
// `%75%73%65%72` is "user".
builder.userinfo("%75%73%65%72");
builder.host("EXAMPLE.COM");
builder.port("");
builder.path("/foo/../%2e%2e/bar/%2e/baz/.");

builder.normalize();

let iri = builder.build::<IriReferenceStr>()?;
# #[cfg(feature = "alloc")] {
assert_eq!(iri.to_string(), "http://user@example.com/bar/baz/");
# }
# Ok::<_, Error>(())

impl<'a> Clone for Builder<'a>

fn clone(self: &Self) -> Builder<'a>

impl<'a> Debug for Builder<'a>

fn fmt(self: &Self, f: &mut Formatter<'_>) -> Result

impl<'a> Default for Builder<'a>

fn default() -> Builder<'a>

impl<'a> Freeze for Builder<'a>

impl<'a> RefUnwindSafe for Builder<'a>

impl<'a> Send for Builder<'a>

impl<'a> Sync for Builder<'a>

impl<'a> Unpin for Builder<'a>

impl<'a> UnsafeUnpin for Builder<'a>

impl<'a> UnwindSafe for Builder<'a>

impl<T> Any for Builder<'a>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for Builder<'a>

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for Builder<'a>

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> CloneToUninit for Builder<'a>

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> From for Builder<'a>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for Builder<'a>

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

impl<T, U> Into for Builder<'a>

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for Builder<'a>

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for Builder<'a>

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>