Struct base_url::BaseUrl

pub struct BaseUrl { /* fields omitted */ }

Any Url which has a host and so can be supplied as a base url

Methods

impl BaseUrl

pub fn as_str(&self) -> &str

Return the serialization of this BaseUrl

This is fast, since internally the Url stores the serialization already

Examples

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

let url_str = "https://example.org/";
let host = BaseUrl::try_from( url_str )?;

assert_eq!( host.as_str( ), url_str );

pub fn into_string(self) -> String

Return the serialization of this BaseUrl

This consumes the BaseUrl and takes ownership of the String

Examples

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

let url_str = "https://example.org/";
let host = BaseUrl::try_from( url_str )?;

assert_eq!( host.into_string( ), url_str );

pub fn origin(&self) -> OriginTuple

Returns the BaseUrl's scheme, host and port as a tuple

Examples

use base_url::{ BaseUrl, OriginTuple, Host, TryFrom };

let url = BaseUrl::try_from( "ftp://example.org/foo" )?;

assert_eq!( url.origin( ),
            ( "ftp".into( ),
              Host::Domain( "example.org".into( ) ),
              21 ) );

pub fn scheme(&self) -> &str

Returns the scheme of the given BaseUrl, lower-cased, as an ASCII string without the ':' delimiter

Examples

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

let url = BaseUrl::try_from( "https://example.org" )?;

assert_eq!( url.scheme( ), "https" );

pub fn strip(&mut self)

Strip out any present username, password, query and fragment information from this BaseUrl

Examples

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

let mut url = BaseUrl::try_from( "http://brady:hunter3@example.org/foo?query=1#fragment=2" )?;

url.strip( );
assert_eq!( url.as_str( ), "http://example.org/foo" );

pub fn make_host_only(&mut self)

Strips a BaseUrl down to only the host and scheme.

Examples

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

let mut url = BaseUrl::try_from( "http://brady:hunter3@example.org:8080/foo?query=1#fragment=2" )?;

url.make_host_only( );
assert_eq!( url.as_str( ), "http://example.org/" );

pub fn set_scheme(&mut self, scheme: &str) -> Result<(), ()>

Set the BaseUrl's scheme

Does nothing and returns Err() if the specified scheme does not match the regular expression [a-zA-Z][a-zA-Z0-9+.-]+

Examples

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

let mut url = BaseUrl::try_from( "http://example.org/" )?;

url.set_scheme( "https" );
assert_eq!( url.as_str( ), "https://example.org/" );

pub fn username(&self) -> &str

Return the username for this BaseUrl. If no username is set an empty string is returned

Examples

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

let url = BaseUrl::try_from( "https://brady@example.org/foo" )?;

assert_eq!( url.username( ), "brady" );

pub fn set_username(&mut self, username: &str)

Change the username of this BaseUrl.

Examples

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

let mut url = BaseUrl::try_from( "http://example.org/" )?;

url.set_username( "brady" );
assert_eq!( url.as_str( ), "http://brady@example.org/" );

pub fn password(&self) -> Option<&str>

Optionally returns the password associated with this BaseUrl as a percent-encoded ASCII string.

Examples

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

let url = BaseUrl::try_from( "https://brady:hunter3@example.org/" )?;
assert_eq!( url.password( ), Some( "hunter3" ) );

let url = BaseUrl::try_from( "https://brady@example.org" )?;
assert_eq!( url.password( ), None );

pub fn set_password(&mut self, password: Option<&str>)

Change the password of this BaseUrl. Use None to remove the password field.

Examples

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

let mut url = BaseUrl::try_from( "http://brady@example.org/" )?;

url.set_password( Some( "hunter3" ) );
assert_eq!( url.as_str( ), "http://brady:hunter3@example.org/" );

url.set_password( None );
assert_eq!( url.password( ), None );

pub fn host_str(&self) -> &str

Returns the domain or IP address for this BaseUrl as a string.

See also the host() method

Examples

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

let url = BaseUrl::try_from( "http://brady@example.org/foo" )?;
assert_eq!( url.host_str( ), "example.org" );

pub fn host(&self) -> Host<&str>

Returns the host for this BaseUrl in an enumerated type.

Examples

use base_url::{ BaseUrl, BaseUrlError, TryFrom, Host };
use std::net::Ipv4Addr;

let url = BaseUrl::try_from( "http://example.org/" )?;
assert_eq!( url.host( ), Host::Domain( "example.org" ) );

let ip = BaseUrl::try_from( "http://127.0.0.1/index.html" )?;
assert_eq!( ip.host( ), Host::Ipv4( Ipv4Addr::new( 127, 0, 0, 1 ) ) );

pub fn set_host(&mut self, host: &str) -> Result<(), ParseError>

