Path

Description

[ShutdownSurvive]
sealed class Tinman.Core.IO.Path

Derived from

SerializableBase abstract
IEquatable<Path>
IComparable<Path>

Represents a file path in a file system.

A valid path string is defined by the following Grammar:

path      := root? separator? (name (separator name)* separator?)? ;

name      := ]/\r\\\n[+ ;
root      := ]/\r\\\n:[+ ':' ;
separator := [/\\]+ ;

Not all valid path strings may be accepted by the underlying file system; some characters may be invalid and thus cannot be used (see IOError.BadPath).

Public / Constants

Current


public static readonly attribute Current → (Path)

A relative Path object for the current directory: '.'

Parent


public static readonly attribute Parent → (Path)

A relative Path object for the parent directory: '.'

Root


public static readonly attribute Root → (Path)

An absolute Path object for the root directory: '/'.

Unknown


public static readonly attribute Unknown → (Path)

Special Path object for representing an unknown file path.

When called on an unknown path or being passed an unknown path as argument, the following methods will return Unknown without performing any further action:

See also

Path.IsUnknown

Public / Constructors

Coalesce


[Pure]
public static method Coalesce → (1)

in : IPathInfo

First path value.

returns → Path

The first non-null path or Unknown.

Returns the first non-null path.

From


[Pure]
public static method From → (1)

path in : string

[not-empty]
The path string.

returns → Path

The Path object.

Parses the given path string and returns the resulting Path object.

IOException

If the given path in is not a valid path name (i.e. FromNull would return null).

From​Null


[Pure]
public static method FromNull → (1)

path in : string

The path string.

returns → Path

The Path object or null if the given path string is invalid, empty or null.

Parses the given path string and returns the resulting Path object.

Guess


public static method Guess → (1)

obj in : object

Some object reference.

returns → Path

The guessed Path value or Unknown.

Tries to guess a Path value from the given object.

First, the method checks if obj in implements the IPathInfo interface and returns the value of the IPathInfo.PathInfo property in that case. Otherwise a Path value is constructed from the string representation of obj in.

Public / Methods

Append​Name


[Pure]
public method AppendName → (1)

name in : string

[not-empty]
The path element to add.

returns → Path

The resulting path.

Appends the given path element to this path.

Example:

c:\some\directory\structure

or

c:\some\directory\structure\

AppendName("myfile.txt") => c:\some\directory\structure\myfile.txt

Append​Path


[Pure]
public method AppendPath → (1)

path in : Path

[not-null]
The other path.

returns → Path

The resulting path.

Appends the given path to this one.

Example:

c:\some\directory\structure

or

c:\some\directory\structure\

AppendPath("myfile.txt") => c:\some\directory\structure\myfile.txt
AppendPath("mydir/myfile.txt") => c:\some\directory\structure\mydir\myfile.txt
AppendPath("\myfile.txt") => c:\some\directory\structure\myfile.txt
AppendPath("c:myfile.txt") => c:\some\directory\structure\myfile.txt
AppendPath("c:\myfile.txt") => c:\some\directory\structure\myfile.txt

Append​Suffix

2 overloads


[Pure]
public method AppendSuffix1 → (1)

suffix in : string

[not-null]
The suffix to append.

returns → Path

The resulting path.

Appends the given suffix to this path.

Example:

c:\some\directory\structure
c:\some\directory\structure\

AppendSuffix(".test") => c:\some\directory\structure.test

c:\some\directory\structure\myfile.txt

AppendSuffix(".bak") => c:\some\directory\structure\myfile.txt.bak

c:\

AppendSuffix("") => c:\
AppendSuffix(".test") => c:\.test

[Pure]
public method AppendSuffix2 → (2)

delimiter in : char

The delimiter char to append.

suffix in : string

[not-empty]
The suffix to append.

returns → Path

The resulting path.

Appends the given suffix to the last path element of this path.

Example:

c:\some\directory\structure
c:\some\directory\structure\

AppendSuffix('.', "test") => c:\some\directory\structure.test

c:\some\directory\structure\myfile.txt

AppendSuffix('.', "bak") => c:\some\directory\structure\myfile.txt.bak

c:\

AppendSuffix('.', "test") => c:\.test

Coalesce


[Pure]
public static method Coalesce → (2)

in : Path

First path value (can be null).

opt : Path = null

Second path value (can be null).

returns → Path

The first non-null and non-unknown path or Unknown.

Returns the first non-null and non-unknown path.

Concat


[Pure]
public static method Concat → (2)

in : Path

First path value or null.

in : Path

Second path value or null.

returns → Path

The resulting path value.

Concatenates the given path values.

Delete​All


public static method DeleteAll → (1)

toDelete in : IVectorConst<Path>

[not-null]
The files resp. directories to delete. The elements are processed from last to first.

returns → bool

true if all files and directories have been deleted,
false if not.

Deletes all filed resp. directories denoted by toDelete in.

IOException

If an I/O error has occurred.

Directories


[Pure]
public static method Directories → (1)

filter opt : PredicateDelegate<Path> = null

The path predicate to wrap or null.

returns → PathFilterDelegate

The path filter for existing directories.

Wraps the given filter opt as a PathFilterDelegate for directories.

Equals

3 overloads


[Pure]
public method Equals3 → (2)

other in : Path

The other path to compare with.

caseSensitive in : bool

Do case-sensitive comparison?

returns → bool

true if this path and the given other in one are equal, false if the paths are different.

Checks if this path is equal to the given other in one.

Files


[Pure]
public static method Files → (1)

filter opt : PredicateDelegate<Path> = null

The path predicate to wrap or null.

returns → PathFilterDelegate

The path filter for existing files.

Wraps the given filter opt as a PathFilterDelegate for files.

Get​File​System


[Pure]
public method GetFileSystem → ()

returns → IFileSystem

The IFileSystem to use.

Returns the IFileSystem object that owns this path value.

Get​Suffix


[Pure]
public method GetSuffix → (1)

delimiter opt : char = '.'

The suffix delimiter character.

returns → string

The suffix string (excluding the delimiter opt character); will be an empty string if this path does not include a suffix or is unknown.

Returns the suffix of the last named element of this path.

Has​Prefix


[Pure]
public method HasPrefix → (2)

prefix in : Path

The prefix path.

caseSensitive opt : bool = true

Do case-sensitive comparison?

returns → bool

true if RemovePrefix would return a path that is relative to prefix in,
false if this path is unrelated to prefix in or unknown.

Checks if given prefix path can be removed from this path.

Has​Suffix


[Pure]
public method HasSuffix → (2)

suffix in : string

[not-null]
The name suffix.

caseSensitive opt : bool = true

Do case-sensitive comparison?

returns → bool

true if this path ends in suffix in, false if not.

Checks if the last named element of this path ends with the given suffix.

Is​Name


[Pure]
public static method IsName → (1)

name in : string

The name to test.

returns → bool

true if name is a valid path element name, false if not.

Is the given string a valid name for a single path element (i.e. file or directory name)?

Matches


[Pure]
public static method Matches → (3)

pattern in : string

The wildcard pattern.

other in : string

The path value.

caseSensitive opt : bool = true

Do case-sensitive comparison?

returns → bool

true if other matches this wildcard path, false if it does not.

Checks if the given wildcard pattern matches the given path value.


[Pure]
public method Matches1 → (2)

other in : string

The path value.

caseSensitive opt : bool = true

Do case-sensitive comparison?

returns → bool

true if other matches this wildcard path, false if it does not.

Checks if this wildcard Path matches the given path value.


[Pure]
public method Matches2 → (2)

other in : Path

The path value.

caseSensitive opt : bool = true

Do case-sensitive comparison?

returns → bool

true if other matches this wildcard path, false if it does not.

Checks if this wildcard Path matches the given path value.

Remove​Last


[Pure]
public method RemoveLast → ()

returns → Path

The resulting path or null if this path has no elements or if the resulting path would be empty.

Removes the last element from this path.

Example:

c:\some\directory\structure\myfile.txt

RemoveLast => c:\some\directory\structure

c:\some\directory\structure\

RemoveLast => c:\some\directory

c:\some

RemoveLast => c:\

c:\

RemoveLast => null
See also

Path.Last

Remove​Prefix


[Pure]
public method RemovePrefix → (3)

prefix in : Path

The prefix path.

unrelated opt : Path = null

The value to return if this path is unrelated to prefix in.

caseSensitive opt : bool = true

Do case-sensitive comparison?

returns → Path

The resulting path (will be this if prefix in is null or relative to prefix in) or unrelated opt if this path is unrelated to prefix in).

