Added extension method on Person to generate Belgian national number (#557)

* feat: Added extension method on Person to generate Belgian national number

* Add README.md API extension.

---------

Co-authored-by: Brian Chavez <[email protected]>

Author: vyruz1986

README.md

@@ -485,6 +485,8 @@ In the examples above, all three alternative styles of using **Bogus** produce t
 	* `WeightedRandom<T>` - Returns a selection of T[] based on a weighted distribution of probability.
 
 #### API Extension Methods
+* **`using Bogus.Extensions.Belgium;`**
+	* `Bogus.Person.NationalNumber()` - Rijksregisternummer / Numéro Nationale
 * **`using Bogus.Extensions.Brazil;`**
 	* `Bogus.Person.Cpf()` - Cadastro de Pessoas Físicas
 	* `Bogus.DataSets.Company.Cnpj()` - Cadastro Nacional da Pessoa Jurídica

Source/Bogus.Tests/ExtensionTests/BelgianExtensionTests.cs

@@ -0,0 +1,89 @@
+using Bogus.DataSets;
+using Bogus.Extensions.Belgium;
+using FluentAssertions;
+using Xunit;
+
+namespace Bogus.Tests.ExtensionTests;
+
+public class BelgianExtensionTests : SeededTest
+{
+   private readonly Faker _faker;
+
+   public BelgianExtensionTests()
+   {
+      _faker = new Faker();
+   }
+
+   [Fact]
+   public void can_generate_national_number_for_belgium()
+   {
+      // Act
+      var obtained = _faker.Person.NationalNumber(includeFormatSymbols: false);
+
+      obtained.Dump();
+
+      // Assert
+      obtained.Should().NotBeNullOrWhiteSpace();
+      ShouldBeLegalBelgianNationalNumber(obtained);
+      ShouldBeCorrectGenderCode(_faker.Person.Gender, obtained);
+      ShouldHaveCorrectChecksum(obtained);
+   }
+
+   [Fact]
+   public void excludes_formatting_national_number()
+   {
+      var result = _faker.Person.NationalNumber(includeFormatSymbols: false);
+      result.Should().NotContainAny("-", ".");
+   }
+
+   [Fact]
+   public void includes_formatting_national_number()
+   {
+      var result = _faker.Person.NationalNumber(includeFormatSymbols: true);
+      result.Should().ContainAll("-", ".");
+   }
+
+
+   private void ShouldHaveCorrectChecksum(string candidate)
+   {
+      var baseNumber = long.Parse(candidate.Substring(0, 9));
+      var checkNumber = candidate.Substring(9);
+      var birthYear = int.Parse(candidate.Substring(0, 2));
+
+      if (birthYear == 00)
+         baseNumber += 2000000000L;
+
+      var expectedCheckNumber = 97 - (int)(baseNumber % 97);
+
+      checkNumber.Should().Be(expectedCheckNumber.ToString());
+   }
+
+   private void ShouldBeLegalBelgianNationalNumber(string candidate)
+   {
+      // Check if the first 6 digits represent a valid date.
+      var year = int.Parse(candidate.Substring(0, 2));
+      var month = int.Parse(candidate.Substring(2, 2));
+      var day = int.Parse(candidate.Substring(4, 2));
+
+      day.Should().BeInRange(1, 31);
+      month.Should().BeInRange(1, 12);
+      year.Should().BeInRange(0, 99);
+   }
+
+   private void ShouldBeCorrectGenderCode(Name.Gender gender, string candidate)
+   {
+      var sequenceNumber = int.Parse(candidate.Substring(6, 3));
+
+      if (gender == Name.Gender.Female)
+      {
+         sequenceNumber.Should()
+            .Match(x => x % 2 == 0);
+      }
+
+      if (gender == Name.Gender.Male)
+      {
+         sequenceNumber.Should()
+            .Match(x => x % 2 == 1);
+      }
+   }
+}

Source/Bogus/Extensions/Belgium/ExtensionsForBelgium.cs

@@ -0,0 +1,59 @@
+namespace Bogus.Extensions.Belgium;
+
+/// <summary>
+/// API extensions specific for a geographical location.
+/// </summary>
+public static class ExtensionsForBelgium
+{
+
+   /// <summary>
+   /// The national number is a unique identification number (11 digits) assigned to persons registered in Belgium.
+   /// Everyone with a Belgian identity document or a residence document has this number.
+   /// </summary>
+   /// <param name="includeFormatSymbols">Includes formatting symbols.</param>
+   public static string NationalNumber(this Person p, bool includeFormatSymbols = true)
+   {
+      /*
+         YY.MM.DD-SSS.CC
+         |  |  |  |   |
+         |  |  |  |   |
+         |  |  |  |   |--> (C)Checksum digit (modulo 97)
+         |  |  |  |------> (S)Sequential number for people born on the same date. Even for women (002-998), odd for men (001-997).
+         |  |  |---------> (D)Day of birth date (may be 0 for international refugees where exact birth date is unknown)
+         |  |------------> (M)Month of birth date (may be 0 for international refugees where exact birth date is unknown)
+         |---------------> (Y)Year of birth date (last two digits)
+
+         https://nl.wikipedia.org/wiki/Rijksregisternummer
+     */
+
+      var sequence = p.Gender == DataSets.Name.Gender.Male
+         ? p.Random.Odd(1, 997)
+         : p.Random.Even(2, 998);
+
+      var baseNumber = $"{p.DateOfBirth:yyMMdd}{sequence:000}";
+      var baseNumberLong = ulong.Parse(baseNumber);
+
+      var bornAfter2000 = p.DateOfBirth.Year >= 2000;
+      var checkNumber = bornAfter2000
+         ? 97 - (int)((baseNumberLong + 2000000000L) % 97)
+         : 97 - (int)(baseNumberLong % 97);
+
+      var nationalNumber = $"{baseNumber}{checkNumber}";
+
+      return includeFormatSymbols
+         ? FormatNationalNumber(nationalNumber)
+         : nationalNumber;
+   }
+
+   private static string FormatNationalNumber(string nationalNumber)
+   {
+      string year = nationalNumber.Substring(0, 2);
+      string month = nationalNumber.Substring(2, 2);
+      string day = nationalNumber.Substring(4, 2);
+      string serial = nationalNumber.Substring(6, 3);
+      string checkDigits = nationalNumber.Substring(9, 2);
+
+      // Format as yy.MM.dd-sss.00
+      return $"{year}.{month}.{day}-{serial}.{checkDigits}";
+   }
+}