Skip to main content

ContentPath

Struct ContentPath 

Source
pub struct ContentPath { /* private fields */ }
Expand description

A path or address identifying a piece of content.

In the common case this is a filesystem path, but it can also hold a synthetic address such as archive.zip://inner/file.txt or C:\proc.exe::1000::module.dll. A ContentPath always exposes a valid UTF-8 printable string for display and filtering; the true bytes are preserved separately when the underlying OS path is not valid UTF-8, so the original file can still be opened.

Construct one with from_str for caller-supplied or synthetic paths, or from_os for real OS paths. From is implemented for &str, String, &Path, and PathBuf so those types convert the same way.

Implementations§

Source§

impl ContentPath

Source

pub fn from_str(s: &str) -> Self

Builds a ContentPath from a UTF-8 string.

Use this for synthetic addresses (zip://…, …::pid::…) and for any path you already know is valid UTF-8. The result is always lossless.

Do not stringify a real OS path yourself and pass it here — a non-UTF-8 filesystem path would lose the bytes needed to reopen it. Route real paths through from_os instead.

Source

pub fn from_os(p: &Path) -> Self

Builds a ContentPath from a real OS path.

When the path is valid UTF-8 (the overwhelmingly common case) only the string is stored. When it is not — non-UTF-8 bytes on Unix, or unpaired surrogates on Windows — the original OsString is kept alongside a lossy string view, so the path stays both displayable and openable.

Source

pub fn empty() -> Self

An empty ContentPath (exact, zero-length).

Useful as a reusable buffer target; see clear and set_from_os.

Source

pub fn clear(&mut self)

Resets to an empty, exact path, retaining the string’s capacity.

Source

pub fn set_from_str(&mut self, s: &str)

Overwrites this path in place from a UTF-8 string, reusing the existing allocation.

Typical use: fill Entry::path from ContentExtractor::advance so a hot loop (directory walk, archive enumeration) does not reallocate per item.

Source

pub fn set_from_os(&mut self, p: &Path)

Overwrites this path in place from an OS path, reusing the string allocation on the common UTF-8 branch.

Source

pub fn as_path(&self) -> &Path

Borrows this path as an OsStr-backed Path suitable for filesystem calls.

Total on every platform. For a lossless path the string is reinterpreted; for a non-UTF-8 path the preserved OsString is used, so the returned &Path always names the original file.

Note this also returns a &Path for synthetic addresses like zip://…; that is intentional — the caller (e.g. the file opener) will simply get an OS error when such a path is not a real file.

Source

pub fn as_bytes(&self) -> &[u8] ⓘ

Borrows the bytes for inspection, filtering, and matching.

On Unix these are the faithful path bytes (from the preserved OsString when the path is non-UTF-8, otherwise the string bytes). On Windows the underlying OsString encoding is not exposable, so this returns the (possibly lossy) string bytes — the best available representation there.

For a lossless path these bytes are exactly as_printable_string’s bytes; for a non-UTF-8 Unix path they may differ.

Source

pub fn as_printable_string(&self) -> &str

Borrows a valid UTF-8 string safe to print or log.

Always available and never fails. For a non-UTF-8 path this is the lossy rendering (U+FFFD in place of invalid sequences); use is_lossless to tell whether it is exact.

Source

pub fn is_lossless(&self) -> bool

Returns true when the printable string is a faithful, exact representation of the path.

false means the path had bytes that cannot be represented in valid UTF-8, so as_printable_string is a lossy stand-in and should not be used as an identity or key. The exact path is still available via as_path (and, on Unix, as_bytes).

Trait Implementations§

Source§

impl Debug for ContentPath

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Default for ContentPath

Source§

fn default() -> ContentPath

Returns the “default value” for a type. Read more
Source§

impl From<&Path> for ContentPath

Source§

fn from(p: &Path) -> Self

Converts to this type from the input type.
Source§

impl From<&PathBuf> for ContentPath

Source§

fn from(p: &PathBuf) -> Self

Converts to this type from the input type.
Source§

impl From<&String> for ContentPath

Source§

fn from(s: &String) -> Self

Converts to this type from the input type.
Source§

impl From<&str> for ContentPath

Source§

fn from(s: &str) -> Self

Converts to this type from the input type.
Source§

impl From<PathBuf> for ContentPath

Source§

fn from(p: PathBuf) -> Self

Converts to this type from the input type.
Source§

impl From<String> for ContentPath

Source§

fn from(s: String) -> Self

Converts to this type from the input type.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.