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 DisplayBuild value.
4. Use core::fmt::Display trait to serialize the resulting DisplayBuild, 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_whatwg();

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

Note that (None, None) is considered as an empty userinfo, rather than unset userinfo.

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

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

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

(None, 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, 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);

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_rfc3986(&mut self)

Normalizes the result using RFC 3986 normalization algorithm.

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_rfc3986();

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

pub fn normalize_whatwg(&mut self)

Normalizes the result using WHATWG URL Standard algorithm.

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_whatwg();

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 Default for Builder<'_>

fn default() -> Self

Returns the “default value” for a type.