std.path

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()).

License:
Boost License 1.0.

Authors:
Walter Bright, Grzegorz Adam Hankiewicz, Thomas Kühne, Bill Baxter, Andrei Alexandrescu

Source:
std/path.d

string sep;

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

string altsep;

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

string pathsep;

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

string linesep;

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

string curdir;

String representing the current directory.

string pardir;

String representing the parent directory.

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") => "d:\path"
     getName("/home/user/.resource") => "/home/user/"
 }

Char[] basename(Char, ExtChar = immutable(char))(Char[] fullname, ExtChar[] extension = null);

Extracts the base name of a path and optionally chops off a specific suffix.

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. After the search has ended, keep the portion to the right of the separator if found, or the entire fullname otherwise. If the kept portion has suffix extension, remove that suffix. Return the remaining string.

Returns:
The portion of fullname left after the path part and the extension part, if any, have been removed.

Throws:
Nothing.

Examples:

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

alias getBaseName;

Alias for basename, kept for backward compatibility. New code should use basename.

Char[] dirname(Char)(Char[] 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 without any trailing path separators are returned. Otherwise, "." is returned.

The found path separator will be included in the returned string if and only if it represents the root.

Throws:
Nothing.

Examples:

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

alias getDirName;

Alias for dirname, kept for backward compatibility. New code should use dirname.

Char[] getDrive(Char)(Char[] 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"

bool isabs(in char[] 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 rel2abs(string path);

Converts a relative path into an absolute path.

string join(const(char)[] p1, const(char)[] p2, const(char)[][] more...);

Joins two or more path components.

If p1 doesn't have a trailing path separator, one will be appended to it before concatenating 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"
 }

bool 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
 }

bool fnmatch(const(char)[] filename, const(char)[] 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;

 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.

Copyright Digital Mars 2000-. | Page generated by Ddoc.