Struct iri_string::build::Builder

pub struct Builder<'a> { /* private fields */ }

URI/IRI reference builder.

Usage

1. Create builder by Builder::new().
2. Set (or unset) components and set normalization mode as you wish.
3. Validate by Builder::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::build::Builder;
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>()?;

// 4a. Serialize by `Display` trait (or `ToString`).
let s = built.to_string();
assert_eq!(s, "http://example.com/");

// 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/");

Implementations

impl<'a> Builder<'a>

pub fn new() -> Self

Creates a builder with empty data.

Examples

use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let builder = Builder::new();

let iri = builder.build::<IriReferenceStr>()?;
assert_eq!(iri.to_string(), "");

pub fn build<T>(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::build::Builder;
use iri_string::types::IriStr;
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>()?;

// 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.

impl<'a> Builder<'a>

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

Sets the scheme.

Examples

use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

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

let iri = builder.build::<IriReferenceStr>()?;
assert_eq!(iri.to_string(), "foo:");

pub fn unset_scheme(&mut self)

Unsets the scheme.

Examples

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>()?;
assert_eq!(iri.to_string(), "");

pub fn path(&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::build::Builder;
use iri_string::types::IriReferenceStr;

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

let iri = builder.build::<IriReferenceStr>()?;
assert_eq!(iri.to_string(), "foo/bar");

pub fn unset_authority(&mut self)

Unsets the authority.

Examples

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>()?;
assert_eq!(iri.to_string(), "");

pub fn userinfo<T: Into<UserinfoBuilder<'a>>>(&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::build::Builder;
use iri_string::types::IriReferenceStr;

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

let iri = builder.build::<IriReferenceStr>()?;
assert_eq!(iri.to_string(), "//user:pass@");

You can specify (user, password) pair.

use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

let mut builder = Builder::new();

builder.userinfo(("user", Some("pass")));
assert_eq!(
    builder.clone().build::<IriReferenceStr>()?.to_string(),
    "//user:pass@"
);

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

use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

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

let iri = builder.build::<IriReferenceStr>()?;
assert_eq!(iri.to_string(), "//@");

pub fn unset_userinfo(&mut self)

Unsets the port.

Examples

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>()?;
assert_eq!(iri.to_string(), "//");

pub fn host(&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 method.

Examples

use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

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

let iri = builder.build::<IriReferenceStr>()?;
assert_eq!(iri.to_string(), "//example.com");

pub fn ip_address<T: Into<IpAddr>>(&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 method.

Examples

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>()?;
assert_eq!(iri.to_string(), "//192.0.2.0");

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

Sets the port.

Examples

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>()?;
assert_eq!(iri.to_string(), "//:80");

pub fn unset_port(&mut self)

Unsets the port.

Examples

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>()?;
assert_eq!(iri.to_string(), "//");

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

Sets the query.

The string after ? should be specified.

Examples

use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

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

let iri = builder.build::<IriReferenceStr>()?;
assert_eq!(iri.to_string(), "?q=example");

pub fn unset_query(&mut self)

Unsets the query.

Examples

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>()?;
assert_eq!(iri.to_string(), "");

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

Sets the fragment.

The string after # should be specified.

Examples

use iri_string::build::Builder;
use iri_string::types::IriReferenceStr;

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

let iri = builder.build::<IriReferenceStr>()?;
assert_eq!(iri.to_string(), "#anchor");

pub fn unset_fragment(&mut self)

Unsets the fragment.

Examples

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>()?;
assert_eq!(iri.to_string(), "");

pub fn unset_normalize(&mut self)

Stop normalizing the result.

Examples

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>()?;
assert_eq!(
    iri.to_string(),
    "http://%75%73%65%72@EXAMPLE.COM:/foo/../%2e%2e/bar/%2e/baz/."
);

pub fn normalize(&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::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>()?;
assert_eq!(iri.to_string(), "http://user@example.com/bar/baz/");

Trait Implementations

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

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

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

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

fn default() -> Builder<'a>

Returns the “default value” for a type.