Changes the host for this BaseUrl. If there is any error parsing the provided string no action is taken and Err() is returned. Host cannot be removed as in the rust-url crate as without a host a url cannot be a base.

Examples

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

let mut url = BaseUrl::try_from( "http://example.org/" )?;

assert!( url.set_host( "rust-lang.org" ).is_ok( ) );
assert_eq!( url.as_str( ), "http://rust-lang.org/" );

Errors

If the provided host string cannot be parsed a ParseError variant is returned.

pub fn set_ip_host(&mut self, address: IpAddr)

Change this BaseUrl's host to the given Ip address.

Compared to calling set_host( ), which can also work with ip address strings this method saves a call to the parser.

Examples

use base_url::{ BaseUrl, BaseUrlError, TryFrom };
use std::net::{ IpAddr, Ipv4Addr };

let mut url = BaseUrl::try_from( "https://example.org/" )?;

url.set_ip_host( IpAddr::V4( Ipv4Addr::new( 127, 0, 0, 1 ) ) );
assert_eq!( url.as_str( ), "https://127.0.0.1/" );

pub fn domain(&self) -> Option<&str>

Return's the domain string of this BaseUrl. Returns None if the host is an Ip address rather than a domain name.

Note the lack of trailing '/' in the example, that is the path component not the domain.

Examples

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

let ip = BaseUrl::try_from( "https://127.0.0.1" )?;
assert!( ip.domain( ).is_none( ) );

let url = BaseUrl::try_from( "https://www.example.org/" )?;
assert_eq!( url.domain( ), Some( "www.example.org" ) );

pub fn port(&self) -> Option<u16>

Optionally return's the port number of this BaseUrl. Note that whenever a known default port is included in a url that port is elided. If you require an API which returns port information including known default port information use port_or_known_default( )

Examples

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

let url = BaseUrl::try_from( "http://example.org/" )?;
assert!( url.port( ).is_none( ) );

let url = BaseUrl::try_from( "https://example.org:42/" )?;
assert_eq!( url.port( ), Some( 42 ) );

let url = BaseUrl::try_from( "https://example.org:443/" )?;
assert!( url.port( ).is_none( ) );

pub fn port_or_known_default(&self) -> Option<u16>

Return's the port number of this BaseUrl. If no port number is present a guess is made based on the scheme, if no guess can be made None is returned.

This method only knows the default port numbers for http, https, ws, wss, ftp and gopher.

Examples

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

let url = BaseUrl::try_from( "http://example.org/" )?;
assert_eq!( url.port_or_known_default( ), Some( 80 ) );

let url = BaseUrl::try_from( "ssh://example.org/" )?;
assert_eq!( url.port_or_known_default( ), None );

let url = BaseUrl::try_from( "foo://example.org:42" )?;
assert_eq!( url.port_or_known_default( ), Some( 42 ) );

pub fn set_port(&mut self, port: Option<u16>)

Change this BaseUrl's port. Note that default ports (as known by port_or_known_default( ) ) are not reflected in Url serializations.

Examples

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

let mut url = BaseUrl::try_from( "https://example.org" )?;

url.set_port( Some( 443 ) );
assert!( url.port( ).is_none( ) );

url.set_port( Some( 42 ) );
assert_eq!( url.port( ), Some(42 ) );

pub fn path(&self) -> &str

Return's the path of this BaseUrl, percent-encoded. Path strings will start with '/' and continue with '/' separated path segments.

Examples

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

let url = BaseUrl::try_from( "https://example.org/index.html" )?;
assert_eq!( url.path( ), "/index.html" );

let url = BaseUrl::try_from( "https://example.org" )?;
assert_eq!( url.path( ), "/" );

pub fn path_segments(&self) -> Split<char>

Return's an iterator through each of this BaseUrl's path segments. Path segments do not contain the separating '/' characters and may be empty, often on the last entry.

Examples

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

let url = BaseUrl::try_from( "https://example.org" )?;
let mut path_segments = url.path_segments( );
assert!( path_segments.next( ) == Some( "" ) );
assert!( path_segments.next( ) == None );

let url = BaseUrl::try_from( "https://example.org/foo/bar/index.html" )?;
let mut path_segments = url.path_segments( );
assert!( path_segments.next( ) == Some( "foo" ) );
assert!( path_segments.next( ) == Some( "bar" ) );
assert!( path_segments.next( ) == Some( "index.html" ) );
assert!( path_segments.next( ) == None );

pub fn set_path(&mut self, path: &str)

Change this BaseUrl's path overwriting any other path information.

Examples

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

let mut url = BaseUrl::try_from( "https://example.org/something/foo.html" )?;

url.set_path( "/foobar" );
assert_eq!( url.as_str( ), "https://example.org/foobar" );

pub fn path_segments_mut(&mut self) -> PathSegmentsMut

