Function std::fs::rename

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

Rename 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(())
}
Run