class Path in Tinman.Core.IO

Represents a file path in a file system.

sealed class	Path	implements	IComparable<Path>
			IEquatable<Path>
		extends	SerializableBase

Remarks

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

Serialization

SerialId

Serialization information about this type.

public static readonly field	SerialId
type	ISerialTypeInfo

Public / Constants

Current

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

public static readonly field	Current
type	Path

Parent

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

public static readonly field	Parent
type	Path

Root

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

public static readonly field	Root
type	Path

Unknown

Special Path object for representing an unknown file path.

public static readonly field	Unknown
type	Path

Public / Attributes

Canonical

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

public property	Canonical { get }
type	Path
value	[not-null]	The canonical path.

Remarks:

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

Returns the first named element of this path.

public property	First { get }
type	string
value		The last path part.

Remarks:

Example:

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

First => "some"

c:\some\directory\structure\

First => "some"

c:\

First => ""

GrammarRulePath

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

public static property	GrammarRulePath { get }
type	IGrammarRule
value	[not-null]	The grammar rule.

HasRootSelector

Is this path rooted?

public property	HasRootSelector { get }
type	bool
value		true if this path has a root selector, false if it does not.

Remarks:

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

See also:

RootSelector

Home

Returns the full path to the current users home directory.

public static property	Home { get }
type	Path
value	[not-null]	The home path.

IsAbsolute

Is this path absolute?

public property	IsAbsolute { get }
type	bool
value		true if this path is absolute, false if it is relative.

Remarks:

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

See also:

ToAbsolute
IsRelative

IsCanonical

Is this path in canonical form?

public property	IsCanonical { get }
type	bool
value		true if this path is in canonical form, false if not.

See also:

Canonical

IsRelative

Is this path relative?

public property	IsRelative { get }
type	bool
value		true if this path is relative, false if it is absolute.

Remarks:

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

See also:

ToRelative
IsAbsolute

IsTrailing

Does this path string end with a directory separator?

public property	IsTrailing { get }
type	bool
value		true if the path ends with a separator, false if not.

See also:

ToTrailing

IsUnknown

Is this an unknown path?

public property	IsUnknown { get }
type	bool
value		true if this is an unknown path, false if not.

IsWildcard

Is this a wildcard path?

public property	IsWildcard { get }
type	bool
value		true if this path contains one or more wildcards, false it not.

Remarks:

The following wildcards are recognized:

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

Last

Returns the last named element of this path.

public property	Last { get }
type	string
value		The last path part.

Remarks:

Example:

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

Last => "myfile.txt"

c:\some\directory\structure\

Last => "structure"

c:\

Last => ""

See also:

RemoveLast

Length

Returns the number of characters in this path string.

public property	Length { get }
type	int32
value	[>=0]	The number of characters in the path string

RootSelector

Returns the root selector of this path.

public property	RootSelector { get }
type	string
value		The root selector or null if this path does not have one.

Remarks:

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.

See also:

HasRootSelector
ToRootSelector

RootSelectorLength

Returns the length of the root selector of this path.

public property	RootSelectorLength { get }
type	int32
value	[>=0]	The root selector length.

SerialType

Returns the serial type of this object.

public property	SerialType { get }
type	ISerialTypeInfo
value	[not-null]	The serial type.
inherited	SerializableBase.SerialType

SerialVersion

Returns the serial data version.

public virtual property	SerialVersion { get }
type	int32
value	[>=1]	The serial data version tag.
inherited	SerializableBase.SerialVersion

Remarks:

An ISerializable implementation is required to support all versions up to the one returned by SerialVersion.

See also:

ISerializable.Serialize
ISerializable.Deserialize

Temp

Returns the full path to the systems temp directory.

public static property	Temp { get }
type	Path
value	[not-null]	The temp path.

Public / Constructors

Coalesce

Returns the first non-null path.

[Pure]
public static method	Coalesce (IPathInfo a)
type	Path
params	a		First path value.
returns		[not-null]	The first non-null path or Unknown.

From

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

[Pure]
public static method	From (string path)
type	Path
params	path	[not-empty]	The path string.
returns		[not-null]	The Path object.

Exceptions:

• IOException:
  If the given path string is invalid (ErrorCode == BadPath).

FromNull

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

[Pure]
public static method	FromNull (string path)
type	Path
params	path		The path string.
returns			The Path object or null if the given path string is invalid.

Guess

Tries to guess a Path value from the given object.

public static method	Guess (object obj)
type	Path
params	obj		Some object reference.
returns		[not-null]	The guessed Path value or Unknown.

Remarks:

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

Public / Methods

AppendName

Appends the given path element to this path.

[Pure]
public method	AppendName (string name)
type	Path
params	name	[not-empty]	The path element to add.
returns		[not-null]	The resulting path.

Remarks:

Example:

c:\some\directory\structure

or

c:\some\directory\structure\

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

AppendPath

Appends the given path to this one.

[Pure]
public method	AppendPath (Path path)
type	Path
params	path	[not-null]	The other path.
returns		[not-null]	The resulting path.

Remarks:

Example:

c:\some\directory\structure

or

c:\some\directory\structure\

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

AppendSuffix

Appends the given suffix to this path.

[Pure]
public method	AppendSuffix (string suffix)
type	Path
params	suffix	[not-empty]	The suffix to append.
returns		[not-null]	The resulting path.

Remarks:

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

See also:

HasSuffix
RemoveSuffix

---

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

[Pure]
public method	AppendSuffix (char delimiter, string suffix)
type	Path
params	delimiter		The delimiter char to append.
	suffix	[not-empty]	The suffix to append.
returns		[not-null]	The resulting path.

Remarks:

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

See also:

GetSuffix
RemoveSuffix

Coalesce

Returns the first non-null path.

[Pure]
public static method	Coalesce (Path a, Path b = null)
type	Path
params	a		First path value (can be null).
	b		Second path value (can be null).
returns		[not-null]	The first non-null path or Unknown.

CompareTo

Compares this object with the given one.

[Pure]
public method	CompareTo (Path other)
type	int32
params	other		The object to compare to.
returns			< 0 : if this object is less than other, = 0 : if this object is equal to other, > 0 : if this object is greater than other.
implements	IComparable.CompareTo

Concat

Concatenates the given path values.

[Pure]
public static method	Concat (Path a, Path b)
type	Path
params	a		First path value or null.
	b		Second path value or null.
returns			The resulting path value.

Deserialize

Initializes the state of this object from the given data stream.

public override method	Deserialize (int32 serialVersion, ISerializer data)
type	ISerializable
params	serialVersion	[>=1]	The serial data version.
	data	[not-null]	The serial data stream.
returns		[not-null]	The deserialized object. This will typically be this, but in some circumstances, another instance may be returned (e.g. singletons).
overrides	SerializableBase.Deserialize

Remarks:

The Deserialize method will be called immediately after the object has been instantiated via its default constructor.

The provided serialVersion number is guaranteed to be equal to or less than the SerialVersion returned by this object (i.e. ISerializable object must provide backwards compatibility).

See also:

ISerializable.Serialize
ISerializable.SerialVersion

Equals

Compares this object with the given one.

[Pure]
public override method	Equals (object other)
type	bool
params	other		The object to compare to.
returns			true if this object is equal to other, false if not.

---

Compares this object with the given one.

[Pure]
public method	Equals (Path other)
type	bool
params	other		The object to compare to.
returns			true if this object is equal to other, false if not.
implements	IEquatable.Equals

GetFileSystem

Returns the IFileSystem object that owns this path value.

[Pure]
public method	GetFileSystem ()
type	IFileSystem
returns		[not-null]	The IFileSystem to use.

GetHashCode

[Pure]
public override method	GetHashCode ()
type	int32

GetSuffix

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

[Pure]
public method	GetSuffix (char delimiter = ''.'')
type	string
params	delimiter		The suffix delimiter character. Defaults to '.'.
returns			The suffix string (excluding the delimiter character); will be an empty string if this path does not include a suffix.

See also:

AppendSuffix
RemoveSuffix

HasSuffix

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

[Pure]
public method	HasSuffix (string suffix)
type	bool
params	suffix	[not-null]	The name suffix.
returns			true if this path ends in suffix, false if not.

