Refactor exceptions to use InvalidCharacterException.

Replaced `ArgumentException` with the new `InvalidCharacterException` for better semantic clarity when handling invalid input.
Added `InvalidCharacterException` class and updated related tests accordingly to align with these changes.
Updated the changelog to document the addition.

Resolves: No entry

Author: shinji-san

CHANGELOG.md

@@ -5,6 +5,9 @@ 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 `InvalidCharacterException` to throw an exception if the input string contains invalid characters.
+
 ### Changed
 - Renamed `Luhn.ConvertAlphaNumericToNumeric` to `Luhn.AlphaNumericToNumeric`
 

src/InvalidCharacterException.cs

@@ -0,0 +1,94 @@
+// ----------------------------------------------------------------------------
+// <copyright file="InvalidCharacterException.cs" company="Private">
+// Copyright (c) 2025 All Rights Reserved
+// </copyright>
+// <author>Sebastian Walther</author>
+// <date>01/01/2025 09:00:26 PM</date>
+// ----------------------------------------------------------------------------
+
+#region License
+
+// ----------------------------------------------------------------------------
+// Copyright 2025 Sebastian Walther
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+#endregion
+
+using System;
+using System.Runtime.Serialization;
+
+namespace LuhnDotNet
+{
+    /// <summary>
+    /// The exception that is thrown when an invalid character is encountered within an argument.
+    /// </summary>
+    [Serializable]
+    public class InvalidCharacterException : ArgumentException
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="InvalidCharacterException"/> class.
+        /// </summary>
+        public InvalidCharacterException() : base("Invalid character encountered in argument.")
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="InvalidCharacterException"/> class with a specified error message.
+        /// </summary>
+        /// <param name="message">The message that describes the error.</param>
+        public InvalidCharacterException(string message) : base(message)
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="InvalidCharacterException"/> class with a specified error message
+        /// and the name of the parameter that caused this exception.
+        /// </summary>
+        /// <param name="message">The error message that explains the reason for the exception.</param>
+        /// <param name="paramName">The name of the parameter that caused the current exception.</param>
+        public InvalidCharacterException(string message, string paramName) : base(message, paramName)
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="InvalidCharacterException"/> class with a specified error message,
+        /// the parameter name, and a reference to the inner exception that is the cause of this exception.
+        /// </summary>
+        /// <param name="message">The error message that explains the reason for the exception.</param>
+        /// <param name="paramName">The name of the parameter that caused the current exception.</param>
+        /// <param name="innerException">The exception that is the cause of the current exception
+        /// or a null reference if no inner exception is specified.</param>
+        public InvalidCharacterException(string message, string paramName, Exception innerException) : base(message, paramName, innerException)
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="InvalidCharacterException"/> class with serialized data.
+        /// </summary>
+        /// <param name="info">The <see cref="SerializationInfo"/> that holds the serialized object data about the exception being thrown.</param>
+        /// <param name="context">The <see cref="StreamingContext"/> that contains contextual information about the source or destination.</param>
+        [Obsolete(
+            "This constructor is obsolete and will be removed in a future version. Use InvalidCharacterException(string message, string paramName, Exception innerException) instead.",
+            false)]
+        protected InvalidCharacterException(SerializationInfo info, StreamingContext context) : base(info, context)
+        {
+        }
+    }
+}

src/Luhn.cs

@@ -268,7 +268,7 @@ public static string AlphaNumericToNumeric(this string alphaNumeric)
                 }
                 else
                 {
-                    throw new ArgumentException($"The character '{c}' is not a letter or a digit!", nameof(alphaNumeric));
+                    throw new InvalidCharacterException($"The character '{c}' is not a letter or a digit!", nameof(alphaNumeric));
                 }
             }
 
@@ -290,7 +290,7 @@ public static string AlphaNumericToNumeric(this string alphaNumeric)
                 }
                 else
                 {
-                    throw new ArgumentException($"The character '{c}' is not a letter or a digit!", nameof(alphaNumeric));
+                    throw new InvalidCharacterException($"The character '{c}' is not a letter or a digit!", nameof(alphaNumeric));
                 }
             }
 
