FILE_DIRNAME

The FILE_DIRNAME function returns the dirname 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 dirname is all of the file path except for the final rightmost segment, which is usually a file name, but can also be a directory name. See Rules used by FILE_DIRNAME for additional information.

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

FILE_DIRNAME is based on the standard Unix dirname(1) utility.

Note
To retrieve the rightmost portion of the file path (the basename), use the FILE_BASENAME function.

Syntax

Result = FILE_DIRNAME(Path [, /MARK_DIRECTORY])

Return Value

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

Note
By default, the dirname does not include a final directory separator character; this behavior can be changed using the MARK_DIRECTORY keyword.

Note
On Windows platforms, the string returned by FILE_DIRNAME always uses the backslash (\) as the directory separator character, even if the slash (/) was used in the Path argument.

Arguments

Path

A scalar string or string array containing paths for which the dirname 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. However, all results produced by FILE_DIRNAME on Windows platforms use the standard backslash for this purpose, regardless of the separator character used in the input Path argument.

Keywords

MARK_DIRECTORY

Set this keyword to include a directory separator character at the end of the returned directory name string. Including the directory character allows you to concatenate a file name to the end of the directory name string without having to supply the separator character manually. This is convenient for cross platform programming, as the separator characters differ between operating systems.

Rules used by FILE_DIRNAME

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

If Path is a NULL string, then FILE_DIRNAME returns a single dot (.) character, representing the current working directory of the IDL process.

Under Microsoft Windows, a file path can start with either of the following:

A drive letter and a colon (for file paths of the form c:\directory\file).

An initial double-backslash and a host name (for UNC file paths of the form \\host\share\directory\file).

If either of these are present in Path, they are considered to be part of the dirname, and are copied to the result without interpretation by the remaining steps below.

If Path consists entirely of directory delimiter characters, the result of FILE_DIRNAME is a single directory delimiter character (prefixed by a Windows drive letter and colon or a UNC prefix, if necessary).

All characters to the right of the rightmost directory delimiter character are removed.

All trailing directory delimiter characters are removed.

If the MARK_DIRECTORY keyword is set, a single directory delimiter character is appended to the end.

Examples

The following statements print the directory in which IDL locates the file dist.pro when it needs a definition for the DIST function. (DIST is part of the standard IDL user library, included with IDL):

temp = DIST(4) ; Ensure that DIST is compiled
PRINT, FILE_DIRNAME((ROUTINE_INFO('DIST', $
/FUNCTION, /SOURCE)).path)

Depending on the platform and location where IDL is installed, IDL prints something like:

/usr/local/itt/idl/lib

Version History


6.0	Introduced