Struct RelativeReference

Source

pub struct RelativeReference<'uri> { /* private fields */ }

Expand description

A relative reference as defined in [RFC3986, Section 4.1].

Specifically, a relative reference is a URI reference without a scheme.

Implementations§

Source §

impl<'uri> RelativeReference<'uri>

Source

pub fn as_uri_reference(&self) -> &URIReference<'uri>

Source

pub fn authority(&self) -> Option<&Authority<'uri>>

Returns the authority, if present, of the relative reference.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("//example.com/my/path").unwrap();
assert_eq!(reference.authority().unwrap().to_string(), "example.com");

Source

pub fn builder<'new_uri>() -> RelativeReferenceBuilder<'new_uri>

Constructs a default builder for a relative reference.

This provides an alternative means of constructing a relative reference besides parsing and RelativeReference::from_parts.

§Examples

use std::convert::TryFrom;

use uriparse::{Fragment, Path, RelativeReference};

let reference = RelativeReference::builder()
    .with_path(Path::try_from("/my/path").unwrap())
    .with_fragment(Some(Fragment::try_from("fragment").unwrap()))
    .build()
    .unwrap();
assert_eq!(reference.to_string(), "/my/path#fragment");

Source

pub fn from_parts<'new_uri, TAuthority, TPath, TQuery, TFragment, TAuthorityError, TPathError, TQueryError, TFragmentError>( authority: Option<TAuthority>, path: TPath, query: Option<TQuery>, fragment: Option<TFragment>, ) -> Result<RelativeReference<'new_uri>, RelativeReferenceError>
where Authority<'new_uri>: TryFrom<TAuthority, Error = TAuthorityError>, Path<'new_uri>: TryFrom<TPath, Error = TPathError>, Query<'new_uri>: TryFrom<TQuery, Error = TQueryError>, Fragment<'new_uri>: TryFrom<TFragment, Error = TFragmentError>, URIReferenceError: From<TAuthorityError> + From<TPathError> + From<TQueryError> + From<TFragmentError>,

Constructs a new RelativeReference from the individual parts: authority, path, query, and fragment.

The lifetime used by the resulting value will be the lifetime of the part that is most restricted in scope.

§Examples

use std::convert::TryFrom;

use uriparse::{Scheme, RelativeReference};

let reference = RelativeReference::from_parts(
    Some("example.com"),
    "/my/path",
    Some("query"),
    Some("fragment")
).unwrap();
assert_eq!(reference.to_string(), "//example.com/my/path?query#fragment");

Source

pub fn fragment(&self) -> Option<&Fragment<'uri>>

Returns the fragment, if present, of the relative reference.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("//example.com#fragment").unwrap();
assert_eq!(reference.fragment().unwrap(), "fragment");

Source

pub fn has_authority(&self) -> bool

Returns whether the relative reference has an authority component.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("//example.com").unwrap();
assert!(reference.has_authority());

let reference = RelativeReference::try_from("").unwrap();
assert!(!reference.has_authority());

Source

pub fn has_fragment(&self) -> bool

Returns whether the relative reference has a fragment component.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("#test").unwrap();
assert!(reference.has_fragment());

let reference = RelativeReference::try_from("/").unwrap();
assert!(!reference.has_fragment());

Source

pub fn has_password(&self) -> bool

Returns whether the relative reference has a password component.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("//user:pass@127.0.0.1").unwrap();
assert!(reference.has_password());

let reference = RelativeReference::try_from("//user@127.0.0.1").unwrap();
assert!(!reference.has_password());

Source

pub fn has_port(&self) -> bool

Returns whether the relative reference has a port.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("//127.0.0.1:8080").unwrap();
assert!(reference.has_port());

let reference = RelativeReference::try_from("//127.0.0.1").unwrap();
assert!(!reference.has_port());

Source

pub fn has_query(&self) -> bool

Returns whether the relative reference has a query component.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("/?my=query").unwrap();
assert!(reference.has_query());

let reference = RelativeReference::try_from("/my/path").unwrap();
assert!(!reference.has_query());

Source

pub fn has_username(&self) -> bool

Returns whether the relative reference has a username component.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("//username@example.com").unwrap();
assert!(reference.has_username());

let reference = RelativeReference::try_from("").unwrap();
assert!(!reference.has_username());

Source

pub fn host(&self) -> Option<&Host<'uri>>

Returns the host, if present, of the relative reference.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("//username@example.com").unwrap();
assert_eq!(reference.host().unwrap().to_string(), "example.com");

Source