Removes the given prefix path from this path, if possible.

See also

Path.HasPrefix

Remove​Suffix

2 overloads


[Pure]
public method RemoveSuffix1 → (1)

delimiter opt : char = '.'

The suffix delimiter character.

returns → Path

The resulting path.

Removes a suffix from the last named element of this path.

c:\directory\myfile.txt

RemoveSuffix('.') => c:\directory\myfile
RemoveSuffix('-') => c:\directory\myfile.txt

c:\directory\myfile.txt.bak

RemoveSuffix('.') => c:\directory\myfile.txt

c:\directory.tmp\

RemoveSuffix('.') => c:\directory

[Pure]
public method RemoveSuffix2 → (1)

count in : int32

[>=0]
The number of suffix characters to remove.

returns → Path

The resulting path.

Removes the suffix from the last named element of this path.

Example:

c:\directory\myfile.txt

RemoveSuffix(4) => c:\directory\myfile

c:\directory\myfile.txt

RemoveSuffix(10) => c:\directory
RemoveSuffix(11) => c:\directory
RemoveSuffix(12) => c:\directory
etc.

c:\directory\

RemoveSuffix(1) => c:\director

Replace​Last


public method ReplaceLast → (1)

last in : string

[not-null]
The last name part, may be empty.

returns → Path

