Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify that std::fs::rename can move #24993

Closed
wants to merge 1 commit into from
Closed

Clarify that std::fs::rename can move #24993

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions src/libstd/fs.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -844,6 +844,9 @@ pub fn symlink_metadata<P: AsRef<Path>>(path: P) -> io::Result<Metadata> {

/// Rename a file or directory to a new name.
///
/// Moving a file or directory is also a rename, in a sense, and so this
/// function is not limited a single directory.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, was the issue misread perhaps? This seems somewhat confusing as the main docs say "Rename" and then this says it's also a rename. Perhaps this could mention that it could move many files (as part of renaming a directory), but I think the issue in question was also asking for clarification that moving across filesystem boundaries probably isn't allowed.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, talking in IRC, the example I used was the behavior they weren't familiar with.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Er, to be clear, the issue states:

std::fs::rename is missing the explicit description that you can also move a file outside of the current folder with it, as long as it's on the same file system.

This documentation doesn't indicate anything related to filesystem boundaries though? (there's also still the mentioning "rename" twice issue I'm worried about)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I think there was a filing of an issue, and a discussion at the same time. Shame the IRC stuff is lost, argh. We should mention the FS issue regardless.

///
/// # Errors
///
/// This function will return an error if the provided `from` doesn't exist, if
Expand All @@ -861,6 +864,17 @@ pub fn symlink_metadata<P: AsRef<Path>>(path: P) -> io::Result<Metadata> {
/// # Ok(())
/// # }
/// ```
///
/// Moving:
///
/// ```
/// use std::fs;
///
/// # fn foo() -> std::io::Result<()> {
/// try!(fs::rename("from/a.txt", "to/b.txt"));
/// # Ok(())
/// # }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<()> {
fs_imp::rename(from.as_ref(), to.as_ref())
Expand Down