TINMAN 3D / REALTIME TERRAIN
Software Development Kit - User Manual

class Path in Tinman.Core.IO

Represents a file path in a file system.

[ShutdownSurvive]
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).

Private / Constructors

Path

Creates a new instance of Path.

[Internal]
public constructor Path ()

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:

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 canonical path to the current users home directory.

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

Exceptions:

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:

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

Exceptions:

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:

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.

DeleteAll

Deletes all filed resp. directories denoted by toDelete.

public static method DeleteAll (IVectorConst<Path> toDelete)
type bool
params toDelete [not-null] The files resp. directories to delete. The elements are processed from last to first.
returns true if all files and directories have been deleted,
false if not.

Exceptions:

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

Exceptions:

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

Exceptions:

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 to null (i.e. none).

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

See also:

RootSelector

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.

Remarks:

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

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

Copy

Copies this file to the given target path.

method Copy (Path target)
params target [not-null] The target path.

Exceptions:

CopyAll

Copies files from this directory to the given directory.

[OwnerReturn]
method CopyAll (Path target, PredicateDelegate<Path> filter = null, PredicateDelegate<Path> recur = null)
type IOperation
params target [not-null] The target directory.
  filter Optional filter that chooses the files and directories to copy. If null, all files and directories are copied. Defaults to null.
  recur Optional filter that decides whether to recur into a subdirectory or not. If null, all subdirectories are visited. Defaults to null.
returns The copy operation or null if no files or directories need to be copied.

Exceptions:

Delete

Deletes the file or directory denoted by this path.

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

Remarks:

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

Exceptions:

DeleteAll

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

method DeleteAll (bool deleteThis = true)
type bool
params deleteThis Delete this path, too? Defaults to true.
returns true if all files and directories have been deleted,
false if not.

Exceptions:

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.

Exceptions:

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. Otherwise, an IOException with NotEmpty is thrown.

Exceptions:

DirectoryExists

Checks if the given directory exists.

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

Exceptions:

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. Will be 0 if the available storage space cannot be determined (for any reason, except IOException s).

Remarks:

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.

Exceptions:

FileDelete

Deletes the given file, if it exists.

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

Exceptions:

FileExists

Shortcut to FileExists.

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

Exceptions:

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.

Exceptions:

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.

Remarks:

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

Exceptions:

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 sub-directory named sibling.

Exceptions:

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.

Exceptions:

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.

Exceptions:

MakeCurrent

Makes this path the current directory in its attached filesystem.

method MakeCurrent ()

Exceptions:

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

MD5

Computes the MD5 checksum of this file.

method MD5 ()
type GUID
returns The MD5 checksum.

Exceptions:

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.

Exceptions:

ReadAllBytes

Reads all bytes from this file.

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

Exceptions:

ReadAllText

Reads all text from this file.

method ReadAllText (CharacterEncoding encoding = null, bool bom = false)
type string
params encoding The character encoding to use if no BOM is found. If null, ASCII will be used. 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.

Exceptions:

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.

Exceptions:

WriteAllBytes

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

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

Exceptions:

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.

Exceptions: