Struct LocalPath

Namespace

TruePath

Assembly

TruePath.dll

A path pointing to a place in the local file system.

It may be either absolute or relative.

An empty path designates the current directory. Normalizing an empty string, . or a/.. produces it, and so does Parent of a relative path consisting of a single segment (e.g. the parent of foo).

Always stored in a normalized form. Read the documentation on Normalize(string) to know what form of normalization the path uses.

public readonly struct LocalPath : IEquatable<LocalPath>, IComparable<LocalPath>, IPath, IPath<LocalPath>

Implements

IEquatable<LocalPath>

IComparable<LocalPath>

IPath

IPath<LocalPath>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Extension Methods

PathExtensions.GetExtensionWithDot(IPath)

PathExtensions.GetExtensionWithoutDot(IPath)

PathExtensions.GetFilenameWithoutExtension(IPath)

PathExtensions.WithExtension(LocalPath, string?)

Remarks

Uninitialized values of this structure (e.g. default(LocalPath)) will throw NullReferenceException from many of the APIs.

Constructors

LocalPath(string)

A path pointing to a place in the local file system.

It may be either absolute or relative.

An empty path designates the current directory. Normalizing an empty string, . or a/.. produces it, and so does Parent of a relative path consisting of a single segment (e.g. the parent of foo).

Always stored in a normalized form. Read the documentation on Normalize(string) to know what form of normalization the path uses.

public LocalPath(string value)

Parameters

value string

Remarks

Uninitialized values of this structure (e.g. default(LocalPath)) will throw NullReferenceException from many of the APIs.

LocalPath(AbsolutePath)

Converts an AbsolutePath to a LocalPath.

public LocalPath(AbsolutePath path)

Parameters

path AbsolutePath

Fields

PlatformDefaultComparer

Provides a default comparer for comparing file paths, aware of the current platform.

On Windows, macOS, iOS and tvOS, this will perform case-insensitive string comparison, since the file systems are case-insensitive on these operating systems by default.

On Linux, the comparison will be case-sensitive.

public static readonly IPathComparer<LocalPath> PlatformDefaultComparer

Field Value

IPathComparer<LocalPath>

Remarks

Note that this comparison does not guarantee correctness: in practice, on any platform to control case-sensitiveness of either the whole file system or a part of it. This class does not take this into account, having a benefit of no accessing the file system for any of the comparisons.

StrictStringComparer

A strict comparer for comparing file paths using ordinal, case-sensitive comparison of the underlying path strings.

public static readonly IPathComparer<LocalPath> StrictStringComparer

Field Value

IPathComparer<LocalPath>

Properties

FileName

The name of this path's last component.

public string FileName { get; }

Property Value

string

IsAbsolute

Checks whether the path is absolute, i.e. it is fully qualified, and doesn't depend on the current directory, or current directory on any drive (Windows-specific).

On Windows, this requires a drive letter and a root directory: C:\Windows is absolute, while \Windows and C:Windows are not.

public bool IsAbsolute { get; }

Property Value

bool

Remarks

Equivalent to checking that Kind is Absolute.

Kind

Determines the kind of this path. See PathKind for the details.

public PathKind Kind { get; }

Property Value

PathKind

Parent

The parent of this path. Will be null for a rooted absolute path. For a relative path, will always resolve to its parent directory — by either removing directories from the end of the path, or appending

..

to the end.

public LocalPath? Parent { get; }

Property Value

LocalPath?

Remarks

The parent of a relative path consisting of a single segment is the empty path (the current directory), not null. Similarly, on Windows, the parent of a bare drive (C:, the current directory of that drive) is C:...

PathRoot

Gets the root of this path, if it can be determined without resolving against the current directory.

• For an absolute path, this is its root: C:\ for C:\foo on Windows, / for /foo on Unix.
• For a drive-relative path on Windows (e.g. C:foo or C:), this is the root of that drive (C:\).
• For a relative path, or a path rooted without a drive letter on Windows (e.g. \foo), this is null.

public AbsolutePath? PathRoot { get; }

Property Value

AbsolutePath?

Value

The normalized path string.

public string Value { get; }

Property Value

string

Methods

CompareTo(LocalPath)

Compares the current LocalPath instance with another LocalPath instance, using the default platform-aware comparison rules provided by TruePath.Comparers.PlatformDefaultPathComparer<TPath>.

