Struct fluent_uri::Builder

pub struct Builder<S> { /* private fields */ }

A builder for URI reference.

This struct is created by UriRef::builder.

Examples

Basic usage:

use fluent_uri::{component::Scheme, encoding::EStr, UriRef};

const SCHEME_FOO: &Scheme = Scheme::new_or_panic("foo");

let uri_ref = UriRef::builder()
    .scheme(SCHEME_FOO)
    .authority_with(|b| {
        b.userinfo(EStr::new_or_panic("user"))
            .host(EStr::new_or_panic("example.com"))
            .port(8042)
    })
    .path(EStr::new_or_panic("/over/there"))
    .query(EStr::new_or_panic("name=ferret"))
    .fragment(EStr::new_or_panic("nose"))
    .build()
    .unwrap();

assert_eq!(
    uri_ref.as_str(),
    "foo://user@example.com:8042/over/there?name=ferret#nose"
);

Note that EStr::new_or_panic panics on invalid input and should normally be used with constant strings. If you want to build a percent-encoded string from scratch, use EString instead.

Constraints

Typestates are used to avoid misconfigurations, which puts the following constraints:

• Components must be set from left to right, no repetition allowed.
• Setting path is mandatory before calling build.
• Methods userinfo, host, and port are only available within a call to authority_with.
• Setting host is mandatory within a call to authority_with.

You may otherwise skip setting optional components (scheme, authority, userinfo, port, query, and fragment) with advance or set them optionally with optional.

The builder typestates are currently private. Please open an issue if it is a problem not being able to name the type of a builder.

Implementations

impl<S> Builder<S>

pub fn advance<T>(self) -> Builder<T>

where S: To<T>, T: AdvanceDst,

Advances the builder state, skipping optional components in between.

Variable rebinding may be necessary as this changes the type of the builder.

use fluent_uri::{component::Scheme, encoding::EStr, UriRef};

fn build(relative: bool) -> UriRef<String> {
    let b = UriRef::builder();
    let b = if relative {
        b.advance()
    } else {
        b.scheme(Scheme::new_or_panic("http"))
            .authority_with(|b| b.host(EStr::new_or_panic("example.com")))
    };
    b.path(EStr::new_or_panic("/foo")).build().unwrap()
}

assert_eq!(build(false).as_str(), "http://example.com/foo");
assert_eq!(build(true).as_str(), "/foo");

pub fn optional<F, V, T>(self, f: F, opt: Option<V>) -> Builder<T>

where F: FnOnce(Builder<S>, V) -> Builder<T>, S: To<T>, T: AdvanceDst,

Optionally calls a builder method with a value.

use fluent_uri::{encoding::EStr, Builder, UriRef};

let uri_ref = UriRef::builder()
    .path(EStr::new_or_panic("foo"))
    .optional(Builder::query, Some(EStr::new_or_panic("bar")))
    .optional(Builder::fragment, None)
    .build()
    .unwrap();

assert_eq!(uri_ref.as_str(), "foo?bar");

impl<S: To<SchemeEnd>> Builder<S>

pub fn scheme(self, scheme: &Scheme) -> Builder<SchemeEnd>

Sets the scheme component.

Note that the scheme component is case-insensitive and its canonical form is lowercase. For consistency, you should only produce lowercase scheme names.

impl<S: To<AuthorityStart>> Builder<S>

pub fn authority_with<F, T>(self, f: F) -> Builder<AuthorityEnd>

where F: FnOnce(Builder<AuthorityStart>) -> Builder<T>, T: To<AuthorityEnd>,

Builds the authority component with the given function.

pub fn authority(self, authority: Authority<'_>) -> Builder<AuthorityEnd>

Sets the authority component.

This method is normally used with an authority which is empty (Authority::EMPTY) or is obtained from a UriRef. If you need to build an authority from its subcomponents (userinfo, host, and port), use authority_with instead.

Examples

use fluent_uri::{
    component::{Authority, Scheme},
    encoding::EStr,
    Builder, UriRef,
};

let uri_ref = UriRef::builder()
    .scheme(Scheme::new_or_panic("file"))
    .authority(Authority::EMPTY)
    .path(EStr::new_or_panic("/path/to/file"))
    .build()
    .unwrap();

assert_eq!(uri_ref, "file:///path/to/file");

let auth = UriRef::parse("foo://user@example.com:8042")?
    .authority()
    .unwrap();
let uri_ref = UriRef::builder()
    .scheme(Scheme::new_or_panic("http"))
    .authority(auth)
    .path(EStr::EMPTY)
    .build()
    .unwrap();

assert_eq!(uri_ref, "http://user@example.com:8042");

impl<S: To<UserinfoEnd>> Builder<S>

pub fn userinfo(self, userinfo: &EStr<Userinfo>) -> Builder<UserinfoEnd>

Sets the userinfo subcomponent of authority.

impl<S: To<HostEnd>> Builder<S>

pub fn host<'a>(self, host: impl AsHost<'a>) -> Builder<HostEnd>

Sets the host subcomponent of authority.

This method takes either an Ipv4Addr, Ipv6Addr, IpAddr, or &EStr<RegName> as argument.

If the contents of an input &EStr<RegName> matches the IPv4address ABNF rule defined in Section 3.2.2 of RFC 3986, the resulting UriRef will output a Host::Ipv4 variant instead.

Note that the host subcomponent is case-insensitive. For consistency, you should only produce normalized hosts.

Examples

use fluent_uri::{component::Host, encoding::EStr, UriRef};

let uri_ref = UriRef::builder()
    .authority_with(|b| b.host(EStr::new_or_panic("127.0.0.1")))
    .path(EStr::EMPTY)
    .build()
    .unwrap();

assert!(matches!(uri_ref.authority().unwrap().host_parsed(), Host::Ipv4(_)));

impl<S: To<PortEnd>> Builder<S>

pub fn port(self, port: impl AsPort) -> Builder<PortEnd>

Sets the port subcomponent of authority.

This method takes either a u16 or &EStr<Port> as argument.

For consistency, you should not produce an empty port.

impl<S: To<PathEnd>> Builder<S>

pub fn path(self, path: &EStr<Path>) -> Builder<PathEnd>

Sets the path component.

impl<S: To<QueryEnd>> Builder<S>

pub fn query(self, query: &EStr<Query>) -> Builder<QueryEnd>

Sets the query component.

impl<S: To<FragmentEnd>> Builder<S>

pub fn fragment(self, fragment: &EStr<Fragment>) -> Builder<FragmentEnd>

Sets the fragment component.

impl<S: To<End>> Builder<S>

pub fn build(self) -> Result<UriRef<String>, BuildError>

Builds the URI reference.

Errors

Returns Err if any of the following conditions is not met.

• When authority is present, the path must either be empty or start with '/'.
• When authority is not present, the path cannot start with "//".
• In a relative-path reference, the first path segment cannot contain ':'.