See also:

AppendSuffix
RemoveSuffix

IsName

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

[Pure]
public static method	IsName (string name)
type	bool
params	name		The name to test.
returns			true if name is a valid path element name, false if not.

See also:

First
Last
AppendName
AppendSuffix
AppendSuffix

Matches

Checks if this wildcard Path matches the given path value.

[Pure]
public method	Matches (string other)
type	bool
params	other		The path value.
returns			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	Matches (Path other)
type	bool
params	other		The path value.
returns			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 static method	Matches (string pattern, string other)
type	bool
params	pattern		The wildcard pattern.
	other		The path value.
returns			true if other matches this wildcard path, false if it does not.

RemoveLast

Removes the last element from this path.

[Pure]
public method	RemoveLast ()
type	Path
returns			The resulting path or null if this path has no elements.

Remarks:

Example:

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

Parent => c:\some\directory\structure

c:\some\directory\structure\

Parent => c:\some\directory

c:\some

Parent => c:\

c:\

Parent => null

See also:

Last

RemovePrefix

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

[Pure]
public method	RemovePrefix (Path prefix, Path unrelated = null)
type	Path
params	prefix		The prefix path.
	unrelated		The value to return if this path is unrelated to prefix. Defaults to null.
returns			The resulting path (will be relative to prefix) or unrelated if this path is unrelated to prefix).

RemoveSuffix

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

[Pure]
public method	RemoveSuffix (char delimiter = ''.'')
type	Path
params	delimiter		The suffix delimiter character. Defaults to '.'.
returns		[not-null]	The resulting path.

Remarks:

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

See also:

AppendSuffix
GetSuffix

---

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

[Pure]
public method	RemoveSuffix (int32 count)
type	Path
params	count	[>=0]	The number of suffix characters to remove.
returns		[not-null]	The resulting path.

Remarks:

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

See also:

AppendSuffix
HasSuffix

Resolve

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

public method	Resolve (Path current)
type	Path
params	current		The current path.
returns		[not-null]	The resolved path (not necessarily in canonical form).

Remarks:

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 the current path and this path.

Serialize

Serializes the current state of this object to the given data stream.

public override method	Serialize (ISerializer data)
params	data	[not-null]	The serial data stream.
overrides	SerializableBase.Serialize

See also:

ISerializable.Deserialize
ISerializable.SerialVersion

ToAbsolute

Makes this path absolute.

[Pure]
public method	ToAbsolute ()
type	Path
returns		[not-null]	The resulting path.

See also:

IsAbsolute

ToRelative

Makes this path relative.

[Pure]
public method	ToRelative ()
type	Path
returns		[not-null]	The resulting path.

ToRootSelector

Changes the root selector of this path.

[Pure]
public method	ToRootSelector (string root)
type	Path
params	root		The new root selector or null.
returns		[not-null]	The resulting path.

See also:

RootSelector

ToString

[Pure]
public override method	ToString ()
type	string

ToTrailing

Appends or removes the trailing directory separator, if necessary.

[Pure]
public method	ToTrailing (bool trailing)
type	Path
params	trailing		true to append a trailing directory separator, if not present, false to remove the trailing directory separator, if present.
returns		[not-null]	The resulting path.

See also:

IsTrailing

ToUrl

Returns this path as a local file URL.

[Pure]
public method	ToUrl ()
type	string
returns		[not-null]	The URL string.

Public / Extensions

DirectoryCreate

Creates the given directory.

method

DirectoryCreate ()

Remarks:

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

The method will create all ancestor directories if necessary.

DirectoryDelete

Deletes the given directory.

method	DirectoryDelete ()
type	bool
returns			true if the directory has been deleted, false if it not.

Remarks:

A directory can only be deleted if it is empty.

DirectoryExists

Checks if the given directory exists.

method	DirectoryExists ()
type	bool
returns			true if the directory exists, false if not.

DirectoryFreeSpace

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

method	DirectoryFreeSpace ()
type	int64
returns		[>=0]	The available storage space, in bytes.

Remarks:

If the directory does not exist, the storage space for the nearest existing ancestor directory is reported.

