BaseUrl

base_url is a thin wrapper around rust-url, which itself implements the URL Standard. The goal of base_url is to implement a strict subset of that standard to remove redundant error checks related to the base-suitability of a given URL.

What is a BaseUrl

A BaseUrl can be converted from any Url which can refer to a remote resource. In practical terms, if you found it on the Internet it will probably work and if you're referring to a resource 'somewhere else' it will probably work, mailto: being a notable exception.

Internally any Url which returns false on a .cannot_be_a_base() call and true on a .has_authority() call will convert. That means setting things like credentials and port numbers cannot fail and likewise setting the path relative to the host cannot fail.

Acquiring a BaseUrl object

A BaseUrl object may be acquired by either converting a Url or &str using TryFrom. If a &str cannot be parsed into a Url object a BaseUrlError::ParseError will be returned which wraps the underlying ParseError type implemented by rust-url.

use base_url::{ BaseUrl, BaseUrlError, Url, ParseError, TryFrom };

assert!( BaseUrl::try_from( "http://[:::1]" ) == Err( BaseUrlError::ParseError( ParseError::InvalidIpv6Address ) ) );

That's a bit unwieldly, so it's suggested that you prefer first parsing the &str into a Url and converting that object into a BaseUrl, allowing you to deal with errors related to parsing separately from errors related to base suitability.

use base_url::{ BaseUrl, BaseUrlError, Url, TryFrom };

let url:Url = Url::parse( "data:text/plain,Hello?World#" )?;
assert!( BaseUrl::try_from( url ) == Err( BaseUrlError::CannotBeBase ) );

let url:Url = Url::parse( "https://example.org/" )?;
let baseurl = BaseUrl::from( url )?;
assert!( baseurl.as_str( ), "https://example.org/ " );

Once we have a BaseUrl we can do (almost) anything we could with a normal Url and with fewer functions admitting potential failures and fewer calls to .unwrap().

If you do need to use some call which can remove the host or otherwise cause the Url to lose base suitability the wrapped Url can be acquired using .from().

Usage

In any Rust project managed by Cargo add the following to your Cargo.toml [dependencies] section:

base_url="^1.0.0"