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 {

import core.sys.posix.sys.types : mode_t;;

alias opOpAssign(istring op = "~") = append;

alias Filter = bool delegate(FilePath, bool);

static FilePath opCall(cstring filepath);

this(cstring filepath);

istring toString();

equals_t opEquals(Object o);

int opEquals(cstring s);

bool isAbsolute();

bool isEmpty();

bool isChild();

FilePath replace(char from, char to);

FilePath standard();

FilePath native();

FilePath cat(cstring[] others);

FilePath append(cstring path);

FilePath prepend(cstring path);

FilePath set(FilePath path);

FilePath set(cstring path, bool convert);

FilePath isFolder(bool folder);

FilePath root(cstring other);

FilePath folder(cstring other);

FilePath name(cstring other);

FilePath suffix(cstring other);

FilePath path(cstring other);

FilePath file(cstring other);

FilePath pop();

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

FilePath absolute(cstring prefix);

static cstring stripped(cstring path, char c);

static cstring padded(cstring path, char c);

static cstring prefixed(cstring s, char c);

FilePath create();

FilePath[] toList(Filter filter);

static FilePath from(FileInfo info);

FilePath rename(FilePath dst);

FilePath copy(cstring source);

Stamps timeStamps();

FilePath copy(FilePath src);

FilePath remove();

FilePath rename(cstring dst);

FilePath createFile(mode_t mode);

FilePath createFolder(mode_t mode);

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

FilePath link(FilePath dst);

}

Constructors

this this(cstring 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().
opOpAssign alias opOpAssign(istring op = "~") = append: Support path ~= x; syntax

Functions

absolute FilePath absolute(cstring prefix)

Convert this FilePath to absolute format, using the given prefix as necessary. If this FilePath is already absolute, return it intact.

accessed Time accessed()

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.

append FilePath append(cstring path)

Append a folder to this path. A leading separator is added as required.

cString mstring 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(cstring[] others)

Concatenate text to this path; no separators are added.

copy FilePath copy(cstring 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 FilePath copy(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 FilePath createFile(mode_t mode)

Create a new file.

createFolder FilePath createFolder(mode_t mode)

Create a new directory.

created Time created()

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()

Duplicate this path.

exists bool exists()

Does this path currently exist?.

ext cstring ext()

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 cstring file()

Return the name + suffix combination.

file FilePath file(cstring other)

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

fileSize ulong fileSize()

Return the file length (in bytes).

folder cstring folder()

Return the file path.

folder FilePath folder(cstring other)

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

isAbsolute bool isAbsolute()

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

isChild bool isChild()

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()

Returns true if this FilePath is empty.

isFile bool isFile()

Is this a regular file?

isFolder FilePath isFolder(bool folder)

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()

Is this file actually a folder/directory?

isWritable bool isWritable()

Is this file writable?

link FilePath link(FilePath dst)

Create a new name for a file (also known as -hard-linking)

modified Time modified()

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 cstring name()

Return the name of this file, or directory.

name FilePath name(cstring other)

Replace the name portion of this path.

native FilePath native()

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

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

List the set of filenames within this folder.

opEquals equals_t 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 int opEquals(cstring s)

Does this FilePath match the given text? Note that some combinations of operations may not produce an identical set of fields. For example:

parent cstring parent()

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 cstring path()

Return the root + folder combination.

path FilePath path(cstring other)

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

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(cstring path)

Prepend a folder to this path. A trailing separator is added if needed.

remove 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(cstring 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'.

root cstring root()

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

root FilePath root(cstring other)

Replace the root portion of this path.

set FilePath set(FilePath path)

Reset the content of this path to that of another and reparse.

set FilePath set(cstring 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 '/').

standard FilePath standard()

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 cstring suffix()

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

suffix FilePath suffix(cstring other)

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

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 istring toString()

Return the complete text of this filepath.

Static functions

from FilePath from(FileInfo info): Construct a FilePath from the given FileInfo.
join istring 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(cstring filepath): Call-site shortcut to create a FilePath instance. This enables the same syntax as struct usage, so may expose a migration path.
padded cstring padded(cstring path, char c): Return an adjusted path such that non-empty instances always have a trailing separator.
prefixed cstring prefixed(cstring s, char c): Return an adjusted path such that non-empty instances always have a prefixed separator.
stripped cstring stripped(cstring 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 istring toString(): Return the complete text of this filepath.
cString mstring cString(): Return the complete text of this filepath.
root cstring root(): Return the root of this path. Roots are constructs such as "C:".
folder cstring folder(): 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 cstring name(): Return the name of this file, or directory, excluding a suffix.
ext cstring ext(): 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 cstring suffix(): Suffix is like ext, but includes the separator e.g. path "foo.bar" has suffix ".bar".
path cstring path(): Return the root + folder combination.
file cstring file(): Return the name + suffix combination.
isAbsolute bool isAbsolute(): Returns true if this FilePath is *not* relative to the current working directory.
isEmpty bool isEmpty(): Returns true if this FilePath is empty.
isChild bool isChild(): Returns true if this FilePath has a parent.
exists bool exists(): Does this path currently exist?
modified Time modified(): Returns the time of the last modification. Accurate to whatever the OS supports.
accessed Time accessed(): Returns the time of the last access. Accurate to whatever the OS supports.
created Time created(): Returns the time of file creation. Accurate to whatever the OS supports.
fileSize ulong fileSize(): Return the file length (in bytes).
isWritable bool isWritable(): Is this file writable?
isFolder bool isFolder(): Is this file actually a folder/directory?
timeStamps Stamps timeStamps(): Return timestamp information.