Merge pull request #48 from shinji-san/release-v1.1.0

Release v1.1.0

Added:
- Add `ConvertAlphaNumericToNumeric` method to convert a string containing alphanumeric characters to a string containing only numeric characters (use case: converting an ISIN to a numeric string for Luhn validation).

Resolves: #48

Author: shinji-san

CHANGELOG.md

@@ -4,7 +4,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.0.1] - 2024-02-19
+## [1.1.0] - 2024-03-30
+### Added
+- Add `ConvertAlphaNumericToNumeric` method to convert a string containing alphanumeric characters to a string containing only numeric characters (use case: converting an ISIN to a numeric string for Luhn validation).
+
+## [1.0.1] - 2024-03-19
 ### Fixed
 - Fixed a bug in `Luhn.ComputeLuhnNumber` and `Luhn.ComputeLuhnCheckDigit` methods that sometimes returned an incorrect result.
 
@@ -42,6 +46,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Added initial version of LuhnDotNet
 
+[1.1.0]: https://github.com/shinji-san/LuhnDotNet/compare/v1.0.1..v1.1.0
 [1.0.1]: https://github.com/shinji-san/LuhnDotNet/compare/v1.0.0..v1.0.1
 [1.0.0]: https://github.com/shinji-san/LuhnDotNet/compare/v0.2.0..v1.0.0
 [0.2.0]: https://github.com/shinji-san/LuhnDotNet/compare/v0.1.0..v0.2.0

README.md

@@ -1,6 +1,8 @@
 # LuhnDotNet
 An C# implementation of the Luhn algorithm.
 
+The Luhn algorithm is a checksum formula used to validate identification numbers like credit card numbers. It works by doubling every second digit from the right, summing all the digits, and checking if the total is a multiple of 10. It's widely used and is specified in ISO/IEC 7812-1.
+
 # Build & Test Status Of Default Branch
 <table>
   <thead>
@@ -61,9 +63,9 @@ An C# implementation of the Luhn algorithm.
   </thead>
   <tbody>
       <tr>
-          <td rowspan=10><a href="https://github.com/shinji-san/LuhnDotNet/actions?query=workflow%3A%22LuhnDotNet+NuGet%22" target="_blank"><img src="https://github.com/shinji-san/LuhnDotNet/workflows/LuhnDotNet%20NuGet/badge.svg?branch=v1.0.1" alt="LuhnDotNet NuGet"/></a></td>
-          <td rowspan=10><a href="https://badge.fury.io/nu/LuhnDotNet" target="_blank"><img src="https://badge.fury.io/nu/LuhnDotNet.svg" alt="NuGet Version 1.0.1"/></a></td>
-          <td rowspan=10><a href="https://github.com/shinji-san/LuhnDotNet/tree/v1.0.1" target="_blank"><img src="https://img.shields.io/badge/LuhnDotNet-1.0.1-green.svg?logo=github&logoColor=959da5&color=2ebb4e&labelColor=2b3137" alt="Tag"/></a></td>
+          <td rowspan=10><a href="https://github.com/shinji-san/LuhnDotNet/actions?query=workflow%3A%22LuhnDotNet+NuGet%22" target="_blank"><img src="https://github.com/shinji-san/LuhnDotNet/workflows/LuhnDotNet%20NuGet/badge.svg?branch=v1.1.0" alt="LuhnDotNet NuGet"/></a></td>
+          <td rowspan=10><a href="https://badge.fury.io/nu/LuhnDotNet" target="_blank"><img src="https://badge.fury.io/nu/LuhnDotNet.svg" alt="NuGet Version 1.1.0"/></a></td>
+          <td rowspan=10><a href="https://github.com/shinji-san/LuhnDotNet/tree/v1.1.0" target="_blank"><img src="https://img.shields.io/badge/LuhnDotNet-1.1.0-green.svg?logo=github&logoColor=959da5&color=2ebb4e&labelColor=2b3137" alt="Tag"/></a></td>
           <td>.NET 6</td>
       </tr>
       <tr>
@@ -100,10 +102,10 @@ An C# implementation of the Luhn algorithm.
 
 1. Open a console and switch to the directory, containing your project file.
 
-2. Use the following command to install version 1.0.1 of the LuhnDotNet package:
+2. Use the following command to install version 1.1.0 of the LuhnDotNet package:
 
     ```dotnetcli
-    dotnet add package LuhnDotNet -v 1.0.1 -f <FRAMEWORK>
+    dotnet add package LuhnDotNet -v 1.1.0 -f <FRAMEWORK>
     ```
 
 3. After the completion of the command, look at the project file to make sure that the package is successfully installed.
@@ -112,7 +114,7 @@ An C# implementation of the Luhn algorithm.
 
     ```xml
     <ItemGroup>
-      <PackageReference Include="LuhnDotNet" Version="1.0.1" />
+      <PackageReference Include="LuhnDotNet" Version="1.1.0" />
     </ItemGroup>
     ```
 ## Remove LuhnDotNet package