Returns an object with chainable methods to manipulate this BaseUrl's path segments.

Note that unlike url's ::parse( ) and join( ), path_segments_mut( ) percent encodes '/' and '%' characters.

Examples

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

let mut url = BaseUrl::try_from( "https://example.org/" )?;

url.path_segments_mut( ).push( "sitemaps" ).push( "sitemap_1.xml" );
assert_eq!( url.as_str( ), "https://example.org/sitemaps/sitemap_1.xml" );

url.path_segments_mut( ).clear( ).push( "foo/bar#fragment=no" );
assert_eq!( url.as_str( ), "https://example.org/foo%2Fbar%23fragment=no" );

pub fn query(&self) -> Option<&str>

Optionally return's this BaseUrl's percent-encoded query string.

Examples

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

let url = BaseUrl::try_from( "https://example.org/foo" )?;
assert_eq!( url.query( ), None );

let url = BaseUrl::try_from( "https://example.org/foo?page=2" )?;
assert_eq!( url.query( ), Some( "page=2" ) );

pub fn query_pairs(&self) -> Parse

Parse the BaseUrl's query string and return an iterator over all found (key, value) pairs.

Examples

use base_url::{ BaseUrl, BaseUrlError, TryFrom };
use std::borrow::Cow;

let url = BaseUrl::try_from( "https://example.org/foo?page=2&sort=newest" )?;
let mut queries = url.query_pairs( );

assert_eq!( queries.next( ), Some( ( Cow::Borrowed( "page" ), Cow::Borrowed( "2" ) ) ) );
assert_eq!( queries.next( ), Some( ( Cow::Borrowed( "sort" ), Cow::Borrowed( "newest" ) ) ) );
assert_eq!( queries.next( ), None );

pub fn set_query(&mut self, query: Option<&str>)

Change this BaseUrl's query string.

Examples

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

let mut url = BaseUrl::try_from( "https://example.org/foo" )?;

url.set_query( Some( "page=2" ) );
assert_eq!( url.as_str( ), "https://example.org/foo?page=2" );

url.set_query( None );
assert_eq!( url.as_str( ), "https://example.org/foo" );

pub fn query_pairs_mut(&mut self) -> Serializer<UrlQuery>

Returns an object with a method chaining API. These methods manipulate the query string of the BaseUrl as a sequence of (key, value) pairs.

Examples

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

let mut url = BaseUrl::try_from( "https://example.org/foo?page=2" )?;

url.query_pairs_mut( ).append_pair( "sort", "newest" );
assert_eq!( url.as_str( ), "https://example.org/foo?page=2&sort=newest");

url.query_pairs_mut( ).clear( ).append_pair( "bar","baz" );
assert_eq!( url.as_str( ), "https://example.org/foo?bar=baz");

pub fn fragment(&self) -> Option<&str>

Optionally returns this BaseUrl's fragment identifier.

Examples

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

let url = BaseUrl::try_from( "https://example.org/index.html#about" )?;
assert_eq!( url.fragment( ), Some( "about" ) );

pub fn set_fragment(&mut self, fragment: Option<&str>)

Change this BaseUrl's fragment identifier.

Examples

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

let mut url = BaseUrl::try_from( "https://example.org/foo?page=2" )?;

url.set_fragment( Some( "head2" ) );
assert_eq!( url.as_str( ), "https://example.org/foo?page=2#head2" );

Trait Implementations

impl From<BaseUrl> for Url

fn from(url: BaseUrl) -> Self

Performs the conversion.

impl PartialEq<BaseUrl> for BaseUrl

fn eq(&self, other: &BaseUrl) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &BaseUrl) -> bool

This method tests for !=.

impl Clone for BaseUrl

fn clone(&self) -> BaseUrl

Returns a copy of the value.

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

Performs copy-assignment from source.

impl PartialOrd<BaseUrl> for BaseUrl

fn partial_cmp(&self, other: &BaseUrl) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &BaseUrl) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &BaseUrl) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &BaseUrl) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &BaseUrl) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Eq for BaseUrl

impl Ord for BaseUrl

fn cmp(&self, other: &BaseUrl) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl Display for BaseUrl

fn fmt(&self, formatter: &mut Formatter) -> FormatResult

Formats the value using the given formatter.

impl Debug for BaseUrl

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

Formats the value using the given formatter.

impl TryFrom<Url> for BaseUrl

type Error = BaseUrlError

The type returned in the event of a conversion error.

fn try_from(url: Url) -> Result<Self, Self::Error>

Performs the conversion.

impl<'a> TryFrom<&'a str> for BaseUrl

type Error = BaseUrlError

The type returned in the event of a conversion error.

fn try_from(url: &'a str) -> Result<Self, Self::Error>

Performs the conversion.

impl Hash for BaseUrl

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].