www.digitalmars.com

D Programming Language 2.0

Last update Wed Jul 9 01:24:32 2008

std.file

Utilities for manipulating files and scanning directories.

Authors:
Walter Bright, Andrei Alexandrescu

class FileException: object.Exception;
Exception thrown for file I/O errors.

void[] read(in string name);
Read file name, return array of bytes read.

Throws:
FileException on error.

void write(in string name, const void[] buffer);
Write buffer[] to file name[].

Throws:
FileException on error.

void append(in string name, in void[] buffer);
Append buffer[] to file name[].

Throws:
FileException on error.

void rename(in string from, in string to);
Rename file from[] to to[].

Throws:
FileException on error.

void remove(in string name);
Delete file name[].

Throws:
FileException on error.

ulong getSize(in string name);
Get size of file name[].

Throws:
FileException on error.

void getTimes(in string name, out d_time ftc, out d_time fta, out d_time ftm);
Get creation/access/modified times of file name.

Throws:
FileException on error.

bool exists(in string name);
Does file name[] (or directory) exist? Return 1 if it does, 0 if not.

uint getAttributes(string name);
Get file name[] attributes.

Throws:
FileException on error.

bool isfile(in string name);
Is name[] a file?

Throws:
FileException if name[] doesn't exist.

bool isdir(in string name);
Is name[] a directory?

Throws:
FileException if name[] doesn't exist.

void chdir(in string pathname);
Change directory to pathname[].

Throws:
FileException on error.

void mkdir(in string pathname);
Make directory pathname[].

Throws:
FileException on error.

void rmdir(in string pathname);
Remove directory pathname[].

Throws:
FileException on error.

string getcwd();
Get current directory.

Throws:
FileException on error.

struct DirEntry;
Directory Entry

string name;
file or directory name

ulong size;
size of file in bytes

d_time creationTime;
time of file creation

d_time lastAccessTime;
time file was last accessed

d_time lastWriteTime;
time file was last written to

uint isdir();
Return !=0 if DirEntry is a directory.

uint isfile();
Return !=0 if DirEntry is a file.

invariant(char)[][] listdir(string pathname);
Return contents of directory pathname[]. The names in the contents do not include the pathname.

Throws:
FileException on error

Example:
This program lists all the files and subdirectories in its path argument.
 import std.stdio;
 import std.file;

 void main(string[] args)
 {
    auto dirs = std.file.listdir(args[1]);

    foreach (d; dirs)
	writefln(d);
 }


invariant(char)[][] listdir(string pathname, string pattern);
invariant(char)[][] listdir(string pathname, RegExp r);
Return all the files in the directory and its subdirectories that match pattern or regular expression r.

Params:
string pathname Directory name
string pattern String with wildcards, such as "*.d". The supported wildcard strings are described under fnmatch() in std.path.
r Regular expression, for more powerful pattern matching.

Example:
This program lists all the files with a "d" extension in the path passed as the first argument.
 import std.stdio;
 import std.file;

 void main(string[] args)
 {
    auto d_source_files = std.file.listdir(args[1], "*.d");

    foreach (d; d_source_files)
	writefln(d);
 }
A regular expression version that searches for all files with "d" or "obj" extensions:
 import std.stdio;
 import std.file;
 import std.regexp;

 void main(string[] args)
 {
    auto d_source_files = std.file.listdir(args[1], RegExp(r"\.(d|obj)$"));

    foreach (d; d_source_files)
	writefln(d);
 }


void listdir(in string pathname, bool delegate(invariant(char)[] filename) callback);
For each file and directory name in pathname[], pass it to the callback delegate.

Note:
This function is being phased off. New code should use dirEntries (see below).

Params:
bool delegate(invariant(char)[] filename) callback Delegate that processes each filename in turn. Returns true to continue, false to stop.

Example:
This program lists all the files in its path argument, including the path.
 import std.stdio;
 import std.path;
 import std.file;

 void main(string[] args)
 {
    auto pathname = args[1];
    string[] result;

    bool listing(string filename)
    {
      result ~= std.path.join(pathname, filename);
      return true; // continue
    }

    listdir(pathname, &listing);

    foreach (name; result)
      writefln("%s", name);
 }


void listdir(in string pathname, bool delegate(DirEntry* de) callback);
For each file and directory DirEntry in pathname[], pass it to the callback delegate.

Note:
This function is being phased off. New code should use dirEntries (see below).

Params:
bool delegate(DirEntry* de) callback Delegate that processes each DirEntry in turn. Returns true to continue, false to stop.

Example:
This program lists all the files in its path argument and all subdirectories thereof.
 import std.stdio;
 import std.file;

 void main(string[] args)
 {
    bool callback(DirEntry* de)
    {
      if (de.isdir)
        listdir(de.name, &callback);
      else
        writefln(de.name);
      return true;
    }

    listdir(args[1], &callback);
 }


const(char)* toMBSz(in string s);
Since Win 9x does not support the "W" API's, first convert to wchar, then convert to multibyte using the current code page. (Thanks to yaneurao for this)

Deprecated:
use std.windows.charset.toMBSz instead.

void copy(in string from, in string to);
Copy a file from[] to[].

enum SpanMode;
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.

DirIterator dirEntries(string path, SpanMode mode);
Iterates a directory using foreach. 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 the how the directory is traversed. The name of the directory entry includes the path prefix.

Example:
 // Iterate a directory in depth
 foreach (string name; dirEntries("destroy/me", SpanMode.depth))
 {
     remove(name);
 }
 // Iterate a 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);
 }