pub fn into_builder(self) -> RelativeReferenceBuilder<'uri>

Consumes the relative reference and converts it into a builder with the same values.

§Examples

use std::convert::TryFrom;

use uriparse::{Fragment, Query, RelativeReference};

let reference = RelativeReference::try_from("//example.com/path?query#fragment").unwrap();
let mut builder = reference.into_builder();
builder.query(None::<Query>).fragment(None::<Fragment>);
let reference = builder.build().unwrap();
assert_eq!(reference.to_string(), "//example.com/path");

Source

pub fn into_owned(self) -> RelativeReference<'static>

Converts the RelativeReference into an owned copy.

If you construct the relative reference from a source with a non-static lifetime, you may run into lifetime problems due to the way the struct is designed. Calling this function will ensure that the returned value has a static lifetime.

This is different from just cloning. Cloning the relative reference will just copy the references, and thus the lifetime will remain the same.

Source

pub fn into_parts( self, ) -> (Option<Authority<'uri>>, Path<'uri>, Option<Query<'uri>>, Option<Fragment<'uri>>)

Consumes the RelativeReference and returns its parts: authority, path, query, and fragment.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from(
    "/my/path?my=query#fragment",
).unwrap();
let (authority, path, query, fragment) = reference.into_parts();

assert_eq!(authority, None);
assert_eq!(path, "/my/path");
assert_eq!(query.unwrap(), "my=query");
assert_eq!(fragment.unwrap(), "fragment");

Source

pub fn is_absolute_path_reference(&self) -> bool

Returns whether the relative reference is an absolute path reference.

A URI reference is an absolute path reference if it is a relative reference that begins with a single '/'.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("/my/path").unwrap();
assert!(reference.is_absolute_path_reference());

Source

pub fn is_network_path_reference(&self) -> bool

Returns whether the relative reference is a network path reference.

A relative reference is a network path reference if it is a relative reference that begins with two '/'.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("//example.com").unwrap();
assert!(reference.is_network_path_reference());

Source

pub fn is_normalized(&self) -> bool

Returns whether the relative reference is normalized.

A normalized relative reference will have all of its components normalized.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("/?a=b").unwrap();
assert!(reference.is_normalized());

let mut reference = RelativeReference::try_from("/././?a=b").unwrap();
assert!(!reference.is_normalized());
reference.normalize();
assert!(reference.is_normalized());

Source

pub fn is_relative_path_reference(&self) -> bool

Returns whether the relative reference is a relative path reference.

A relative reference is a relative path reference if it is a relative reference that does not begin with a '/'.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("my/path").unwrap();
assert!(reference.is_relative_path_reference());

Source

