FilePath

Models a file path. These are expected to be used as the constructor argument to various file classes. The intention is that they easily convert to other representations such as absolute, canonical, or Url.

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 FilePath, and is both consistent & compatible with the approach taken with the Uri class.

FilePath is designed to be transformed, thus each mutating method modifies the internal content. See module Path.d for a lightweight immutable variation.

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 that Win32 '\' characters are converted to '/' by default via the FilePath constructor.

class FilePath : PathView {

FilePath opOpAssign(const(char)[] path);

alias Filter = bool delegate(FilePath, bool);

static FilePath opCall(char[] filepath);

this(char[] filepath);

string toString();

FilePath dup [@property getter];

inout(char)[] cString();

inout(char)[] root [@property getter];

inout(char)[] folder [@property getter];

inout(char)[] parent [@property getter];

inout(char)[] name [@property getter];

char[] ext [@property getter];

inout(char)[] suffix [@property getter];

inout(char)[] path [@property getter];

inout(char)[] file [@property getter];

bool opEquals(Object o);

bool opEquals(const(char)[] s);

bool isAbsolute [@property getter];

bool isEmpty [@property getter];

bool isChild [@property getter];

FilePath replace(char from, char to);

FilePath standard [@property getter];

FilePath native [@property getter];

FilePath cat(const(char[])[] others);

FilePath append(const(char)[] path);

FilePath prepend(const(char)[] path);

FilePath set(FilePath path);

FilePath set(const(char)[] path, bool convert);

bool isFolder [@property setter];

const(char)[] root [@property setter];

const(char)[] folder [@property setter];

const(char)[] name [@property setter];

const(char)[] suffix [@property setter];

const(char)[] path [@property setter];

const(char)[] file [@property setter];

FilePath pop();

static char[] join(const(char[])[] paths);

FilePath absolute(const(char)[] prefix);

static inout(char)[] stripped(inout(char)[] path, char c);

static inout(char[]) padded(inout(char[]) path, char c);

static inout(char)[] prefixed(inout(char)[] s, char c);

FilePath create();

FilePath[] toList(Filter filter);

static FilePath from(FileInfo info);

bool exists [@property getter];

Time modified [@property getter];

Time accessed [@property getter];

Time created [@property getter];

FilePath rename(FilePath dst);

inout(FilePath) copy(const(char)[] source);

ulong fileSize();

bool isWritable [@property getter];

bool isFolder [@property getter];

bool isFile [@property getter];

Stamps timeStamps();

inout(FilePath) copy(const(FilePath) src);

inout(FilePath) remove();

FilePath rename(const(char)[] dst);

inout(FilePath) createFile();

inout(FilePath) createFolder();

int opApply(int delegate(ref FileInfo) dg);

}

Constructors

this this(char[] filepath): Create a FilePath from a copy of the provided string.

Members

Aliases

Filter alias Filter = bool delegate(FilePath, bool): Filter used for screening paths via toList().

Functions

absolute FilePath absolute(const(char)[] prefix): Convert this FilePath to absolute format, using the given prefix as necessary. If this FilePath is already absolute, return it intact.
append FilePath append(const(char)[] path): Append a folder to this path. A leading separator is added as required.
cString inout(char)[] cString(): Return the complete text of this filepath as a null terminated string for use with a C api. Use toString instead for any D api.
cat FilePath cat(const(char[])[] others): Concatenate text to this path; no separators are added.
copy inout(FilePath) copy(const(char)[] source): Transfer the content of another file to this one. Returns a reference to this class on success, or throws an IOException upon failure.
copy inout(FilePath) copy(const(FilePath) src): Transfer the content of another file to this one. Returns a reference to this class on success, or throws an IOException upon failure.
create FilePath create(): Create an entire path consisting of this folder along with all parent folders. The path must not contain '.' or '..' segments. Related methods include PathUtil.normalize() and absolute().
createFile inout(FilePath) createFile(): Create a new file.
createFolder inout(FilePath) createFolder(): Create a new directory.
fileSize ulong fileSize(): Return the file length (in bytes).
opApply int opApply(int delegate(ref FileInfo) dg): List the set of filenames within this folder.
opEquals bool opEquals(Object o): Returns true if all fields are identical. Note that some combinations of operations may not produce an identical set of fields. For example:
opEquals bool opEquals(const(char)[] s): Does this FilePath match the given text? Note that some combinations of operations may not produce an identical set of fields. For example:
opOpAssign FilePath opOpAssign(const(char)[] path): Undocumented in source. Be warned that the author may not have intended to support it.
pop FilePath pop(): Pop to the parent of the current filepath (in situ - mutates this FilePath). Note that this differs from parent() in that it does not include any special cases.
prepend FilePath prepend(const(char)[] path): Prepend a folder to this path. A trailing separator is added if needed.
remove inout(FilePath) remove(): Remove the file/directory from the file system.
rename FilePath rename(FilePath dst): Change the name or location of a file/directory, and adopt the provided Path.
rename FilePath rename(const(char)[] dst): change the name or location of a file/directory, and adopt the provided Path.
replace FilePath replace(char from, char to): Replace all 'from' instances with 'to'.
set FilePath set(FilePath path): Reset the content of this path to that of another and reparse.
set FilePath set(const(char)[] path, bool convert): Reset the content of this path, and reparse. There's an optional boolean flag to convert the path into standard form, before parsing (converting '\' into '/').
timeStamps Stamps timeStamps(): Return timestamp information.
toList FilePath[] toList(Filter filter): List the set of filenames within this folder, using the provided filter to control the list:
toString string toString(): Return the complete text of this filepath.

