Menu

- Learn
- Documentation
  - Language Reference
  - Library Reference
  - Command-line Reference
  - Feature Overview
  - Articles
- Packages
- Community
  - Blog
  - Orgs using D
  - Twitter
  - Forums
  - IRC
  - Wiki
  - GitHub
  - Issues
  - Foundation
  - Donate
- Resources
  - Books
  - Tutorials
  - Tools
  - Editors
  - IDEs
  - Visual D
  - Acknowledgments
  - D Style
  - Glossary
  - Sitemap

Search
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

# std.file

Utilities for manipulating files and scanning directories. Functions in this module handle files as a unit, e.g., read or write one file at a time. For opening files and manipulating them via handles refer to module std.stdio.

Category | Functions
--- | ---
General | exists isDir isFile isSymlink rename thisExePath
Directories | chdir dirEntries getcwd mkdir mkdirRecurse rmdir rmdirRecurse tempDir
Files | append copy read readText remove slurp write
Symlinks | symlink readLink
Attributes | attrIsDir attrIsFile attrIsSymlink getAttributes getLinkAttributes getSize setAttributes
Timestamp | getTimes getTimesWin setTimes timeLastModified
Other | DirEntry FileException PreserveAttributes SpanMode

See Also:
The official tutorial for an introduction to working with files in D, module std.stdio for opening files and manipulating them via handles, and module std.path for manipulating path strings.
License:
Boost License 1.0.
Authors:
Walter Bright, Andrei Alexandrescu, Jonathan M Davis

Source: std/file.d

class `FileException`: object.Exception;
  Exception thrown for file I/O errors.
  immutable uint `errno`;
    OS error code.
  pure @safe this(in char[] `name`, in char[] `msg`, string `file` = __FILE__, size_t `line` = __LINE__);
    Constructor which takes an error message.
    Parameters:

    char[] `name` | Name of `file` for which the error occurred.
    char[] `msg` | Message describing the error.
    string `file` | The `file` where the error occurred.
    size_t `line` | The `line` where the error occurred.

  @trusted this(in 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:

    char[] `name` | Name of `file` for which the error occurred.
    uint `errno` | The error number.
    string `file` | The `file` where the error occurred. Defaults to __FILE__.
    size_t `line` | The `line` where the error occurred. Defaults to __LINE__.

void[] `read`(R)(R `name`, size_t `upTo` = size_t.max)
if (isInputRange!R && isSomeChar!(ElementEncodingType!R) && !isInfinite!R && !isConvertibleToString!R);
void[] `read`(R)(auto ref R `name`, size_t `upTo` = size_t.max)
if (isConvertibleToString!R);
  Read entire contents of file `name` and returns it as an untyped array. If the file size is larger than `upTo`, only `upTo` bytes are `read`.
  Parameters:

  R `name` | string or range of characters representing the file name
  size_t `upTo` | if present, the maximum number of bytes to `read`

  Returns:
  Untyped array of bytes read.
  Throws:
  FileException on error.
  Examples:

      import std.utf : byChar;
      scope(exit)
      {
          assert(exists(deleteme));
          remove(deleteme);
      }

      write(deleteme, "1234"); // deleteme is the name of a temporary file
      assert(read(deleteme, 2) == "12");
      assert(read(deleteme.byChar) == "1234");
      assert((cast(const(ubyte)[])read(deleteme)).length == 4);

S `readText`(S = string, R)(R `name`)
if (isSomeString!S && (isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!R) || isSomeString!R) && !isConvertibleToString!R);
S `readText`(S = string, R)(auto ref R `name`)
if (isConvertibleToString!R);
  Read and validates (using std.utf.validate) a text file. S can be a type of array of characters of any width and constancy. No width conversion is performed; if the width of the characters in file `name` is different from the width of elements of S, validation will fail.
  Parameters:

  R `name` | string or range of characters representing the file name

  Returns:
  Array of characters read.
  Throws:
  FileException on file error, UTFException on UTF decoding error.
  Examples:

      import std.exception : enforce;
      write(deleteme, "abc"); // deleteme is the name of a temporary file
      scope(exit) remove(deleteme);
      string content = readText(deleteme);
      enforce(content == "abc");

