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
Then, a special hash-table (maintained by the generator) is checked whether such a pathname was already registered in it.

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
Then, the reference counter is increased by 1 and the modified pathname is returned by the function.
This algorithm ensures that each subsequent call of 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).

Parameters:

parentDir

Specifies the parent directory pathname.

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
Specify the name of the file or directory that the result pathname will denote.

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
Specify the extension of the file/directory name.

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
already ends with the given extension, it won't be added again. However, to make the pathname unique, the numeric suffix will be inserted before the extension.

The string specified in this parameter should not contain file name-separator characters. If it does, those characters will be removed.

Returns:

The unique absolute pathname.

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:

Example:

Three subsequent calls of the expression:

makeUniquePath (
  "C:\doc", "element", ".html"
)
will return pathnames:
C:/doc/element.html
C:/doc/element_1.html
C:/doc/element_2.html