Luhn.cs: Add ConvertAlphaNumericToNumeric

... method to convert a string containing alphanumeric characters to
a string containing only numeric characters.

Resolves: No entry

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.
+
 ## [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,33 @@ 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}");
+    }
+  }
+}
+```
+
 # 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,71 @@ 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()));
+        }
     }
-}
+}