public int CompareTo(LocalPath other)

Parameters

other LocalPath

The LocalPath instance to compare with the current instance.

Returns

int

A signed integer that indicates the relative order of the compared objects.

Value	Meaning
Less than zero	The current instance precedes other in the sort order.
Zero	The current instance occurs in the same position in the sort order as other.
Greater than zero	The current instance follows other in the sort order.

Create(string)

Creates a new LocalPath instance from the specified string value.

public static LocalPath Create(string value)

Parameters

value string

The string representation of the path to create.

Returns

LocalPath

A new normalized LocalPath instance representing the specified path.

Equals(object?)

Compares the path with another.

public override bool Equals(object? obj)

Parameters

obj object

Returns

bool

Remarks

Uses PlatformDefaultComparer for platform-default case sensitivity.

Equals(LocalPath)

Compares the path with another.

public bool Equals(LocalPath other)

Parameters

other LocalPath

Returns

bool

Remarks

Uses PlatformDefaultComparer for platform-default case sensitivity.

Equals(LocalPath, IEqualityComparer<LocalPath>)

Determines whether the specified LocalPath is equal to the current LocalPath using the specified string comparer.

public bool Equals(LocalPath other, IEqualityComparer<LocalPath> comparer)

Parameters

other LocalPath

The LocalPath to compare with the current LocalPath.

comparer IEqualityComparer<LocalPath>

The comparer to use for comparing the paths.

Returns

bool

true if the specified LocalPath is equal to the current LocalPath using the specified string comparer; otherwise, false.

GetHashCode()

public override int GetHashCode()

Returns

int

IsPrefixOf(LocalPath)

public bool IsPrefixOf(LocalPath other)

Parameters

other LocalPath

Returns

bool

Remarks

Checks for a non-strict prefix: if the paths are equal, then they are still considered prefixes of each other, so every path is a prefix of itself.

RelativeTo(LocalPath)

Calculates the relative path from a base path to this path.

public LocalPath RelativeTo(LocalPath basePath)

Parameters

basePath LocalPath

The base path from which to calculate the relative path.

Returns

LocalPath

The relative path from the base path to this path, or the resolved absolute path to this path if the paths have different roots.

Remarks

If either path is not absolute, it is first resolved against the current directory, the same way ResolveToCurrentDirectory() does, so the result may depend on the current directory (or a drive-specific current directory on Windows). Two relative paths are resolved against the same directory, so a/b relative to a is b. An empty path designates the current directory.

If the resolved paths have different roots (on Windows, e.g. paths on different drives), there's no relative path between them, and the resolved absolute path to this path is returned instead: D:\x relative to C:\y is D:\x. On Unix, all paths share the same root, so this never happens.

ResolveToCurrentDirectory()

Resolves this path to an absolute path based on the current working directory.

public AbsolutePath ResolveToCurrentDirectory()

Returns

AbsolutePath

An AbsolutePath that represents this path resolved against the current working directory.

Remarks

Note that if this path is already absolute, it will just transform to AbsolutePath. The current directory won't matter for such a case.

On Windows, a path rooted without a drive letter (\x) is resolved against the drive of the current directory, and a path relative to the current directory of a drive (D:x) is resolved against the current directory of that drive, as tracked by the process (see GetFullPath(string)), or against the root of that drive if the process doesn't track one.

This is the same as AbsolutePath.CurrentWorkingDirectory / this (see operator /(AbsolutePath, LocalPath)), so the result is always absolute.

StartsWith(LocalPath)

Determines whether the current path starts with the specified path.

public bool StartsWith(LocalPath other)

Parameters

other LocalPath

The path to compare to the current path.

Returns

bool

Remarks

Checks for a non-strict prefix: if the paths are equal, then each still starts with the other, so every path starts with itself.

ToString()

public override string ToString()

Returns

string

The normalized path string contained in this object.

Operators

operator /(LocalPath, string)

Appends another path to this one.

public static LocalPath operator /(LocalPath basePath, string b)

Parameters

basePath LocalPath

The path to append to.

b string

The path to append.

Returns

LocalPath

The combined path, normalized.

Remarks

The result designates the same location as changing the current directory first to basePath, and then to b: a / b means the same as cd /d a && cd /d b on Windows, or cd a && cd b on Unix. A base path without a drive letter is considered to be on a different drive than any drive letter in b.

