From 461d14724934f7a05fabfe74e8e51f801fa6993a Mon Sep 17 00:00:00 2001
From: Tobias Bucher <tobiasbucher5991@gmail.com>
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")]