TruePath 2.0.0

• .NETStandard 2.0

  • Microsoft.Bcl.Memory (>= 10.0.13)

• net8.0

  • No dependencies.

This is a major release with certain breaking changes. No public APIs have been broken, but the amount of minor behavior changes required us to bump the major version.

The main change (outlined below) is the introduction of the relative path kinds (most important for Windows). TruePath's path resolve APIs now follow the new rules regarding the relative path resolve (especially regarding more exotic relative path kinds on Windows); check the relevant documentation.

Another notable change is that, while LocalPath still considers an empty path to designate the current directory, current directory now always gets normalized as "." and not an empty string.

There were a bunch of unrelated important (sometimes breaking) changes to other APIs, read the details below.

[Changed]

- Breaking: (#224 (https://github.com/ForNeVeR/TruePath/issues/224)) on Windows, LocalPath.IsAbsolute now only returns true for fully qualified paths, such as C:\Windows. Paths rooted without a drive letter (\Windows), and paths relative to the current directory of a drive (C:Windows, C:) are not absolute anymore, and AbsolutePath now rejects them. Previously, this was following the Path.IsPathRooted API.
- Breaking: (#224 (https://github.com/ForNeVeR/TruePath/issues/224)) on Windows, the / operator of LocalPath and AbsolutePath no longer delegates to Path.Combine, and instead follows the algorithm of C++ std::filesystem::path::operator/ (fs.path.append (https://eel.is/c++draft/fs.path.append)) with case-insensitive drive letters. In particular, C:\base / \x is now C:\x (was \x), C:\base / C:x is now C:\base\x (was C:x), and C: / x is now C:x (was C:\x). On Unix, the behavior is unchanged.
- Breaking: path normalization now represents the current directory as . instead of an empty string: PathStrings.Normalize returns "." for "", "." and "a/..", and so do LocalPath.Value and ToString() (and LocalPath.Parent of a single-segment relative path is .). As a consequence, LocalPath.FileName of such a path is ., the same way it is .. for .., and GetExtensionWithDot returns . for it.
- Breaking: LocalPath.IsPrefixOf and StartsWith now consider paths of different PathKind unrelated: an absolute path is never a prefix of a relative one, nor the other way round, and on Windows \Windows, C:Windows and Windows are all unrelated to each other.
- Breaking: PathExtensions.WithExtension now throws an ArgumentException unless the path ends with a file name and the result of the change is a file name in its place: an extension change may no longer alter the number or the kind of any path's segments. It used to do so, e.g.:
- new LocalPath(@"C:\foo\.gitignore").WithExtension(null) returned C:\foo,
- new LocalPath(".gitignore").WithExtension(null) returned the empty path,
- and new LocalPath(@"C:\").WithExtension("bar") returned C:\.bar.
None of the examples above take place anymore.
- #224 (https://github.com/ForNeVeR/TruePath/issues/224): on Windows, AbsolutePath / LocalPath now resolves a path relative to the current directory of another drive against the current directory of that drive, so the result is always absolute: e.g. C:\base / D:x is D:\x if the current directory of drive D: is its root. Previously, the result was D:x, which is not absolute.
- #224 (https://github.com/ForNeVeR/TruePath/issues/224): on Windows, LocalPath.ResolveToCurrentDirectory now resolves \x against the drive of the current directory, and D:x against the current directory of drive D:.
- #240 (https://github.com/ForNeVeR/TruePath/issues/240): more performant AbsolutePath.ReadKind: it now queries the entry attributes only once, and on Windows it no longer allocates or performs additional IO in cases not concerning reparse points. Thanks to @FalconTechDev for help!
- AbsolutePath.ReadKind now only returns null if the entry doesn't exist, and throws an exception if its attributes cannot be read for another reason: e.g. an UnauthorizedAccessException if the access is denied, or an IOException if the path contains a name rejected by the file system (on .NET Framework, also ArgumentException or PathTooLongException). Previously, it returned null in these cases.
- The platform-default path comparers (LocalPath.PlatformDefaultComparer, AbsolutePath.PlatformDefaultComparer) are now case-insensitive on iOS and tvOS as well, matching the .NET runtime.

[Added]

- #215 (https://github.com/ForNeVeR/TruePath/issues/215): AbsolutePath.PathRoot property. Thanks to @fskalkan!
- LocalPath.PathRoot property, similar to the previous entry, returning the root of an absolute path, or the drive root of a drive-relative path (e.g. C:foo, which only exists on Windows, will return C:), or null when the root can't be determined.
- #202: path.GetFiles(LocalPathPattern) (https://github.com/ForNeVeR/TruePath/issues/202). Thanks to @hamdiakin!
- #224 (https://github.com/ForNeVeR/TruePath/issues/224): PathKind enumeration and LocalPath.Kind property, telling an absolute path from a relative one, and on Windows also from a path rooted without a drive letter (\Windows) and from a path relative to the current directory of a drive (C:Windows). These are experimental (diagnostic TRUEPATH001): more kinds may be added later, e.g. for UNC paths.

[Fixed]

- #239 (https://github.com/ForNeVeR/TruePath/issues/239): on Unix, AbsolutePath.Canonicalize() no longer closes the file descriptor 0 when the path doesn't exist. This used to close the standard input of the process, or any file or socket that later took this descriptor number. Also, it no longer leaks the memory allocated for the resolved path.
- #217 (https://github.com/ForNeVeR/TruePath/issues/217): the IsPrefixOf and StartsWith methods for both LocalPath and AbsolutePath are now exact opposites (use same code), and always operate on whole path segments (file and directory names) instead of raw strings. For example, new AbsolutePath("/foo1").StartsWith(new AbsolutePath("/foo")) is now false, where it used to be true. Thanks to @berkcantmr for help on this fix!
- #221 (https://github.com/ForNeVeR/TruePath/issues/221): IsPrefixOf now handles the root folders correctly as prefixes of all the absolute paths under the same root. Thanks to @berkcantmr and @t957095!
- IsPrefixOf and StartsWith now compare path strings using ordinal string comparison.
- #225 (https://github.com/ForNeVeR/TruePath/issues/225): IsPrefixOf and StartsWith now compare path strings using the same platform-default case sensitivity as path equality. Thanks to @amirani8137!
- #224 (https://github.com/ForNeVeR/TruePath/issues/224): path normalization no longer drops the root separator when a rooted path ends with ..: C:\base\.. is now normalized to C:\ (was C:, a path relative to the current directory of drive C:), and /base/.. to / (was an empty path, i.e. the current directory).
- #219 (https://github.com/ForNeVeR/TruePath/issues/219): path normalization no longer applies Windows drive-specific logic to all paths. Thanks to @hamdiakin!
- #95 (https://github.com/ForNeVeR/TruePath/issues/95): Path normalization now drops a .. directly after the root, since the root has no parent: /.. is normalized to /, and C:\..\x to C:\x, the same as Path.GetFullPath does. Thanks to @sinthu-14 for help!
- #226 (https://github.com/ForNeVeR/TruePath/issues/226): LocalPath.IsPrefixOf and StartsWith now take leading .. references of relative paths into account instead of comparing them as strings. For example, new LocalPath("..").IsPrefixOf(new LocalPath("foo")) is now true, and new LocalPath("..").IsPrefixOf(new LocalPath("../..")) is now false. Thanks to @rghvgrv!
- In .NET Standard 2.0's version of TruePath (e.g., the one targeting .NET Framework), LocalPath.RelativeTo and AbsolutePath.RelativeTo now use a port of the .NET runtime's Path.GetRelativePath, and return the same results as on .NET 8+ (except for the stream syntax, see #235 (https://github.com/ForNeVeR/TruePath/issues/235)). Previously, the result was wrong for a destination equal to or above the base path, and for names containing %XX sequences.
- AbsolutePath.ReadKind no longer throws an exception if the entry gets deleted during the call.
- LocalPath.RelativeTo no longer throws an exception when either path designates the current directory.