Struct uriparse::uri_reference::URIReference

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

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

Specifically, a URI reference is either a URI or a relative reference (a schemeless URI).

Implementations

impl<'uri> URIReference<'uri>

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

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

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

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

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

Constructs a default builder for a URI reference.

This provides an alternative means of constructing a URI reference besides parsing and URIReference::from_parts.

Examples

use std::convert::TryFrom;

use uriparse::{Authority, Path, Scheme, URIReference};

let reference = URIReference::builder()
    .with_scheme(Some(Scheme::HTTP))
    .with_authority(Some(Authority::try_from("example.com").unwrap()))
    .with_path(Path::try_from("/my/path").unwrap())
    .build()
    .unwrap();
assert_eq!(reference.to_string(), "http://example.com/my/path");

pub fn can_be_a_base(&self) -> bool

Returns whether the URI reference can act as a base URI.

A URI can be a base if it is absolute (i.e. it has no fragment component).

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from("http://example.com/my/path").unwrap();
assert!(reference.can_be_a_base());

let reference = URIReference::try_from("ftp://127.0.0.1#fragment").unwrap();
assert!(!reference.can_be_a_base());

pub fn from_parts<'new_uri, TScheme, TAuthority, TPath, TQuery, TFragment, TSchemeError, TAuthorityError, TPathError, TQueryError, TFragmentError>(
    scheme: Option<TScheme>,
    authority: Option<TAuthority>,
    path: TPath,
    query: Option<TQuery>,
    fragment: Option<TFragment>
) -> Result<URIReference<'new_uri>, URIReferenceError> where
    Scheme<'new_uri>: TryFrom<TScheme, Error = TSchemeError>,
    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<TSchemeError> + From<TAuthorityError> + From<TPathError> + From<TQueryError> + From<TFragmentError>, 

Constructs a new URIReference from the individual parts: scheme, 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, URIReference};

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

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

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

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

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

pub fn has_authority(&self) -> bool

Returns whether the URI reference has an authority component.

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

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

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

pub fn has_fragment(&self) -> bool

Returns whether the URI reference has a fragment component.

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

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

let reference = URIReference::try_from("http://example.com").unwrap();
assert!(!reference.has_fragment());

pub fn has_password(&self) -> bool

Returns whether the URI reference has a password component.

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

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

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

pub fn has_port(&self) -> bool

Returns whether the URI reference has a port.

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

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

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

pub fn has_query(&self) -> bool

Returns whether the URI reference has a query component.

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

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

let reference = URIReference::try_from("http://example.com/my/path").unwrap();
assert!(!reference.has_query());

pub fn has_scheme(&self) -> bool

Returns whether the URI reference has a scheme component.

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from("http://example.com?my=query").unwrap();
assert!(reference.has_scheme());

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

pub fn has_username(&self) -> bool

Returns whether the URI reference has a username component.

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

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

let reference = URIReference::try_from("http://example.com").unwrap();
assert!(!reference.has_username());

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

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

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

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

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

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

Examples

use std::convert::TryFrom;

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

let reference = URIReference::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");

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

Converts the URIReference into an owned copy.

If you construct the URI 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 URI reference will just copy the references, and thus the lifetime will remain the same.

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

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

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from(
    "http://username:password@example.com:80/my/path?my=query#fragment",
).unwrap();
let (scheme, authority, path, query, fragment) = reference.into_parts();

assert_eq!(scheme.unwrap(), "http");
assert_eq!(authority.unwrap().to_string(), "username:password@example.com:80");
assert_eq!(path, "/my/path");
assert_eq!(query.unwrap(), "my=query");
assert_eq!(fragment.unwrap(), "fragment");

pub fn is_absolute_path_reference(&self) -> bool

Returns whether the URI 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::URIReference;

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

pub fn is_network_path_reference(&self) -> bool

Returns whether the URI reference is a network path reference.

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

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

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

pub fn is_normalized(&self) -> bool

Returns whether the URI reference is normalized.

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

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from("http://example.com/?a=b").unwrap();
assert!(reference.is_normalized());

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

pub fn is_relative_path_reference(&self) -> bool

Returns whether the URI reference is a relative path reference.

A URI 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::URIReference;

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

pub fn is_relative_reference(&self) -> bool

Returns whether the URI reference is a relative reference.

A URI reference is a relative reference if it has no scheme.

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

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

pub fn is_uri(&self) -> bool

Returns whether the URI reference is a URI.

A URI reference is a URI if it has a scheme.

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from("http://example.com").unwrap();
assert!(reference.is_uri());

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 URI reference becomes invalid.

Examples

use std::convert::TryFrom;

use uriparse::{Authority, URIReference};

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

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, URIReference};

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

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 URI reference becomes invalid.

Examples

use std::convert::TryFrom;

use uriparse::{Authority, URIReference};

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

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, URIReference};

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

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