pub fn map_authority<TMapper>( &mut self, mapper: TMapper, ) -> Option<&Authority<'uri>>
where TMapper: FnOnce(Option<Authority<'uri>>) -> Option<Authority<'uri>>,

Maps the authority using the given map function.

This function will panic if, as a result of the authority change, the relative reference becomes invalid.

§Examples

use std::convert::TryFrom;

use uriparse::{Authority, RelativeReference};

let mut reference = RelativeReference::try_from("").unwrap();
reference.map_authority(|_| Some(Authority::try_from("127.0.0.1").unwrap()));
assert_eq!(reference.to_string(), "//127.0.0.1/");

Source

pub fn map_fragment<TMapper>( &mut self, mapper: TMapper, ) -> Option<&Fragment<'uri>>
where TMapper: FnOnce(Option<Fragment<'uri>>) -> Option<Fragment<'uri>>,

Maps the fragment using the given map function.

§Examples

use std::convert::TryFrom;

use uriparse::{Fragment, RelativeReference};

let mut reference = RelativeReference::try_from("/").unwrap();
reference.map_fragment(|_| Some(Fragment::try_from("fragment").unwrap()));
assert_eq!(reference.to_string(), "/#fragment");

Source

pub fn map_path<TMapper>(&mut self, mapper: TMapper) -> &Path<'uri>
where TMapper: FnOnce(Path<'uri>) -> Path<'uri>,

Maps the path using the given map function.

This function will panic if, as a result of the path change, the relative reference becomes invalid.

§Examples

use std::convert::TryFrom;

use uriparse::{Authority, URIReference};

let mut reference = URIReference::try_from("").unwrap();
reference.map_path(|mut path| {
    path.push("test").unwrap();
    path.push("path").unwrap();
    path
});
assert_eq!(reference.to_string(), "test/path");

Source

pub fn map_query<TMapper>(&mut self, mapper: TMapper) -> Option<&Query<'uri>>
where TMapper: FnOnce(Option<Query<'uri>>) -> Option<Query<'uri>>,

Maps the query using the given map function.

§Examples

use std::convert::TryFrom;

use uriparse::{Query, RelativeReference};

let mut reference = RelativeReference::try_from("/path").unwrap();
reference.map_query(|_| Some(Query::try_from("query").unwrap()));
assert_eq!(reference.to_string(), "/path?query");

Source

pub fn normalize(&mut self)

Normalizes the relative reference.

A normalized relative reference will have all of its components normalized.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let mut reference = RelativeReference::try_from("/?a=b").unwrap();
reference.normalize();
assert_eq!(reference.to_string(), "/?a=b");

let mut reference = RelativeReference::try_from("/././?a=b").unwrap();
assert_eq!(reference.to_string(), "/././?a=b");
reference.normalize();
assert_eq!(reference.to_string(), "/?a=b");

Source

pub fn path(&self) -> &Path<'uri>

Returns the path of the relative reference.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("/my/path").unwrap();
assert_eq!(reference.path(), "/my/path");

Source

pub fn password(&self) -> Option<&Password<'uri>>

Returns the password, if present, of the relative reference.

Usage of a password in URI and URI references is deprecated.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("//user:pass@example.com").unwrap();
assert_eq!(reference.password().unwrap(), "pass");

Source

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

Returns the port, if present, of the relative reference.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("//example.com:8080/").unwrap();
assert_eq!(reference.port().unwrap(), 8080);

Source

pub fn query(&self) -> Option<&Query<'uri>>

Returns the query, if present, of the relative reference.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("?my=query").unwrap();
assert_eq!(reference.query().unwrap(), "my=query");

Source

pub fn set_authority<TAuthority, TAuthorityError>( &mut self, authority: Option<TAuthority>, ) -> Result<Option<&Authority<'uri>>, RelativeReferenceError>
where Authority<'uri>: TryFrom<TAuthority, Error = TAuthorityError>, URIReferenceError: From<TAuthorityError>,

Sets the authority of the relative reference.

An error will be returned if the conversion to an Authority fails.

The existing path will be set to absolute (i.e. starts with a '/').

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let mut reference = RelativeReference::try_from("//example.com").unwrap();
reference.set_authority(Some("user@example.com:80"));
assert_eq!(reference.to_string(), "//user@example.com:80/");

Source

pub fn set_fragment<TFragment, TFragmentError>( &mut self, fragment: Option<TFragment>, ) -> Result<Option<&Fragment<'uri>>, RelativeReferenceError>
where Fragment<'uri>: TryFrom<TFragment, Error = TFragmentError>, URIReferenceError: From<TFragmentError>,

Sets the fragment of the relative reference.

An error will be returned if the conversion to a Fragment fails.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let mut reference = RelativeReference::try_from("/my/path").unwrap();
reference.set_fragment(Some("fragment"));
assert_eq!(reference.to_string(), "/my/path#fragment");

Source

pub fn set_path<TPath, TPathError>( &mut self, path: TPath, ) -> Result<&Path<'uri>, RelativeReferenceError>
where Path<'uri>: TryFrom<TPath, Error = TPathError>, URIReferenceError: From<TPathError>,

Sets the path of the relative reference.

An error will be returned in one of two cases:

The conversion to Path failed.
The path was set to a value that resulted in an invalid URI reference.

Regardless of whether the given path was set as absolute or relative, if the relative reference currently has an authority, the path will be forced to be absolute.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let mut reference = RelativeReference::try_from("").unwrap();
reference.set_path("my/path");
assert_eq!(reference.to_string(), "my/path");

Source

pub fn set_query<TQuery, TQueryError>( &mut self, query: Option<TQuery>, ) -> Result<Option<&Query<'uri>>, RelativeReferenceError>
where Query<'uri>: TryFrom<TQuery, Error = TQueryError>, URIReferenceError: From<TQueryError>,

Sets the query of the relative reference.

An error will be returned if the conversion to a Query fails.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let mut reference = RelativeReference::try_from("").unwrap();
reference.set_query(Some("myquery"));
assert_eq!(reference.to_string(), "?myquery");

Source

pub fn to_borrowed(&self) -> RelativeReference<'_>

Returns a new relative reference which is identical but has a lifetime tied to this relative reference.

This function will perform a memory allocation.

Source

pub fn username(&self) -> Option<&Username<'uri>>

Returns the username, if present, of the relative reference.

§Examples

use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("//username@example.com").unwrap();
assert_eq!(reference.username().unwrap(), "username");