void `write`(R)(R `name`, const void[] `buffer`)
if ((isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!R) || isSomeString!R) && !isConvertibleToString!R);
void `write`(R)(auto ref R `name`, const void[] `buffer`)
if (isConvertibleToString!R);
  Write `buffer` to file `name`.
  Creates the file if it does not already exist.
  Parameters:

  R `name` | string or range of characters representing the file name
  void[] `buffer` | data to be written to file

  Throws:
  FileException on error.
  See Also:
  std.stdio.toFile
  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 file
      assert(cast(int[]) read(deleteme) == a);

void `append`(R)(R `name`, const void[] `buffer`)
if ((isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!R) || isSomeString!R) && !isConvertibleToString!R);
void `append`(R)(auto ref R `name`, const void[] `buffer`)
if (isConvertibleToString!R);
  Appends `buffer` to file `name`.
  Creates the file if it does not already exist.
  Parameters:

  R `name` | string or range of characters representing the file name
  void[] `buffer` | data to be appended to file

  Throws:
  FileException on error.
  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 file
      int[] b = [ 13, 21 ];
      append(deleteme, b);
      assert(cast(int[]) read(deleteme) == a ~ b);

void `rename`(RF, RT)(RF `from`, RT `to`)
if ((isInputRange!RF && !isInfinite!RF && isSomeChar!(ElementEncodingType!RF) || isSomeString!RF) && !isConvertibleToString!RF && (isInputRange!RT && !isInfinite!RT && isSomeChar!(ElementEncodingType!RT) || isSomeString!RT) && !isConvertibleToString!RT);
void `rename`(RF, RT)(auto ref RF `from`, auto ref RT `to`)
if (isConvertibleToString!RF || isConvertibleToString!RT);
  Rename file `from` `to` `to`. If the target file exists, it is overwritten.
  Parameters:

  RF `from` | string or range of characters representing the existing file name
  RT `to` | string or range of characters representing the target file name

  Throws:
  FileException on error.
void `remove`(R)(R `name`)
if (isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!R) && !isConvertibleToString!R);
void `remove`(R)(auto ref R `name`)
if (isConvertibleToString!R);
  Delete file `name`.
  Parameters:

  R `name` | string or range of characters representing the file `name`

  Throws:
  FileException on error.
ulong `getSize`(R)(R `name`)
if (isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!R) && !isConvertibleToString!R);
ulong `getSize`(R)(auto ref R `name`)
if (isConvertibleToString!R);
  Get size of file `name` in bytes.
  Parameters:

  R `name` | string or range of characters representing the file `name`

  Throws:
  FileException on error (e.g., file not found).
void `getTimes`(R)(R `name`, out SysTime `accessTime`, out SysTime `modificationTime`)
if (isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!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 folder `name`.
  Parameters:

  R `name` | File/Folder `name` to get times for.
  SysTime `accessTime` | Time the file/folder was last accessed.
  SysTime `modificationTime` | Time the file/folder was last modified.

  Throws:
  FileException on error.
void `getTimesWin`(R)(R `name`, out SysTime `fileCreationTime`, out SysTime `fileAccessTime`, out SysTime `fileModificationTime`)
if (isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!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:

  R `name` | File `name` to get times for.
  SysTime `fileCreationTime` | Time the file was created.
  SysTime `fileAccessTime` | Time the file was last accessed.
  SysTime `fileModificationTime` | Time the file was last modified.

  Throws:
  FileException on error.
void `setTimes`(R)(R `name`, SysTime `accessTime`, SysTime `modificationTime`)
if (isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!R) && !isConvertibleToString!R);
void `setTimes`(R)(auto ref R `name`, SysTime `accessTime`, SysTime `modificationTime`)
if (isConvertibleToString!R);
  Set access/modified times of file or folder `name`.
  Parameters:

  R `name` | File/Folder `name` to get times for.
  SysTime `accessTime` | Time the file/folder was last accessed.
  SysTime `modificationTime` | Time the file/folder was last modified.

  Throws:
  FileException on error.
SysTime `timeLastModified`(R)(R `name`)
if (isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!R) && !isConvertibleToString!R);
SysTime `timeLastModified`(R)(auto ref R `name`)
if (isConvertibleToString!R);
  Returns the time that the given file was last modified.
  Throws:
  FileException if the given file does not exist.