@@ -210,6 +212,101 @@ namespace Example4
 }
 ```
 
+## Validate ISIN with LuhnDotNet and ConvertAlphaNumericToNumeric
+
+The `LuhnDotNet` library can be used in combination with the `ConvertAlphaNumericToNumeric` method to validate an International Securities Identification Number (ISIN). An ISIN uniquely identifies a security, such as stocks, bonds or derivatives. It is a 12-character alphanumeric code.
+
+The `ConvertAlphaNumericToNumeric` method is used to convert the alphanumeric ISIN to a numeric string, where each letter in the input string is replaced by its decimal ASCII value minus 55. This numeric string can then be validated using the `Luhn.IsValid` method.
+
+Here is an example of how to use these methods to validate an ISIN:
+
+```csharp
+using System;
+using LuhnDotNet;
+
+namespace Example5
+{
+  public class Program
+  {
+    public static void Main(string[] args)
+    {
+      string isin = "US0378331005";
+      bool isValid = Luhn.IsValid(isin.ConvertAlphaNumericToNumeric());
+
+      Console.WriteLine($"The ISIN {isin} is valid: {isValid}");
+    }
+  }
+}
+```
+## Compute ISIN Check Digit with LuhnDotNet and ConvertAlphaNumericToNumeric
+
+The `LuhnDotNet` library provides the `ComputeLuhnCheckDigit` method which can be used to compute the check digit of a numeric string according to the Luhn algorithm. When dealing with an International Securities Identification Number (ISIN), which is a 12-character alphanumeric code, we first need to convert the alphanumeric ISIN to a numeric string. This can be achieved using the `ConvertAlphaNumericToNumeric` method.
+
+Here is an example of how to compute the check digit of an ISIN:
+
+```csharp
+using System;
+using LuhnDotNet;
+
+namespace Example6
+{
+  public class Program
+  {
+    public static void Main(string[] args)
+    {
+      string isinWithoutCheckDigit = "US037833100";
+      byte checkDigit = Luhn.ComputeLuhnCheckDigit(isinWithoutCheckDigit.ConvertAlphaNumericToNumeric());
+
+      Console.WriteLine($"The check digit for ISIN {isinWithoutCheckDigit} is: {checkDigit}");
+    }
+  }
+}
+```
+
+## Compute credit card number with LuhnDotNet
+The `LuhnDotNet` library can be used to compute the check digit of a credit card number. The check digit is the last digit of the credit card number, which is used to validate the number according to the Luhn algorithm.
+
+```csharp
+using System;
+using LuhnDotNet;
+
+namespace Example7
+{
+  public class Program
+  {
+    public static void Main(string[] args)
+    {
+      string creditCardNumberWithoutCheckDigit = "4417 1234 5678 911".Replace(" ", "");
+      byte checkDigit = Luhn.ComputeLuhnCheckDigit(creditCardNumberWithoutCheckDigit);
+
+      Console.WriteLine($"The check digit for credit card number {creditCardNumberWithoutCheckDigit} is: {checkDigit}");
+    }
+  }
+}
+```
+
+## Validate credit card number with LuhnDotNet
+The `LuhnDotNet` library can be used to validate a credit card number according to the Luhn algorithm. The `IsValid` method returns `true` if the credit card number is valid, and `false` otherwise.
+
+```csharp
+using System;
+using LuhnDotNet;
+
+namespace Example8
+{
+  public class Program
+  {
+    public static void Main(string[] args)
+    {
+      string creditCardNumber = "4417 1234 5678 9113".Replace(" ", "");
+      bool isValid = Luhn.IsValid(creditCardNumber);
+
+      Console.WriteLine($"The credit card number {creditCardNumber} is valid: {isValid}");
+    }
+  }
+}
+```
+
 # CLI building instructions
 For the following instructions, please make sure that you are connected to the internet. If necessary, NuGet will try to restore the [xUnit](https://xunit.net/) packages.
 ## Using dotnet to build for .NET 6, .NET 7, .NET 8 and .NET FX 4.x
@@ -219,30 +316,36 @@ Use one of the following solutions with `dotnet` to build [LuhnDotNet](#luhndotn
 
 The syntax is:
 ```dotnetcli
-dotnet {build|test} -c {Debug|Release} LuhnDotNet.sln
+dotnet {restore|build|test} -c {Debug|Release} LuhnDotNet.sln
+```
+
+### Restore NuGet packages
+
+```dotnetcli
+dotnet restore LuhnDotNet.sln
 ```
 
 The instructions below are examples, which operate on the `LuhnDotNet.sln`.
 ### Build Debug configuration
 
 ```dotnetcli
-dotnet build -c Debug LuhnDotNet.sln
+dotnet build -c Debug --no-restore LuhnDotNet.sln
 ```
 
 ### Build Release configuration
 
 ```dotnetcli