@@ -346,7 +346,7 @@ private static string ValidateAndTrimNumber(this string number)
             string trimmedNumber = number?.Trim();
             if (string.IsNullOrWhiteSpace(trimmedNumber) || !Regex.IsMatch(trimmedNumber, @"^\d+$"))
             {
-                throw new ArgumentException($"The string '{number}' is not a number!", nameof(number));
+                throw new InvalidCharacterException($"The string '{number}' is not a number!", nameof(number));
             }
 
             return trimmedNumber;
@@ -365,7 +365,7 @@ private static ReadOnlySpan<char> ValidateAndTrimNumber(this ReadOnlySpan<char>
             var trimmedNumber = number.Trim();
             if (trimmedNumber.Length == 0 || !trimmedNumber.IsDigits())
             {
-                throw new ArgumentException($"The string '{number}' is not a number!", nameof(number));
+                throw new InvalidCharacterException($"The string '{number}' is not a number!", nameof(number));
             }
 
             return trimmedNumber;

tests/LuhnTest.cs

@@ -183,9 +183,9 @@ public void ComputeLuhnNumber_ValidRawNumber_ReturnsExpectedLuhnNumber(
         /// </summary>
         /// <param name="expectedResult">The expected validation result</param>
         /// <param name="luhnNumber">Test number inclusive check digit</param>
-        [Theory(DisplayName = "Validates a number containing a check digit")]
+        [Theory(DisplayName = "Validates a valid Luhn number")]
         [MemberData(nameof(LuhnNumberValidationSet), MemberType = typeof(LuhnTest))]
-        public void LuhnNumberValidationTest(bool expectedResult, string luhnNumber)
+        public void IsValidLuhnNumber_ValidLuhnNumber_ReturnsExpectedResult(bool expectedResult, string luhnNumber)
         {
             Assert.Equal(expectedResult, luhnNumber.IsValidLuhnNumber());
             Assert.Equal(expectedResult, luhnNumber.AsSpan().IsValidLuhnNumber());
@@ -197,9 +197,12 @@ public void LuhnNumberValidationTest(bool expectedResult, string luhnNumber)
         /// <param name="expectedResult">Expected validation result</param>
         /// <param name="number">Test number exclusive check digit</param>
         /// <param name="checkDigit">Test Luhn check digit</param>
-        [Theory(DisplayName = "Validates a number with separate check digit between 0 and 9")]
+        [Theory(DisplayName = "Validates a valid number with separate, valid check digit between 0 and 9")]
         [MemberData(nameof(LuhnCheckDigitValidationSet), MemberType = typeof(LuhnTest))]
-        public void LuhnCheckDigitValidationTest(bool expectedResult, string number, byte checkDigit)
+        public void IsValidLuhnCheckDigit_ValidNumberAndCheckDigit_ReturnsExpectedResult(
+            bool expectedResult,
+            string number,
+            byte checkDigit)
         {
             Assert.Equal(expectedResult, checkDigit.IsValidLuhnCheckDigit(number));
             Assert.Equal(expectedResult, checkDigit.IsValidLuhnCheckDigit(number.AsSpan()));
@@ -212,10 +215,10 @@ public void LuhnCheckDigitValidationTest(bool expectedResult, string number, byt
         /// <param name="invalidNumber">Invalid raw number</param>
         [Theory(DisplayName = "Calculates the check digit for an invalid raw number to throw an exception")]
         [MemberData(nameof(InvalidNumbers), MemberType = typeof(LuhnTest))]
-        public void ComputeLuhnCheckDigit_InvalidRawNumber_ThrowsArgumentException(string invalidNumber)
+        public void ComputeLuhnCheckDigit_InvalidRawNumber_ThrowsInvalidCharacterException(string invalidNumber)
         {
-            Assert.Throws<ArgumentException>(() => invalidNumber.ComputeLuhnCheckDigit());
-            Assert.Throws<ArgumentException>(() => invalidNumber.AsSpan().ComputeLuhnCheckDigit());
+            Assert.Throws<InvalidCharacterException>(() => invalidNumber.ComputeLuhnCheckDigit());
+            Assert.Throws<InvalidCharacterException>(() => invalidNumber.AsSpan().ComputeLuhnCheckDigit());
         }
 
         /// <summary>
@@ -225,10 +228,10 @@ public void ComputeLuhnCheckDigit_InvalidRawNumber_ThrowsArgumentException(strin
         /// <param name="invalidNumber">Invalid raw number</param>
         [Theory(DisplayName = "Calculates the Luhn number for an invalid raw number to throw an exception")]
         [MemberData(nameof(InvalidNumbers), MemberType = typeof(LuhnTest))]
-        public void ComputeLuhnNumber_InvalidRawNumber_ThrowsArgumentException(string invalidNumber)
+        public void ComputeLuhnNumber_InvalidRawNumber_ThrowsInvalidCharacterException(string invalidNumber)
         {
-            Assert.Throws<ArgumentException>(invalidNumber.ComputeLuhnNumber);
-            Assert.Throws<ArgumentException>(() => invalidNumber.AsSpan().ComputeLuhnNumber());
+            Assert.Throws<InvalidCharacterException>(invalidNumber.ComputeLuhnNumber);
+            Assert.Throws<InvalidCharacterException>(() => invalidNumber.AsSpan().ComputeLuhnNumber());
         }
 
         /// <summary>
@@ -237,22 +240,23 @@ public void ComputeLuhnNumber_InvalidRawNumber_ThrowsArgumentException(string in
         /// </summary>
         [Theory(DisplayName = "Validates an invalid Luhn number (e.g. none-numeric characters) to throw an exception")]
         [MemberData(nameof(InvalidNumbers), MemberType = typeof(LuhnTest))]
-        public void LuhnNumberValidationExceptionTest(string invalidNumber)
+        public void IsValidLuhnNumber_InvalidInput_ThrowsInvalidCharacterException(string invalidNumber)
         {
-            Assert.Throws<ArgumentException>(() => invalidNumber.IsValidLuhnNumber());
-            Assert.Throws<ArgumentException>(() => invalidNumber.AsSpan().IsValidLuhnNumber());
+            Assert.Throws<InvalidCharacterException>(() => invalidNumber.IsValidLuhnNumber());
+            Assert.Throws<InvalidCharacterException>(() => invalidNumber.AsSpan().IsValidLuhnNumber());
         }
 
         /// <summary>
-        /// Tests whether an exception is thrown when an invalid number and a valid check digit between 0 and 9
-        /// is passed to the Luhn validation algorithm.
+        /// Tests whether an exception is thrown when an invalid number is passed to the Luhn validation algorithm.
         /// </summary>
         [Theory(DisplayName = "Validates an invalid number with any check digit between 0 and 9 to throw an exception")]
         [MemberData(nameof(InvalidNumbersAndCheckDigits), MemberType = typeof(LuhnTest))]
-        public void NumberValidationExceptionTest(string invalidNumber, byte checkDigit)
+        public void IsValidLuhnCheckDigit_InvalidInput_ThrowsInvalidCharacterException(
+            string invalidNumber,
+            byte checkDigit)
         {
-            Assert.Throws<ArgumentException>(() => checkDigit.IsValidLuhnCheckDigit(invalidNumber));
-            Assert.Throws<ArgumentException>(() => checkDigit.IsValidLuhnCheckDigit(invalidNumber.AsSpan()));
+            Assert.Throws<InvalidCharacterException>(() => checkDigit.IsValidLuhnCheckDigit(invalidNumber));
+            Assert.Throws<InvalidCharacterException>(() => checkDigit.IsValidLuhnCheckDigit(invalidNumber.AsSpan()));
         }
 
         /// <summary>
@@ -261,7 +265,9 @@ public void NumberValidationExceptionTest(string invalidNumber, byte checkDigit)
         /// </summary>
         [Theory(DisplayName = "Validates a number with separate check digit greater than 9 to throw an exception")]
         [MemberData(nameof(NumbersWithInvalidCheckDigits), MemberType = typeof(LuhnTest))]
-        public void LuhnCheckDigitValidationExceptionTest(string invalidNumber, byte checkDigit)
+        public void IsValidLuhnCheckDigit_InvalidInput_ThrowsArgumentOutOfRangeException(
+            string invalidNumber,
+            byte checkDigit)
         {
             Assert.Throws<ArgumentOutOfRangeException>(() => checkDigit.IsValidLuhnCheckDigit(invalidNumber));
             Assert.Throws<ArgumentOutOfRangeException>(() => checkDigit.IsValidLuhnCheckDigit(invalidNumber.AsSpan()));
@@ -270,7 +276,7 @@ public void LuhnCheckDigitValidationExceptionTest(string invalidNumber, byte che
         /// <summary>
         /// Test data for AlphaNumericToNumeric method.
         /// </summary>
-        public static IEnumerable<object[]> ConvertAlphaNumericToNumericData =>
+        public static IEnumerable<object[]> AlphaNumericToNumericData =>
             new List<object[]>
             {
                 new object[] { "A1B2C3", "101112123" },
@@ -287,8 +293,8 @@ public void LuhnCheckDigitValidationExceptionTest(string invalidNumber, byte che
         /// <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 ConvertAlphaNumericToNumeric_ShouldReturnExpectedResult(string input, string expected)
+        [MemberData(nameof(AlphaNumericToNumericData), MemberType = typeof(LuhnTest))]
+        public void AlphaNumericToNumeric_ValidInput_ShouldReturnExpectedResult(string input, string expected)
         {
             Assert.Equal(expected, input.AlphaNumericToNumeric());
         }
@@ -302,9 +308,9 @@ public void ConvertAlphaNumericToNumeric_ShouldReturnExpectedResult(string input
         /// xUnit to check if the expected exception is thrown.
         /// </remarks>
         [Fact(DisplayName = "Converts an invalid alphanumeric string to a numeric string to throw an exception")]
-        public void ConvertAlphaNumericToNumeric_InvalidInput_ThrowsArgumentException()
+        public void AlphaNumericToNumeric_InvalidInput_ThrowsInvalidCharacterException()
         {
-            Assert.Throws<ArgumentException>(()=> "!@#$%^&*()".AlphaNumericToNumeric());
+            Assert.Throws<InvalidCharacterException>(()=> "!@#$%^&*()".AlphaNumericToNumeric());
         }
 
         /// <summary>
@@ -328,7 +334,7 @@ public void ConvertAlphaNumericToNumeric_InvalidInput_ThrowsArgumentException()
         /// <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)
+        public void IsValidLuhnNumber_WithAlphaNumericToNumeric_ReturnsExpectedCheckDigit(string input, bool expected)
         {
             Assert.Equal(expected, input.AlphaNumericToNumeric().IsValidLuhnNumber());
             Assert.Equal(expected, input.AlphaNumericToNumeric().AsSpan().IsValidLuhnNumber());
@@ -366,7 +372,7 @@ public void IsValidWithConvertTest(string input, bool expected)
         /// </remarks>
         [Theory(DisplayName = "Calculates the check digit for a valid alphanumeric string")]
         [MemberData(nameof(ComputeLuhnCheckDigitWithConvertData), MemberType = typeof(LuhnTest))]
-        public void ComputeLuhnCheckDigit_WithConvertAlphaNumericToNumeric_ReturnsExpectedCheckDigit(
+        public void ComputeLuhnCheckDigit_WithAlphaNumericToNumeric_ReturnsExpectedCheckDigit(
             string input,
             byte expected)
         {