Class PathExtensions

Namespace

TruePath

Assembly

TruePath.dll

Extension methods for IPath and IPath<TPath>.

public static class PathExtensions

Inheritance

object

PathExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

GetExtensionWithDot(IPath)

Gets the extension of the file name of the path with the dot character.

For example, for the path file.txt, this method will return a string .txt.

File name entirely consisting of extension, such as .gitignore, is returned as-is.

public static string GetExtensionWithDot(this IPath path)

Parameters

path IPath

Returns

string

The extension of the file name of the path with the dot character (if present).

Remarks

This method will return an empty string for paths without extensions, and will return a dot for paths whose names end with a dot (even though it is an unusual path). This behavior allows to distinguish such paths, and potentially reconstruct the file name from its part without the extension and the "extension with dot".

GetExtensionWithoutDot(IPath)

Gets the extension of the file name of the path without the dot character.

For example, for the path file.txt, this method will return a string txt.

File name entirely consisting of extension, such as .gitignore, is returned with its leading dot trimmed.

public static string GetExtensionWithoutDot(this IPath path)

Parameters

path IPath

Returns

string

The extension of the file name of the path without the dot.

Remarks

This method will return an empty string for paths without extensions and with empty extensions (ending with dot, which may be unusual). This behavior doesn't allow to distinguish such paths using this method, to reconstruct the original name from its name without extension and its extension without dot.

GetFilenameWithoutExtension(IPath)

Gets the file name of the path without the extension.

For example, for the path file.txt, this method will return a string file.

public static string GetFilenameWithoutExtension(this IPath path)

Parameters

path IPath

Returns

string

The file name of the path without the extension. If the path has no extension, the file name is returned as-is (one trailing dot will be stripped, though).

WithExtension(AbsolutePath, string?)

Returns a new path of type AbsolutePath with the extension of its file name component changed.

public static AbsolutePath WithExtension(this AbsolutePath path, string? extension)

Parameters

path AbsolutePath

The original path.

extension string

The new extension, either with or without the leading dot: both txt and .txt give the same result, since the dot is added when missing.

Pass null to remove the extension entirely (file.txt becomes file), or an empty string to remove it but keep the trailing dot (file.txt becomes file.).

The extension may not contain a directory separator, and neither null, an empty string nor a lone dot may be passed for a file name that consists entirely of an extension: see the exception below.

Returns

AbsolutePath

A new path of type AbsolutePath with the modified file name component. The original path object is not modified.

Remarks

Only the last extension is replaced: for archive.tar.gz and the extension zip, the result is archive.tar.zip. The extension itself may contain dots, so .tar.gz applied to archive.zip gives archive.tar.gz.

If the file name has no extension, the new one is appended: file becomes file.txt.

A file name consisting entirely of an extension is treated as an extension, consistently with GetExtensionWithDot(IPath): .gitignore with the extension hgignore becomes .hgignore. Removing the extension of such a name is impossible, though: nothing would be left of the file name.

This method changes the extension and nothing else: the path always ends with a file name both before and after the call, and the number and the kind of its segments are always the same. Whenever the requested change would break that, it throws an ArgumentException instead of returning a path of a different shape.

Exceptions

ArgumentException

Thrown if the path has no file name to change: it is empty (which designates the current directory), it consists of a root or a drive designator alone, such as C:\, / or C:, or its last segment is a parent directory reference (..).

Also thrown if the requested change would leave something other than a file name in the file name's place: replacing .gitignore with null would leave nothing at all, and file.txt with the extension foo/bar would add a whole new segment.

WithExtension(LocalPath, string?)

Returns a new path of type LocalPath with the extension of its file name component changed.

public static LocalPath WithExtension(this LocalPath path, string? extension)

Parameters

path LocalPath

The original path.

extension string

The new extension, either with or without the leading dot: both txt and .txt give the same result, since the dot is added when missing.

Pass null to remove the extension entirely (file.txt becomes file), or an empty string to remove it but keep the trailing dot (file.txt becomes file.).

The extension may not contain a directory separator, and neither null, an empty string nor a lone dot may be passed for a file name that consists entirely of an extension: see the exception below.

Returns

LocalPath

A new path of type LocalPath with the modified file name component. The original path object is not modified.

Remarks

Only the last extension is replaced: for archive.tar.gz and the extension zip, the result is archive.tar.zip. The extension itself may contain dots, so .tar.gz applied to archive.zip gives archive.tar.gz.

If the file name has no extension, the new one is appended: file becomes file.txt.

A file name consisting entirely of an extension is treated as an extension, consistently with GetExtensionWithDot(IPath): .gitignore with the extension hgignore becomes .hgignore. Removing the extension of such a name is impossible, though: nothing would be left of the file name.

This method changes the extension and nothing else: the path always ends with a file name both before and after the call, and the number and the kind of its segments are always the same. Whenever the requested change would break that, it throws an ArgumentException instead of returning a path of a different shape.

Exceptions

ArgumentException

Thrown if the path has no file name to change: it is empty (which designates the current directory), it consists of a root or a drive designator alone, such as C:\, / or C:, or its last segment is a parent directory reference (..).

Also thrown if the requested change would leave something other than a file name in the file name's place: e.g. replacing C:\foo\.gitignore with null would leave nothing at all, and file.txt with the extension foo/bar would add a whole new segment.