From 461d14724934f7a05fabfe74e8e51f801fa6993a Mon Sep 17 00:00:00 2001 From: Tobias Bucher Date: Fri, 11 Nov 2022 21:38:00 +0100 Subject: [PATCH] Document `Path::parent` behavior around relative paths A relative path with just one component will return `Some("")` as its parent, which wasn't clear to me from the documentation. The parent of `""` is `None`, which was missing from the documentation as well. --- library/std/src/path.rs | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/library/std/src/path.rs b/library/std/src/path.rs index 9d63281627d66..af88b9070c189 100644 --- a/library/std/src/path.rs +++ b/library/std/src/path.rs @@ -2142,7 +2142,10 @@ impl Path { /// Returns the `Path` without its final component, if there is one. /// - /// Returns [`None`] if the path terminates in a root or prefix. + /// This means it returns `Some("")` for relative paths with one component. + /// + /// Returns [`None`] if the path terminates in a root or prefix, or if it's + /// the empty string. /// /// # Examples /// @@ -2156,6 +2159,14 @@ impl Path { /// let grand_parent = parent.parent().unwrap(); /// assert_eq!(grand_parent, Path::new("/")); /// assert_eq!(grand_parent.parent(), None); + /// + /// let relative_path = Path::new("foo/bar"); + /// let parent = relative_path.parent(); + /// assert_eq!(parent, Some(Path::new("foo"))); + /// let grand_parent = parent.and_then(Path::parent); + /// assert_eq!(grand_parent, Some(Path::new(""))); + /// let great_grand_parent = grand_parent.and_then(Path::parent); + /// assert_eq!(great_grand_parent, None); /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[doc(alias = "dirname")]