(翻译)Phobos 2.029 P部 std.path

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()).
该模块操作文件名，所有的操作均针对string，没有输入/输出操作。这意味着假如path是一个包含句点的目录名，则象getExt()这样的方法就会把它当成一个文件.要区分这种情况，先用std.file模块(如std.file.isDir())。
Authors:
作者：
Walter Bright, Grzegorz Adam Hankiewicz, Thomas Kühne, Andrei Alexandrescu 
invariant char[1u] sep;           
String used to separate directory names in a path. Under Windows this is a backslash, under Linux a slash.
以不变量字符串形式返回目录分隔符。Windows下为 '\' ，Linux 下为 '/'  。
invariant char[1u] altsep;          
Alternate version of sep[] used in Windows (a slash). Under Linux this is empty.
以不变量字符串形式返回备选目录分隔符。Windows下为 '/' ，Linux 下为空格 。
invariant char[1u] pathsep;          
Path separator string. A semi colon under Windows, a colon under Linux.
以不变量字符串形式返回路径分隔符。Windows下为 ';' , Linux 下为 ':' 。
invariant char[2u] linesep;          
String used to separate lines. String used to separate lines, \r\n under Windows and \n under Linux.
以不变量字符串形式返回行分隔符。Windows下为 \r\n ，Linux 下为 \n 。
invariant char[1u] curdir;          
String representing the current directory.
以不变量字符串形式返回返回当前目录。
invariant char[2u] pardir;          
String representing the parent directory.
以不变量字符串形式返回父目录。
alias fcmp;            
Compare file names.
比较文件名。
Returns: 返回值：           
< 0 
0 filename1 == filename2 //文件名相同        
> 0 
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.
该方法在fullname中自尾向前查找，直至遇到的第一个句点 、路径分隔符或者第一个字符。Window下遇到磁盘分隔符（:）时终止查找。
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.
如果找到句点，返回句点之右的字符串；否则，如果找到路径分隔符，或fullname未包含句点或路径分隔符时，均返回null。
Throws:抛出异常：
Nothing.  无           
Examples:示例：
version(Win32) 　 　 　 　 　 　 　 　 　 　 　
{
     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.
该方法在fullname中自尾向前查找，直至遇到的第一个句点 、路径分隔符或者第一个字符。Window下遇到磁盘分隔符（:）时终止查找。
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.
如果找到句点，返回句点之左的字符串；否则，如果找到路径分隔符，或fullname未包含句点或路径分隔符时，均返回null。
Throws:抛出异常：
Nothing. 无
Examples:示例：
version(Win32)
{ 　 　 　 　 　 　 　 　 　 　 　 　
     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/" 　 　 　 　 　 　 　
}
string basename(string fullname, string 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.
该方法在fullname中自尾向前查找，直至遇到的第一个路径分隔符或者第一个字符。Window下遇到磁盘分隔符（:）时终止查找。如果找到路径分隔符，保留分隔符之后的部分；否则返回整个fullname.如果分隔符之右的部门包含后缀扩展名，移除后缀再返回剩余部分字符串。
Returns:返回值：
The portion of fullname left after the path part and the extension part, if any, have been removed.
返回fullname之中最后一个分隔符与扩展名（如有，被移除）之间的部分。
Throws:抛出异常：
Nothing. 无
Examples:示例：
version(Win32)
{
     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.
Basename方法的别名，为向后兼容而保留，新代码应该使用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.
该方法在fullname中自尾向前查找，直至遇到的第一个路径分隔符或者第一个字符。Window下遇到磁盘分隔符（:）时终止查找。
Returns:
If a path separator was found, all the characters to its left are returned. Otherwise, "." is returned.
如果找到路径分隔符，其左边所有字符被返回；否则返回"."。
Under Windows, the found path separator will be included in the returned string if it is preceeded by a colon.
Windows下紧跟在磁盘分隔符(:)之后的路径分隔符包含则返回值中。
Throws:抛出异常：
Nothing. 无
Examples:示例：
version(Win32)
{
     assert(dirname(r"d:\path\foo.bat") == r"d:\path");
     assert(dirname(dirname(r"d:\path\foo.bat")) == r"d:\");
}
version(Posix)
{
     assert(dirname("/home/user") == "/home");
     assert(dirname(dirname("/home/user")) == "");
}
alias getDirName; 
Alias for dirname, kept for backward compatibility. New code should use dirname.
dirname方法的别名，为向后兼容而保留，新代码应该使用dirname方法。
String getDrive(String)(String fullname); 
Extracts the drive letter of a path.
提取路径中的盘符。
This function will search fullname for a colon from the beginning.
该方法在fullname中从头开始查找冒号(:)。
Returns:返回值：
If a colon is found, all the characters to its left plus the colon are returned. Otherwise, null is returned.
如找到冒号(:)，其左边所字符连同其本身一起返回，如未找到则返回null。
Under Linux, this function always returns null immediately.
Linux下该方法只会返回null。
Throws:抛出异常：
Nothing. 无
Examples:示例：
getDrive(r"d:\path\foo.bat") => "d:"
string defaultExt(string filename, string ext); 
Appends a default extension to a filename.
给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.
该方法首先在filename中查找扩展名，如未找到则添加ext为其扩展名。ext不能有前导句点，如filename末尾有句点，直接添加ext;如filename末尾无句点，则添加句点+ext。
Returns:返回值：
filename if it contains an extension, otherwise filename + ext.
如filename已包含扩展名，则返回filename;否则返回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.
给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.
该方法首先在filename中查找扩展名，如找到则用ext替换原扩展名；如未找到则添加ext为其扩展名，添加时ext不能有前导句点，如filename末尾有句点，直接添加ext;如filename末尾无句点，则添加句点+ext。
Returns:返回值：
filename + ext if filename is extensionless. Otherwise strips filename's extension off, appends ext and returns the result.
如filename无扩展名，返回filename+ext;否则去掉扩展名，添加ext为其扩展名然后返回整个字符串。
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.
检查path是否为绝对路径。
Returns:返回值：
non-zero if the path starts from the root directory (Linux) or drive letter and root directory (Windows), zero otherwise.
Linux下如果path以根目录开始，返回非零值，Windows下如果path以盘符+根目录开始，返回非零值；否则返回0。
Throws:抛出异常：
Nothing. 无
Examples:示例：
version(Win32)
{
     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.
把相对路径path转换为绝对路径。
string join(in char[] p1, in char[] p2, in char[][] more...); 
Joins two or more path components.
把两个及以上路径p1,p2…more 连接成一个路径。
If p1 doesn't have a trailing path separator, one will be appended to it before concatenating p2.
如果p1末尾未包含路径分隔符，方法在连接之前添加路径分隔符然后连接。
Returns:返回值：
p1 ~ p2. However, if p2 is an absolute path, only p2 will be returned.
如果p2为绝对路径，则返回p2;否则返回p1~p2…. 。
Throws:抛出异常：
Nothing. 无
Examples:示例：
version(Win32)
{
     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.
对比时Windows下不区分大小写；Linux下区分大小写。
Returns:返回值：
non zero if c1 matches c2, zero otherwise.
匹配返回非零值，否则返回0。
Throws:抛出异常：
Nothing. 无
Examples:示例：
version(Win32)
{
     fncharmatch('a', 'b') => 0
     fncharmatch('A', 'a') => 1
}
version(Posix)
{
     fncharmatch('a', 'b') => 0
     fncharmatch('A', 'a') => 0
}
bool fnmatch(in char[] filename, in char[] pattern); 
Matches a pattern against a filename.
在filename中匹配pattern。
Some characters of pattern have special a meaning (they are meta-characters) and can't be escaped. These are:
有些字符含有特殊的意义（它们是元字符），不能转义。它们是：
*
?
[chars]       [字符]
[!chars]     [!字符]

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.
方法内部单个字符的比较调用fncharmath(),所有前者的匹配规则在这时也适用。请留意路径分隔符和句点不阻止元字符在filename的后续部分继续匹配。

Returns:返回值：
non zero if pattern matches filename, zero otherwise.
如匹配返回非零值；否则返回0。

See Also:参见：
fncharmatch(). 

Throws:抛出异常：
Nothing. 无

Examples:示例：
version(Win32)
{
     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.
有两种方法应用代字符。第一种方法是单用代字符~后跟路径分隔符，这种情况代字符将被扩展为系统环境变量HOME的值；第二种方法是代字符后加用户名（即~john/Mail）。这种情况首先将在用户数据库（即 Unix 系统下 /etc/passwd）中查找该用户名，然后扩展为其存贮的实际路径。用户名被认定为代字符与第一个路径分隔符之间的字符串。
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.
请留意如果环境变量与存贮在用户数据库中的值不匹配时，使用~user的语法和只用~的结果可能不一致。
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.
代字符扩展后的inputPath，当inputPath不能被扩展时，返回inputPath;Window下仅仅返回inputPath。
Throws:抛出异常：
std.outofmemory.OutOfMemoryException if there is not enough memory to perform the database lookup for the ~user syntax.
使用~user 语法版本时，如果没有足够内存查寻数据库，抛出std.outofmemory.OutOfMemoryException异常。
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.
自v0.143起可用。
Authors:作者：
Grzegorz Adam Hankiewicz, Thomas Kühne. 

评论

1 楼 hqs7636 2009-04-23  

不错，速度很快