Issue#63183: Add fs::read_dir() and ReadDir warning about iterator order + example

[ali-raheem]

As per #63183

Add warning about iterator order to read_dir and ReadDir, add example of explicitly ordering direntrys.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @KodrAus (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[totsteps]

Ping from triage, @KodrAus can you please review this.

Thanks.

[KodrAus]

Thanks for your patience @ali-raheem! I think this example could be closer to a typical usecase if we retain the DirEntry itself, and sorting by the path:

let mut entries = fs::read_dir(".")?.collect::<Result<Vec<_>, io::Error>>()?;
        
entries.sort_by_key(|e| e.path());

That way the entries collection contains the whole DirEntry along with easy access to other filesystem metadata. It means that we couldn't use the println! statements so easily, but I don't think we really need them.

[abonander]

@KodrAus DirEntry::path() performs a copy, though.

[KodrAus]

Ah yes that's not really ideal is it. Thanks @abonander!

Ok I think this will be good to go once we remove the printlns (or convert them into comments).

[ali-raheem]

@KodrAus Like this? I've commented out the printlns so if someone wanted they could uncomment them and run it as a demonstration.

[wirelessringo]

Ping from triage. @KodrAus any updates on this? Thanks.

[KodrAus]

Ah sorry @ali-raheem, I meant that I think we should just remove those statements altogether, but could have a comment in the example source like:

fn main() -> io::Result<()> {
    let mut entries = fs::read_dir(".")?
        .map(|res| res.map(|e| e.path()))
        .collect::<Result<Vec<_>, io::Error>>()?;

    // The order in which `read_dir` returns entries is not guaranteed. If reproducible
    // ordering is required the entries should be explicitly sorted.

    entries.sort();

    // The contents of `entries` are now sorted by their path

    Ok(())
}

[abonander]

The entire reason for opening the issue is that there should be a clear statement that the user should not rely on iteration order; comments in examples are too easy to ignore.

[KodrAus]

@abonander Hm, I would think prose within the example would be clearer for someone scanning it than println statements they can’t actually see the result of.

[abonander]

Ah, my mistake. I thought you were referring to the statements in the actual doc comments and I just immediately thought "No! That was my whole complaint to begin with!"

[ali-raheem]

@KodrAus

Sorry it occured to me you might not get a notification when I push a new commit so I thought I'd ping.

Hopefully made the changes now.

[wirelessringo]

Ping from triage. @KodrAus any updates on this? Thanks. 😄

[KodrAus]

Thanks for your patience @ali-raheem!

This looks good to me

[KodrAus]

@bors r+ rollup

[bors]

📌 Commit 1161aeb has been approved by KodrAus