SysTime `timeLastModified`(R)(R `name`, SysTime `returnIfMissing`)
if (isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!R));
  Returns the time that the given file was last modified. If the file does not exist, returns `returnIfMissing`.
  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:

  R `name` | The `name` of the file to get the modification time for.
  SysTime `returnIfMissing` | The time to return if the given file does not exist.

  Example:

      if (timeLastModified(source) >= timeLastModified(target, SysTime.min))
      {
          // must (re)build
      }
      else
      {
          // target is up-to-date
      }

bool `exists`(R)(R `name`)
if (isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!R) && !isConvertibleToString!R);
bool `exists`(R)(auto ref R `name`)
if (isConvertibleToString!R);
  Determine whether the given file (or directory) `exists`.
  Parameters:

  R `name` | string or range of characters representing the file `name`

  Returns:
  `true` if the filename specified as input `exists`
uint `getAttributes`(R)(R `name`)
if (isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!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:

  R `name` | The file to get the attributes of.

  Throws:
  FileException on error.
uint `getLinkAttributes`(R)(R `name`)
if (isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!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 is not 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:

  R `name` | The file to get the symbolic link attributes of.

  Returns:
  the attributes
  Throws:
  FileException on error.
void `setAttributes`(R)(R `name`, uint `attributes`)
if (isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!R) && !isConvertibleToString!R);
void `setAttributes`(R)(auto ref R `name`, uint `attributes`)
if (isConvertibleToString!R);
  Set the `attributes` of the given file.
  Parameters:

  R `name` | the file `name`
  uint `attributes` | the `attributes` to set the file to

  Throws:
  FileException if the given file does not exist.
@property bool `isDir`(R)(R `name`)
if (isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!R) && !isConvertibleToString!R);
@property bool `isDir`(R)(auto ref R `name`)
if (isConvertibleToString!R);
  Returns whether the given file is a directory.
  Parameters:

  R `name` | The path to the file.

  Returns:
  `true` if the `name` specifies a directory
  Throws:
  FileException if the given file does not exist.

  Example:

      assert(!"/etc/fonts/fonts.conf".isDir);
      assert("/usr/share/include".isDir);

pure nothrow @nogc @safe bool `attrIsDir`(uint `attributes`);
  Returns whether the given file `attributes` are for a directory.
  Parameters:

  uint `attributes` | The file `attributes`.

  Returns:
  `true` if attibutes specifies a directory

  Example:

      assert(!attrIsDir(getAttributes("/etc/fonts/fonts.conf")));
      assert(!attrIsDir(getLinkAttributes("/etc/fonts/fonts.conf")));

@property bool `isFile`(R)(R `name`)
if (isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!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:

  R `name` | The path to the file.

  Returns:
  `true` if `name` specifies a file
  Throws:
  FileException if the given file does not exist.

  Example:

      assert("/etc/fonts/fonts.conf".isFile);
      assert(!"/usr/share/include".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:

  uint `attributes` | 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")));

@property bool `isSymlink`(R)(R `name`)
if (isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!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, returns `true` when the file is either a symbolic link or a junction point.
  Parameters:

  R `name` | The path to the file.

  Returns:
  `true` if `name` is a symbolic link
  Throws:
  FileException if the given file does not exist.
pure nothrow @nogc @safe bool `attrIsSymlink`(uint `attributes`);
  Returns whether the given file `attributes` are for a symbolic link.
  On Windows, return `true` when the file is either a symbolic link or a junction point.
  Parameters:

  uint `attributes` | 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);

void `chdir`(R)(R `pathname`)
if (isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!R) && !isConvertibleToString!R);
void `chdir`(R)(auto ref R `pathname`)
if (isConvertibleToString!R);
  Change directory to `pathname`.
  Throws:
  FileException on error.
void `mkdir`(R)(R `pathname`)
if (isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!R) && !isConvertibleToString!R);
void `mkdir`(R)(auto ref R `pathname`)
if (isConvertibleToString!R);
  Make directory `pathname`.
  Throws:
  FileException on Posix or WindowsException on Windows if an error occured.
@safe void `mkdirRecurse`(in char[] `pathname`);
  Make directory and all parent directories as needed.
  Does nothing if the directory specified by `pathname` already exists.
  Throws:
  FileException on error.
void `rmdir`(R)(R `pathname`)
if (isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!R) && !isConvertibleToString!R);
void `rmdir`(R)(auto ref R `pathname`)
if (isConvertibleToString!R);
  Remove directory `pathname`.
  Parameters:

  R `pathname` | Range or string specifying the directory name

  Throws:
  FileException on error.
