From c51b8328d1b922c0a166fe7bb72721e8cbfc3a87 Mon Sep 17 00:00:00 2001
From: Joachim Dekker <jdekker3008@gmail.com>
Date: Wed, 8 May 2024 15:51:58 +0200
Subject: [PATCH] feat: add IPathfinder (#50)

* feat: Add IPathfinder

* docs: add documentation
---
 Aplib.Extensions/Aplib.Extensions.csproj | 13 ++++++++
 Aplib.Extensions/IPathfinder.cs          | 39 ++++++++++++++++++++++++
 Aplib.Net.sln                            |  6 ++++
 3 files changed, 58 insertions(+)
 create mode 100644 Aplib.Extensions/Aplib.Extensions.csproj
 create mode 100644 Aplib.Extensions/IPathfinder.cs

diff --git a/Aplib.Extensions/Aplib.Extensions.csproj b/Aplib.Extensions/Aplib.Extensions.csproj
new file mode 100644
index 00000000..6358f10e
--- /dev/null
+++ b/Aplib.Extensions/Aplib.Extensions.csproj
@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <TargetFramework>netstandard2.1</TargetFramework>
+        <LangVersion>9</LangVersion>
+        <Nullable>enable</Nullable>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <ProjectReference Include="..\Aplib.Core\Aplib.Core.csproj"/>
+    </ItemGroup>
+
+</Project>
diff --git a/Aplib.Extensions/IPathfinder.cs b/Aplib.Extensions/IPathfinder.cs
new file mode 100644
index 00000000..8fe10059
--- /dev/null
+++ b/Aplib.Extensions/IPathfinder.cs
@@ -0,0 +1,39 @@
+using System;
+
+namespace Aplib.Extensions
+{
+    /// <summary>
+    /// Defines a pathfinding algorithm used to find a path from a starting point to an end point.
+    /// </summary>
+    /// <typeparam name="T">The type of the elements in the path.</typeparam>
+    public interface IPathfinder<T>
+    {
+        /// <summary>
+        /// Finds a path from the specified starting point to the specified end point.
+        /// </summary>
+        /// <typeparam name="T">The type of the elements in the path.</typeparam>
+        /// <param name="begin">The starting point of the path.</param>
+        /// <param name="end">The end point of the path.</param>
+        /// <returns>A read-only span of elements representing the path from the starting point to the end point.</returns>
+        public ReadOnlySpan<T> FindPath(T begin, T end);
+
+        /// <summary>
+        /// Gets the next step towards the specified end point from the current point in the path.
+        /// </summary>
+        /// <typeparam name="T">The type of the elements in the path.</typeparam>
+        /// <param name="current">The current point in the path.</param>
+        /// <param name="end">The end point of the path.</param>
+        /// <returns>The next step towards the end point.</returns>
+        public T GetNextStep(T current, T end);
+
+        /// <summary>
+        /// Tries to get the next step towards the specified end point from the current point in the path.
+        /// </summary>
+        /// <typeparam name="T">The type of the elements in the path.</typeparam>
+        /// <param name="current">The current point in the path.</param>
+        /// <param name="end">The end point of the path.</param>
+        /// <param name="nextStep">When this method returns, contains the next step towards the end point if it exists, or the default value of type T if there is no next step.</param>
+        /// <returns>true if the next step towards the end point is obtained successfully; otherwise, false.</returns>
+        public bool TryGetNextStep(T current, T end, out T nextStep);
+    }
+}
diff --git a/Aplib.Net.sln b/Aplib.Net.sln
index 9fce7b06..1d2ab7b9 100644
--- a/Aplib.Net.sln
+++ b/Aplib.Net.sln
@@ -7,6 +7,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Aplib.Core", "Aplib.Core\Ap
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Aplib.Core.Tests", "Aplib.Tests\Aplib.Core.Tests.csproj", "{67D4F6C5-758D-489F-A100-8B259B2158D2}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Aplib.Extensions", "Aplib.Extensions\Aplib.Extensions.csproj", "{8D5F1FCC-D4DF-4D50-BCC4-EBE52D0D4F5B}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -21,6 +23,10 @@ Global
 		{67D4F6C5-758D-489F-A100-8B259B2158D2}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{67D4F6C5-758D-489F-A100-8B259B2158D2}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{67D4F6C5-758D-489F-A100-8B259B2158D2}.Release|Any CPU.Build.0 = Release|Any CPU
+		{8D5F1FCC-D4DF-4D50-BCC4-EBE52D0D4F5B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{8D5F1FCC-D4DF-4D50-BCC4-EBE52D0D4F5B}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{8D5F1FCC-D4DF-4D50-BCC4-EBE52D0D4F5B}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{8D5F1FCC-D4DF-4D50-BCC4-EBE52D0D4F5B}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE