chore(release): prepare 1.8.9 release

- bump documented version to 1.8.9 and country count to 127 in README
- add "What's New in 1.8.9" section (IbanBuilder, 7 new countries,
  regex/component utilities, Country/CountryUtil consolidation)
- polish Javadoc across iban-commons, iban-commons-junit and
  iban-commons-validation (accurate @return/@throws, HTML markup
  instead of markdown bold, typo fixes)
- fix IbanConstraintValidator to enforce per-field allowSpace=false
  even when the global IbanConfig allows spaces
- bump license-maven-plugin to 5.1.2 and pitest to 1.30.0

Author: spannm

README.md

@@ -17,7 +17,7 @@
 **[🚀 Quick Start](#-quick-start) • [📖 Examples](#-code-examples) • [📊 Benchmarks](#-performance-benchmarks) • [📚 Javadoc](https://javadoc.io/doc/de.speedbanking/iban-commons/latest/) • [💬 Discussions](https://github.com/SpeedBankingDe/iban-commons/discussions)**
 
 `iban-commons` is a Java IBAN validation library and BIC validator for Java 8+, providing fast and reliable parsing, validation, and formatting of International Bank Account Numbers (IBAN) and Business Identifier Codes (BIC/SWIFT codes).
-Designed for high-performance enterprise applications, it covers 120 countries, is Android-compatible (API 21+), and has zero compile or runtime dependencies outside the Java Standard Library.
+Designed for high-performance enterprise applications, it covers 127 countries, is Android-compatible (API 21+), and has zero compile or runtime dependencies outside the Java Standard Library.
 
 ## Why IBAN Commons?
 
@@ -28,7 +28,7 @@ Designed for high-performance enterprise applications, it covers 120 countries,
 | **Dependencies**           |        0       |     0     |       5        |     0     |     0     |
 | **Java Version**           |       8+       |    8+     |       8+       |    11+    |    8+     |
 | **Android (API 21+)**      |        ✅       |     ?     |       ?        |     ?     |     ✅     |
-| **Countries**              |       120      |    82     |      n/a       |    111    |    111    |
+| **Countries**              |       127      |    82     |      n/a       |    111    |    111    |
 
 > Throughput: rejection path (invalid IBANs) — JMH · OpenJDK 21.0.7 · Linux · single core · ParallelGC · `-XX:-StackTraceInThrowable` · 2026-04-19
 
@@ -43,13 +43,13 @@ Designed for high-performance enterprise applications, it covers 120 countries,
 <dependency>
     <groupId>de.speedbanking</groupId>
     <artifactId>iban-commons</artifactId>
-    <version>1.8.8</version>
+    <version>1.8.9</version>
 </dependency>
 ```
 
 **Gradle:**
 ```gradle
-implementation 'de.speedbanking:iban-commons:1.8.8'
+implementation 'de.speedbanking:iban-commons:1.8.9'
 ```
 
 ### 2. Validate & Parse
@@ -362,6 +362,22 @@ All performance tests are fully open and available in the [SpeedBankingDe/iban-c
 
 -----
 
+## 🆕 What's New in 1.8.9
+
+### IbanBuilder
+New `IbanBuilder` API (obtained via `IbanRegistry#builder()`) generates structurally valid, correctly checksummed IBANs from explicit or randomly filled components — useful for tests and fixtures.
+
+### 7 New Countries
+Added CG (Congo-Brazzaville), CI (Côte d'Ivoire), GW (Guinea-Bissau), MG (Madagascar), ML (Mali), NE (Niger), and TD (Chad) to `IbanRegistry`, bringing total country coverage to 127.
+
+### Regex & Component Utilities
+Added `PatternCache` (thread-safe compiled-`Pattern` cache) and `RegexSimplifier` (consolidates consecutive same-class regex blocks), plus new `IndexRange` offset methods and gap-range support in component string formatting.
+
+### Internal Consolidation
+`CountryUtil` was merged into `Country` (including `createFlagEmoji`), and several country data entries were corrected (Bolivia name, Tonga continent, ZWL→ZWG rename, KGS typo).
+
+-----
+
 ## 🆕 What's New in 1.8.8
 
 ### Optimized BIC Validation Pipeline

iban-commons-junit/src/main/java/de/speedbanking/iban/junit/jupiter/params/provider/IbanCountrySource.java

@@ -15,6 +15,7 @@
  */
 package de.speedbanking.iban.junit.jupiter.params.provider;
 
+import static java.util.stream.Collectors.toList;
 import static java.util.stream.Collectors.toSet;
 
 import de.speedbanking.iban.IbanRegistry;
@@ -32,6 +33,7 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 import java.util.Arrays;
+import java.util.List;
 import java.util.Set;
 import java.util.stream.Stream;
 
@@ -45,6 +47,8 @@
  *   <li>The country name (e.g., "Germany")</li>
  * </ul>
  * The list of provided IBAN registries can be filtered using the {@link #includeCountries()} and {@link #excludeCountries()} parameters.
+ *
+ * @since 1.8.6
  */
 @Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
 @Retention(RetentionPolicy.RUNTIME)
@@ -57,8 +61,8 @@
      * If specified, only the constants listed here will be considered. If not specified (default),
      * all enum constants are initially taken into consideration before applying {@link #excludeCountries()}.
      * <p>
-     * **Note:** The names must match existing enum constants, otherwise an {@link IllegalArgumentException} is thrown
-     * by the calling code.
+     * <strong>Note:</strong> entries are type-safe {@link IbanRegistry} enum constants, so an invalid
+     * name is already rejected at compile time, not at runtime.
      */
     IbanRegistry[] includeCountries() default {};
 
@@ -67,13 +71,25 @@
      * <p>
      * Constants listed here will be filtered out from the final list of arguments.
      * <p>
-     * **Note:** The names must match existing enum constants, otherwise an {@link IllegalArgumentException} is thrown
-     * by the calling code.
+     * <strong>Note:</strong> entries are type-safe {@link IbanRegistry} enum constants, so an invalid
+     * name is already rejected at compile time, not at runtime.
      */
     IbanRegistry[] excludeCountries() default {};
 
+    /**
+     * Implementation of {@link ArgumentsProvider} for {@link IbanCountrySource}.
+     */
     class IbanCountryArgumentsProvider implements ArgumentsProvider {
 
+        /**
+         * Provides the filtered stream of {@link IbanRegistry} entries as test arguments.
+         *
+         * @param parameters parameter declarations of the test method (unused)
+         * @param context    the current extension context
+         * @return a non-empty stream of {@link Arguments}, each wrapping a country code and country name
+         * @throws IllegalStateException if the {@code @IbanCountrySource} annotation is not present on the
+         *                                test element, or if the configured filters match no entries
+         */
         @Override
         public Stream<? extends Arguments> provideArguments(ParameterDeclarations parameters, ExtensionContext context) {
             // find the annotation on the element (usually a method) or throw if not present
@@ -90,10 +106,18 @@ public Stream<? extends Arguments> provideArguments(ParameterDeclarations parame
             Set<IbanRegistry> excludedCountries = Arrays.stream(src.excludeCountries())
                 .collect(toSet());
 
-            // filter the included stream by the excluded set and map to Arguments
-            return includeCountries
+            // filter the included stream by the excluded set
+            List<IbanRegistry> result = includeCountries
                 .filter(registry -> !excludedCountries.contains(registry))
-                .map(registry -> Arguments.of(registry.getCountryCode(), registry.getCountryName()));
+                .collect(toList());
+
+            if (result.isEmpty()) {
+                throw new IllegalStateException(
+                    "No " + IbanRegistry.class.getSimpleName() + " entries matched the configured "
+                    + "includeCountries/excludeCountries filter of @" + IbanCountrySource.class.getSimpleName() + ".");
+            }
+
+            return result.stream().map(registry -> Arguments.of(registry.getCountryCode(), registry.getCountryName()));
         }
 
     }

iban-commons-junit/src/main/java/de/speedbanking/iban/junit/jupiter/params/provider/IbanRegistrySource.java

@@ -279,7 +279,7 @@ public Stream<? extends Arguments> provideArguments(ParameterDeclarations parame
             // the filter combination is too restrictive.
             if (result.isEmpty()) {
                 throw new IllegalStateException(
-                    "No " + IbanRegistry.class.getSimpleName() + " entries matched " + describe(config) + "."
+                    "No " + IbanRegistry.class.getSimpleName() + " entries matched " + describe(config) + ". "
                     + "Check that the filter combination is not contradictory "
                     + "(e.g. sepa=YES with a non-SEPA currency) or overly restrictive.");
             }

iban-commons-junit/src/main/java/de/speedbanking/iban/junit/jupiter/params/provider/RandomIbanSource.java

@@ -208,7 +208,7 @@ private static List<IbanRegistry> validateAndBuild(RandomIbanSource config) {
 
             // value() and includeCountries() must not both be specified
             if (!valueCountries.isEmpty() && !includeCountries.isEmpty()) {
-                throwIllegalArgument(": value and includeCountries must not be used simultaneously");
+                throwIllegalArgument("value and includeCountries must not be used simultaneously");
             }
 
             // resolve effective include list

iban-commons-junit/src/main/java/de/speedbanking/iban/junit/jupiter/params/provider/package-info.java

@@ -23,8 +23,8 @@
  *
  * <ul>
  *   <li>{@link de.speedbanking.iban.junit.jupiter.params.provider.IbanCountrySource} –
- *       supplies {@link de.speedbanking.iban.IbanRegistry} entries filtered by SEPA
- *       membership or an explicit country list.</li>
+ *       supplies {@link de.speedbanking.iban.IbanRegistry} entries filtered by an
+ *       explicit include/exclude country list.</li>
  *   <li>{@link de.speedbanking.iban.junit.jupiter.params.provider.IbanRegistrySource} –
  *       supplies all (or a filtered subset of) {@link de.speedbanking.iban.IbanRegistry}
  *       enum constants.</li>

iban-commons-validation/src/main/java/de/speedbanking/validation/IbanConstraintValidator.java

@@ -17,6 +17,7 @@
 
 import de.speedbanking.iban.Iban;
 import de.speedbanking.iban.IbanConfig;
+import de.speedbanking.iban.IbanValidationError;
 import de.speedbanking.iban.InvalidIbanException;
 
 import jakarta.validation.ConstraintValidator;
@@ -61,8 +62,18 @@ public boolean isValid(CharSequence value, ConstraintValidatorContext ctx) {
             return true;
         }
 
-        // If the annotation permits spaces but the global IbanConfig does not,
-        // strip spaces before delegating so that Iban.validate() does not reject them.
+        // Iban.validate() only ever honors the global IbanConfig.isAllowSpace() flag, so the
+        // per-field allowSpace() attribute has to be enforced here on both sides:
+        if (!allowSpace && IbanConfig.isAllowSpace() && containsSpace(value)) {
+            // annotation forbids spaces even though the global config would otherwise accept them
+            ctx.disableDefaultConstraintViolation();
+            ctx.buildConstraintViolationWithTemplate(IbanValidationError.ILLEGAL_CHARACTERS.getText())
+               .addConstraintViolation();
+            return false;
+        }
+
+        // annotation permits spaces but the global IbanConfig does not: strip them before
+        // delegating so that Iban.validate() does not reject them.
         CharSequence input = allowSpace && !IbanConfig.isAllowSpace() ? stripSpaces(value) : value;
 
         try {
@@ -78,6 +89,15 @@ public boolean isValid(CharSequence value, ConstraintValidatorContext ctx) {
         }
     }
 
+    private static boolean containsSpace(CharSequence value) {
+        for (int i = 0; i < value.length(); i++) {
+            if (value.charAt(i) == ' ') {
+                return true;
+            }
+        }
+        return false;
+    }
+
     private static String stripSpaces(CharSequence value) {
         // avoids regex overhead for the common case of no spaces
         String s = value.toString();

iban-commons/src/main/java/de/speedbanking/bic/Bic.java

@@ -103,7 +103,7 @@ public final class Bic implements Serializable, CharSequence, Comparable<Bic> {
      * Package-private constructor.
      * <p>
      * Construction is restricted to {@link BicValidator} which guarantees
-     * the input character sequence {@code csBic} is valid, normalized,
+     * the input character sequence {@code bicInput} is valid, normalized,
      * and correctly sized (8 or 11 characters long).
      * <p>
      * For BIC-11 input the branch code is stored eagerly so that {@link #toBic11()}
@@ -336,7 +336,7 @@ public String getLocationCode() {
      * <ul>
      *   <li>For BIC {@code BHLSDEMMXXX}: Branch Code is {@code XXX} (Head Office of Bankhaus Ludwig Sperrer KG)</li>
      *   <li>For BIC {@code DEUTDEFFXXX}: Branch Code is {@code XXX} (Head Office of Deutsche Bank AG)</li>
-     *   <li>For BIC {@code DEUTDEFF444}: Branch Code is {@code 500} (Specific Branch of Deutsche Bank AG Frankfurt am Main)</li>
+     *   <li>For BIC {@code DEUTDEFF444}: Branch Code is {@code 444} (Specific Branch of Deutsche Bank AG Frankfurt am Main)</li>
      * </ul>
      *
      * @return the Branch Code (e.g., {@code "XXX"}), or {@code null} if the BIC is a BIC-8 (8 characters long)

iban-commons/src/main/java/de/speedbanking/iban/AbstractCountryValidator.java

@@ -21,7 +21,7 @@
  * <h3>Design</h3>
  * Every country-specific {@code CountryValidator} implementation (declared in {@link CountryValidators})
  * extends this base instead of implementing {@link CountryValidator} directly.
- * Centralising shared behaviour here keeps the generated subclasses minimal:
+ * Centralizing shared behavior here keeps the generated subclasses minimal:
  * they only contain a {@code validateIban} implementation and nothing else.
  *
  * <h3>toString</h3>

iban-commons/src/main/java/de/speedbanking/iban/Iban.java

@@ -29,17 +29,17 @@
 import java.util.Optional;
 
 /**
- * Represents a valid, immutable **International Bank Account Number (IBAN)**,
- * structured according to the **ISO 13616** standard.
+ * Represents a valid, immutable <strong>International Bank Account Number (IBAN)</strong>,
+ * structured according to the <strong>ISO 13616</strong> standard.
  * <p>
  * The validity is guaranteed by successful checks on length, country-specific
- * structure (BBAN), and the **ISO 7064 Mod 97-10** checksum.
+ * structure (BBAN), and the <strong>ISO 7064 Mod 97-10</strong> checksum.
  * <p>
  * The IBAN format consists of:
  * <ul>
- *   <li>**Country Code** (2 letters, ISO 3166-1 alpha-2)</li>
- *   <li>**Check Digits** (2 numbers, calculated using ISO 7064 Mod 97-10)</li>
- *   <li>**Basic Bank Account Number (BBAN)** (country-specific length and structure)</li>
+ *   <li><strong>Country Code</strong> (2 letters, ISO 3166-1 alpha-2)</li>
+ *   <li><strong>Check Digits</strong> (2 numbers, calculated using ISO 7064 Mod 97-10)</li>
+ *   <li><strong>Basic Bank Account Number (BBAN)</strong> (country-specific length and structure)</li>
  * </ul>
  * Creation is done exclusively via static factory methods after successful validation.
  *
@@ -99,7 +99,7 @@ public final class Iban implements Serializable, CharSequence, Comparable<Iban>
      * Package-private constructor.
      * <p>
      * Construction is restricted to static factory methods after validation and guarantees
-     * the input {@code ibanArr} is valid, normalized, and correctly sized.
+     * the input {@code normIban} is valid, normalized, and correctly sized.
      *
      * @param normIban    the normalized, validated IBAN characters
      * @param countryData the metadata for the country code (format, structure)
@@ -250,7 +250,7 @@ public static boolean isValid(final String iban) {
     /**
      * Returns the two-letter ISO country code (positions 1 and 2).
      * <p>
-     * This is the {@code <strong>ISO 3166-1 Alpha-2</strong>} country code, which identifies the country of the bank.
+     * This is the <strong>ISO 3166-1 Alpha-2</strong> country code, which identifies the country of the bank.
      * This code forms the initial part of every IBAN.
      * <p>
      * Examples:

iban-commons/src/main/java/de/speedbanking/iban/IbanBuilder.java

@@ -162,6 +162,8 @@ public final B accountNumber(String accountNumber) {
      * Builds and returns a fully formatted and valid IBAN instance.
      *
      * @return the constructed IBAN
+     * @throws IllegalStateException if a subclass hook alters the IBAN length to an invalid value
+     * @throws InvalidIbanException  if the assembled IBAN string unexpectedly fails validation
      */
     public final Iban build() {
         String countryCode = getCountryData().getBaseCountry().getCountryCode();
@@ -190,12 +192,17 @@ public final Iban build() {
                 + " (expected: " + expectedLength + ")");
         }
 
-        // always calculdate NCD regardless of IbanConfig#isCalculateNcd
+        // always calculate NCD regardless of IbanConfig#isCalculateNcd
         fixNationalCheckDigit(getCountryData(), ibanBuilder);
 
         fixCheckDigits(ibanBuilder);
 
-        return Iban.of(ibanBuilder.toString());
+        // fixCheckDigits() already ran a full structural validation (with placeholder check
+        // digits, whose value does not influence structure validation) and just installed the
+        // correct checksum, so the result is provably valid at this point. Re-parsing it via
+        // Iban.of() would repeat that same structural + checksum validation for no benefit;
+        // constructing directly (this class shares Iban's package) skips that redundant pass.
+        return new Iban(ibanBuilder, getCountryData());
     }
 
     /**
@@ -286,7 +293,7 @@ StringBuilder resolveComponent(StringBuilder target, IbanComponent ibanComponent
             boolean canPad = paddingLen > 0 && IbanPatternConverter.allMatch(segments, Segment::isNumericOrAlphanumeric);
 
             // validate pattern against the input (or padded representation if padding will be applied)
-            String regex = IbanPatternConverter.buildRegex(segments);
+            String regex = IbanPatternConverter.buildRegex(ibanComponent.getPattern(), segments);
             CharSequence checkTarget = canPad ? padLeft(input.toString(), requiredLength, '0') : input;
             if (!PatternCache.getDefault().getPattern(regex).matcher(checkTarget).matches()) {
                 throw InvalidIbanException.of(errorFor(ibanComponent.getType()), input, getCountryData().getCountryCode());