void `symlink`(RO, RL)(RO `original`, RL `link`)
if ((isInputRange!RO && !isInfinite!RO && isSomeChar!(ElementEncodingType!RO) || isConvertibleToString!RO) && (isInputRange!RL && !isInfinite!RL && isSomeChar!(ElementEncodingType!RL) || isConvertibleToString!RL));
  This function is Posix-Only.
  Creates a symbolic link (symlink).
  Parameters:

  RO `original` | 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.
  RL `link` | 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 (isInputRange!R && !isInfinite!R && isSomeChar!(ElementEncodingType!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.
  Throws:
  FileException on error.
string `getcwd`();
  Get the current working directory.
  Throws:
  FileException on error.
@trusted string `thisExePath`();
  Returns the full path of the current executable.
  Throws:
  std.object.Exception
struct `DirEntry`;
  Info on a file, similar to what you'd get from stat on a Posix system.
  this(string `path`);
    Constructs a DirEntry for the given file (or directory).
    Parameters:

    string `path` | The file (or directory) to get a DirEntry for.

    Throws:
    FileException if the file does not exist.
  const @property string `name`();
    Returns the path to the file represented by this DirEntry.

    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 bool `isDir`();
    Returns whether the file represented by this DirEntry is a directory.

    Example:

        auto de1 = DirEntry("/etc/fonts/fonts.conf");
        assert(!de1.isDir);

        auto de2 = DirEntry("/usr/share/include");
        assert(de2.isDir);

  @property bool `isFile`();
    Returns whether the file represented by this DirEntry 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 bool `isSymlink`();
    Returns whether the file represented by this DirEntry is a symbolic link.
    On Windows, return `true` when the file is either a symbolic link or a junction point.
  @property ulong `size`();
    Returns the `size` of the the file represented by this DirEntry in bytes.
  const @property SysTime `timeCreated`();
    This function is Windows-Only.
    Returns the creation time of the file represented by this DirEntry.
  @property SysTime `timeLastAccessed`();
    Returns the time that the file represented by this DirEntry 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 that `timeLastAccessed` will return the same value as timeLastModified.
  @property SysTime `timeLastModified`();
    Returns the time that the file represented by this DirEntry was last modified.
  @property uint `attributes`();
    Returns the `attributes` of the file represented by this DirEntry.
    Note that the file `attributes` on Windows and Posix systems are completely different. On, Windows, they're what is returned by GetFileAttributes GetFileAttributes 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 uint `linkAttributes`();
    On Posix systems, if the file represented by this DirEntry is a symbolic link, then `linkAttributes` are the attributes of the symbolic link itself. Otherwise, `linkAttributes` is identical to attributes.
    On Windows, `linkAttributes` is identical to attributes. It exists on Windows so that you don't have to special-case code for Windows when dealing with symbolic links.
  @property stat_t `statBuf`();
    This function is Posix-Only.
    The stat struct gotten from calling stat.
PreserveAttributes `preserveAttributesDefault`;
  Defaults to Yes.preserveAttributes on Windows, and the opposite on all other platforms.
void `copy`(RF, RT)(RF `from`, RT `to`, PreserveAttributes `preserve` = preserveAttributesDefault)
if (isInputRange!RF && !isInfinite!RF && isSomeChar!(ElementEncodingType!RF) && !isConvertibleToString!RF && isInputRange!RT && !isInfinite!RT && isSomeChar!(ElementEncodingType!RT) && !isConvertibleToString!RT);
void `copy`(RF, RT)(auto ref RF `from`, auto ref RT `to`, PreserveAttributes `preserve` = preserveAttributesDefault)
if (isConvertibleToString!RF || isConvertibleToString!RT);
  Copy file `from` `to` file `to`. File timestamps are preserved. File attributes are preserved, if `preserve` equals Yes.preserveAttributes. On Windows only Yes.preserveAttributes (the default on Windows) is supported. If the target file exists, it is overwritten.
  Parameters:

  RF `from` | string or range of characters representing the existing file name
  RT `to` | string or range of characters representing the target file name
  PreserveAttributes `preserve` | whether `to` `preserve` the file attributes

  Throws:
  FileException on error.
void `rmdirRecurse`(in char[] `pathname`);
  Remove directory and all of its content and subdirectories, recursively.
  Throws:
  FileException if there is an error (including if the given file is not a directory).
void `rmdirRecurse`(ref DirEntry `de`);
void `rmdirRecurse`(DirEntry `de`);
  Remove directory and all of its content and subdirectories, recursively.
  Throws:
  FileException if there is an error (including if the given file is not a directory).
enum `SpanMode`: int;
  Dictates directory spanning policy for dirEntries (see below).
  `shallow`
    Only spans one directory.
  `depth`
    Spans the directory `depth`-first, i.e. the content of any subdirectory is spanned before that subdirectory itself. Useful e.g. when recursively deleting files.
  `breadth`
    Spans the directory `breadth`-first, i.e. the content of any subdirectory is spanned right after that subdirectory itself.
auto `dirEntries`(string `path`, 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 `path`.
  Parameters:

  string `path` | The directory to iterate over. If empty, the current directory will be iterated.
  SpanMode `mode` | Whether the directory's sub-directories should be iterated over depth-first (depth), breadth-first (breadth), or not at all (shallow).
  bool `followSymlink` | Whether symbolic links which point to directories should be treated as directories and their contents iterated over.

  Throws:
  FileException if the directory does not exist.

  Example:

      // Iterate a directory in depth
      foreach (string name; dirEntries("destroy/me", SpanMode.depth))
      {
          remove(name);
      }

      // Iterate the current directory in breadth
      foreach (string name; dirEntries("", SpanMode.breadth))
      {
          writeln(name);
      }

      // Iterate a directory and get detailed info about it
      foreach (DirEntry e; dirEntries("dmd-testing", SpanMode.breadth))
      {
          writeln(e.name, "\t", e.size);
      }

      // Iterate over all *.d files in current directory and all its subdirectories
      auto 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.system(cmd);
      }

  Examples:
  Duplicate functionality of D1's std.file.listdir():

      string[] listdir(string pathname)
      {
          import std.algorithm;
          import std.array;
          import std.file;
          import std.path;

          return std.file.dirEntries(pathname, SpanMode.shallow)
              .filter!(a => a.isFile)
              .map!(a => std.path.baseName(a.name))
              .array;
      }

      void main(string[] args)
      {
          import std.stdio;

          string[] files = listdir(args[1]);
          writefln("%s", files);
       }

auto `dirEntries`(string `path`, string `pattern`, SpanMode `mode`, bool `followSymlink` = true);
  Convenience wrapper for filtering file names with a glob `pattern`.
  Parameters:

  string `path` | The directory to iterate over.
  string `pattern` | String with wildcards, such as "*.d". The supported wildcard strings are described under std.path.globMatch.
  SpanMode `mode` | Whether the directory's sub-directories should be iterated over depth-first (depth), breadth-first (breadth), or not at all (shallow).
  bool `followSymlink` | Whether symbolic links which point to directories should be treated as directories and their contents iterated over.

  Throws:
  FileException if the directory does not exist.

  Example:

      // Iterate over all D source files in current directory and all its
      // subdirectories
      auto dFiles = dirEntries("","*.{d,di}",SpanMode.depth);
      foreach (d; dFiles)
          writeln(d.name);

Select!(Types.length == 1, Types[0][], Tuple!Types[]) `slurp`(Types...)(string `filename`, in 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
  string `filename` | the name of the file to read
  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:

      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");
      assert(a.length == 2);
      assert(a[0] == tuple(12, 12.25));
      assert(a[1] == tuple(345, 1.125));

@trusted string `tempDir`();
  Returns the path to a directory for temporary files.
  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:
  1. The directory given by the TMPDIR environment variable.
  2. The directory given by the TEMP environment variable.
  3. The directory given by the TMP environment variable.
  4. /tmp
  5. /var/tmp
  6. /usr/tmp
  On all platforms, `tempDir` returns "." on failure, representing the current working directory.
  The return value of the function is cached, so the procedures described above will only be performed the first time the function is called. All subsequent runs will return the same string, regardless of whether environment variables and directory structures have changed in the meantime.
  The POSIX `tempDir` algorithm is inspired by Python's tempfile.tempdir.

Copyright © 1999-2017 by the D Language Foundation | Page generated by Ddoc on Thu Aug 10 17:51:08 2017