tango.io.Path

License:

Version:

Mar 2008: Initial version
Oct 2009: Added PathUtil code

A more direct route to the file-system than FilePath. Use this if you don't need path editing features. For example, if all you want is to check some path exists, using this module would likely be more convenient than FilePath:

1 2	if (exists ("some/file/path")) ...

These functions may be less efficient than FilePath because they generally attach a null to the filename for each underlying O/S call. Use Path when you need pedestrian access to the file-system, and are not manipulating the path components. Use FilePath where path-editing or mutation is desired.

We encourage the use of "named import" with this module, such as:

import Path = tango.io.Path;

if (Path.exists ("some/file/path"))
    ...

Also residing here is a lightweight path-parser, which splits a filepath into constituent components. FilePath is based upon the same PathParser:

auto p = Path.parse ("some/file/path");
auto path = p.path;
auto name = p.name;
auto suffix = p.suffix;
...

Path normalization and pattern-matching is also hosted here via the normalize() and pattern() functions. See the doc towards the end of this module.

Compile with -version=Win32SansUnicode to enable Win95 & Win32s file support.

struct FS [package] ¶

Wraps the O/S specific calls with a D API. Note that these accept null-terminated strings only, which is why it's not public. We need this declared first to avoid forward-reference issues.

struct Stamps ¶

TimeStamp information. Accurate to whatever the F/S supports.

Time created ¶: Time created.
Time accessed ¶: Last time accessed.
Time modified ¶: Last time modified.

struct Listing ¶

Some fruct glue for directory listings.

void exception(const(char)[] filename) [static] ¶

Throw an exception using the last known error.

void exception(const(char)[] prefix, const(char)[] error) [static] ¶

Throw an IO exception.

inout(char)[] padded(inout(char)[] path, char c = '/') [static] ¶

Return an adjusted path such that non-empty instances always have a trailing separator.

Note:

Allocates memory where path is not already terminated.

inout(char)[] paddedLeading(inout(char)[] path, char c = '/') [static] ¶

Return an adjusted path such that non-empty instances always have a leading separator.

Note:

Allocates memory where path is not already terminated.

inout(char)[] stripped(inout(char)[] path, char c = '/') [static] ¶

Return an adjusted path such that non-empty instances do not have a trailing separator.

char[] join(const(char[])[] paths...) [static] ¶

Join a set of path specs together. A path separator is potentially inserted between each of the segments.

Note:

Allocates memory.

char[] strz(const(char)[] src, char[] dst) [static] ¶

Append a terminating null onto a string, cheaply where feasible.

Note:

Allocates memory where the dst is too small.

bool exists(const(char)[] name) [static] ¶

Return whether the file or path exists.

ulong fileSize(const(char)[] name) [static] ¶

Return the file length (in bytes.)

bool isWritable(const(char)[] name) [static] ¶

Is this file writable?

bool isFolder(const(char)[] name) [static] ¶

Is this file actually a folder/directory?

bool isFile(const(char)[] name) [static] ¶

Is this a normal file?

Stamps timeStamps(const(char)[] name) [static] ¶

Return timestamp information.

Timestamps are returns in a format dictated by the file-system. For example NTFS keeps UTC time, while FAT timestamps are based on the local time.

void timeStamps(const(char)[] name, Time accessed, Time modified) [static] ¶

Set the accessed and modified timestamps of the specified file.

void copy(const(char)[] source, const(char)[] dest) [static] ¶

Transfer the content of another file to this one. Returns a reference to this class on success, or throws an IOException upon failure.

Note:

Allocates a memory buffer.

bool remove(const(char)[] name) [static] ¶

Remove the file/directory from the file-system. Returns true on success - false otherwise.

void rename(const(char)[] src, const(char)[] dst) [static] ¶

Change the name or location of a file/directory.

void createFile(const(char)[] name) [static] ¶

Create a new file.

void createFolder(const(char)[] name) [static] ¶

Create a new directory.

int list(const(char)[] folder, scope int delegate(ref FileInfo) dg, bool all = false) [static] ¶

List the set of filenames within this folder.

Each path and filename is passed to the provided delegate, along with the path prefix and whether the entry is a folder or not.

Note:

Allocates and reuses a small memory buffer.

struct PathParser(char_t = char) ¶

Parses a file path.

File paths containing non-ansi characters should be UTF-8 encoded. Supporting Unicode in this manner was deemed to be more suitable than providing a wchar version of PathParser, and is both consistent & compatible with the approach taken with the Uri class.

Note that patterns of adjacent '.' separators are treated specially in that they will be assigned to the name where there is no distinct suffix. In addition, a '.' at the start of a name signifies it does not belong to the suffix i.e. ".file" is a name rather than a suffix. Patterns of intermediate '.' characters will otherwise be assigned to the suffix, such that "file....suffix" includes the dots within the suffix itself. See method ext() for a suffix without dots.