The resulting path.

Replaces the last name part (if any) of this path with the given value.

Resolve


public method Resolve → (1)

current in : Path

The current path.

returns → Path

The resolved path (not necessarily in canonical form).

Resolves this path, if it is relative, using the given current in path as the base directory.

If the given current path is null or Unknown, the method returns this. If this path is absolute or unknown, the method also returns this. Otherwise, the method appends this path to the current path.

To​Absolute


[Pure]
public method ToAbsolute → ()

returns → Path

The resulting path.

Makes this path absolute.

See also

Path.IsAbsolute

To​Relative


[Pure]
public method ToRelative → ()

returns → Path

The resulting path.

Makes this path relative.

To​Root​Selector

2 overloads


[Pure]
public method ToRootSelector1 → ()

returns → Path

The resulting path.

Changes the root selector of this path to null (i.e. none).


[Pure]
public method ToRootSelector2 → (1)

root in : string

The new root selector or null.

returns → Path

The resulting path.

Changes the root selector of this path.

If the given root in selector does not start with '//' resp. '\\' and does not end with ':', the root selector format of this path value will be retained.

To​Trailing


[Pure]
public method ToTrailing → (1)

trailing in : bool

true to append a trailing directory separator, if not present,
false to remove the trailing directory separator, if present.

returns → Path

The resulting path.

Appends or removes the trailing directory separator, if necessary.

See also

Path.IsTrailing

To​Url


[Pure]
public method ToUrl → ()

returns → string

The URL string.

Returns this path as a local file URL.

Validate


public method Validate → ()

returns → bool

true if all characters in this path are valid,
false if some characters are invalid.

Checks if this path contains only valid characters.

This method checks for additional restrictions on path names that are imposed by the IFileSystem that is associated with this path (see FileSystem.From).

Public / Attributes

Canonical


public attribute Canonical → (get)

value : Path

[not-null]
The canonical path or Unknown iff this path is unknown.

Returns the canonical name of this path (i.e. the fully resolved absolute path).

The resolved path will have the following properties:

  • It is absolute (see IsAbsolute).

  • It does not have a trailing directory separator (see IsTrailing).

  • It does not contain any '.' elements.

  • It does not contain any '..' elements.

  • All directory separator characters match the one defined by the operating system.

First


public attribute First → (get)

value : string

The last path part.

Returns the first named element of this path.

Example:

c:\some\directory\structure\myfile.txt

