|
2 | 2 | //! |
3 | 3 | //! This module is an async version of [`std::path`]. |
4 | 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 | +//! |
5 | 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 | +//! |
| 57 | +//! [`Component`]: enum.Component.html |
| 58 | +//! [`components`]: struct.Path.html#method.components |
| 59 | +//! [`PathBuf`]: struct.PathBuf.html |
| 60 | +//! [`Path`]: struct.Path.html |
| 61 | +//! [`push`]: struct.PathBuf.html#method.push |
| 62 | +//! [`String`]: https://doc.rust-lang.org/std/string/struct.String.html |
| 63 | +//! |
| 64 | +//! [`str`]: https://doc.rust-lang.org/std/primitive.str.html |
| 65 | +//! [`OsString`]: https://doc.rust-lang.org/std/ffi/struct.OsString.html |
| 66 | +//! [`OsStr`]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html |
6 | 67 | |
7 | 68 | mod ancestors; |
8 | 69 | mod path; |
|
0 commit comments