Function tracing::stdlib::fs::rename

1.0.0 · source · 
pub fn rename<P, Q>(from: P, to: Q) -> Result<(), Error>
where
    P: AsRef<Path>,
    Q: AsRef<Path>,
Expand description

Renames a file or directory to a new name, replacing the original file if to already exists.

This will not work if the new name is on a different mount point.

§Platform-specific behavior

This function currently corresponds to the rename function on Unix and the MoveFileEx function with the MOVEFILE_REPLACE_EXISTING flag on Windows.

Because of this, the behavior when both from and to exist differs. On Unix, if from is a directory, to must also be an (empty) directory. If from is not a directory, to must also be not a directory. In contrast, on Windows, from can be anything, but to must not be a directory.

Note that, this may change in the future.

§Errors

This function will return an error in the following situations, but is not limited to just these cases:

  • from does not exist.
  • The user lacks permissions to view contents.
  • from and to are on separate filesystems.

§Examples

use std::fs;

fn main() -> std::io::Result<()> {
    fs::rename("a.txt", "b.txt")?; // Rename a.txt to b.txt
    Ok(())
}