standard_lib/fs/path/
mod.rs

1//! Types for representing valid file system paths. [`OwnedPath`] and [`Path`] are available as
2//! owned and slice representations, respectively.
3//! 
4//! This module provides types which represent valid (although not necessarily existent) paths for
5//! an operating system / file system. (Currently only for Linux, like the rest of [`fs`](super)).
6//! 
7//! # Approach
8//! Paths are represented by one of two types, using the type-state pattern:
9//! - [`OwnedPath`]: An owned mutable string representing a valid path.
10//! - [`Path`]: A slice representing a valid path. (Note: The slice itself is valid, and isn't just
11//!   a slice of a valid [`OwnedPath`].)
12//! 
13//! Each of these types is accompanied by a state, representing whether the path is absolute
14//! ([`Abs`]) or relative ([`Rel`]). Both of these states are represented as zero-variant enums, so
15//! they can't be instantiated.
16//! 
17//! For most file operations, an [`Abs`] path will be required, meaning that relative paths need to
18//! be [`resolved`](Path<Rel>::resolve) first.
19//! 
20//! # Validity
21//! Both path types uphold the following invariants to ensure that the contained
22//! [`OsString`](std::ffi::OsString) is _valid_:
23//! - The string starts with `/`.
24//! - The string contains no repeated `/` characters or occurrences of `/./`.
25//! - The string contains no trailing `/` or `.`.
26//! - The string contains no `\0`.
27//! 
28//! Although these invariants are relatively strict, constructing an `OwnedPath` from an `&OsStr` or
29//! `&str` is infallible because it sanitizes any invalid string provided. On the other hand,
30//! constructing a `Path` from another slice type can fail and may do so relatively often, because
31//! it won't mutate the original value, only verify that it is already valid.
32//! 
33//! # Instantiation
34//! | Method | Output | Input | Description |
35//! |-|-|-|-|
36//! | [`OwnedPath::from`] | `OwnedPath` | `AsRef<OsStr>` | Clones and sanitizes. |
37//! | [`OwnedPath::from_unchecked`] | `OwnedPath` | `Into<OsString>` | Moves without sanitizing, **unsafe**. |
38//! | [`Path::new`] | `Cow<_, Path>` | `AsRef<OsStr>` | Validates and sanitizes if required. |
39//! | [`Path::from_checked`] | `Option<&Path>` | `AsRef<OsStr>` | Fallibly validates. |
40//! | [`Path::from_unchecked`] | `&Path` | `AsRef<OsStr>` | Coerces without sanitizing, **unsafe**. |
41//! | [`Path::from_unchecked_mut`] | `&mut Path` | `AsMut<OsStr>` | Coerces mutably without sanitizing, **unsafe**. |
42//! 
43//! # Ensuring Existence
44//! A path being valid doesn't ensure that it exists. TODO
45//! 
46//! # Ownership
47//! Most methods which use Paths will take arguments bound by one the following:
48//! - `T: AsRef<Path<_>>` - for borrowed data, allowing anything which can be converted to a
49//!   `&Path`. This is used by any path manipulation methods that don't require ownership.
50//! - `T: Into<OwnedPath<_>>` - for owned data, allowing either an owned or borrowed `Path` to be
51//!   provided and cloned when required. Many file system operation do this, be cause they need to
52//!   extend the underlying OsString to make it valid for passing to glibc functions.
53// TODO: determine approach for existence checking methods and document TOCTOU choices.
54
55#[cfg(doc)]
56use std::convert::From;
57
58mod abs;
59mod dispatch;
60mod display;
61mod error;
62mod iter;
63mod path;
64mod rel;
65pub(crate) mod validity;
66
67pub use abs::*;
68pub use dispatch::*;
69pub use display::*;
70pub use error::*;
71pub use iter::*;
72pub use path::*;
73pub use rel::*;
standard_lib/fs/path/mod.rs

standard_lib/fs/path/
mod.rs
