class
FileException:
object.Exception;
Exception thrown for file I/O errors.
Examples:import std.exception : assertThrown;assertThrown!FileException("non.existing.file.".readText); OS error code.
pure @safe this(scope const(char)[]
name, scope const(char)[]
msg, string
file = __FILE__, size_t
line = __LINE__);
Constructor which takes an error message.
Parameters:const(char)[]name | Name of file for which the error occurred. |
const(char)[]msg | Message describing the error. |
stringfile | The file where the error occurred. |
size_tline | The line where the error occurred. |
@trusted this(scope const(char)[]
name, uint
errno = .
errno, string
file = __FILE__, size_t
line = __LINE__);
Constructor which takes the error number (
GetLastError in Windows,
errno in POSIX).
Parameters:const(char)[]name | Name of file for which the error occurred. |
uinterrno | The error number. |
stringfile | The file where the error occurred. Defaults to__FILE__. |
size_tline | The line where the error occurred. Defaults to__LINE__. |
void[]
read(R)(R
name, size_t
upTo = size_t.max)
if (isSomeFiniteCharInputRange!R && !isConvertibleToString!R);
void[]
read(R)(auto ref R
name, size_t
upTo = size_t.max)
if (isConvertibleToString!R);
Read entire contents of filename and returns it as an untypedarray. If the file size is larger thanupTo, onlyupTobytes are read.
Parameters:Rname | string or range of characters representing the file name |
size_tupTo | if present, the maximum number of bytes to read |
Returns:Untyped array of bytes read.
Examples:import std.utf : byChar;scope(exit){assert(exists(deleteme)); remove(deleteme);}std.file.write(deleteme,"1234");// deleteme is the name of a temporary filewriteln(read(deleteme, 2));// "12"writeln(read(deleteme.byChar));// "1234"writeln((cast(const(ubyte)[])read(deleteme)).length);// 4 S
readText(S = string, R)(auto ref R
name)
if (isSomeString!S && (isSomeFiniteCharInputRange!R || is(StringTypeOf!R)));
Reads and validates (using
std.utf.validate) a text file. S can be an array of any character type. However, no width or endian conversions are performed. So, if the width or endianness of the characters in the given file differ from the width or endianness of the element type of S, then validation will fail.
Parameters:| S | the string type of the file |
Rname | string or range of characters representing the file name |
Returns:Array of characters read.
Examples:Read file with UTF-8 text.
write(deleteme,"abc");// deleteme is the name of a temporary filescope(exit) remove(deleteme);string content =readText(deleteme);writeln(content);// "abc"
void
write(R)(R
name, const void[]
buffer)
if ((isSomeFiniteCharInputRange!R || isSomeString!R) && !isConvertibleToString!R);
void
write(R)(auto ref R
name, const void[]
buffer)
if (isConvertibleToString!R);
Writebuffer to filename.
Creates the file if it does not already exist.
Parameters:Rname | string or range of characters representing the file name |
void[]buffer | data to be written to file |
Examples:scope(exit){assert(exists(deleteme)); remove(deleteme);}int[] a = [ 0, 1, 1, 2, 3, 5, 8 ];write(deleteme, a);// deleteme is the name of a temporary fileconst bytes = read(deleteme);const fileInts = () @trusted {returncast(int[]) bytes; }();writeln(fileInts);// a void
append(R)(R
name, const void[]
buffer)
if ((isSomeFiniteCharInputRange!R || isSomeString!R) && !isConvertibleToString!R);
void
append(R)(auto ref R
name, const void[]
buffer)
if (isConvertibleToString!R);
Appendsbuffer to filename.
Creates the file if it does not already exist.
Parameters:Rname | string or range of characters representing the file name |
void[]buffer | data to be appended to file |
Examples:scope(exit){assert(exists(deleteme)); remove(deleteme);}int[] a = [ 0, 1, 1, 2, 3, 5, 8 ];write(deleteme, a);// deleteme is the name of a temporary fileint[] b = [ 13, 21 ];append(deleteme, b);const bytes = read(deleteme);const fileInts = () @trusted {returncast(int[]) bytes; }();writeln(fileInts);// a ~ b void
rename(RF, RT)(RF
from, RT
to)
if ((isSomeFiniteCharInputRange!RF || isSomeString!RF) && !isConvertibleToString!RF && (isSomeFiniteCharInputRange!RT || isSomeString!RT) && !isConvertibleToString!RT);
void
rename(RF, RT)(auto ref RF
from, auto ref RT
to)
if (isConvertibleToString!RF || isConvertibleToString!RT);
Rename filefrom toto, moving it between directories if required. If the target file exists, it is overwritten.
It is not possible to rename a file across different mount points or drives. On POSIX, the operation is atomic. That means, if
to already exists there will be no time period during the operation where
to is missing. See
manpage for rename for more details.
Parameters:RFfrom | string or range of characters representing the existing file name |
RTto | string or range of characters representing the target file name |
Examples:auto t1 = deleteme, t2 = deleteme~"2";scope(exit)foreach (t; [t1, t2])if (t.exists) t.remove();t1.write("1");t1.rename(t2);writeln(t2.readText);// "1"t1.write("2");t1.rename(t2);writeln(t2.readText);// "2" void
remove(R)(R
name)
if (isSomeFiniteCharInputRange!R && !isConvertibleToString!R);
void
remove(R)(auto ref R
name)
if (isConvertibleToString!R);
Delete filename.
Parameters:Rname | string or range of characters representing the file name |
Examples:import std.exception : assertThrown;deleteme.write("Hello");writeln(deleteme.readText);// "Hello"deleteme.remove;assertThrown!FileException(deleteme.readText); ulong
getSize(R)(R
name)
if (isSomeFiniteCharInputRange!R && !isConvertibleToString!R);
ulong
getSize(R)(auto ref R
name)
if (isConvertibleToString!R);
Get size of filename in bytes.
Parameters:Rname | string or range of characters representing the file name |
Returns:The size of file in bytes.
Examples:scope(exit) deleteme.remove;// create a file of size 1write(deleteme,"a");writeln(getSize(deleteme));// 1// create a file of size 3write(deleteme,"abc");writeln(getSize(deleteme));// 3
void
getTimes(R)(R
name, out SysTime
accessTime, out SysTime
modificationTime)
if (isSomeFiniteCharInputRange!R && !isConvertibleToString!R);
void
getTimes(R)(auto ref R
name, out SysTime
accessTime, out SysTime
modificationTime)
if (isConvertibleToString!R);
Get the access and modified times of file or foldername.
Parameters:Rname | File/Folder name to get times for. |
SysTimeaccessTime | Time the file/folder was last accessed. |
SysTimemodificationTime | Time the file/folder was last modified. |
Examples:import std.datetime : abs, SysTime;scope(exit) deleteme.remove;write(deleteme,"a");SysTimeaccessTime,modificationTime;getTimes(deleteme,accessTime,modificationTime);import std.datetime : Clock, seconds;auto currTime = Clock.currTime();enum leeway = 5.seconds;auto diffAccess =accessTime - currTime;auto diffModification =modificationTime - currTime;assert(abs(diffAccess) <= leeway);assert(abs(diffModification) <= leeway);
void
getTimesWin(R)(R
name, out SysTime
fileCreationTime, out SysTime
fileAccessTime, out SysTime
fileModificationTime)
if (isSomeFiniteCharInputRange!R || isConvertibleToString!R);
This function is Windows-Only.
Get creation/access/modified times of file
name.
This is the same as
getTimes except that it also gives you the file creation time - which isn't possible on POSIX systems.
Parameters:Rname | File name to get times for. |
SysTimefileCreationTime | Time the file was created. |
SysTimefileAccessTime | Time the file was last accessed. |
SysTimefileModificationTime | Time the file was last modified. |
void
setTimes(R)(R
name, SysTime
accessTime, SysTime
modificationTime)
if (isSomeFiniteCharInputRange!R && !isConvertibleToString!R);
void
setTimes(R)(auto ref R
name, SysTime
accessTime, SysTime
modificationTime)
if (isConvertibleToString!R);
Set access/modified times of file or foldername.
Parameters:Rname | File/Folder name to get times for. |
SysTimeaccessTime | Time the file/folder was last accessed. |
SysTimemodificationTime | Time the file/folder was last modified. |
Examples:import std.datetime : DateTime, hnsecs, SysTime;scope(exit) deleteme.remove;write(deleteme,"a");SysTimeaccessTime = SysTime(DateTime(2010, 10, 4, 0, 0, 30));SysTimemodificationTime = SysTime(DateTime(2018, 10, 4, 0, 0, 30));setTimes(deleteme,accessTime,modificationTime);SysTime accessTimeResolved, modificationTimeResolved;getTimes(deleteme, accessTimeResolved, modificationTimeResolved);writeln(accessTime);// accessTimeResolvedwriteln(modificationTime);// modificationTimeResolved
SysTime
timeLastModified(R)(R
name)
if (isSomeFiniteCharInputRange!R && !isConvertibleToString!R);
SysTime
timeLastModified(R)(auto ref R
name)
if (isConvertibleToString!R);
Returns the time that the given file was last modified.
Parameters:Rname | the name of the file to check |
Examples:import std.datetime : abs, DateTime, hnsecs, SysTime;scope(exit) deleteme.remove;import std.datetime : Clock, seconds;auto currTime = Clock.currTime();enum leeway = 5.seconds;deleteme.write("bb");assert(abs(deleteme.timeLastModified - currTime) <= leeway); SysTime
timeLastModified(R)(R
name, SysTime
returnIfMissing)
if (isSomeFiniteCharInputRange!R);
Returns the time that the given file was last modified. If the file does not exist, returnsreturnIfMissing.
A frequent usage pattern occurs in build automation tools such as
make or
ant. To check whether file
target must be rebuilt from file
source (i.e.,
target is older than
source or does not exist), use the comparison below. The code throws a
FileException if
source does not exist (as it should). On the other hand, the
SysTime.min default makes a non-existing
target seem infinitely old so the test correctly prompts building it.
Parameters:Rname | The name of the file to get the modification time for. |
SysTimereturnIfMissing | The time to return if the given file does not exist. |
Example
if (source.timeLastModified >= target.timeLastModified(SysTime.min)){// must (re)build}else{// target is up-to-date}Examples:import std.datetime : SysTime;writeln("file.does.not.exist".timeLastModified(SysTime.min));// SysTime.minauto source = deleteme ~"source";auto target = deleteme ~"target";scope(exit) source.remove, target.remove;source.write(".");assert(target.timeLastModified(SysTime.min) < source.timeLastModified);target.write(".");assert(target.timeLastModified(SysTime.min) >= source.timeLastModified); pure nothrow SysTime
timeLastModified()(auto ref stat_t
statbuf);
This function is POSIX-Only.
Returns the time that the given file was last modified.
Parameters:stat_tstatbuf | stat_t retrieved from file. |
pure nothrow SysTime
timeLastAccessed()(auto ref stat_t
statbuf);
This function is POSIX-Only.
Returns the time that the given file was last accessed.
Parameters:stat_tstatbuf | stat_t retrieved from file. |
pure nothrow SysTime
timeStatusChanged()(auto ref stat_t
statbuf);
This function is POSIX-Only.
Returns the time that the given file was last changed.
Parameters:stat_tstatbuf | stat_t retrieved from file. |
bool
exists(R)(R
name)
if (isSomeFiniteCharInputRange!R && !isConvertibleToString!R);
bool
exists(R)(auto ref R
name)
if (isConvertibleToString!R);
Determine whether the given file (or directory) exists.
Parameters:Rname | string or range of characters representing the file name |
Returns:true if the file name specified as input exists
Examples:auto f = deleteme ~"does.not.exist";assert(!f.exists);f.write("hello");assert(f.exists);f.remove;assert(!f.exists); uint
getAttributes(R)(R
name)
if (isSomeFiniteCharInputRange!R && !isConvertibleToString!R);
uint
getAttributes(R)(auto ref R
name)
if (isConvertibleToString!R);
Returns the attributes of the given file.
Note that the file attributes on Windows and POSIX systems are completely different. On Windows, they're what is returned by
GetFileAttributes, whereas on POSIX systems, they're the
st_mode value which is part of the
stat struct gotten by calling the
stat function.
On POSIX systems, if the given file is a symbolic link, then attributes are the attributes of the file pointed to by the symbolic link.
Parameters:Rname | The file to get the attributes of. |
Returns:The attributes of the file as auint.
Examples:getAttributes with a file
import std.exception : assertThrown;auto f = deleteme ~"file";scope(exit) f.remove;assert(!f.exists);assertThrown!FileException(f.getAttributes);f.write(".");auto attributes = f.getAttributes;assert(!attributes.attrIsDir);assert(attributes.attrIsFile); Examples:getAttributes with a directory
import std.exception : assertThrown;auto dir = deleteme ~"dir";scope(exit) dir.rmdir;assert(!dir.exists);assertThrown!FileException(dir.getAttributes);dir.mkdir;auto attributes = dir.getAttributes;assert(attributes.attrIsDir);assert(!attributes.attrIsFile);
uint
getLinkAttributes(R)(R
name)
if (isSomeFiniteCharInputRange!R && !isConvertibleToString!R);
uint
getLinkAttributes(R)(auto ref R
name)
if (isConvertibleToString!R);
If the given file is a symbolic link, then this returns the attributes of the symbolic link itself rather than file that it points to. If the given file isnot a symbolic link, then this function returns the same result as getAttributes.
On Windows, getLinkAttributes is identical to getAttributes. It exists on Windows so that you don't have to special-case code for Windows when dealing with symbolic links.
Parameters:Rname | The file to get the symbolic link attributes of. |
Examples:import std.exception : assertThrown;auto source = deleteme ~"source";auto target = deleteme ~"target";assert(!source.exists);assertThrown!FileException(source.getLinkAttributes);// symlinking isn't available on Windowsversion (Posix){scope(exit) source.remove, target.remove; target.write("target"); target.symlink(source); writeln(source.readText);// "target"assert(source.isSymlink);assert(source.getLinkAttributes.attrIsSymlink);} Examples:if the file is no symlink, getLinkAttributes behaves like getAttributes
import std.exception : assertThrown;auto f = deleteme ~"file";scope(exit) f.remove;assert(!f.exists);assertThrown!FileException(f.getLinkAttributes);f.write(".");auto attributes = f.getLinkAttributes;assert(!attributes.attrIsDir);assert(attributes.attrIsFile); Examples:if the file is no symlink, getLinkAttributes behaves like getAttributes
import std.exception : assertThrown;auto dir = deleteme ~"dir";scope(exit) dir.rmdir;assert(!dir.exists);assertThrown!FileException(dir.getLinkAttributes);dir.mkdir;auto attributes = dir.getLinkAttributes;assert(attributes.attrIsDir);assert(!attributes.attrIsFile);
void
setAttributes(R)(R
name, uint
attributes)
if (isSomeFiniteCharInputRange!R && !isConvertibleToString!R);
void
setAttributes(R)(auto ref R
name, uint
attributes)
if (isConvertibleToString!R);
Set the attributes of the given file.
For example, a programmatic equivalent of Unix'schmod +xname to make a file executable isname.setAttributes(name.getAttributes | octal!700).
Parameters:Rname | the file name |
uintattributes | the attributes to set the file to |
Examples:setAttributes with a file
import std.exception : assertThrown;import std.conv : octal;auto f = deleteme ~"file";version (Posix){scope(exit) f.remove;assert(!f.exists); assertThrown!FileException(f.setAttributes(octal!777)); f.write(".");autoattributes = f.getAttributes;assert(!attributes.attrIsDir);assert(attributes.attrIsFile); f.setAttributes(octal!777);attributes = f.getAttributes; writeln((attributes & 1023));// octal!777} Examples:setAttributes with a directory
import std.exception : assertThrown;import std.conv : octal;auto dir = deleteme ~"dir";version (Posix){scope(exit) dir.rmdir;assert(!dir.exists); assertThrown!FileException(dir.setAttributes(octal!777)); dir.mkdir;autoattributes = dir.getAttributes;assert(attributes.attrIsDir);assert(!attributes.attrIsFile); dir.setAttributes(octal!777);attributes = dir.getAttributes; writeln((attributes & 1023));// octal!777} @property bool
isDir(R)(R
name)
if (isSomeFiniteCharInputRange!R && !isConvertibleToString!R);
@property bool
isDir(R)(auto ref R
name)
if (isConvertibleToString!R);
Returns whether the given file is a directory.
Parameters:Rname | The path to the file. |
Returns:true if name specifies a directory
Examples:import std.exception : assertThrown;auto dir = deleteme ~"dir";auto f = deleteme ~"f";scope(exit) dir.rmdir, f.remove;assert(!dir.exists);assertThrown!FileException(dir.isDir);dir.mkdir;assert(dir.isDir);f.write(".");assert(!f.isDir); pure nothrow @nogc @safe bool
attrIsDir(uint
attributes);
Returns whether the given file attributes are for a directory.
Parameters:uintattributes | The file attributes. |
Returns:true if attributes specifies a directory
Examples:import std.exception : assertThrown;auto dir = deleteme ~"dir";auto f = deleteme ~"f";scope(exit) dir.rmdir, f.remove;assert(!dir.exists);assertThrown!FileException(dir.getAttributes.attrIsDir);dir.mkdir;assert(dir.isDir);assert(dir.getAttributes.attrIsDir);f.write(".");assert(!f.isDir);assert(!f.getAttributes.attrIsDir); @property bool
isFile(R)(R
name)
if (isSomeFiniteCharInputRange!R && !isConvertibleToString!R);
@property bool
isFile(R)(auto ref R
name)
if (isConvertibleToString!R);
Returns whether the given file (or directory) is a file.
On Windows, if a file is not a directory, then it's a file. So, either
isFile or
isDir will return true for any given file.
On POSIX systems, if
isFile is
true, that indicates that the file is a regular file (e.g. not a block not device). So, on POSIX systems, it's possible for both
isFile and
isDir to be
false for a particular file (in which case, it's a special file). You can use
getAttributes to get the attributes to figure out what type of special it is, or you can use
DirEntry to get at its
statBuf, which is the result from
stat. In either case, see the man page for
stat for more information.
Parameters:Rname | The path to the file. |
Returns:true if name specifies a file
Examples:import std.exception : assertThrown;auto dir = deleteme ~"dir";auto f = deleteme ~"f";scope(exit) dir.rmdir, f.remove;dir.mkdir;assert(!dir.isFile);assert(!f.exists);assertThrown!FileException(f.isFile);f.write(".");assert(f.isFile); pure nothrow @nogc @safe bool
attrIsFile(uint
attributes);
Returns whether the given file attributes are for a file.
On Windows, if a file is not a directory, it's a file. So, either
attrIsFile or
attrIsDir will return
true for the attributes of any given file.
On POSIX systems, if
attrIsFile is
true, that indicates that the file is a regular file (e.g. not a block not device). So, on POSIX systems, it's possible for both
attrIsFile and
attrIsDir to be
false for a particular file (in which case, it's a special file). If a file is a special file, you can use the attributes to check what type of special file it is (see the man page for
stat for more information).
Parameters:uintattributes | The file attributes. |
Returns:true if the given file attributes are for a file
Example
assert(attrIsFile(getAttributes("/etc/fonts/fonts.conf")));assert(attrIsFile(getLinkAttributes("/etc/fonts/fonts.conf")));Examples:import std.exception : assertThrown;auto dir = deleteme ~"dir";auto f = deleteme ~"f";scope(exit) dir.rmdir, f.remove;dir.mkdir;assert(!dir.isFile);assert(!dir.getAttributes.attrIsFile);assert(!f.exists);assertThrown!FileException(f.getAttributes.attrIsFile);f.write(".");assert(f.isFile);assert(f.getAttributes.attrIsFile); @property bool
isSymlink(R)(R
name)
if (isSomeFiniteCharInputRange!R && !isConvertibleToString!R);
@property bool
isSymlink(R)(auto ref R
name)
if (isConvertibleToString!R);
Returns whether the given file is a symbolic link.
On Windows, returnstrue when the file is either a symbolic link or a junction point.
Parameters:Rname | The path to the file. |
Returns:true if name is a symbolic link
Examples:import std.exception : assertThrown;auto source = deleteme ~"source";auto target = deleteme ~"target";assert(!source.exists);assertThrown!FileException(source.isSymlink);// symlinking isn't available on Windowsversion (Posix){scope(exit) source.remove, target.remove; target.write("target"); target.symlink(source); writeln(source.readText);// "target"assert(source.isSymlink);assert(source.getLinkAttributes.attrIsSymlink);} pure nothrow @nogc @safe bool
attrIsSymlink(uint
attributes);
Returns whether the given file attributes are for a symbolic link.
On Windows, returntrue when the file is either a symbolic link or a junction point.
Parameters:uintattributes | The file attributes. |
Returns:true if attributes are for a symbolic link
Example
core.sys.posix.unistd.symlink("/etc/fonts/fonts.conf","/tmp/alink");assert(!getAttributes("/tmp/alink").isSymlink);assert(getLinkAttributes("/tmp/alink").isSymlink);Examples:import std.exception : assertThrown;auto source = deleteme ~"source";auto target = deleteme ~"target";assert(!source.exists);assertThrown!FileException(source.getLinkAttributes.attrIsSymlink);// symlinking isn't available on Windowsversion (Posix){scope(exit) source.remove, target.remove; target.write("target"); target.symlink(source); writeln(source.readText);// "target"assert(source.isSymlink);assert(source.getLinkAttributes.attrIsSymlink);} void
chdir(R)(R
pathname)
if (isSomeFiniteCharInputRange!R && !isConvertibleToString!R);
void
chdir(R)(auto ref R
pathname)
if (isConvertibleToString!R);
Change directory topathname. Equivalent tocd onWindows and POSIX.
Parameters:Rpathname | the directory to step into |
Examples:import std.algorithm.comparison : equal;import std.algorithm.sorting : sort;import std.array : array;import std.path : buildPath;auto cwd = getcwd;auto dir = deleteme ~"dir";dir.mkdir;scope(exit) cwd.chdir, dir.rmdirRecurse;dir.buildPath("a").write(".");dir.chdir;// step into dir"b".write(".");assert(dirEntries(".", SpanMode.shallow).array.sort.equal( [".".buildPath("a"),".".buildPath("b")])); void
mkdir(R)(R
pathname)
if (isSomeFiniteCharInputRange!R && !isConvertibleToString!R);
void
mkdir(R)(auto ref R
pathname)
if (isConvertibleToString!R);
Make a new directorypathname.
Parameters:Rpathname | the path of the directory to make |
Examples:import std.file :mkdir;auto dir = deleteme ~"dir";scope(exit) dir.rmdir;dir.mkdir;assert(dir.exists);
Examples:import std.exception : assertThrown;assertThrown("a/b/c/d/e".mkdir); @safe void
mkdirRecurse(scope const(char)[]
pathname);
Make directory and all parent directories as needed.
Does nothing if the directory specified bypathname already exists.
Parameters:const(char)[]pathname | the full path of the directory to create |
Examples:import std.path : buildPath;auto dir = deleteme ~"dir";scope(exit) dir.rmdirRecurse;dir.mkdir;assert(dir.exists);dir.mkdirRecurse;// does nothing// creates all parent directories as neededauto nested = dir.buildPath("a","b","c");nested.mkdirRecurse;assert(nested.exists); Examples:import std.exception : assertThrown;scope(exit) deleteme.remove;deleteme.write("a");// cannot make directory as it's already a fileassertThrown!FileException(deleteme.mkdirRecurse); void
rmdir(R)(R
pathname)
if (isSomeFiniteCharInputRange!R && !isConvertibleToString!R);
void
rmdir(R)(auto ref R
pathname)
if (isConvertibleToString!R);
Remove directorypathname.
Parameters:Rpathname | Range or string specifying the directory name |
Examples:auto dir = deleteme ~"dir";dir.mkdir;assert(dir.exists);dir.rmdir;assert(!dir.exists);
void
symlink(RO, RL)(RO
original, RL
link)
if ((isSomeFiniteCharInputRange!RO || isConvertibleToString!RO) && (isSomeFiniteCharInputRange!RL || isConvertibleToString!RL));
This function is POSIX-Only.
Creates a symbolic link (symlink).
Parameters:ROoriginal | The file that is being linked. This is the target path that's stored in the symlink. A relative path is relative to the created symlink. |
RLlink | The symlink to create. A relative path is relative to the current working directory. |
Throws:FileException on error (which includes if the symlink already exists).
string
readLink(R)(R
link)
if (isSomeFiniteCharInputRange!R || isConvertibleToString!R);
This function is POSIX-Only.
Returns the path to the file pointed to by a symlink. Note that the path could be either relative or absolute depending on the symlink. If the path is relative, it's relative to the symlink, not the current working directory.
Get the current working directory.
Examples:auto s =getcwd();assert(s.length);
@trusted string
thisExePath();
Returns the full path of the current executable.
Returns:The path of the executable as astring.
Examples:import std.path : isAbsolute;auto path =thisExePath();assert(path.exists);assert(path.isAbsolute);assert(path.isFile);
Info on a file, similar to what you'd get from stat on a POSIX system.
@safe this(return scope string
path);
Constructs aDirEntry for the given file (or directory).
Parameters:stringpath | The file (or directory) to get a DirEntry for. |
@property @safe string
name() const return scope;
Returns the path to the file represented by thisDirEntry.
Example
auto de1 = DirEntry("/etc/fonts/fonts.conf");assert(de1.name =="/etc/fonts/fonts.conf");auto de2 = DirEntry("/usr/share/include");assert(de2.name =="/usr/share/include");@property @safe bool
isDir();
Returns whether the file represented by thisDirEntry is a directory.
Example
auto de1 = DirEntry("/etc/fonts/fonts.conf");assert(!de1.isDir);auto de2 = DirEntry("/usr/share/include");assert(de2.isDir);@property @safe bool
isFile();
Returns whether the file represented by thisDirEntry is a file.
On Windows, if a file is not a directory, then it's a file. So, either
isFile or
isDir will return
true.
On POSIX systems, if
isFile is
true, that indicates that the file is a regular file (e.g. not a block not device). So, on POSIX systems, it's possible for both
isFile and
isDir to be
false for a particular file (in which case, it's a special file). You can use
attributes or
statBuf to get more information about a special file (see the stat man page for more details).
Example
auto de1 = DirEntry("/etc/fonts/fonts.conf");assert(de1.isFile);auto de2 = DirEntry("/usr/share/include");assert(!de2.isFile);@property @safe bool
isSymlink();
Returns whether the file represented by thisDirEntry is a symbolic link.
On Windows, returntrue when the file is either a symbolic link or a junction point.
@property @safe ulong
size();
Returns the size of the file represented by thisDirEntry in bytes.
@property @safe SysTime
timeCreated() const;
This function is Windows-Only.
Returns the creation time of the file represented by thisDirEntry.
@property @safe SysTime
timeLastAccessed();
Returns the time that the file represented by thisDirEntry was last accessed.
Note that many file systems do not update the access time for files (generally for performance reasons), so there's a good chance thattimeLastAccessed will return the same value astimeLastModified.
@property @safe SysTime
timeLastModified();
Returns the time that the file represented by thisDirEntry was last modified.
@property @safe SysTime
timeStatusChanged() const;
This function is POSIX-Only.
Returns the time that the file represented by thisDirEntry was last changed (not only in contents, but also in permissions or ownership).
@property @safe uint
attributes();
Returns the attributes of the file represented by thisDirEntry.
Note that the file attributes on Windows and POSIX systems are completely different. On, Windows, they're what is returned by
GetFileAttributesGetFileAttributes Whereas, an POSIX systems, they're the
st_mode value which is part of the
stat struct gotten by calling
stat.
On POSIX systems, if the file represented by this
DirEntry is a symbolic link, then attributes are the attributes of the file pointed to by the symbolic link.
@property @safe uint
linkAttributes();
On POSIX systems, if the file represented by thisDirEntry is a symbolic link, thenlinkAttributes are the attributes of the symbolic link itself. Otherwise,linkAttributes is identical toattributes.
On Windows,linkAttributes is identical toattributes. It exists on Windows so that you don't have to special-case code for Windows when dealing with symbolic links.
@property @safe stat_t
statBuf();
This function is POSIX-Only.
Thestat struct gotten from callingstat.
PreserveAttributes
preserveAttributesDefault;
Defaults toYes.preserveAttributes on Windows, and the opposite on all other platforms.
void
copy(RF, RT)(RF
from, RT
to, PreserveAttributes
preserve = preserveAttributesDefault)
if (isSomeFiniteCharInputRange!RF && !isConvertibleToString!RF && isSomeFiniteCharInputRange!RT && !isConvertibleToString!RT);
void
copy(RF, RT)(auto ref RF
from, auto ref RT
to, PreserveAttributes
preserve = preserveAttributesDefault)
if (isConvertibleToString!RF || isConvertibleToString!RT);
Copy filefrom to fileto. File timestamps are preserved.File attributes are preserved, ifpreserve equalsYes.preserveAttributes.On Windows onlyYes.preserveAttributes (the default on Windows) is supported.If the target file exists, it is overwritten.
Parameters:RFfrom | string or range of characters representing the existing file name |
RTto | string or range of characters representing the target file name |
PreserveAttributespreserve | whether to preserve the file attributes |
Examples:auto source = deleteme ~"source";auto target = deleteme ~"target";auto targetNonExistent = deleteme ~"target2";scope(exit) source.remove, target.remove, targetNonExistent.remove;source.write("source");target.write("target");writeln(target.readText);// "target"source.copy(target);writeln(target.readText);// "source"source.copy(targetNonExistent);writeln(targetNonExistent.readText);// "source" @safe void
rmdirRecurse(scope const(char)[]
pathname);
@safe void
rmdirRecurse(ref scope DirEntry
de);
@safe void
rmdirRecurse(scope DirEntry
de);
Remove directory and all of its content and subdirectories, recursively.
Parameters:const(char)[]pathname | the path of the directory to completely remove |
DirEntryde | TheDirEntry to remove |
Throws:FileException if there is an error (including if the given file is not a directory).
Examples:import std.path : buildPath;auto dir = deleteme.buildPath("a","b","c");dir.mkdirRecurse;assert(dir.exists);deleteme.rmdirRecurse;assert(!dir.exists);assert(!deleteme.exists); Dictates directory spanning policy fordirEntries (see below).
Examples:import std.algorithm.comparison : equal;import std.algorithm.iteration : map;import std.algorithm.sorting : sort;import std.array : array;import std.path : buildPath, relativePath;auto root = deleteme ~"root";scope(exit) root.rmdirRecurse;root.mkdir;root.buildPath("animals").mkdir;root.buildPath("animals","cat").mkdir;alias removeRoot = (returnscope e) => e.relativePath(root);assert(root.dirEntries(SpanMode.depth).map!removeRoot.equal( [buildPath("animals","cat"),"animals"]));assert(root.dirEntries(SpanMode.breadth).map!removeRoot.equal( ["animals", buildPath("animals","cat")]));root.buildPath("plants").mkdir;assert(root.dirEntries(SpanMode.shallow).array.sort.map!removeRoot.equal( ["animals","plants"])); Only spans one directory.
Spans the directory in
depth-firstpost-order, i.e. the content of any subdirectory is spanned before that subdirectory itself. Useful e.g. when recursively deleting files.
Spans the directory in
depth-firstpre-order, i.e. the content of any subdirectory is spanned right after that subdirectory itself.
Note that
SpanMode.breadth will not result in all directory members occurring before any subdirectory members, i.e. it is not true
breadth-first traversal.
auto
dirEntries(bool useDIP1000 = dip1000Enabled)(string
path, SpanMode
mode, bool
followSymlink = true);
auto
dirEntries(bool useDIP1000 = dip1000Enabled)(string
path, string
pattern, SpanMode
mode, bool
followSymlink = true);
Returns an
input range of
DirEntry that lazily iterates a given directory, also provides two ways of foreach iteration. The iteration variable can be of type
string if only the name is needed, or
DirEntry if additional details are needed. The span mode dictates how the directory is traversed. The name of each iterated directory entry contains the absolute or relative path (depending on pathname).
NoteThe order of returned directory entries is as it is provided by the operating system / filesystem, and may not follow any particular sorting.
Parameters:| useDIP1000 | used to instantiate this function separately for code with and without -preview=dip1000 compiler switch, because it affects the ABI of this function. Set automatically - don't touch. |
stringpath | The directory to iterate over. If empty, the current directory will be iterated. |
stringpattern | Optional string with wildcards, such as "*.d". When present, it is used to filter the results by their file name. The supported wildcard strings are described under std.path.globMatch. |
SpanModemode | Whether the directory's sub-directories should be iterated in depth-first post-order (depth), depth-first pre-order (breadth), or not at all (shallow). |
boolfollowSymlink | Whether symbolic links which point to directories should be treated as directories and their contents iterated over. |
Throws:- FileException if thepath directory does not exist or read permission is denied.
- FileException ifmode is notshallow and a subdirectory cannot be read.
Example
// Iterate a directory in depthforeach (string name;dirEntries("destroy/me", SpanMode.depth)){ remove(name);}// Iterate the current directory in breadthforeach (string name;dirEntries("", SpanMode.breadth)){ writeln(name);}// Iterate a directory and get detailed info about itforeach (DirEntry e;dirEntries("dmd-testing", SpanMode.breadth)){ writeln(e.name,"\t", e.size);}// Iterate over all *.d files in current directory and all its subdirectoriesauto dFiles =dirEntries("", SpanMode.depth).filter!(f => f.name.endsWith(".d"));foreach (d; dFiles) writeln(d.name);// Hook it up with std.parallelism to compile them all in parallel:foreach (d; parallel(dFiles, 1))//passes by 1 file to each thread{ string cmd ="dmd -c " ~ d.name; writeln(cmd); std.process.executeShell(cmd);}// Iterate over all D source files in current directory and all its// subdirectoriesauto dFiles =dirEntries("","*.{d,di}",SpanMode.depth);foreach (d; dFiles) writeln(d.name);To handle subdirectories with denied read permission, use
SpanMode.shallow:
void scan(stringpath){foreach (DirEntry entry;dirEntries(path, SpanMode.shallow)) {try { writeln(entry.name);if (entry.isDir) scan(entry.name); }catch (FileException fe) {continue; }// ignore }}scan("");Examples:Duplicate functionality of D1's
std.file.listdir():
string[] listdir(string pathname){import std.algorithm.iteration : map, filter;import std.array : array;import std.path : baseName;returndirEntries(pathname, SpanMode.shallow) .filter!(a => a.isFile) .map!((return a) => baseName(a.name)) .array;}// Can be safe only with -preview=dip1000@safevoid main(string[] args){import std.stdio : writefln; string[] files = listdir(args[1]); writefln("%s", files);} Select!(Types.length == 1, Types[0][], Tuple!Types[])
slurp(Types...)(string
filename, scope const(char)[]
format);
Reads a file line by line and parses the line into a single value or a
std.typecons.Tuple of values depending on the length of
Types. The lines are parsed using the specified format string. The format string is passed to
std.format.formattedRead, and therefore must conform to the format string specification outlined in
std.format.
Parameters:| Types | the types that each of the elements in the line should be returned as |
stringfilename | the name of the file to read |
const(char)[]format | the format string to use when reading |
Returns:If only one type is passed, then an array of that type. Otherwise, an array of
std.typecons.Tuples.
Throws:Exception if the format string is malformed. Also, throws
Exception if any of the lines in the file are not fully consumed by the call to
std.format.formattedRead. Meaning that no empty lines or lines with extra characters are allowed.
Examples:import std.typecons : tuple;scope(exit){assert(exists(deleteme)); remove(deleteme);}write(deleteme,"12 12.25\n345 1.125");// deleteme is the name of a temporary file// Load file; each line is an int followed by comma, whitespace and a// double.auto a =slurp!(int,double)(deleteme,"%s %s");writeln(a.length);// 2writeln(a[0]);// tuple(12, 12.25)writeln(a[1]);// tuple(345, 1.125) @trusted string
tempDir();
Returns the path to a directory for temporary files.On POSIX platforms, it searches through the following list of directoriesand returns the first one which is found to exist:
- The directory given by theTMPDIR environment variable.
- The directory given by theTEMP environment variable.
- The directory given by theTMP environment variable.
- /tmp/
- /var/tmp/
- /usr/tmp/
On all platforms,
tempDir returns the current working directory on failure.
The return value of the function is cached, so the procedures describedbelow will only be performed the first time the function is called. Allsubsequent runs will return the same string, regardless of whetherenvironment variables and directory structures have changed in themeantime.
The POSIX
tempDir algorithm is inspired by Python's
tempfile.tempdir.
Returns:On Windows, this function returns the result of calling the Windows API function
GetTempPath.
On POSIX platforms, it searches through the following list of directories and returns the first one which is found to exist:
- The directory given by theTMPDIR environment variable.
- The directory given by theTEMP environment variable.
- The directory given by theTMP environment variable.
- /tmp
- /var/tmp
- /usr/tmp
On all platforms,
tempDir returns
"." on failure, representing the current working directory.
Examples:import std.ascii : letters;import std.conv : to;import std.path : buildPath;import std.random : randomSample;import std.utf : byCodeUnit;// random id with 20 lettersauto id = letters.byCodeUnit.randomSample(20).to!string;auto myFile =tempDir.buildPath(id ~"my_tmp_file");scope(exit) myFile.remove;myFile.write("hello");writeln(myFile.readText);// "hello" @safe ulong
getAvailableDiskSpace(scope const(char)[]
path);
Returns the available disk space based on a given path.On Windows,path must be a directory; on POSIX systems, it can be a file or directory.
Parameters:const(char)[]path | on Windows, it must be a directory; on POSIX it can be a file or directory |
Returns:Available space in bytes
Examples:import std.exception : assertThrown;auto space =getAvailableDiskSpace(".");assert(space > 0);assertThrown!FileException(getAvailableDiskSpace("ThisFileDoesNotExist123123"));
