1//! Cross-platform path manipulation.
2//!
3//! This module is an async version of [`std::path`].
4//!
5//! This module provides two types, [`PathBuf`] and [`Path`][`Path`] (akin to [`String`]
6//! and [`str`]), for working with paths abstractly. These types are thin wrappers
7//! around [`OsString`] and [`OsStr`] respectively, meaning that they work directly
8//! on strings according to the local platform's path syntax.
9//!
10//! Paths can be parsed into [`Component`]s by iterating over the structure
11//! returned by the [`components`] method on [`Path`]. [`Component`]s roughly
12//! correspond to the substrings between path separators (`/` or `\`). You can
13//! reconstruct an equivalent path from components with the [`push`] method on
14//! [`PathBuf`]; note that the paths may differ syntactically by the
15//! normalization described in the documentation for the [`components`] method.
16//!
17//! [`std::path`]: https://doc.rust-lang.org/std/path/index.html
18//!
19//! ## Simple usage
20//!
21//! Path manipulation includes both parsing components from slices and building
22//! new owned paths.
23//!
24//! To parse a path, you can create a [`Path`] slice from a [`str`]
25//! slice and start asking questions:
26//!
27//! ```
28//! use async_std::path::Path;
29//! use std::ffi::OsStr;
30//!
31//! let path = Path::new("/tmp/foo/bar.txt");
32//!
33//! let parent = path.parent();
34//! assert_eq!(parent, Some(Path::new("/tmp/foo")));
35//!
36//! let file_stem = path.file_stem();
37//! assert_eq!(file_stem, Some(OsStr::new("bar")));
38//!
39//! let extension = path.extension();
40//! assert_eq!(extension, Some(OsStr::new("txt")));
41//! ```
42//!
43//! To build or modify paths, use [`PathBuf`]:
44//!
45//! ```
46//! use async_std::path::PathBuf;
47//!
48//! // This way works...
49//! let mut path = PathBuf::from("c:\\");
50//!
51//! path.push("windows");
52//! path.push("system32");
53//!
54//! path.set_extension("dll");
55//!
56//! // ... but push is best used if you don't know everything up
57//! // front. If you do, this way is better:
58//! let path: PathBuf = ["c:\\", "windows", "system32.dll"].iter().collect();
59//! ```
60//!
61//! [`Component`]: enum.Component.html
62//! [`components`]: struct.Path.html#method.components
63//! [`PathBuf`]: struct.PathBuf.html
64//! [`Path`]: struct.Path.html
65//! [`push`]: struct.PathBuf.html#method.push
66//! [`String`]: https://doc.rust-lang.org/std/string/struct.String.html
67//!
68//! [`str`]: https://doc.rust-lang.org/std/primitive.str.html
69//! [`OsString`]: https://doc.rust-lang.org/std/ffi/struct.OsString.html
70//! [`OsStr`]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html
71
72mod ancestors;
73mod components;
74mod iter;
75mod path;
76mod pathbuf;
77
78#[doc(inline)]
79pub use std::path::{
80 is_separator, Component, Display, Prefix, PrefixComponent, StripPrefixError, MAIN_SEPARATOR,
81};
82
83pub use ancestors::Ancestors;
84pub use components::Components;
85pub use iter::Iter;
86pub use path::Path;
87pub use pathbuf::PathBuf;
88