Creates a unique file/directory pathname basing on the specified parameters.
The function works as follows.
From the specified parameters, a new pathname is created (and converted to the absolute one):
parentPath + '/' + name + ext
If it wasn't, the pathname is registered in the hash-tabled with the reference
counter 1
and returned by the function as it is.
If that pathname already exists in the hash-table, its reference counter will be retrieved and used to create a modified pathname as the following:
parentPath + '/' + name + '_' + counter + ext
1
and
the modified pathname is returned by the function.
makeUniquePath()
function
(even with the same parameters) will return a unique pathname.
At that, the returned pathname will look almost the same as the requested one.
Only a short numeric suffix may be added before the extension.
The file extension is always preserved, because it indicates the file type (e.g. ".html"
)
The same functionality is used by the generator internally to ensure the uniqueness of all generated output files (whose names are typically produced from something related to the information document in them).
parentDir
The value of this parameter is expected to be an absolute pathname. However, if this is a relative pathname, it will be converted to the absolute one against the current system directory.
The allowed name-separator character may be '/'
or '\'
.
The parent directory pathname may end with the name-separator character
or not. It is irrelevant as long as the 'name'
parameter is non-empty.
Otherwise, the ending name-separator will be inherited by the result pathname.
name
The name passed in this parameter may end with the extension specified in the
'ext'
parameter.
However, in that case, the actual name (that is suffixed in case of duplications)
will be produced by excluding the extension from the initial name.
ext
The extension is just an ending of the name (typically started with a dot, e.g. ".html"
).
Many systems use the file name extension to recognize the file type (which may determine how the file is processed).
Because of this, the extension must not be distorted by any modifications.
That's why it is specified here with a separate parameter.
When the pathname produced by the first two arguments:
parentPath + '/' + name
The string specified in this parameter should not contain file name-separator characters. If it does, those characters will be removed.
Here, the uniqueness is meant only for the current generation session according to the algorithm described above. Any files/directories that already exist in the destination file system won't be taken into account.
Notes:
'/'
parentPath + '/' + name
ends with the separator character ('/'
or '\'
),
such a pathname will be returned by the function without any modifications
(as well as no extension will be added to it).
Three subsequent calls of the expression:
makeUniquePath (
"C:\doc", "element", ".html"
)
C:/doc/element.html
C:/doc/element_1.html
C:/doc/element_2.html