devela::_dep::_std::fs

Function rename

1.0.0 · Source 
pub fn rename<P, Q>(from: P, to: Q) -> Result<(), Error> ⓘ
where
    P: AsRef<Path>,
    Q: AsRef<Path>,
Available on crate feature std only.
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 SetFileInformationByHandle function 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. The behavior on Windows is the same on Windows 10 1607 and higher if FileRenameInfoEx is supported by the filesystem; otherwise, 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(())
}