Struct object_store::path::Path

pub struct Path { /* private fields */ }

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

Path Safety

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

This presents libraries with two options for consistent path handling:

1. Allow constructing unsafe paths, allowing for both reading and writing of data to paths that may not be consistently understood or supported
2. Disallow constructing unsafe paths, ensuring data written can be consistently handled by all other systems, but preventing interaction with objects at unsafe paths

This library takes the second approach, in particular:

• Paths are delimited by /
• Paths do not start with a /
• Empty path segments are discarded (e.g. // is treated as though it were /)
• Relative path segments, i.e. . and .. are percent encoded
• Unsafe characters are percent encoded, as described by RFC 1738
• All paths are relative to the root of the object store

In order to provide these guarantees there are two ways to safely construct a Path

Encode

A string containing potentially illegal path segments can be encoded to a Path using Path::from or Path::from_iter.

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_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 created from an existing string, returning an error if it is invalid. Unlike the encoding methods, this will permit valid percent encoded sequences.

assert_eq!(Path::parse("/foo/foo%2Fbar").unwrap().as_ref(), "foo/foo%2Fbar");
Path::parse("..").unwrap_err();
Path::parse("/foo//").unwrap_err();
Path::parse("😀").unwrap_err();

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 by Path::parse 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 by Path::parse, or base is not an absolute path

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

Returns the PathPart of this Path

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 Pathwhere
    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,

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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

Restrict a value to a certain interval.

impl PartialEq<Path> for Path

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

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

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl Eq for Path

impl StructuralEq for Path

impl StructuralPartialEq for Path