First => "some"

c:\some\directory\structure\

First => "some"

c:\

First => ""

Grammar​Rule​Path


public static attribute GrammarRulePath → (get)

value : IGrammarRule

[not-null]
The grammar rule.

Returns the grammar rule ('path') for parsing a path value.

Has​Root​Selector


public attribute HasRootSelector → (get)

value : bool

true if this path has a root selector, false if it does not.

Is this path rooted?

On some platforms, a path may contain a root selector (e.g. C: on windows platforms).

Home


public static attribute Home → (get)

value : Path

[not-null]
The home path.

Returns the canonical path to the current users home directory.

IOException

If an I/O error has occurred while obtaining the home path of the current user.

Is​Absolute


public attribute IsAbsolute → (get)

value : bool

true if this path is absolute, false if it is relative.

Is this path absolute?

An absolute path points to a file or directory independently of the current directory of the process.

Is​Canonical


public attribute IsCanonical → (get)

value : bool

true if this path is in canonical form, false if not.

Is this path in canonical form?

See also

Path.Canonical

Is​Relative


public attribute IsRelative → (get)

value : bool

true if this path is relative, false if it is absolute.

Is this path relative?

The file or directory a relative path points to is dependent on the current directory of the process.

Is​Trailing


public attribute IsTrailing → (get)

value : bool

true if the path ends with a separator, false if not.

Does this path string end with a directory separator?

See also

Path.ToTrailing

Is​Unknown


public attribute IsUnknown → (get)

value : bool

true if this is an unknown path, false if not.

Is this an unknown path?

See also

Path.Unknown

Is​Wildcard


public attribute IsWildcard → (get)

value : bool

true if this path contains one or more wildcards, false it not.

Is this a wildcard path?

The following wildcards are recognized:

  • '*': Matches zero or more characters of a name element.

  • '?': Matches one character of a name element.

Last


public attribute Last → (get)

value : string

The last path part.

Returns the last named element of this path.

Example:

c:\some\directory\structure\myfile.txt

Last => "myfile.txt"

c:\some\directory\structure\

Last => "structure"

c:\

Last => ""
See also

Path.RemoveLast

Length


public attribute Length → (get)

value : int32

[>=0]
The number of characters in the path string

Returns the number of characters in this path string.

Root​Selector


public attribute RootSelector → (get)

value : string

The root selector or null if this path does not have one.

Returns the root selector of this path.

On some platforms, a path may contain a root selector (e.g. C: on windows platforms):

c:\somefile.txt
C:\somefile.txt

RootSelector => "c:"

/usr/tmp

RootSelector => null

http://some.website.net

RootSelector => "http:"

The root selector contains lower-case characters only.

Root​Selector​Length


public attribute RootSelectorLength → (get)

value : int32

[>=0]
The root selector length, including the separator character.

Returns the length of the root selector of this path.

Temp


public static attribute Temp → (get)

value : Path

[not-null]
The temp path.

Returns the full path to the systems temp directory.

IOException

If an I/O error has occurred.

Extensions

Copy


public static method Copy → (1)

target in : Path

[not-null]
The target path.

Copies this file to the given target path.

For copying very large files, Operation.Copy may be used.

IOException

If an I/O error has occurred.

Copy​All


[OwnerReturn]
public static method CopyAll → (3)

target in : Path

[not-null]
The target directory.

filter opt : PredicateDelegate<Path> = null

Optional filter that chooses the files to copy. If null, all files are copied.

recur opt : PredicateDelegate<Path> = null

Optional filter that decides whether to recur into a subdirectory or not. If null, all subdirectories are visited.

returns → IOperation

The copy operation or null if no files or directories need to be copied.

Copies files from this directory to the given directory.

This method uses FindAll and Operation.Copy to build the returned IOperation.

IOException

If an I/O error has occurred.

See also

Path.Files

Delete


public static method Delete → ()

returns → bool

true if the file or directory has been deleted,
false if not or unknown, see Path.IsUnknown

Deletes the file or directory denoted by this path.

This method swallows IOError.NotEmpty errors and returns false in this case.

IOException

If an I/O error has occurred.

Delete​All


