Feature/national check digits validation

[RedSlowpoke]

Rationale

Previously, the iban4j library only performed standard IBAN validation (format, length, and international check digit validation). However, many countries have additional national check digit validation rules that provide an extra layer of validation for their domestic banking systems. This change extends the library to support country-specific national check digit validation rules, providing more comprehensive IBAN validation capabilities for applications that need to ensure the highest level of accuracy when processing international bank account numbers.

Changes

Core Infrastructure

• New ValidationConfig class: Added configuration system for enabling/disabling national check digit validation
• New IbanValidator class: Created non-static, reusable validator with configurable validation options
• Enhanced IbanUtil: Added convenience methods for country-specific validation (validateWithCountryRules, isValidWithCountryRules)
• Country Rules Framework: Implemented extensible framework for country-specific validation algorithms

National Check Digit Algorithms

Implemented validation algorithms for 20 countries with separate documentation and implementation files:

• Documentation: Detailed algorithm specifications in docs/references/check digits/
• Implementation: Country-specific algorithms in src/main/java/org/iban4j/countryrules/algorithms/
• Supported Countries: Belgium, Bosnia and Herzegovina, Croatia, Czech Republic, Estonia, Finland, France, Iceland, Italy, Macedonia, Montenegro, Netherlands, Norway, Portugal, Serbia, Slovak Republic, Slovenia, Spain, Tunisia

Utility Classes

• Iso7064 utility: Implemented ISO 7064 standard validation methods
• Country Rules Registry: Centralized registration and lookup system for country algorithms
• Enhanced IbanFormatException: Added COUNTRY_RULES_FAILED violation type

Documentation

• Comprehensive documentation: Added detailed national check digit validation guide covering all supported countries
• Updated README: Enhanced with examples of country-specific validation usage
• Algorithm specifications: Documented validation rules and valid IBAN examples for each country

API Enhancements

• Backward compatibility: All new features are opt-in and disabled by default
• Builder pattern: Clean API for configuring validation options
• Thread-safe design: Validator instances are immutable and reusable

Tests

Unit Tests

• IbanValidatorTest: Comprehensive testing of the new validator class with various configurations
• NationalCheckDigitAlgorithmTest: Individual algorithm testing for all 20 supported countries
• ValidationConfigTest: Configuration class testing
• CountryRulesRegistryTest: Registry functionality testing
• IbanUtilCountryRulesTest: Integration testing with IbanUtil convenience methods

Test Coverage

• Valid IBANs with correct national check digits
• Invalid IBANs with incorrect national check digits
• Edge cases and boundary conditions
• Configuration validation
• Error handling and exception scenarios

Impact

Enhanced Validation Capabilities

• Provides comprehensive IBAN validation that goes beyond standard ISO 13616 requirements
• Enables applications to catch invalid IBANs that would pass basic validation but fail country-specific rules
• Supports 20 countries with their specific national check digit algorithms

Developer Experience

• Clean, intuitive API with builder pattern for configuration
• Comprehensive documentation with examples for each supported country
• Backward compatibility ensures existing code continues to work unchanged

Performance Considerations

• Country-specific validation is opt-in and disabled by default to preserve performance
• Lazy initialization of country rules algorithms
• Immutable validator instances for thread safety

Backward Compatibility

• All existing functionality remains unchanged
• New features are opt-in and disabled by default
• No breaking changes to existing APIs
• Existing codebases will continue to work without modification

Future Extensibility

• Extensible framework allows easy addition of new countries
• Clear separation of concerns between standard and country-specific validation
• Well-documented algorithm patterns for implementing new country rules

[RedSlowpoke]

@hajk1 Could you kindly review my PR and tell me whether this approach is suitable for the project?

[hajk1]

@RedSlowpoke The general approach is right. However there is an active issue and development related to this feature here.
I need to review and take a decision to choose one of the development PRs in couple of days.

[RedSlowpoke]

Let me know if anything is expected from me to make this happen @hajk1

[hajk1]

@RedSlowpoke I will review till end of the month.