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
impl ContentPath
Sourcepub fn from_str(s: &str) -> Self
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.
Sourcepub fn from_os(p: &Path) -> Self
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.
Sourcepub fn empty() -> Self
pub fn empty() -> Self
An empty ContentPath (exact, zero-length).
Useful as a reusable buffer target; see clear and
set_from_os.
Sourcepub fn set_from_str(&mut self, s: &str)
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.
Sourcepub fn set_from_os(&mut self, p: &Path)
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.
Sourcepub fn as_path(&self) -> &Path
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.
Sourcepub fn as_bytes(&self) -> &[u8] ⓘ
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.
Sourcepub fn as_printable_string(&self) -> &str
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.
Sourcepub fn is_lossless(&self) -> bool
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).