File Exchange

image thumbnail

getUniqueFileName(f​ile, varargin)

version (4.22 KB) by Zhengyi
GETUNIQUEFILENAME returns a unique file name if the supplied file name has been taken.


Updated 14 May 2018

View License

In scenarios where you want to save a file and the file name is generated programmatically, you may want to check whether the file name has been taken by another file in the same path. In this case, GETUNIQUEFILENAME generates a new file name by adding a suffix to the original file name with a specified pattern.
OutFile = getUniqueFileName(InFile, Argments);
InFile: file name including file path and extension. File path can be skipped if it is the current Matlab path.
OutFile: if no conflict, the original file name if conflicting, a file name suffixed with a sequential integer enclosed in parenthesis. Sequential integer starts from 1.
Arguments: one or both of the following:
- an integer: custom start number for the sequential integer.
- formatting spec:
string formatting spec: must include one and only one operator '%d', additional operators may cause error or unexpected file name.

datetime format spec: use formatted datetime string as suffix, now is used to get the serial date number.

'DefaultDateSpec': uses '_ddmmyy-HHMMSSFFF' as the datetime format spec

Note: If a datetime suffixed filename still conflicts with one of the existing file's name, ' (%d)' will be suffixed.


For a file structure:
|- file.txt
|- file (1).txt
|- file (2).txt

fname = 'X:/file.txt';
NEWFILE_1 = getUniqueFileName(fname);
NEWFILE_2 = getUniqueFileName(fname, 5);
NEWFILE_3 = getUniqueFileName(fname, '_%d');
NEWFILE_4 = getUniqueFileName(fname, 0, '_v%d');
NEWFILE_5 = getUniqueFileName(fname, '_dd-mm-yy_HH-MM-SS-FFF');
NEWFILE_6 = getUniqueFileName(fname, 'DefaultDate');

NEWFILE_1 = X:/file (3).txt
NEWFILE_2 = X:/file (5).txt
NEWFILE_3 = X:/file_1.txt
NEWFILE_4 = X:/file_v0.txt
NEWFILE_5 = X:/file_01-01-1900_00-00-00-000.txt
NEWFILE_6 = X:/file_0101190000-0000000.txt

Cite As

Zhengyi (2020). getUniqueFileName(file, varargin) (, MATLAB Central File Exchange. Retrieved .

Comments and Ratings (1)

See also my FEX submission, which is optimized for speed (particularly with many files):

I like the date option, although for the default an ISO 8601 date format would be preferable, to ensure that the files sort correctly into chronological order: <>

The help is clear, with useful explanations, and illustrative examples. Altogether a very tidy submission.

Note that this function calls SPRINTF, DIR, LOWER, and ISMEMBER in a WHILE loop, checking the newly generated name against existing filenames: for folders with a large number of files, this loop could be quite slow. This could easily be improved by calling DIR outside of the local EXISTWITHEXT function and passing just the required FILES data, and also replacing the ISMEMBER with something like this:

re = any(strcmpi(file,{}));

Or see my submission for a faster alternative.


Fixed a problem where supplying a file name with path included results in an infinite loop.

Now works for files with no extension.
Fixed a mistake in description.

MATLAB Release Compatibility
Created with R10
Compatible with any release
Platform Compatibility
Windows macOS Linux