-dotnet build -c Release LuhnDotNet.sln
+dotnet build -c Release --no-restore LuhnDotNet.sln
 ```
 
 ### Test Debug configuration
 
 ```dotnetcli
-dotnet test -c Debug LuhnDotNet.sln
+dotnet test -c Debug --no-restore --no-build LuhnDotNet.sln
 ```
 
 ### Test Release configuration
 
 ```dotnetcli
-dotnet test -c Release LuhnDotNet.sln
+dotnet test -c Release --no-restore --no-build LuhnDotNet.sln
 ```

src/Luhn.cs

@@ -38,6 +38,7 @@ namespace LuhnDotNet
     using System.Diagnostics.CodeAnalysis;
     using System.Globalization;
 #if !NET6_0_OR_GREATER
+    using System.Text;
     using System.Text.RegularExpressions;
 #endif
 
@@ -162,6 +163,68 @@ public static bool IsValid(string number, byte checkDigit)
                 .SumDigits() == 0;
         }
 
+        /// <summary>
+        /// Converts an alphanumeric string to a numeric string.
+        /// </summary>
+        /// <param name="alphaNumeric">The alphanumeric string to convert.</param>
+        /// <returns>A numeric string where each letter in the input string is replaced by its decimal ASCII value
+        /// minus 55.</returns>
+        /// <remarks>
+        /// This method iterates over each character in the input string. If the character is a letter, it is replaced
+        /// by its decimal ASCII value minus 55. If the character is a digit, it is left unchanged.
+        /// </remarks>
+        public static string ConvertAlphaNumericToNumeric(this string alphaNumeric)
+#if NET6_0_OR_GREATER
+        {
+            Span<char> result = stackalloc char[alphaNumeric.Length * 2];
+            int index = 0;
+
+            foreach (char c in alphaNumeric.ToUpper())
+            {
+                if (char.IsLetter(c))
+                {
+                    string numericValue = (c - 55).ToString();
+                    foreach (char numChar in numericValue)
+                    {
+                        result[index++] = numChar;
+                    }
+                }
+                else if (char.IsDigit(c))
+                {
+                    result[index++] = c;
+                }
+                else
+                {
+                    throw new ArgumentException($"The character '{c}' is not a letter or a digit!", nameof(alphaNumeric));
+                }
+            }
+
+            return result[..index].ToString();
+        }
+#else
+        {
+            var result = new StringBuilder();
+
+            foreach (char c in alphaNumeric.ToUpper())
+            {
+                if (char.IsLetter(c))
+                {
+                    result.Append(c - 55);
+                }
+                else if (char.IsDigit(c))
+                {
+                    result.Append(c);
+                }
+                else
+                {
+                    throw new ArgumentException($"The character '{c}' is not a letter or a digit!", nameof(alphaNumeric));
+                }
+            }
+
+            return result.ToString();
+        }
+#endif
+
         /// <summary>
         /// Doubling of every second digit.
         /// </summary>

src/LuhnDotNet.csproj

@@ -6,18 +6,19 @@
         <SignAssembly>True</SignAssembly>
         <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
         <ImplicitUsings>disable</ImplicitUsings>
+        <LangVersion>latest</LangVersion>
         <Nullable>disable</Nullable>
         <Authors>Sebastian Walther</Authors>
         <PackageId>LuhnDotNet</PackageId>
         <PackageLicenseExpression>MIT</PackageLicenseExpression>
-        <PackageReleaseNotes>Changelog: https://github.com/shinji-san/LuhnDotNet/blob/v1.0.1/CHANGELOG.md</PackageReleaseNotes>
+        <PackageReleaseNotes>Changelog: https://github.com/shinji-san/LuhnDotNet/blob/v1.1.0/CHANGELOG.md</PackageReleaseNotes>
         <PackageDescription>An C# implementation of the Luhn algorithm</PackageDescription>
         <PackageReadmeFile>README.md</PackageReadmeFile>
         <PackageTags>luhn;luhn-algorithm</PackageTags>
         <PackageProjectUrl>https://github.com/shinji-san/LuhnDotNet</PackageProjectUrl>
         <RepositoryUrl>https://github.com/shinji-san/LuhnDotNet</RepositoryUrl>
         <RepositoryType>git</RepositoryType>
-        <Version>1.0.1</Version>
+        <Version>1.1.0</Version>
         <Authors>Sebastian Walther</Authors>
         <Company>Private Person</Company>
         <GenerateDocumentationFile>true</GenerateDocumentationFile>

src/Properties/AssemblyInfo.cs

@@ -15,8 +15,8 @@
 
 [assembly: Guid("bba40d96-b58d-4a8f-b6fc-3699e0addf98")]
 
-[assembly: AssemblyVersion("1.0.1")]
-[assembly: AssemblyFileVersion("1.0.1")]
+[assembly: AssemblyVersion("1.1.0")]
+[assembly: AssemblyFileVersion("1.1.0")]
 [assembly: NeutralResourcesLanguage("en")]
 
 [assembly: System.CLSCompliant(true)]