Struct Path

pub struct Path<'path> { /* private fields */ }

The path component as defined in [RFC3986, Section 3.3].

A path is composed of a sequence of segments. It is also either absolute or relative, where an absolute path starts with a '/'. A URI with an authority always has an absolute path regardless of whether the path was empty (i.e. “http://example.com” has a single empty path segment and is absolute).

Each segment in the path is case-sensitive. Furthermore, percent-encoding plays no role in equality checking for characters in the unreserved character set meaning that "segment" and "s%65gment" are identical. Both of these attributes are reflected in the equality and hash functions.

However, be aware that just because percent-encoding plays no role in equality checking does not mean that either the path or a given segment is normalized. If the path or a segment needs to be normalized, use either the Path::normalize or Segment::normalize functions, respectively.

Implementations

impl<'path> Path<'path>

pub fn clear(&mut self)

Clears all segments from the path leaving a single empty segment.

Examples

use std::convert::TryFrom;

use uriparse::Path;

let mut path = Path::try_from("/my/path").unwrap();
assert_eq!(path, "/my/path");
path.clear();
assert_eq!(path, "/");

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

Converts the Path into an owned copy.

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

pub fn is_absolute(&self) -> bool

Returns whether the path is absolute (i.e. it starts with a '/').

Any path following an [Authority] will always be parsed to be absolute.

Examples

use std::convert::TryFrom;

use uriparse::Path;

let path = Path::try_from("/my/path").unwrap();
assert_eq!(path.is_absolute(), true);

pub fn is_normalized(&self, as_reference: bool) -> bool

Returns whether the path is normalized either as or as not a reference.

See Path::normalize for a full description of what path normalization entails.

Although this function does not operate in constant-time in general, it will be constant-time in the vast majority of cases.

Examples

use std::convert::TryFrom;

use uriparse::Path;

let path = Path::try_from("/my/path").unwrap();
assert!(path.is_normalized(false));

let path = Path::try_from("/my/p%61th").unwrap();
assert!(!path.is_normalized(false));

let path = Path::try_from("..").unwrap();
assert!(path.is_normalized(true));

let path = Path::try_from("../.././.").unwrap();
assert!(!path.is_normalized(true));

pub fn is_relative(&self) -> bool

Returns whether the path is relative (i.e. it does not start with a '/').

Any path following an [Authority] will always be parsed to be absolute.

Examples

use std::convert::TryFrom;

use uriparse::Path;

let path = Path::try_from("my/path").unwrap();
assert_eq!(path.is_relative(), true);

pub fn normalize(&mut self, as_reference: bool)

Normalizes the path and all of its segments.

There are two components to path normalization, the normalization of each segment individually and the removal of unnecessary dot segments. It is also guaranteed that whether the path is absolute will not change as a result of normalization.

The normalization of each segment will proceed according to Segment::normalize.

If the path is absolute (i.e., it starts with a '/'), then as_reference will be set to false regardless of its set value.

If as_reference is false, then all dot segments will be removed as they would be if you had called Path::remove_dot_segments. Otherwise, when a dot segment is removed is dependent on whether it’s "." or ".." and its location in the path.

In general, "." dot segments are always removed except for when it is at the beginning of the path and is followed by a segment containing a ':', e.g. "./a:b" stays the same.

For ".." dot segments, they are kept whenever they are at the beginning of the path and removed whenever they are not, e.g. "a/../.." normalizes to "..".

pub fn pop(&mut self)

Pops the last segment off of the path.

If the path only contains one segment, then that segment will become empty.

use std::convert::TryFrom;

use uriparse::Path;

let mut path = Path::try_from("/my/path").unwrap();
path.pop();
assert_eq!(path, "/my");
path.pop();
assert_eq!(path, "/");

pub fn push<TSegment, TSegmentError>( &mut self, segment: TSegment, ) -> Result<(), PathError>

where Segment<'path>: TryFrom<TSegment, Error = TSegmentError>, PathError: From<TSegmentError>,

Pushes a segment onto the path.

If the conversion to a Segment fails, an [InvalidPath] will be returned.

The behavior of this function is different if the current path is just one empty segment. In this case, the pushed segment will replace that empty segment unless the pushed segment is itself empty.

use std::convert::TryFrom;

use uriparse::Path;

let mut path = Path::try_from("/my/path").unwrap();
path.push("test");
assert_eq!(path, "/my/path/test");

let mut path = Path::try_from("/").unwrap();
path.push("test");
assert_eq!(path, "/test");

let mut path = Path::try_from("/").unwrap();
path.push("");
assert_eq!(path, "//");

pub fn remove_dot_segments(&mut self)

Removes all dot segments from the path according to the algorithm described in [RFC3986, Section 5.2.4].

This function will perform no memory allocations during removal of dot segments.

If the path currently has no dot segments, then this function is a no-op.

Examples

use std::convert::TryFrom;

use uriparse::Path;

let mut path = Path::try_from("/a/b/c/./../../g").unwrap();
path.remove_dot_segments();
assert_eq!(path, "/a/g");

pub fn segments(&self) -> &[Segment<'path>]

Returns the segments of the path.

If you require mutability, use Path::segments_mut.

Examples

use std::convert::TryFrom;

use uriparse::Path;

let mut path = Path::try_from("/my/path").unwrap();
assert_eq!(path.segments()[1], "path");

pub fn segments_mut(&mut self) -> &mut [Segment<'path>]

Returns the segments of the path mutably.

Due to the required restriction that there must be at least one segment in a path, this mutability only applies to the segments themselves, not the container.

Examples

use std::convert::TryFrom;

use uriparse::{Path, Segment};

let mut path = Path::try_from("/my/path").unwrap();
let mut segments = path.segments_mut();
segments[1] = Segment::try_from("test").unwrap();

assert_eq!(path, "/my/test");

pub fn set_absolute(&mut self, absolute: bool)

Sets whether the path is absolute (i.e. it starts with a '/').

Examples

use std::convert::TryFrom;

use uriparse::Path;

let mut path = Path::try_from("/my/path").unwrap();
path.set_absolute(false);
assert_eq!(path, "my/path");

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

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

This function will perform a memory allocation.

Trait Implementations

impl<'path> Clone for Path<'path>

fn clone(&self) -> Path<'path>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'path> Debug for Path<'path>

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

Formats the value using the given formatter.

impl Display for Path<'_>

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

Formats the value using the given formatter.

impl<'path> From<Path<'path>> for String

fn from(value: Path<'path>) -> Self

Converts to this type from the input type.

impl Hash for Path<'_>

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

where H: Hasher,

Feeds this value into the given Hasher.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a> PartialEq<&'a [u8]> for Path<'_>

fn eq(&self, other: &&'a [u8]) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> PartialEq<&'a str> for Path<'_>

fn eq(&self, other: &&'a str) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<[u8]> for Path<'_>

fn eq(&self, other: &[u8]) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'path> PartialEq<Path<'path>> for &'a [u8]

fn eq(&self, other: &Path<'path>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'path> PartialEq<Path<'path>> for &'a str

fn eq(&self, other: &Path<'path>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'path> PartialEq<Path<'path>> for [u8]

fn eq(&self, other: &Path<'path>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'path> PartialEq<Path<'path>> for str

fn eq(&self, other: &Path<'path>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<str> for Path<'_>

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for Path<'_>

fn eq(&self, other: &Path<'_>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'path> TryFrom<&'path [u8]> for Path<'path>

type Error = PathError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl<'path> TryFrom<&'path str> for Path<'path>

type Error = PathError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl<'path> Eq for Path<'path>