relative-path
Portable, relative paths for Rust.
Relative Paths
This library provides two structures: RelativePath
and RelativePathBuf
.
These are analogous to the Path
and PathBuf
structures provided through standard Rust.
While Path
provides an API that adapts to a given platform, RelativePath
does not, making the
representations it provide platform-neutral.
The representation of Rust's Path
is not portable since it permits different things across
platforms.
Windows permit using drive volumes (e.g. "c:\"
) and backslash (\
) as a separator.
Using this to store relative paths would make it possible for software developers working to target
Windows to build projects which work on their platform, but not others.
RelativePath
only uses /
as a separator. Anything else will be considered part of distinct
components.
Conversion to Path
can only happen if it is known which path it is relative to, through the
to_path
function. This is where the 'relative' part of the name comes from.
let relative_path = new;
let path = new;
let full_path = relative_path.to_path;
This would for example, permit relative paths to portably be used in project manifests or configurations, where files are references from some specific, well-known point in the filesystem.
The following is a simple example configuration for a made up project:
= "src/lib.rs"
= "src/bin/hello.rs"
The corresponding Rust struct could look like this:
Portability Note
RelativePath
, similarly to Path
, makes no guarantees that the components represented in them
makes up legal file names.
NUL
is not permitted on unix platforms - this is a terminator in C-based filesystem APIs. Slash
(/
) is also used as a path separator.
Windows has a number of reserved characters.
TODO
- Verify that relative paths are - indeed - portable.
- Better function documentation with examples.
- Support more
Path
-like functions.