D Programming Language 1.0

std.path

Source:
std/path.d

http:
//www.digitalmars.com

Grzegorz Adam Hankiewicz added some documentation.

This module is used to parse file names. All the operations work only on strings; they don't perform any input/output operations. This means that if a path contains a directory name with a dot, functions like getExt() will work with it just as if it was a file. To differentiate these cases, use the std.file module first (i.e. std.file.isDir()).

const char[1u] sep;

String used to separate directory names in a path. Under Windows this is a backslash, under Linux a slash.

const char[1u] altsep;

Alternate version of sep[] used in Windows (a slash). Under Linux this is empty.

const char[1u] pathsep;

Path separator string. A semi colon under Windows, a colon under Linux.

const char[2u] linesep;

String used to separate lines. String used to separate lines, \r\n under Windows and \n under Linux.

const char[1u] curdir;

String representing the current directory.

const char[2u] pardir;

String representing the parent directory.

alias fcmp;

Compare file names.

Returns:

< 0	filename1 < filename2
= 0	filename1 == filename2
> 0	filename1 > filename2

string getExt(string fullname);

Extracts the extension from a filename or path.

This function will search fullname from the end until the first dot, path separator or first character of fullname is reached. Under Windows, the drive letter separator (colon) also terminates the search.

Returns:
If a dot was found, characters to its right are returned. If a path separator was found, or fullname didn't contain any dots or path separators, returns null.

Throws:
Nothing.

Examples:

 version(Windows)
 {
     getExt(r"d:\path\foo.bat") // "bat"
     getExt(r"d:\path.two\bar") // null
 }
 version(Posix)
 {
     getExt(r"/home/user.name/bar.")  // ""
     getExt(r"d:\path.two\bar")     // "two\\bar"
     getExt(r"/home/user/.resource")  // "resource"
 }

string getName(string fullname);

Returns the extensionless version of a filename or path.

This function will search fullname from the end until the first dot, path separator or first character of fullname is reached. Under Windows, the drive letter separator (colon) also terminates the search.

Returns:
If a dot was found, characters to its left are returned. If a path separator was found, or fullname didn't contain any dots or path separators, returns null.

Throws:
Nothing.

Examples:

 version(Windows)
 {
     getName(r"d:\path\foo.bat") => "d:\path\foo"
     getName(r"d:\path.two\bar") => null
 }
 version(Posix)
 {
     getName("/home/user.name/bar.")  => "/home/user.name/bar"
     getName(r"d:\path.two\bar") => r"d:\path"
     getName("/home/user/.resource") => "/home/user/"
 }

string getBaseName(string fullname);

Extracts the base name of a path.

This function will search fullname from the end until the first path separator or first character of fullname is reached. Under Windows, the drive letter separator (colon) also terminates the search.

Returns:
If a path separator was found, all the characters to its right are returned. Otherwise, fullname is returned.

Throws:
Nothing.

Examples:

 version(Windows)
 {
     getBaseName(r"d:\path\foo.bat") => "foo.bat"
 }
 version(Posix)
 {
     getBaseName("/home/user.name/bar.")  => "bar."
 }

string getDirName(string fullname);

Extracts the directory part of a path.

This function will search fullname from the end until the first path separator or first character of fullname is reached. Under Windows, the drive letter separator (colon) also terminates the search.

Returns:
If a path separator was found, all the characters to its left are returned. Otherwise, fullname is returned.

Under Windows, the found path separator will be included in the returned string if it is preceeded by a colon.

Throws:
Nothing.

Examples:

 version(Windows)
 {
     getDirName(r"d:\path\foo.bat") => r"d:\path"
     getDirName(getDirName(r"d:\path\foo.bat")) => r"d:\"
 }
 version(Posix)
 {
     getDirName("/home/user")  => "/home"
     getDirName(getDirName("/home/user"))  => ""
 }

string getDrive(string fullname);

Extracts the drive letter of a path.

This function will search fullname for a colon from the beginning.

Returns:
If a colon is found, all the characters to its left plus the colon are returned. Otherwise, null is returned.

Under Linux, this function always returns null immediately.

Throws:
Nothing.

Examples:

 getDrive(r"d:\path\foo.bat") => "d:"

string defaultExt(string filename, string ext);

Appends a default extension to a filename.

This function first searches filename for an extension and appends ext if there is none. ext should not have any leading dots, one will be inserted between filename and ext if filename doesn't already end with one.

Returns:
filename if it contains an extension, otherwise filename + ext.

Throws:
Nothing.

Examples:

 defaultExt("foo.txt", "raw") => "foo.txt"
 defaultExt("foo.", "raw") => "foo.raw"
 defaultExt("bar", "raw") => "bar.raw"

string addExt(string filename, string ext);

Adds or replaces an extension to a filename.

