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 `/`.
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//! # Ensuring Existence
34//! A path being valid doesn't ensure that it exists. TODO
35// TODO: determine approach for existence checking methods and document TOCTOU choices.
36
37mod abs;
38mod dispatch;
39mod display;
40mod error;
41mod iter;
42mod path;
43mod rel;
44
45pub use abs::*;
46pub use dispatch::*;
47pub use display::*;
48pub use error::*;
49pub use iter::*;
50pub use path::*;
51pub use rel::*;