FileDelete

Deletes the given file, if it exists.

method	FileDelete ()
type	bool
returns			true if the file has been deleted, false if not.

FileExists

Shortcut to FileExists.

method	FileExists ()
type	bool
returns			true if path points to an existing file, false if not.

FileNew

Creates a new instance of IFile for this path.

[OwnerReturn]
method	FileNew (FileFlags flags)
type	IFile
params	flags		The file flags (creation disposition and behaviour flags).
returns		[not-null]	The created file.

FindAll

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

method	FindAll (PredicateDelegate<Path> filter = null, PredicateDelegate<Path> recur = null, IBag<Path> found = null)
type	IBag<Path>
params	filter		The filter predicate that determines which Path s to collect in found. If null, all child Path s are collected. Defaults to null.
	recur		The filter predicate that decides whether to recur into the testes directory or not. If null, recursion is done for all child directories. Defaults to null.
	found		Output collection for found Path s. If null, a new collection is created. Defaults to null.
returns		[not-null]	A collection that holds all found Path s.

Finder

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

method	Finder (string pattern = null)
type	PathFinder
params	pattern		Optional name pattern using '?' and '*' wildcards. If null, the wildcards in this path are used, if present (see IsWildcard); otherwise all files or directories are found. Defaults to null.
returns		[not-null]	The PathFinder object.

FindSiblingInAncestor

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

method	FindSiblingInAncestor (string sibling)
type	Path
params	sibling	[not-empty]	Name of the file or directory to find.
returns			The full path to the found file or directory or null if no directory has been found.

Remarks:

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

ListDirectories

Lists all subdirectories in the given directory.

method	ListDirectories (string pattern = null)
type	Path[]
params	pattern		Optional name pattern using '?' and '*' wildcards. Defaults to null.
returns		[not-null]	The list of canonical directory paths. The returned list order has no particular sort order.

ListFiles

Lists all files in the given directory.

method	ListFiles (string pattern = null)
type	Path[]
params	pattern		Optional name pattern using '?' and '*' wildcards. Defaults to null.
returns		[not-null]	The list of canonical file paths. The returned list order has no particular sort order.

MakeCurrent

Makes this path the current directory in its attached filesystem.

method

MakeCurrent ()

MakeRelative

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

method	MakeRelative (Path home, bool appendCurrent = false)
type	Path
params	home	[not-null]	The home path.
	appendCurrent		Append Current before returning a relative path (e.g. './my/relative/path' instead of 'my/relative/path')? Defaults to false.
returns			The relative path from home to this or null if no relative path has been found.

Remarks:

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

ParentDirectoryCreate

Creates the parent directory.

method	ParentDirectoryCreate ()
type	Path
returns		[not-null]	this

Remarks:

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

The method will create all ancestor directories if necessary.

ReadAllBytes

Reads all bytes from this file.

[OwnerReturn]
method	ReadAllBytes ()
type	ByteBuffer
returns		[not-null]	A buffer holding all bytes.

ReadAllText

Reads all text from this file.

method	ReadAllText (CharacterEncoding encoding = null, bool bom = false)
type	string
params	encoding		The character encoding to use (giving null will use ASCII). Defaults to null.
	bom		Consume a byte-order mark to choose the character encoding (will override encoding, if present)? Defaults to false.
returns		[not-null]	The file text.

StreamNew

Creates a new instance of IDataStream for this path.

[OwnerReturn]
method	StreamNew (FileFlags flags, int32 bufferSize = 65536)
type	IDataStream
params	flags		The file flags (creation disposition and behaviour flags).
	bufferSize	[>0]	The buffer size to use. Defaults to 65536.
returns		[not-null]	The created file stream.

WriteAllBytes

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

method	WriteAllBytes (ByteBuffer buffer)
params	buffer	[not-null]	The byte buffer.

WriteAllText

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

method	WriteAllText (string text, CharacterEncoding encoding = null, bool bom = false)
params	text	[not-null]	The text to write.
	encoding		The character encoding to use (giving null will use ASCII). Defaults to null.
	bom		Output a byte-order mark (BOM), if applicable to the chosen encoding? Defaults to false.