pub struct Path<'path> { /* private fields */ }
Expand description
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"
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
sourceimpl<'path> Path<'path>
impl<'path> Path<'path>
sourcepub fn clear(&mut self)
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, "/");
sourcepub fn into_owned(self) -> Path<'static>
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.
sourcepub fn is_absolute(&self) -> bool
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);
sourcepub fn is_normalized(&self, as_reference: bool) -> bool
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));
sourcepub fn is_relative(&self) -> bool
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);
sourcepub fn normalize(&mut self, as_reference: bool)
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 due to 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 ".."
.
sourcepub fn pop(&mut self)
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, "/");
sourcepub fn push<SegmentType, SegmentError>(
&mut self,
segment: SegmentType
) -> Result<(), InvalidPath>where
Segment<'path>: TryFrom<SegmentType, Error = SegmentError>,
InvalidPath: From<SegmentError>,
pub fn push<SegmentType, SegmentError>(
&mut self,
segment: SegmentType
) -> Result<(), InvalidPath>where
Segment<'path>: TryFrom<SegmentType, Error = SegmentError>,
InvalidPath: From<SegmentError>,
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, "//");
sourcepub fn remove_dot_segments(&mut self)
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");
sourcepub fn segments(&self) -> &[Segment<'path>]
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");
sourcepub fn segments_mut(&mut self) -> &mut [Segment<'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();
// TODO: Remove this block once NLL is stable.
{
let mut segments = path.segments_mut();
segments[1] = Segment::try_from("test").unwrap();
}
assert_eq!(path, "/my/test");
sourcepub fn set_absolute(&mut self, absolute: bool)
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");
sourcepub fn to_borrowed(&self) -> 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.