This function first searches filename for an extension and replaces it with ext if found. If there is no extension, ext will be appended. ext should not have any leading dots, one will be inserted between filename and ext if filename doesn't already end with one.

Returns:
filename + ext if filename is extensionless. Otherwise strips filename's extension off, appends ext and returns the result.

Throws:
Nothing.

Examples:

 addExt("foo.txt", "raw") => "foo.raw"
 addExt("foo.", "raw") => "foo.raw"
 addExt("bar", "raw") => "bar.raw"

int isabs(string path);

Checks if path is absolute.

Returns:
non-zero if the path starts from the root directory (Linux) or drive letter and root directory (Windows), zero otherwise.

Throws:
Nothing.

Examples:

 version(Windows)
 {
     isabs(r"relative\path") => 0
     isabs(r"\relative\path") => 0
     isabs(r"d:\absolute") => 1
 }
 version(Posix)
 {
     isabs("/home/user") => 1
     isabs("foo") => 0
 }

string join(string p1, string p2);

Joins two path components.

If p1 doesn't have a trailing path separator, one will be appended to it before concatting p2.

Returns:
p1 ~ p2. However, if p2 is an absolute path, only p2 will be returned.

Throws:
Nothing.

Examples:

 version(Windows)
 {
     join(r"c:\foo", "bar") => r"c:\foo\bar"
     join("foo", r"d:\bar") => r"d:\bar"
 }
 version(Posix)
 {
     join("/foo/", "bar") => "/foo/bar"
     join("/foo", "/bar") => "/bar"
 }

int fncharmatch(dchar c1, dchar c2);

Matches filename characters.

Under Windows, the comparison is done ignoring case. Under Linux an exact match is performed.

Returns:
non zero if c1 matches c2, zero otherwise.

Throws:
Nothing.

Examples:

 version(Windows)
 {
     fncharmatch('a', 'b') => 0
     fncharmatch('A', 'a') => 1
 }
 version(Posix)
 {
     fncharmatch('a', 'b') => 0
     fncharmatch('A', 'a') => 0
 }

int fnmatch(string filename, string pattern);

Matches a pattern against a filename.

Some characters of pattern have special a meaning (they are meta-characters) and can't be escaped. These are:

*	Matches 0 or more instances of any character.
?	Matches exactly one instances of any character.
[chars]	Matches one instance of any character that appears between the brackets.
[!chars]	Matches one instance of any character that does not appear between the brackets after the exclamation mark.

Internally individual character comparisons are done calling fncharmatch(), so its rules apply here too. Note that path separators and dots don't stop a meta-character from matching further portions of the filename.

Returns:
non zero if pattern matches filename, zero otherwise.

See Also:
fncharmatch().

Throws:
Nothing.

Examples:

 version(Windows)
 {
     fnmatch("foo.bar", "*") => 1
     fnmatch(r"foo/foo\bar", "f*b*r") => 1
     fnmatch("foo.bar", "f?bar") => 0
     fnmatch("Goo.bar", "[fg]???bar") => 1
     fnmatch(r"d:\foo\bar", "d*foo?bar") => 1
 }
 version(Posix)
 {
     fnmatch("Go*.bar", "[fg]???bar") => 0
     fnmatch("/foo*home/bar", "?foo*bar") => 1
     fnmatch("foobar", "foo?bar") => 1
 }

string expandTilde(string inputPath);

Performs tilde expansion in paths.

There are two ways of using tilde expansion in a path. One involves using the tilde alone or followed by a path separator. In this case, the tilde will be expanded with the value of the environment variable HOME. The second way is putting a username after the tilde (i.e. ~john/Mail). Here, the username will be searched for in the user database (i.e. /etc/passwd on Unix systems) and will expand to whatever path is stored there. The username is considered the string after the tilde ending at the first instance of a path separator.

Note that using the ~user syntax may give different values from just ~ if the environment variable doesn't match the value stored in the user database.

When the environment variable version is used, the path won't be modified if the environment variable doesn't exist or it is empty. When the database version is used, the path won't be modified if the user doesn't exist in the database or there is not enough memory to perform the query.

Returns:
inputPath with the tilde expanded, or just inputPath if it could not be expanded. For Windows, expandTilde() merely returns its argument inputPath.

Throws:
std.outofmemory.OutOfMemoryException if there is not enough memory to perform the database lookup for the ~user syntax.

Examples:

 import std.path;

 void process_file(string filename)
 {
     string path = expandTilde(filename);
     ...
 }

 import std.path;

 const string RESOURCE_DIR_TEMPLATE = "~/.applicationrc";
 string RESOURCE_DIR;    // This gets expanded in main().

 int main(string[] args)
 {
     RESOURCE_DIR = expandTilde(RESOURCE_DIR_TEMPLATE);
     ...
 }

Version:
Available since v0.143.

Authors:
Grzegorz Adam Hankiewicz, Thomas Kühne.

Placed into public domain. | Page generated by Ddoc.