Expand/Shrink

rename_file

Definition: bool res = rename_file(string src, string dest, bool overwrite=false)
Description: Rename a file.

src: the name of the file or directory to rename.
dest: the new name for the renamed file.
overwrite: false (0/the default) to abandon the operation if the destination file already exists, or true (1) to delete and replace any existing destination file.

Returns: false (0) on failure, true (1) on success.
pwa/p2js: Not supported.
Comments: If dest contains a path specification, it is equivalent to moving the file, as well as possibly changing its name. However, the path must exist and be on the same drive.

Unlike some other routines here, any path separators should be appropriate for the operating system, namely backslash ('\\') on Windows and forwardslash ('/') on Linux.
If in doubt (not already a result from the top half of the table) pass src/dest through get_proper_path() and/or get_proper_dir() before passing them to this routine.

For best results, use fully qualified absolute pathnames. You should not rely on relative paths in dest any more than you do in src; for instance rename_file(`demo\test`,`demo\test2`) is fine, whereas rename_file(`demo\test`,"test2") is likely to move it up a directory, and rename_file(`C:\Program Files (x86)\Phix\demo\test`,"test2") is likely to move it to the current directory. The precise behaviour of path-less operations is operating system dependent.

If overwrite was requested but the rename fails, there is no guarantee that any existing destination file is preserved, deleted, corrupted, or all three.

The use of a named parameter when setting the overwrite flag is recommended, to make the intent clear and the code easier to read.
Implementation: See builtins\pfile.e (an autoinclude) for details of the actual implementation.
See Also: move_file, copy_file