Depending on the Kind of b:

• Absolute (D:\x, /x): b replaces the base path.
• Relative (x): b is appended after a separator, so C:\base / x is C:\base\x. No separator is added after a bare drive: C: / x is C:x. Appending an empty path returns the base path unchanged, and appending to an empty path returns b.
• DriveRootRelative (\x): the drive of the base path is kept, if there is one. C:\base / \x and C:base / \x are both C:\x, while base / \x is \x.
• DriveCurrentDirectoryRelative (C:x): if the base path is on the same drive, the rest of b is appended as a relative path, so C:\base / C:x is C:\base\x. Otherwise, b replaces the base path: C:\base / D:x is D:x, and base / C:x is C:x. Drive letters are compared case-insensitively.

This is the algorithm of C++'s std::filesystem::path::operator/, except that the result is normalized (e.g. C:\base / "" gets no trailing separator after normalization).

Important: this operator differs from Combine(string, string), which returns its second argument if that is rooted, and otherwise joins the arguments with a separator:

• C:\base / \x is C:\x, while Path.Combine returns \x;
• C:\base / C:x is C:\base\x, while Path.Combine returns C:x;
• C: / x is C:x, while Path.Combine returns C:\x on .NET 10 (.NET Framework 4.8.1, though, will return C:x);
• the result is normalized.

On Unix, the result is the same as the one of Path.Combine, up to normalization.

See Also

C++ standard: path appends (fs.path.append)

operator /(LocalPath, LocalPath)

Appends another path to this one.

public static LocalPath operator /(LocalPath basePath, LocalPath b)

Parameters

basePath LocalPath

The path to append to.

b LocalPath

The path to append.

Returns

LocalPath

The combined path, normalized.

Remarks

The result designates the same location as changing the current directory first to basePath, and then to b: a / b means the same as cd /d a && cd /d b on Windows, or cd a && cd b on Unix. A base path without a drive letter is considered to be on a different drive than any drive letter in b.

Depending on the Kind of b:

• Absolute (D:\x, /x): b replaces the base path.
• Relative (x): b is appended after a separator, so C:\base / x is C:\base\x. No separator is added after a bare drive: C: / x is C:x. Appending an empty path returns the base path unchanged, and appending to an empty path returns b.
• DriveRootRelative (\x): the drive of the base path is kept, if there is one. C:\base / \x and C:base / \x are both C:\x, while base / \x is \x.
• DriveCurrentDirectoryRelative (C:x): if the base path is on the same drive, the rest of b is appended as a relative path, so C:\base / C:x is C:\base\x. Otherwise, b replaces the base path: C:\base / D:x is D:x, and base / C:x is C:x. Drive letters are compared case-insensitively.

This is the algorithm of C++'s std::filesystem::path::operator/, except that the result is normalized (e.g. C:\base / "" gets no trailing separator after normalization).

Important: this operator differs from Combine(string, string), which returns its second argument if that is rooted, and otherwise joins the arguments with a separator:

• C:\base / \x is C:\x, while Path.Combine returns \x;
• C:\base / C:x is C:\base\x, while Path.Combine returns C:x;
• C: / x is C:x, while Path.Combine returns C:\x on .NET 10 (.NET Framework 4.8.1, though, will return C:x);
• the result is normalized.

On Unix, the result is the same as the one of Path.Combine, up to normalization.

See Also

C++ standard: path appends (fs.path.append)

operator ==(LocalPath, LocalPath)

Compares the path with another.

public static bool operator ==(LocalPath left, LocalPath right)

Parameters

left LocalPath

right LocalPath

Returns

bool

Remarks

Uses PlatformDefaultComparer for platform-default case sensitivity.

implicit operator LocalPath(AbsolutePath)

Implicitly converts an AbsolutePath to a LocalPath.

public static implicit operator LocalPath(AbsolutePath path)

Parameters

path AbsolutePath

Returns

LocalPath

Remarks

Note that this conversion doesn't lose any information.

operator !=(LocalPath, LocalPath)

Compares the path with another.

public static bool operator !=(LocalPath left, LocalPath right)

Parameters

left LocalPath

right LocalPath

Returns

bool

Remarks

Uses PlatformDefaultComparer for platform-default case sensitivity.