Routines (alphabetical) > Routines: F > FILE_BASENAME

FILE_BASENAME

The FILE_BASENAME function returns the basename of a file path. A file path is a string containing one or more segments consisting of names separated by directory delimiter characters (slash (/) under UNIX, or backslash (\) under Microsoft Windows). The basename is the final rightmost segment of the file path; it is usually a file, but can also be a directory name.

Note: FILE_BASENAME operates on strings based strictly on their syntax. The Path argument need not refer to actual or existing files.

FILE_BASENAME is based on the standard UNIX basename(1) utility.

Note: To retrieve the leftmost portion of the file path (the dirname), use the FILE_DIRNAME function.

Syntax

Result = FILE_BASENAME(Path [, RemoveSuffix] [, /FOLD_CASE])

Return Value

A scalar string or string array containing the basename for each element of the Path argument.

Arguments

Path

A scalar string or string array containing paths for which the basename is desired.

Note: Under Microsoft Windows, the backslash (\) character is used to separate directories within a path. For compatibility with UNIX, and general convenience, the forward slash (/) character is also accepted as a directory separator in the Path argument.

RemoveSuffix

An optional scalar string or 1-element string array specifying a filename suffix to be removed from the end of the basename, if present.

Note: If the entire basename string matches the suffix, the suffix is not removed.

Keywords

FOLD_CASE

By default, FILE_BASENAME follows the case sensitivity policy of the underlying operating system when attempting to match a string specified by the RemoveSuffix argument. By default, matches are case sensitive on UNIX platforms, and case insensitive on Microsoft Windows platforms. The FOLD_CASE keyword is used to change this behavior. Set it to a non-zero value to cause FILE_BASENAME to do all string matching case insensitively. Explicitly set FOLD_CASE equal to zero to cause all string matching to be case sensitive.

Note: The value of the FOLD_CASE keyword is ignored if the RemoveSuffix argument is not present.

Rules used by FILE_BASENAME

FILE_BASENAME makes a copy of the input file path string, then modifies the copy according to the following rules:

If Path is an empty string, then FILE_BASENAME returns an empty string.
If Path consists entirely of directory delimiter characters, the result of FILE_BASENAME is a single directory delimiter character.
If there are any trailing directory delimiter characters, they are removed.
Under Microsoft Windows, remove any of the following, if present:
The drive letter and colon (for file paths of the form c:\directory\file).
The initial double-backslash and host name (for UNC file paths of the form \\host\share\directory\file).
If any directory delimiter characters remain, all characters up to and including the last directory delimiter are removed.
If the RemoveSuffix argument is present, is not identical to the characters remaining, and matches the suffix of the characters remaining, the suffix is removed. Otherwise, the Result is not modified by this step. The case sensitivity of the string comparison used in this step is controlled by the FOLD_CASE keyword.

Examples

The following command prints the basename of an IDL .pro file, removing the .pro suffix:

PRINT, FILE_BASENAME('/usr/local/exelis/idl/lib/dist.pro', '.pro')

IDL prints:

dist

Similarly, the following command prints the basenames of all .pro files in the lib subdirectory of the IDL distribution that begin with the letter “I,” performing a case insensitive match for the suffix:

PRINT, FILE_BASENAME(FILE_SEARCH(FILEPATH('lib')+'/i*.pro'), $
'.pro', /FOLD_CASE)

Version History

6.0	Introduced