Merge pull request #47 from shinji-san/feature-ISIN_AlphaNumericSupport

Feature - Converting an ISIN to a numeric string for Luhn validation & Luhn check digit computation

Resolves: #47

Author: shinji-san

CHANGELOG.md

@@ -4,6 +4,10 @@ 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).
 
+## [Unreleased]
+### 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-02-19
 ### Fixed
 - Fixed a bug in `Luhn.ComputeLuhnNumber` and `Luhn.ComputeLuhnCheckDigit` methods that sometimes returned an incorrect result.

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>
@@ -210,6 +212,57 @@ 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}");
+    }
+  }
+}
+```
+
 # 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

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,6 +6,7 @@
         <SignAssembly>True</SignAssembly>
         <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
         <ImplicitUsings>disable</ImplicitUsings>
+        <LangVersion>latest</LangVersion>
         <Nullable>disable</Nullable>
         <Authors>Sebastian Walther</Authors>
         <PackageId>LuhnDotNet</PackageId>

tests/LuhnTest.cs

@@ -243,5 +243,108 @@ public void LuhnCheckDigitValidationExceptionTest(string invalidNumber, byte che
         {
             Assert.Throws<ArgumentOutOfRangeException>(() => IsValid(invalidNumber, checkDigit));
         }
+
+        /// <summary>
+        /// Test data for ConvertAlphaNumericToNumeric method.
+        /// </summary>
+        public static IEnumerable<object[]> ConvertAlphaNumericToNumericData =>
+            new List<object[]>
+            {
+                new object[] { "A1B2C3", "101112123" },
+                new object[] { "Z9Y8X7", "359348337" },
+                new object[] { "123", "123" },
+                new object[] { "DE0006069008", "13140006069008" },
+                new object[] { "ABC", "101112" },
+                new object[] { "", "" },
+            };
+
+        /// <summary>
+        /// Tests the ConvertAlphaNumericToNumeric method.
+        /// </summary>
+        /// <param name="input">Input string</param>
+        /// <param name="expected">Expected output</param>
+        [Theory(DisplayName = "Converts an alphanumeric string to a numeric string")]
+        [MemberData(nameof(ConvertAlphaNumericToNumericData), MemberType = typeof(LuhnTest))]
+        public void ConvertAlphaNumericToNumericTest(string input, string expected)
+        {
+            Assert.Equal(expected, input.ConvertAlphaNumericToNumeric());
+        }
+
+        /// <summary>
+        /// Tests the ConvertAlphaNumericToNumeric method with invalid input.
+        /// </summary>
+        /// <remarks>
+        /// This test checks if the ConvertAlphaNumericToNumeric method throws an ArgumentException when it is given an
+        /// invalid input string that contains non-alphanumeric characters. The test uses the Assert.Throws method from
+        /// xUnit to check if the expected exception is thrown.
+        /// </remarks>
+        [Fact]
+        public void ConvertAlphaNumericToNumericExceptionTest()
+        {
+            Assert.Throws<ArgumentException>(()=> "!@#$%^&*()".ConvertAlphaNumericToNumeric());
+        }
+
+        /// <summary>
+        /// Test data for IsValid method in combination with ConvertAlphaNumericToNumeric.
+        /// </summary>
+        public static IEnumerable<object[]> IsValidWithConvertData =>
+            new List<object[]>
+            {
+                new object[] { "DE0006069008", true },
+                new object[] { "DE0006069007", false },
+                new object[] { "DE000BAY0017", true },
+                new object[] { "DE000BAY0018", false },
+                new object[] { "AU0000XVGZA3", true },
+                new object[] { "US0378331005", true },
+            };
+
+        /// <summary>
+        /// Tests the IsValid method in combination with ConvertAlphaNumericToNumeric.
+        /// </summary>
+        /// <param name="input">Input string</param>
+        /// <param name="expected">Expected output</param>
+        [Theory(DisplayName = "Validates a numeric string converted from an alphanumeric string")]
+        [MemberData(nameof(IsValidWithConvertData), MemberType = typeof(LuhnTest))]
+        public void IsValidWithConvertTest(string input, bool expected)
+        {
+            Assert.Equal(expected, IsValid(input.ConvertAlphaNumericToNumeric()));
+        }
+
+        /// <summary>
+        /// Provides test data for the ComputeLuhnCheckDigit method in combination with ConvertAlphaNumericToNumeric.
+        /// </summary>
+        /// <remarks>
+        /// This method returns a collection of object arrays, where each array contains an input string and the
+        /// expected output for the ComputeLuhnCheckDigit method. The input string is an alphanumeric string that
+        /// represents a part of an ISIN without the check digit. The expected output is the check digit that makes the
+        /// entire ISIN valid according to the Luhn algorithm.
+        /// </remarks>
+        public static IEnumerable<object[]> ComputeLuhnCheckDigitWithConvertData =>
+            new List<object[]>
+            {
+                new object[] { "DE000606900", 8 },
+                new object[] { "DE000BAY001", 7 },
+                new object[] { "AU0000XVGZA", 3 },
+                new object[] { "US037833100", 5 },
+            };
+
+        /// <summary>
+        /// Tests the ComputeLuhnCheckDigit method in combination with ConvertAlphaNumericToNumeric.
+        /// </summary>
+        /// <param name="input">Input string</param>
+        /// <param name="expected">Expected output</param>
+        /// <remarks>
+        /// This test checks if the ComputeLuhnCheckDigit method returns the expected check digit when it is given an
+        /// alphanumeric string that represents a part of an ISIN without the check digit. The input string is first
+        /// converted to a numeric string using the ConvertAlphaNumericToNumeric method, and then the
+        /// ComputeLuhnCheckDigit method is called with this numeric string. The test uses the Assert.Equal method from
+        /// xUnit to check if the actual check digit matches the expected check digit.
+        /// </remarks>
+        [Theory]
+        [MemberData(nameof(ComputeLuhnCheckDigitWithConvertData), MemberType = typeof(LuhnTest))]
+        public void ComputeLuhnCheckDigitWithConvertTest(string input, byte expected)
+        {
+            Assert.Equal(expected, ComputeLuhnCheckDigit(input.ConvertAlphaNumericToNumeric()));
+        }
     }
-}
+}