public static method DeleteAll → (3)

deleteThis opt : bool = true

Delete this path, too?

filter opt : PathFilterDelegate = null

The filter predicate that determines which Paths to collect for deletion. If null, all child Paths are collected.

recur opt : PredicateDelegate<Path> = null

The filter predicate that decides whether to recur into the tested directory or not. If null, recursion is done for all child directories.

returns → bool

true if all files and directories have been deleted,
false if not or unknown, see Path.IsUnknown.

Recursively deletes all files and directories, starting at this path.

IOException

If an I/O error has occurred.

Directory​Create


public static method DirectoryCreate → ()

returns → Path

this

Creates the directory this path points to.

If the given directory already exists, the method returns silently. The method will create all ancestor directories if necessary.

IOException

If an I/O error has occurred.

Directory​Delete


public static method DirectoryDelete → ()

returns → bool

true if the directory has been deleted,
false if it not or unknown, Path.IsUnknown.

Deletes the directory this path points to.

A directory can only be deleted if it is empty. Otherwise, an IOException with IOError.NotEmpty is thrown.

IOException

If an I/O error has occurred.

Directory​Exists


public static method DirectoryExists → ()

returns → bool

true if the directory exists,
false if not or unknown, see Path.IsUnknown.

Checks if this path points to an existing directory.

IOException

If an I/O error has occurred.

Directory​Free​Space


public static method DirectoryFreeSpace → ()

returns → int64

The available storage space, in bytes. Will be 0 if the available storage space cannot be determined (for any reason, except IOExceptions).

Returns the amount of storage space that is available in this directory.

If the given directory does not exist, the storage space for the nearest existing ancestor directory is reported. The returned value is intended to be used for coarse-grained resource decisions.

IOException

If an I/O error has occurred.

File​Delete


public static method FileDelete → ()

returns → bool

true if the file has been deleted,
false if not or unknown, see Path.IsUnknown.

Deletes the file this path points to.

IOException

If an I/O error has occurred.

File​Exists


public static method FileExists → ()

returns → bool

true if the file exists,
false if not or unknown, see Path.IsUnknown.

Checks if this path points to an existing file.

IOException

If an I/O error has occurred.

File​New


[OwnerReturn]
public static method FileNew → (1)

flags in : FileFlags

The file flags (creation disposition and behaviour flags).

returns → IFile

The created file.

Creates a new instance of IFile for this path.

IOException

If an I/O error has occurred.

Find​All


public static method FindAll → (3)

filter opt : PathFilterDelegate = null

The filter predicate that determines which Paths to collect in found opt. If null, all child Paths are collected.

recur opt : PredicateDelegate<Path> = null

The filter predicate that decides whether to recur into the tested directory or not. If null, recursion is done for all child directories.

found opt : IBag<Path> = null

Output collection for found Paths. If null, a new collection is created (see OrderedSet).

returns → IBag<Path>

A collection that holds all found Paths.

Finds all subdirectories and files in the directory pointed to by this Path object which match the given filter.

The found files and directories are added to the resulting collection in such order so that all of them may be deleted by iterating over the collection in reverse order.

IOException

If an I/O error has occurred.

Finder


public static method Finder → (1)

pattern opt : string = null

Optional name pattern using '?' and '*' wildcards. If null, the wildcards in this path are used, if present (see Path.IsWildcard); otherwise all files or directories are found.

returns → PathFinder

The PathFinder object.

Returns a PathFinder object that can later be used to find individual files or directories in this directory.

Find​Sibling​In​Ancestor


public static method FindSiblingInAncestor → (1)

sibling in : string

[not-empty]
Name of the file or directory to find.

returns → Path

The full path to the found file or directory or null if no directory has been found.

Tries to find a file or directory in the ancestor chain of this directory.

Beginning at the directory pointed to by this Path object, this method probes each parent directory in order to find a file or sub-directory named sibling in.

IOException

If an I/O error has occurred.

List​Directories


public static method ListDirectories → (2)

pattern opt : string = null

Optional name pattern using '?' and '*' wildcards.

caseSensitive opt : bool = true

Do case-sensitive comparison?

returns → Path [ ]

