tango.io.FilePath

License:

Version:

Version:

Version:

Version:

Version:

Version:

Author:

class FilePath : PathView ¶

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.

alias bool delegate(FilePath, bool) Filter ¶

Filter used for screening paths via toList().

FilePath opCall(char[] filepath = null) [static] ¶

Call-site shortcut to create a FilePath instance. This enables the same syntax as struct usage, so may expose a migration path.

this(char[] filepath = null) ¶

Create a FilePath from a copy of the provided string.

FilePath assumes both path & name are present, and therefore may split what is otherwise a logically valid path. That is, the 'name' of a file is typically the path segment following a rightmost path-separator. The intent is to treat files and directories in the same manner; as a name with an optional ancestral structure. It is possible to bias the interpretation by adding a trailing path-separator to the argument. Doing so will result in an empty name attribute.

With regard to the filepath copy, we found the common case to be an explicit .dup, whereas aliasing appeared to be rare by comparison. We also noted a large proportion interacting with C-oriented OS calls, implying the postfix of a null terminator. Thus, FilePath combines both as a single operation.

Note that Win32 '\' characters are normalized to '/' instead.

string toString() [override, final, const] ¶

Return the complete text of this filepath.

FilePath dup() [@property, final, const] ¶

Duplicate this path.

inout(char)[] cString() [inout, final] ¶

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.

Note that the nul is always embedded within the string maintained by FilePath, so there's no heap overhead when making a C call.

inout(char)[] root() [@property, inout, final] ¶

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

inout(char)[] folder() [@property, inout, final] ¶

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)[] parent() [@property, inout, final] ¶

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

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

See pop() also, which is generally more useful when working with FilePath instances.

inout(char)[] name() [@property, inout, final] ¶

Return the name of this file, or directory.

char[] ext() [@property, final] ¶

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)[] suffix() [@property, inout, final] ¶

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

inout(char)[] path() [@property, inout, final] ¶

Return the root + folder combination.

inout(char)[] file() [@property, inout, final] ¶

Return the name + suffix combination.

bool opEquals(Object o) [override, final, const] ¶

Returns true if all fields are identical. Note that some combinations of operations may not produce an identical set of fields. For example:

FilePath("/foo").append("bar").pop() == "/foo"; FilePath("/foo/").append("bar").pop() != "/foo/";

The latter is different due to variance in how append injects data, and how pop is expected to operate under different circumstances (both examples produce the same pop result, although the initial path is not identical).

However, opEquals() can overlook minor distinctions such as this example, and will return a match.

bool opEquals(const(char)[] s) [final, const] ¶

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

FilePath("/foo").append("bar").pop() == "/foo"; FilePath("/foo/").append("bar").pop() != "/foo/";

The latter Is Different due to variance in how append injects data, and how pop is expected to operate under different circumstances (both examples produce the same pop result, although the initial path is not identical).

However, opEquals() can overlook minor distinctions such as this example, and will return a match.

bool isAbsolute() [@property, final, const] ¶

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

bool isEmpty() [@property, final, const] ¶

Returns true if this FilePath is empty.

bool isChild() [@property, final, const] ¶

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.

FilePath replace(char from, char to) [final] ¶

Replace all 'from' instances with 'to'.

FilePath standard() [@property, final] ¶

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 current path.

FilePath native() [@property, final] ¶

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

Note:

Mutates the current path. Use this pattern to obtain a copy instead: path.dup.native

FilePath cat(const(char[])[] others...) [final] ¶

Concatenate text to this path; no separators are added.

See Also:

join()

FilePath append(const(char)[] path) [final] ¶

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

FilePath prepend(const(char)[] path) [final] ¶

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

FilePath set(FilePath path) ¶

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

FilePath set(const(char)[] path, bool convert = false) [final] ¶

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 '/').

FilePath isFolder(bool folder) [@property, final] ¶

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

FilePath root(const(char)[] other) [@property, final] ¶

Replace the root portion of this path.

FilePath folder(const(char)[] other) [@property, final] ¶

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

FilePath name(const(char)[] other) [@property, final] ¶

Replace the name portion of this path.

FilePath suffix(const(char)[] other) [@property, final] ¶

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

FilePath path(const(char)[] other) [@property, final] ¶

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

FilePath file(const(char)[] other) [@property, final] ¶

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

FilePath pop() [final] ¶

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.

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

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

FilePath absolute(const(char)[] prefix) [final] ¶

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

Returns this FilePath, adjusted as necessary.

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

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

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

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

inout(char)[] prefixed(inout(char)[] s, char c = PathSeparatorChar) [static] ¶

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

FilePath create() [final] ¶

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

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

Returns:

A chaining reference (this).

Throws:

IOException upon systen errors.

Throws:

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

FilePath[] toList(Filter filter = null) [final] ¶

List the set of filenames within this folder, using the provided filter to control the list:

bool delegate (FilePath path, bool isFolder) Filter;

Returning true from the filter includes the given path, whilst returning false excludes it. Parameter 'isFolder' indicates whether the path is a file or folder.

Note that paths composed of '.' characters are ignored.

FilePath from(ref FileInfo info) [static] ¶

Construct a FilePath from the given FileInfo.

bool exists() [@property, inout, final] ¶

Does this path currently exist?.

Time modified() [@property, final, const] ¶

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.

Time accessed() [@property, final, const] ¶

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.

Time created() [@property, final, const] ¶

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.

FilePath rename(FilePath dst) [final] ¶

Change the name or location of a file/directory, and adopt the provided Path.

inout(FilePath) copy(const(char)[] source) [inout, final] ¶

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

ulong fileSize() [final, const] ¶

Return the file length (in bytes).

bool isWritable() [@property, final, const] ¶

Is this file writable?

bool isFolder() [@property, final, const] ¶

Is this file actually a folder/directory?

bool isFile() [@property, final, const] ¶

Is this a regular file?

Stamps timeStamps() [final, const] ¶

Return timestamp information.

Timstamps 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.

inout(FilePath) copy(const(FilePath) src) [inout, final] ¶

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

inout(FilePath) remove() [inout, final] ¶

Remove the file/directory from the file system.

FilePath rename(const(char)[] dst) [final] ¶

change the name or location of a file/directory, and adopt the provided Path.

inout(FilePath) createFile() [inout, final] ¶

Create a new file.

inout(FilePath) createFolder() [inout, final] ¶

Create a new directory.

int opApply(scope int delegate(ref FileInfo) dg) [final, const] ¶

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.

Returns the number of files scanned.

interface PathView ¶

immutable(char)[] toString() [const] ¶

Return the complete text of this filepath.

inout(char)[] cString()() [inout] ¶

Return the complete text of this filepath.

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

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

inout(char)[] 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)[] name() [@property, inout] ¶

Return the name of this file, or directory, excluding a suffix.

char[] 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)[] suffix() [@property, inout] ¶

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

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

Return the root + folder combination.

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

Return the name + suffix combination.

bool isAbsolute() [@property, const] ¶

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

bool exists() [@property, inout] ¶

Does this path currently exist?

Time modified() [@property, const] ¶

Returns the time of the last modification. Accurate to whatever the OS supports.

Time accessed() [@property, const] ¶

Returns the time of the last access. Accurate to whatever the OS supports.

Time created() [@property, const] ¶

Returns the time of file creation. Accurate to whatever the OS supports.

ulong fileSize() [@property, const] ¶

Return the file length (in bytes).

bool isWritable() [@property, const] ¶

Is this file writable?

bool isFolder() [@property, const] ¶

Is this file actually a folder/directory?

Stamps timeStamps() [@property, const] ¶

Return timestamp information.