(#20) Comparers: upgrade docs and naming, move to separate namespace

TruePath.Tests/AbsolutePathTests.cs

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: MIT
 
 using System.Diagnostics;
+using TruePath.Comparers;
 
 namespace TruePath.Tests;
 
@@ -219,7 +220,7 @@ public void EqualsUseStrictStringPathComparer_SamePaths_True()
         var path2 = new AbsolutePath(nonCanonicalPath);
 
         // Act
-        var equals = path1.Equals(path2, StrictStringPathComparer.Comparer);
+        var equals = path1.Equals(path2, StrictPathComparer.Instance);
 
         // Assert
         Assert.True(equals);
@@ -230,13 +231,13 @@ public void EqualsUseStrictStringPathComparer_NotSamePaths_False()
     {
         // Arrange
         var currentDirectory = Environment.CurrentDirectory;
-        var nonCanonicalPath = new string(currentDirectory.MakeNonCanonicalPath().ToArray());
+        var nonCanonicalPath = new string(currentDirectory.ToNonCanonicalCase().ToArray());
 
         var path1 = new AbsolutePath(currentDirectory);
         var path2 = new AbsolutePath(nonCanonicalPath);
 
         // Act
-        var equals = path1.Equals(path2, StrictStringPathComparer.Comparer);
+        var equals = path1.Equals(path2, StrictPathComparer.Instance);
 
         // Assert
         Assert.False(equals);
@@ -252,7 +253,7 @@ public void OnLinux_EqualsDefault_CaseSensitive_False()
         }
 
         var currentDirectory = Environment.CurrentDirectory;
-        var nonCanonicalPath = new string(currentDirectory.MakeNonCanonicalPath().ToArray());
+        var nonCanonicalPath = new string(currentDirectory.ToNonCanonicalCase().ToArray());
 
         var path1 = new AbsolutePath(currentDirectory);
         var path2 = new AbsolutePath(nonCanonicalPath);
@@ -274,7 +275,7 @@ public void OnWindowsOrOsx_EqualsDefault_CaseInsensitive_True()
         }
 
         var currentDirectory = Environment.CurrentDirectory;
-        var nonCanonicalPath = new string(currentDirectory.MakeNonCanonicalPath().ToArray());
+        var nonCanonicalPath = new string(currentDirectory.ToNonCanonicalCase().ToArray());
 
         var path1 = new AbsolutePath(currentDirectory);
         var path2 = new AbsolutePath(nonCanonicalPath);

TruePath.Tests/LocalPathTests.cs

@@ -2,6 +2,7 @@
 //
 // SPDX-License-Identifier: MIT
 
+using TruePath.Comparers;
 using Xunit.Abstractions;
 
 namespace TruePath.Tests;
@@ -102,7 +103,7 @@ public void EqualsUseStrictStringPathComparer_SamePaths_True()
         var path2 = new LocalPath(nonCanonicalPath);
 
         // Act
-        var equals = path1.Equals(path2, StrictStringPathComparer.Comparer);
+        var equals = path1.Equals(path2, StrictPathComparer.Instance);
 
         // Assert
         Assert.True(equals);
@@ -113,13 +114,13 @@ public void EqualsUseStrictStringPathComparer_NotSamePaths_False()
     {
         // Arrange
         var currentDirectory = Environment.CurrentDirectory;
-        var nonCanonicalPath = new string(currentDirectory.MakeNonCanonicalPath().ToArray());
+        var nonCanonicalPath = new string(currentDirectory.ToNonCanonicalCase().ToArray());
 
         var path1 = new LocalPath(currentDirectory);
         var path2 = new LocalPath(nonCanonicalPath);
 
         // Act
-        var equals = path1.Equals(path2, StrictStringPathComparer.Comparer);
+        var equals = path1.Equals(path2, StrictPathComparer.Instance);
 
         // Assert
         Assert.False(equals);
@@ -135,7 +136,7 @@ public void OnLinux_EqualsDefault_CaseSensitive_False()
         }
 
         var currentDirectory = Environment.CurrentDirectory;
-        var nonCanonicalPath = new string(currentDirectory.MakeNonCanonicalPath().ToArray());
+        var nonCanonicalPath = new string(currentDirectory.ToNonCanonicalCase().ToArray());
 
         var path1 = new LocalPath(currentDirectory);
         var path2 = new LocalPath(nonCanonicalPath);
@@ -157,7 +158,7 @@ public void OnWindowsOrOsx_EqualsDefault_CaseInsensitive_True()
         }
 
         var currentDirectory = Environment.CurrentDirectory;
-        var nonCanonicalPath = new string(currentDirectory.MakeNonCanonicalPath().ToArray());
+        var nonCanonicalPath = new string(currentDirectory.ToNonCanonicalCase().ToArray());
 
         var path1 = new LocalPath(currentDirectory);
         var path2 = new LocalPath(nonCanonicalPath);

TruePath.Tests/Utils.cs