The list of canonical directory paths. The returned list order has no particular sort order.

Lists all subdirectories in the given directory.

IOException

If an I/O error has occurred.

List​Files


public static method ListFiles → (2)

pattern opt : string = null

Optional name pattern using '?' and '*' wildcards.

caseSensitive opt : bool = true

Do case-sensitive comparison?

returns → Path [ ]

The list of canonical file paths. The returned list order has no particular sort order.

Lists all files in the given directory.

IOException

If an I/O error has occurred.

Make​Current


public static method MakeCurrent → ()

Makes this path the current directory in its attached filesystem.

IOException

If an I/O error has occurred.

Make​Relative


[Pure]
public static method MakeRelative → (3)

home in : Path

[not-null]
The home path.

appendCurrent opt : bool = false

Append Path.Current before returning a relative path (e.g. './my/relative/path' instead of 'my/relative/path')?

caseSensitive opt : bool = true

Do case-sensitive comparison?

returns → Path

The relative path from home in to this or null if no relative path has been found.

Tries to create a relative path that points from home in to this path.

The canonical form of this path and home in will be used by this method (see Path.Canonical).

MD5


public static method MD5 → ()

returns → GUID

The MD5 checksum.

Computes the MD5 checksum of this file.

IOException

If an I/O error has occurred.

Parent​Directory​Create


public static method ParentDirectoryCreate → ()

returns → Path

this

Creates the parent directory.

If the parent directory already exists, the method returns silently.

The method will create all ancestor directories if necessary.

IOException

If an I/O error has occurred.

Read​All​Bytes


[OwnerReturn]
public static method ReadAllBytes → ()

returns → ByteBuffer

A buffer holding all bytes.

Reads all bytes from this file.

IOException

If an I/O error has occurred.

Read​All​Text


public static method ReadAllText → (2)

encoding opt : CharacterEncoding = null

The character encoding to use if no BOM is found. If null, CharacterEncodingSimple.ASCII will be used.

bom opt : bool = false

Consume a byte-order mark to choose the character encoding (will override encoding opt, if present)?

returns → string

The file text.

Reads all text from this file.

IOException

If an I/O error has occurred.

Rename


public static method Rename → (1)

name in : string

[not-empty]
The new file or directory name (see Path.Last).

returns → Path

The canonical path of the renamed file or directory.

Renames this file or directory to the given name in.

IOException

If an I/O error has occurred.

Stream​New


[OwnerReturn]
public static method StreamNew → (2)

flags in : FileFlags

The file flags (creation disposition and behaviour flags).

bufferSize opt : int32 = 65536

[>0]
The buffer size to use.

returns → IDataStream

The created file stream.

Creates a new instance of IDataStream for this path.

IOException

If an I/O error has occurred.

Throw​If​Unknown


public static method ThrowIfUnknown → (1)

source in : string

The error source tag to use.

Throws an IOException with IOError.BadPath if this path is unknown.

IOException

If this path is unknown.

See also

Path.IsUnknown

Timestamp

2 overloads


public static method Timestamp1 → ()

returns → int64

The timestamp value (see LicenceUtil.SystemTime).

Returns the timestamp of the last file modification.

IOException

If an I/O error has occurred.


public static method Timestamp2 → (1)

timestamp in : int64

The timestamp value (see LicenceUtil.SystemTime).

Sets the timestamp of the last file modification.

IOException

If an I/O error has occurred.

Write​All​Bytes


public static method WriteAllBytes → (1)

buffer in : ByteBuffer

[not-null]
The byte buffer.

Writes the given bytes to the file pointed to by this path.

IOException

If an I/O error has occurred.

Write​All​Text


public static method WriteAllText → (3)

text in : string

[not-null]
The text to write.

encoding opt : CharacterEncoding = null

The character encoding to use (giving null will use CharacterEncodingSimple.ASCII).

bom opt : bool = false

Output a byte-order mark (BOM), if applicable to the chosen encoding?

Writes the given text to the file pointed to by this path.

IOException

If an I/O error has occurred.

Serialization

Serial​Id


public static readonly attribute SerialId → (ISerialTypeInfo)

Serialization information about this type.