Struct object_store::path::Path

pub struct Path { /* private fields */ }

A parsed path representation that can be safely written to object storage

A Path maintains the following invariants:

• Paths are delimited by /
• Paths do not contain leading or trailing /
• Paths do not contain relative path segments, i.e. . or ..
• Paths do not contain empty path segments
• Paths do not contain any ASCII control characters

There are no enforced restrictions on path length, however, it should be noted that most object stores do not permit paths longer than 1024 bytes, and many filesystems do not support path segments longer than 255 bytes.

Encode

In theory object stores support any UTF-8 character sequence, however, certain character sequences cause compatibility problems with some applications and protocols. Additionally some filesystems may impose character restrictions, see LocalFileSystem. As such the naming guidelines for S3, GCS and Azure Blob Storage all recommend sticking to a limited character subset.

A string containing potentially problematic path segments can therefore be encoded to a Path using Path::from or Path::from_iter. This will percent encode any problematic segments according to RFC 1738.

assert_eq!(Path::from("foo/bar").as_ref(), "foo/bar");
assert_eq!(Path::from("foo//bar").as_ref(), "foo/bar");
assert_eq!(Path::from("foo/../bar").as_ref(), "foo/%2E%2E/bar");
assert_eq!(Path::from("/").as_ref(), "");
assert_eq!(Path::from_iter(["foo", "foo/bar"]).as_ref(), "foo/foo%2Fbar");

Note: if provided with an already percent encoded string, this will encode it again

assert_eq!(Path::from("foo/foo%2Fbar").as_ref(), "foo/foo%252Fbar");

Parse

Alternatively a Path can be parsed from an existing string, returning an error if it is invalid. Unlike the encoding methods above, this will permit arbitrary unicode, including percent encoded sequences.

assert_eq!(Path::parse("/foo/foo%2Fbar").unwrap().as_ref(), "foo/foo%2Fbar");
Path::parse("..").unwrap_err(); // Relative path segments are disallowed
Path::parse("/foo//").unwrap_err(); // Empty path segments are disallowed
Path::parse("\x00").unwrap_err(); // ASCII control characters are disallowed

Implementations

impl Path

pub fn parse(path: impl AsRef<str>) -> Result<Self, Error>

Parse a string as a Path, returning a Error if invalid, as defined on the docstring for Path

Note: this will strip any leading / or trailing /

pub fn from_filesystem_path(path: impl AsRef<Path>) -> Result<Self, Error>

Convert a filesystem path to a Path relative to the filesystem root

This will return an error if the path contains illegal character sequences as defined on the docstring for Path or does not exist

Note: this will canonicalize the provided path, resolving any symlinks

pub fn from_absolute_path(path: impl AsRef<Path>) -> Result<Self, Error>

Convert an absolute filesystem path to a Path relative to the filesystem root

This will return an error if the path contains illegal character sequences, as defined on the docstring for Path, or base is not an absolute path

pub fn from_url_path(path: impl AsRef<str>) -> Result<Self, Error>

Parse a url encoded string as a Path, returning a Error if invalid

This will return an error if the path contains illegal character sequences as defined on the docstring for Path

pub fn parts(&self) -> impl Iterator<Item = PathPart<'_>>

Returns the PathPart of this Path

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

Returns the last path segment containing the filename stored in this Path

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

Returns the extension of the file stored in this Path, if any

pub fn prefix_match( &self, prefix: &Self, ) -> Option<impl Iterator<Item = PathPart<'_>> + '_>

Returns an iterator of the PathPart of this Path after prefix

Returns None if the prefix does not match

pub fn prefix_matches(&self, prefix: &Self) -> bool

Returns true if this Path starts with prefix

pub fn child<'a>(&self, child: impl Into<PathPart<'a>>) -> Self

Creates a new child of this Path

Trait Implementations

impl AsRef<str> for Path

fn as_ref(&self) -> &str

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Path

fn clone(&self) -> Path

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Path

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

Formats the value using the given formatter.

impl Default for Path

fn default() -> Path

Returns the “default value” for a type.

impl Display for Path

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

Formats the value using the given formatter.

impl From<&str> for Path

fn from(path: &str) -> Self

Converts to this type from the input type.

impl From<Path> for String

fn from(path: Path) -> Self

Converts to this type from the input type.

impl From<String> for Path

fn from(path: String) -> Self

Converts to this type from the input type.

impl<'a, I> FromIterator<I> for Path

where I: Into<PathPart<'a>>,

fn from_iter<T: IntoIterator<Item = I>>(iter: T) -> Self

Creates a value from an iterator.

impl Hash for Path

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, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Path

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

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

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

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

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 PartialOrd for Path

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl Eq for Path

impl StructuralPartialEq for Path