FILE_BASENAME

IDL Reference Guide: Procedures and Functions

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. See Rules used by FILE_BASENAME for additional information.

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 a NULL string, then FILE_BASENAME returns a NULL 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/itt/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

FILE_BASENAME

Syntax

Return Value

Arguments

Path

RemoveSuffix

Keywords

FOLD_CASE

Rules used by FILE_BASENAME

Examples

Version History

See Also