Properties

accessed Time accessed [@property getter]

Returns the time of the last access. Accurate to whatever the OS 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.

created Time created [@property getter]

Returns the time of file creation. Accurate to whatever the OS 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.

dup FilePath dup [@property getter]

Duplicate this path.

exists bool exists [@property getter]

Does this path currently exist?.

ext char[] ext [@property getter]

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.

file inout(char)[] file [@property getter]

Return the name + suffix combination.

file const(char)[] file [@property setter]

Replace the file and suffix portions of this path and reparse. The replacement will be prefixed with a suffix separator as required.

folder inout(char)[] folder [@property getter]

Return the file path.

folder const(char)[] folder [@property setter]

Replace the folder portion of this path. The folder will be padded with a path-separator as required.

isAbsolute bool isAbsolute [@property getter]

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

isChild bool isChild [@property getter]

Returns true if this FilePath 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.

isEmpty bool isEmpty [@property getter]

Returns true if this FilePath is empty.

isFile bool isFile [@property getter]

Is this a regular file?

isFolder bool isFolder [@property setter]

Sidestep the normal lookup for paths that are known to be folders. Where folder is true, file system lookups will be skipped.

isFolder bool isFolder [@property getter]

Is this file actually a folder/directory?

isWritable bool isWritable [@property getter]

Is this file writable?

modified Time modified [@property getter]

Returns the time of the last modification. Accurate to whatever the OS 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.

name inout(char)[] name [@property getter]

Return the name of this file, or directory.

name const(char)[] name [@property setter]

Replace the name portion of this path.

native FilePath native [@property getter]

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

parent inout(char)[] parent [@property getter]

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

path inout(char)[] path [@property getter]

Return the root + folder combination.

path const(char)[] path [@property setter]

Replace the root and folder portions of this path and reparse. The replacement will be padded with a path separator as required.

root inout(char)[] root [@property getter]

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

root const(char)[] root [@property setter]

Replace the root portion of this path.

standard FilePath standard [@property getter]

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.

suffix inout(char)[] suffix [@property getter]

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

suffix const(char)[] suffix [@property setter]

Replace the suffix portion of this path. The suffix will be prefixed with a file-separator as required.

Static functions

from FilePath from(FileInfo info): Construct a FilePath from the given FileInfo.
join char[] join(const(char[])[] paths): Join a set of path specs together. A path separator is potentially inserted between each of the segments.
opCall FilePath opCall(char[] filepath): Call-site shortcut to create a FilePath instance. This enables the same syntax as struct usage, so may expose a migration path.
padded inout(char[]) padded(inout(char[]) path, char c): Return an adjusted path such that non-empty instances always have a trailing separator.
prefixed inout(char)[] prefixed(inout(char)[] s, char c): Return an adjusted path such that non-empty instances always have a prefixed separator.
stripped inout(char)[] stripped(inout(char)[] path, char c): Return an adjusted path such that non-empty instances do not have a trailing separator.

Inherited Members

From PathView

Stamps alias Stamps = FS.Stamps: Undocumented in source.
toString immutable(char)[] toString(): Return the complete text of this filepath.
cString inout(char)[] cString(): Return the complete text of this filepath.
root inout(char)[] root [@property getter]: Return the root of this path. Roots are constructs such as "C:".
folder inout(char)[] folder [@property getter]: 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.
name inout(char)[] name [@property getter]: Return the name of this file, or directory, excluding a suffix.
ext char[] ext [@property getter]: 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.
suffix inout(char)[] suffix [@property getter]: Suffix is like ext, but includes the separator e.g. path "foo.bar" has suffix ".bar".
path inout(char)[] path [@property getter]: Return the root + folder combination.
file inout(char)[] file [@property getter]: Return the name + suffix combination.
isAbsolute bool isAbsolute [@property getter]: Returns true if this FilePath is *not* relative to the current working directory.
isEmpty bool isEmpty [@property getter]: Returns true if this FilePath is empty.
isChild bool isChild [@property getter]: Returns true if this FilePath has a parent.
exists bool exists [@property getter]: Does this path currently exist?
modified Time modified [@property getter]: Returns the time of the last modification. Accurate to whatever the OS supports.
accessed Time accessed [@property getter]: Returns the time of the last access. Accurate to whatever the OS supports.
created Time created [@property getter]: Returns the time of file creation. Accurate to whatever the OS supports.
fileSize ulong fileSize [@property getter]: Return the file length (in bytes).
isWritable bool isWritable [@property getter]: Is this file writable?
isFolder bool isFolder [@property getter]: Is this file actually a folder/directory?
timeStamps Stamps timeStamps [@property getter]: Return timestamp information.