iri_string::build

Struct Builder

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

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§

source§

impl<'a> Builder<'a>

source

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

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.
source§

impl<'a> Builder<'a>

source

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:");
source

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

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

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

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(), "//@");
source

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

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

pub fn ip_address<T: Into<IpAddr>>(&mut self, addr: T)

Available on crate feature std only.

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

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

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

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

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

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

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

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

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§

source§

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

source§

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

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

source§

fn default() -> Builder<'a>

Returns the “default value” for a type. Read more

Auto Trait Implementations§

§

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> UnwindSafe for Builder<'a>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

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

source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

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

Performs the conversion.