Note also that normalization of path-separators does *not* occur by default. This means that usage of '\' characters should be explicitly converted beforehand into '/' instead (an exception is thrown in those cases where '\' is present). On-the-fly conversion is avoided because (a) the provided path is considered immutable and (b) we avoid taking a copy of the original path. Module FilePath exists at a higher level, without such contraints.

PathParser parse(char_t[] path) ¶

Parse the path spec.

PathParser dup() [@property, const] ¶

Duplicate this path.

Note:

Allocates memory for the path content.

inout(char_t)[] dString() [inout] ¶

Return the complete text of this filepath.

inout(char_t)[] root() [@property, inout] ¶

Return the root of this path. Roots are constructs such as "C:".

inout(char_t)[] folder() [@property, inout] ¶

Return the file path. Paths may start and end with a "/". The root path is "/" and an unspecified path is returned as an empty string. Directory paths may be split such that the directory name is placed into the 'name' member; directory paths are treated no differently than file paths.

inout(char_t)[] parent() [@property, inout] ¶

Returns a path representing the parent of this one. This will typically return the current path component, though with a special case where the name component is empty. In such cases, the path is scanned for a prior segment:

normal: /x/y/z => /x/y
special: /x/y/ => /x
normal: /x => /
normal: / => [empty]

Note that this returns a path suitable for splitting into path and name components (there's no trailing separator).

inout(char_t)[] pop() [inout] ¶

Pop the rightmost element off this path, stripping off a trailing '/' as appropriate:

/x/y/z => /x/y
/x/y/ => /x/y (note trailing '/' in the original)
/x/y => /x
/x => /
/ => [empty]

Note that this returns a path suitable for splitting into path and name components (there's no trailing separator).

inout(char_t)[] name() [@property, inout] ¶

Return the name of this file, or directory.

char_t[] ext() [@property] ¶

Ext is the tail of the filename, rightward of the rightmost '.' separator e.g. path "foo.bar" has ext "bar". Note that patterns of adjacent separators are treated specially - for example, ".." will wind up with no ext at all.

inout(char_t)[] suffix() [@property, inout] ¶

Suffix is like ext, but includes the separator e.g. path "foo.bar" has suffix ".bar".

inout(char_t)[] path() [@property, inout] ¶

Return the root + folder combination.

inout(char_t)[] file() [@property, inout] ¶

Return the name + suffix combination.

bool isAbsolute() [@property, const] ¶

Returns true if this path is *not* relative to the current working directory.

bool isEmpty() [@property, const] ¶

Returns true if this FilePath is empty.

bool isChild() [@property, const] ¶

Returns true if this path has a parent. Note that a parent is defined by the presence of a path-separator in the path. This means 'foo' within "/foo" is considered a child of the root.

bool equals(const(char)[] s) [const] ¶

Does this path equate to the given text? We ignore trailing path-separators when testing equivalence.

PathParser parse(char_t[] path, size_t end) [package] ¶

Parse the path spec with explicit end point. A '\' is considered illegal in the path and should be normalized out before this is invoked (the content managed here is considered immutable, and thus cannot be changed by this function.)

bool exists(const(char)[] name) ¶

Does this path currently exist?

Time modified(const(char)[] name) ¶

Returns the time of the last modification. Accurate to whatever the F/S supports, and in a format dictated by the file-system. For example NTFS keeps UTC time, while FAT timestamps are based on the local time.

Time accessed(const(char)[] name) ¶

Returns the time of the last access. Accurate to whatever the F/S supports, and in a format dictated by the file-system. For example NTFS keeps UTC time, while FAT timestamps are based on the local time.

Time created(const(char)[] name) ¶

Returns the time of file creation. Accurate to whatever the F/S supports, and in a format dictated by the file-system. For example NTFS keeps UTC time, while FAT timestamps are based on the local time.

ulong fileSize(const(char)[] name) ¶

Return the file length (in bytes.)

bool isWritable(const(char)[] name) ¶

Is this file writable?

bool isFolder(const(char)[] name) ¶

Is this file actually a folder/directory?

bool isFile(const(char)[] name) ¶

Is this file actually a normal file? Not a directory or (on unix) a device file or link.

FS.Stamps timeStamps(const(char)[] name) ¶

Return timestamp information.

Timestamps are returns in a format dictated by the file-system. For example NTFS keeps UTC time, while FAT timestamps are based on the local time.

void timeStamps(const(char)[] name, Time accessed, Time modified) ¶

Set the accessed and modified timestamps of the specified file.

Since:

0.99.9

bool remove(const(char)[] name) ¶

Remove the file/directory from the file-system. Returns true if successful, false otherwise.

char[][] remove(char[][] paths) ¶

Remove the files and folders listed in the provided paths. Where folders are listed, they should be preceded by their contained files in order to be successfully removed. Returns a set of paths that failed to be removed (where .length is zero upon success).

The collate() function can be used to provide the input paths:

1	remove (collate (".", "*.d", true));

Use with great caution.

Note:

May allocate memory.

Since:

0.99.9

void createFile(const(char)[] name) ¶

Create a new file.

void createFolder(const(char)[] name) ¶

Create a new directory.

void createPath(const(char)[] path) ¶

Create an entire path consisting of this folder along with all parent folders. The path should not contain '.' or '..' segments, which can be removed via the normalize() function.

Note that each segment is created as a folder, including the trailing segment.

Throws:

IOException upon system errors.

Throws:

IllegalArgumentException if a segment exists but as a file instead of a folder.

void rename(const(char)[] src, const(char)[] dst) ¶

Change the name or location of a file/directory.

void copy(const(char)[] src, const(char)[] dst) ¶

Transfer the content of one file to another. Throws an IOException upon failure.

FS.Listing children(const(char)[] path, bool all = false) ¶

Provides foreach support via a fruct, as in

1 2	foreach (info; children("myfolder")) ...

Each path and filename is passed to the foreach delegate, along with the path prefix and whether the entry is a folder or not. The info construct exposes the following attributes:

char[]  path
char[]  name
ulong   bytes
bool    folder

Argument 'all' controls whether hidden and system files are included - these are ignored by default.

char[][] collate(const(char)[] path, const(char)[] pattern, bool recurse = false) ¶

Collate all files and folders from the given path whose name matches the given pattern. Folders will be traversed where recurse is enabled, and a set of matching names is returned as filepaths (including those folders which match the pattern.)

Note:

Allocates memory for returned paths.

Since:

0.99.9

char[] join(const(char[])[] paths...) ¶

Join a set of path specs together. A path separator is potentially inserted between each of the segments.

Note:

May allocate memory.

char[] standard(char[] path) ¶

Convert path separators to a standard format, using '/' as the path separator. This is compatible with Uri and all of the contemporary O/S which Tango supports. Known exceptions include the Windows command-line processor, which considers '/' characters to be switches instead. Use the native() method to support that.

Note:

Mutates the provided path.

char[] native(char[] path) ¶

Convert to native O/S path separators where that is required, such as when dealing with the Windows command-line.

Note:

Mutates the provided path. Use this pattern to obtain a copy instead: native(path.dup);

inout(char)[] parent(inout(char)[] path) ¶

Returns a path representing the parent of this one, with a special case concerning a trailing '/':

normal: /x/y/z => /x/y
normal: /x/y/ => /x/y
special: /x/y/ => /x
normal: /x => /
normal: / => empty

The result can be split via parse().

inout(char)[] pop(inout(char)[] path) ¶

Returns a path representing the parent of this one:

normal: /x/y/z => /x/y
normal: /x/y/ => /x/y
normal: /x => /
normal: / => empty

The result can be split via parse().

inout(char)[] split(inout(char)[] path, out inout(char)[] head, out inout(char)[] tail) ¶

Break a path into "head" and "tail" components. For example:

"/a/b/c" -> "/a","b/c"
"a/b/c" -> "a","b/c"

char[] replace(char[] path, char from, char to) ¶

Replace all path 'from' instances with 'to', in place (overwrites the provided path).

PathParser!(char_t) parse(char_t)(char_t[] path) ¶

Parse a path into its constituent components.

Note that the provided path is sliced, not duplicated.

bool patternMatch(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 charMatch(), 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:

true if pattern matches filename, false otherwise.

Throws:

Nothing.

version (Win32)
{
  patternMatch("foo.bar", "*"); // => true
  patternMatch(r"foo/foo\bar", "f*b*r"); // => true
  patternMatch("foo.bar", "f?bar"); // => false
  patternMatch("Goo.bar", "[fg]???bar"); // => true
  patternMatch(r"d:\foo\bar", "d*foo?bar"); // => true
}
version (Posix)
{
  patternMatch("Go*.bar", "[fg]???bar"); // => false
  patternMatch("/foo*home/bar", "?foo*bar"); // => true
  patternMatch("foobar", "foo?bar"); // => true
}

char[] normalize(const(char)[] in_path, char[] buf = null) ¶

Normalizes a path component.

. segments are removed
<segment>/.. are removed

Multiple consecutive forward slashes are replaced with a single forward slash. On Windows, \ will be converted to / prior to any normalization.

Note that any number of .. segments at the front is ignored, unless it is an absolute path, in which case they are removed.

The input path is copied into either the provided buffer, or a heap allocated array if no buffer was provided. Normalization modifies this copy before returning the relevant slice.

1	normalize("/home/foo/./bar/../../john/doe"); // => "/home/john/doe"

Note:

Allocates memory.