From 9755fe80ee88803f2ecf7e86d7ae6d6fb8e25f55 Mon Sep 17 00:00:00 2001 From: Ali Raheem Date: Wed, 7 Aug 2019 15:59:18 +0100 Subject: [PATCH 1/5] Add fs::read_dir() and ReadDir warning about iterator order + example --- src/libstd/fs.rs | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index f7c32a5c20d3d..2a55c79a93ce4 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -114,6 +114,11 @@ pub struct Metadata(fs_imp::FileAttr); /// information like the entry's path and possibly other metadata can be /// learned. /// +/// #### Note: Iteration Order is Implementation-Defined +/// +/// The order in which this iterator returns entries is platform and filesystem +/// dependent. +/// /// # Errors /// /// This [`io::Result`] will be an [`Err`] if there's some sort of intermittent @@ -1959,6 +1964,11 @@ pub fn remove_dir_all>(path: P) -> io::Result<()> { /// /// [changes]: ../io/index.html#platform-specific-behavior /// +/// #### Note: Iteration Order is Implementation-Defined +/// +/// The order in which this iterator returns entries is platform and filesystem +/// dependent. +/// /// # Errors /// /// This function will return an error in the following situations, but is not @@ -1991,6 +2001,28 @@ pub fn remove_dir_all>(path: P) -> io::Result<()> { /// Ok(()) /// } /// ``` +/// +/// ```rust,no_run +/// use std::{fs, io}; +/// +/// fn main() -> io::Result<()> { +/// // The order read_dir returns entries is not guaranteed. If reproducible +/// // ordering is required the entries should be explicitly sorted. +/// let mut entries = fs::read_dir(".")? +/// .map(|res| res.map(|e| e.path())) +/// .collect::, io::Error>>()?; +/// +/// println!( +/// "Entries before sorting (may or may not be sorted already): {:?}", +/// entries +/// ); +/// +/// entries.sort(); +/// +/// println!("Entries after sorting: {:?}", entries); +/// Ok(()) +/// } +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn read_dir>(path: P) -> io::Result { fs_imp::readdir(path.as_ref()).map(ReadDir) From 8068812d042fa1bfb2133332152ee591705fdef7 Mon Sep 17 00:00:00 2001 From: Ali Raheem Date: Thu, 8 Aug 2019 15:33:39 +0100 Subject: [PATCH 2/5] Remove Iteration order heading --- src/libstd/fs.rs | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index 2a55c79a93ce4..ad279d7f754a6 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -114,8 +114,6 @@ pub struct Metadata(fs_imp::FileAttr); /// information like the entry's path and possibly other metadata can be /// learned. /// -/// #### Note: Iteration Order is Implementation-Defined -/// /// The order in which this iterator returns entries is platform and filesystem /// dependent. /// @@ -1964,8 +1962,6 @@ pub fn remove_dir_all>(path: P) -> io::Result<()> { /// /// [changes]: ../io/index.html#platform-specific-behavior /// -/// #### Note: Iteration Order is Implementation-Defined -/// /// The order in which this iterator returns entries is platform and filesystem /// dependent. /// From 53c504650dc6e51c45a256f56c92b872082d0642 Mon Sep 17 00:00:00 2001 From: Ali Raheem Date: Thu, 15 Aug 2019 10:53:29 +0100 Subject: [PATCH 3/5] Fix gramitcal error in read_dir example --- src/libstd/fs.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index ad279d7f754a6..42ce044c5abe5 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -2002,7 +2002,7 @@ pub fn remove_dir_all>(path: P) -> io::Result<()> { /// use std::{fs, io}; /// /// fn main() -> io::Result<()> { -/// // The order read_dir returns entries is not guaranteed. If reproducible +/// // The order in which `read_dir` returns entries is not guaranteed. If reproducible /// // ordering is required the entries should be explicitly sorted. /// let mut entries = fs::read_dir(".")? /// .map(|res| res.map(|e| e.path())) From 3c820fef9fafca1f25da37274aea683b9e341339 Mon Sep 17 00:00:00 2001 From: Ali Raheem Date: Mon, 26 Aug 2019 11:24:08 +0100 Subject: [PATCH 4/5] Comment out println in read_dir sorting example --- src/libstd/fs.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index 42ce044c5abe5..689c50c6b80fa 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -2008,14 +2008,14 @@ pub fn remove_dir_all>(path: P) -> io::Result<()> { /// .map(|res| res.map(|e| e.path())) /// .collect::, io::Error>>()?; /// -/// println!( -/// "Entries before sorting (may or may not be sorted already): {:?}", -/// entries -/// ); +/// // println!( +/// // "Entries before sorting (may or may not be sorted already): {:?}", +/// // entries +/// // ); /// /// entries.sort(); /// -/// println!("Entries after sorting: {:?}", entries); +/// // println!("Entries after sorting: {:?}", entries); /// Ok(()) /// } /// ``` From 1161aeb2b423da744e687315648a49cc4774220b Mon Sep 17 00:00:00 2001 From: Ali Raheem Date: Mon, 9 Sep 2019 20:38:21 +0100 Subject: [PATCH 5/5] Replace println statements with explanatory comments --- src/libstd/fs.rs | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index 689c50c6b80fa..246587b4233cd 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -2002,20 +2002,17 @@ pub fn remove_dir_all>(path: P) -> io::Result<()> { /// use std::{fs, io}; /// /// fn main() -> io::Result<()> { -/// // The order in which `read_dir` returns entries is not guaranteed. If reproducible -/// // ordering is required the entries should be explicitly sorted. /// let mut entries = fs::read_dir(".")? /// .map(|res| res.map(|e| e.path())) /// .collect::, io::Error>>()?; /// -/// // println!( -/// // "Entries before sorting (may or may not be sorted already): {:?}", -/// // entries -/// // ); +/// // The order in which `read_dir` returns entries is not guaranteed. If reproducible +/// // ordering is required the entries should be explicitly sorted. /// /// entries.sort(); /// -/// // println!("Entries after sorting: {:?}", entries); +/// // The entries have now been sorted by their path. +/// /// Ok(()) /// } /// ```