@@ -6,7 +6,7 @@ namespace TruePath.Tests;
 
 public static class Utils
 {
-    internal static string MakeNonCanonicalPath(this string path)
+    internal static string ToNonCanonicalCase(this string path)
     {
         var result = new char[path.Length];
         for (var i = 0; i < path.Length; i++)

TruePath/AbsolutePath.cs

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: MIT
 
 using System.Runtime.InteropServices;
+using TruePath.Comparers;
 
 namespace TruePath;
 
@@ -103,7 +104,7 @@ public bool IsPrefixOf(AbsolutePath other)
     /// <remarks>Note that currently this comparison is case-sensitive.</remarks>
     public bool Equals(AbsolutePath other)
     {
-        var comparer = PlatformDefaultPathComparer.Comparer;
+        var comparer = PlatformDefaultPathComparer.Instance;
         return comparer.Compare(Underlying.Value, other.Underlying.Value) == 0;
     }
 
@@ -115,9 +116,6 @@ public bool Equals(AbsolutePath other)
     /// <returns>
     /// <see langword="true"/> if the specified <see cref="AbsolutePath"/> is equal to the current <see cref="AbsolutePath"/> using the specified string comparer; otherwise, <see langword="false"/>.
     /// </returns>
-    /// <remarks>
-    /// If the comparer is null, this method returns <see langword="false"/>.
-    /// </remarks>
     public bool Equals(AbsolutePath other, IComparer<string> comparer)
     {
         return comparer.Compare(Value, other.Value) == 0;

TruePath/Comparers/PlatformDefaultPathComparer.cs

@@ -0,0 +1,51 @@
+// SPDX-FileCopyrightText: 2024 TruePath contributors <https://github.com/ForNeVeR/TruePath>
+//
+// SPDX-License-Identifier: MIT
+
+using System.Runtime.InteropServices;
+
+namespace TruePath.Comparers;
+
+/// <summary>
+/// <para>Provides a default comparer for comparing file paths, aware of the current platform.</para>
+/// <para>
+///     On <b>Windows</b> and <b>macOS</b>, this will perform <b>case-insensitive</b> comparison, since the file
+///     systems are case-insensitive on these operating systems by default.
+/// </para>
+/// <para>On <b>Linux</b>, the comparison will be <b>case-sensitive</b>.</para>
+/// </summary>
+/// <remarks>
+/// Note that this comparison <b>does not guarantee correctness</b>: 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.
+/// </remarks>
+public class PlatformDefaultPathComparer : IComparer<string>
+{
+    /// <summary>
+    /// Gets the singleton instance of the <see cref="PlatformDefaultPathComparer"/> class.
+    /// </summary>
+    public static readonly PlatformDefaultPathComparer Instance = new();
+
+    private readonly StringComparer _comparisonType;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PlatformDefaultPathComparer"/> class.
+    /// </summary>
+    private PlatformDefaultPathComparer()
+    {
+        if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows) || RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
+        {
+            _comparisonType = StringComparer.OrdinalIgnoreCase;
+        }
+        else
+        {
+            _comparisonType = StringComparer.Ordinal;
+        }
+    }
+
+    /// <inheritdoc cref="IComparer{T}.Compare"/>
+    public int Compare(string? x, string? y)
+    {
+        return _comparisonType.Compare(x, y);
+    }
+}

TruePath/Comparers/StrictPathComparer.cs

@@ -0,0 +1,20 @@
+// SPDX-FileCopyrightText: 2024 TruePath contributors <https://github.com/ForNeVeR/TruePath>
+//
+// SPDX-License-Identifier: MIT
+
+namespace TruePath.Comparers;
+
+/// <summary>A strict comparer for comparing file paths using ordinal comparison.</summary>
+public class StrictPathComparer : IComparer<string>
+{
+    /// <summary>
+    /// Gets the singleton instance of the <see cref="StrictPathComparer"/> class.
+    /// </summary>
+    public static readonly StrictPathComparer Instance = new();
+
+    /// <inheritdoc cref="IComparer{T}.Compare"/>
+    public int Compare(string? x, string? y)
+    {
+        return StringComparer.Ordinal.Compare(x, y);
+    }
+}

TruePath/LocalPath.cs

@@ -2,7 +2,7 @@
 //
 // SPDX-License-Identifier: MIT
 
-using System.Runtime.InteropServices;
+using TruePath.Comparers;
 
 namespace TruePath;
 
@@ -44,7 +44,7 @@ public readonly struct LocalPath(string value) : IEquatable<LocalPath>, IPath, I
     /// <remarks>Note that currently this comparison is case-sensitive.</remarks>
     public bool Equals(LocalPath other)
     {
-        var comparer = PlatformDefaultPathComparer.Comparer;
+        var comparer = PlatformDefaultPathComparer.Instance;
         return comparer.Compare(Value, other.Value) == 0;
     }
 
@@ -56,9 +56,6 @@ public bool Equals(LocalPath other)
     /// <returns>
     /// <see langword="true"/> if the specified <see cref="LocalPath"/> is equal to the current <see cref="LocalPath"/> using the specified string comparer; otherwise, <see langword="false"/>.
     /// </returns>
-    /// <remarks>
-    /// If the comparer is null, this method returns <see langword="false"/>.
-    /// </remarks>
     public bool Equals(LocalPath other, IComparer<string> comparer)
     {
         return comparer.Compare(Value, other.Value) == 0;