From dbb98e6460015b9ebc36b501e7c6fe5253a90923 Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Mon, 8 Jan 2024 13:14:30 -0500 Subject: [PATCH] Increase visibility of `join_path` and `split_paths` Add some crosslinking among `std::env` pages. Also add aliases to help anyone searching for `PATH`. --- library/std/src/env.rs | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/library/std/src/env.rs b/library/std/src/env.rs index 5bd20ebe208c0..6f8ac17f12c70 100644 --- a/library/std/src/env.rs +++ b/library/std/src/env.rs @@ -258,6 +258,9 @@ fn _var(key: &OsStr) -> Result { /// None => println!("{key} is not defined in the environment.") /// } /// ``` +/// +/// If expecting a delimited variable (such as `PATH`), [`split_paths`] +/// can be used to separate items. #[must_use] #[stable(feature = "env", since = "1.0.0")] pub fn var_os>(key: K) -> Option { @@ -441,6 +444,16 @@ pub struct SplitPaths<'a> { /// Returns an iterator over the paths contained in `unparsed`. The iterator /// element type is [`PathBuf`]. /// +/// On most Unix platforms, the separator is `:` and on Windows it is `;`. This +/// also performs unquoting on Windows. +/// +/// [`join_paths`] can be used to recombine elements. +/// +/// # Panics +/// +/// This will panic on systems where there is no delimited `PATH` variable, +/// such as UEFI. +/// /// # Examples /// /// ``` @@ -496,7 +509,8 @@ pub struct JoinPathsError { /// /// Returns an [`Err`] (containing an error message) if one of the input /// [`Path`]s contains an invalid character for constructing the `PATH` -/// variable (a double quote on Windows or a colon on Unix). +/// variable (a double quote on Windows or a colon on Unix), or if the system +/// does not have a `PATH`-like variable (e.g. UEFI or WASI). /// /// # Examples ///