Maps the scheme using the given map function.

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

Examples

use std::convert::TryFrom;

use uriparse::{Scheme, URIReference};

let mut reference = URIReference::try_from("http://example.com").unwrap();
reference.map_scheme(|_| Some(Scheme::try_from("https").unwrap()));
assert_eq!(reference.to_string(), "https://example.com/");

pub fn normalize(&mut self)

Normalizes the URI reference.

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

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

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

let mut reference = URIReference::try_from("http://EXAMPLE.com/?a=b").unwrap();
assert_eq!(reference.to_string(), "http://EXAMPLE.com/?a=b");
reference.normalize();
assert_eq!(reference.to_string(), "http://example.com/?a=b");

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

Returns the path of the URI reference.

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

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

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

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

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

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

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

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

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

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

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

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

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

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from("http://127.0.0.1?my=query").unwrap();
assert_eq!(reference.query().unwrap(), "my=query");

pub fn scheme(&self) -> Option<&Scheme<'uri>>

Returns the scheme, if present, of the URI reference.

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from("http://127.0.0.1/").unwrap();
assert_eq!(reference.scheme().unwrap(), "http");

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

Sets the authority of the URI 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::URIReference;

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

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

Sets the fragment of the URI reference.

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

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

let mut reference = URIReference::try_from("http://example.com").unwrap();
reference.set_fragment(Some("fragment"));
assert_eq!(reference.to_string(), "http://example.com/#fragment");

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

Sets the path of the URI 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 URI reference currently has an authority, the path will be forced to be absolute.

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

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

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

Sets the query of the URI reference.

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

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

let mut reference = URIReference::try_from("http://example.com").unwrap();
reference.set_query(Some("myquery"));
assert_eq!(reference.to_string(), "http://example.com/?myquery");

pub fn set_scheme<TScheme, TSchemeError>(
    &mut self,
    scheme: Option<TScheme>
) -> Result<Option<&Scheme<'uri>>, URIReferenceError> where
    Scheme<'uri>: TryFrom<TScheme, Error = TSchemeError>,
    URIReferenceError: From<TSchemeError>, 

Sets the scheme of the URI reference.

An error will be returned in one of two cases:

• The conversion to Scheme failed.
• The scheme was set to None, but the resulting URI reference has an invalid schemeless path.

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

let mut reference = URIReference::try_from("http://example.com").unwrap();
reference.set_scheme(Some("https"));
assert_eq!(reference.to_string(), "https://example.com/");

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

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

This function will perform a memory allocation.

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

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

Examples

use std::convert::TryFrom;

use uriparse::URIReference;

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

Trait Implementations

impl<'uri> Clone for URIReference<'uri>

fn clone(&self) -> URIReference<'uri>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'uri> Debug for URIReference<'uri>

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

Formats the value using the given formatter.

impl Display for URIReference<'_>

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

Formats the value using the given formatter.

impl<'uri> From<RelativeReference<'uri>> for URIReference<'uri>

fn from(value: RelativeReference<'uri>) -> Self

Performs the conversion.

impl<'uri> From<URI<'uri>> for URIReference<'uri>

fn from(value: URI<'uri>) -> Self

Performs the conversion.

impl<'uri> From<URIReference<'uri>> for String

fn from(value: URIReference<'uri>) -> Self

Performs the conversion.

impl<'uri> Hash for URIReference<'uri>

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.

impl<'uri> PartialEq<URIReference<'uri>> for URIReference<'uri>

fn eq(&self, other: &URIReference<'uri>) -> bool

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

fn ne(&self, other: &URIReference<'uri>) -> bool

This method tests for !=.

impl<'uri> TryFrom<&'uri [u8]> for URIReference<'uri>

type Error = URIReferenceError

The type returned in the event of a conversion error.

fn try_from(value: &'uri [u8]) -> Result<Self, Self::Error>

Performs the conversion.

impl<'uri> TryFrom<&'uri str> for URIReference<'uri>

type Error = URIReferenceError

The type returned in the event of a conversion error.

fn try_from(value: &'uri str) -> Result<Self, Self::Error>

Performs the conversion.

impl<'uri> TryFrom<URIReference<'uri>> for RelativeReference<'uri>

type Error = RelativeReferenceError

The type returned in the event of a conversion error.

fn try_from(value: URIReference<'uri>) -> Result<Self, Self::Error>

Performs the conversion.

impl<'uri> TryFrom<URIReference<'uri>> for URI<'uri>

type Error = URIError

The type returned in the event of a conversion error.

fn try_from(value: URIReference<'uri>) -> Result<Self, Self::Error>

Performs the conversion.

impl<'uri> Eq for URIReference<'uri>

impl<'uri> StructuralEq for URIReference<'uri>

impl<'uri> StructuralPartialEq for URIReference<'uri>