sec_id 4.1.0 → 4.3.0

data/lib/sec_id/cik.rb

@@ -1,33 +1,61 @@
 # frozen_string_literal: true
 
 module SecId
-  # https://en.wikipedia.org/wiki/Central_Index_Key
+  # Central Index Key (CIK) - SEC identifier for entities filing with the SEC.
+  # A 1-10 digit number that uniquely identifies entities in SEC systems.
+  #
+  # @note CIK identifiers have no check digit. The {#has_check_digit?} method
+  #   returns false and validation is based solely on format.
+  #
+  # @see https://en.wikipedia.org/wiki/Central_Index_Key
+  #
+  # @example Validate a CIK
+  #   SecId::CIK.valid?('0001521365')  #=> true
+  #   SecId::CIK.valid?('1521365')     #=> true
+  #
+  # @example Normalize a CIK to 10 digits
+  #   SecId::CIK.normalize!('1521365')  #=> '0001521365'
   class CIK < Base
+    include Normalizable
+
+    # Regular expression for parsing CIK components.
     ID_REGEX = /\A
       (?=\d{1,10}\z)(?<padding>0*)(?<identifier>[1-9]\d{0,9})
     \z/x
 
+    # @return [String, nil] the leading zeros in the CIK
     attr_reader :padding
 
+    # @param cik [String, Integer] the CIK to parse
     def initialize(cik)
-      cik_parts = parse cik
+      cik_parts = parse(cik)
       @padding = cik_parts[:padding]
       @identifier = cik_parts[:identifier]
+      @check_digit = nil
     end
 
-    def valid?
-      valid_format?
-    end
-
-    def valid_format?
-      !identifier.nil?
+    # @return [Boolean] always false
+    def has_check_digit?
+      false
     end
 
-    def restore!
-      raise InvalidFormatError, "CIK '#{full_number}' is invalid and cannot be restored!" unless valid_format?
+    # Normalizes the CIK to a 10-digit zero-padded format.
+    # Updates both @full_number and @padding to reflect the normalized state.
+    #
+    # @return [String] the normalized 10-digit CIK
+    # @raise [InvalidFormatError] if the CIK format is invalid
+    def normalize!
+      raise InvalidFormatError, "CIK '#{full_number}' is invalid and cannot be normalized!" unless valid_format?
 
-      @padding = '0' * (10 - @identifier.length)
       @full_number = @identifier.rjust(10, '0')
+      @padding = @full_number[0, 10 - @identifier.length]
+      @full_number
+    end
+
+    # @return [String]
+    def to_s
+      full_number
     end
+    alias to_str to_s
   end
 end

data/lib/sec_id/cusip.rb

@@ -1,8 +1,21 @@
 # frozen_string_literal: true
 
 module SecId
-  # https://en.wikipedia.org/wiki/CUSIP
+  # Committee on Uniform Securities Identification Procedures (CUSIP) - a 9-character
+  # alphanumeric code that identifies North American securities.
+  #
+  # Format: 6-character issuer code (CUSIP-6) + 2-character issue number + 1-digit check digit
+  #
+  # @see https://en.wikipedia.org/wiki/CUSIP
+  #
+  # @example Validate a CUSIP
+  #   SecId::CUSIP.valid?('037833100')  #=> true
+  #
+  # @example Convert to ISIN
+  #   cusip = SecId::CUSIP.new('037833100')
+  #   cusip.to_isin('US')  #=> #<SecId::ISIN>
   class CUSIP < Base
+    # Regular expression for parsing CUSIP components.
     ID_REGEX = /\A
       (?<identifier>
         (?<cusip6>[A-Z0-9]{5}[A-Z0-9*@#])
@@ -10,8 +23,13 @@ module SecId
       (?<check_digit>\d)?
     \z/x
 
-    attr_reader :cusip6, :issue
+    # @return [String, nil] the 6-character issuer code
+    attr_reader :cusip6
 
+    # @return [String, nil] the 2-character issue number
+    attr_reader :issue
+
+    # @param cusip [String] the CUSIP string to parse
     def initialize(cusip)
       cusip_parts = parse cusip
       @identifier = cusip_parts[:identifier]
@@ -20,14 +38,16 @@ module SecId
       @check_digit = cusip_parts[:check_digit]&.to_i
     end
 
+    # @return [Integer] the calculated check digit (0-9)
+    # @raise [InvalidFormatError] if the CUSIP format is invalid
     def calculate_check_digit
-      unless valid_format?
-        raise InvalidFormatError, "CUSIP '#{full_number}' is invalid and check-digit cannot be calculated!"
-      end
-
+      validate_format_for_calculation!
       mod10(modified_luhn_sum)
     end
 
+    # @param country_code [String] the ISO 3166-1 alpha-2 country code (must be CGS country)
+    # @return [ISIN] a new ISIN instance
+    # @raise [InvalidFormatError] if the country code is not a CGS country
     def to_isin(country_code)
       unless ISIN::CGS_COUNTRY_CODES.include?(country_code)
         raise(InvalidFormatError, "'#{country_code}' is not a CGS country code!")
@@ -39,14 +59,15 @@ module SecId
       isin
     end
 
-    # CUSIP International Numbering System
+    # @return [Boolean] true if first character is a letter (CINS identifier)
     def cins?
       cusip6[0] < '0' || cusip6[0] > '9'
     end
 
     private
 
-    # https://en.wikipedia.org/wiki/Luhn_algorithm
+    # @return [Integer] the modified Luhn sum
+    # @see https://en.wikipedia.org/wiki/Luhn_algorithm
     def modified_luhn_sum
       reversed_id_digits.each_slice(2).reduce(0) do |sum, (even, odd)|
         double_even = (even || 0) * 2
@@ -54,6 +75,7 @@ module SecId
       end
     end
 
+    # @return [Array<Integer>] the reversed digit array
     def reversed_id_digits
       identifier.each_char.map(&method(:char_to_digit)).reverse!
     end

data/lib/sec_id/figi.rb

@@ -3,7 +3,22 @@
 require 'set'
 
 module SecId
+  # Financial Instrument Global Identifier (FIGI) - a 12-character alphanumeric code
+  # that uniquely identifies financial instruments.
+  #
+  # Format: 2-character prefix + 'G' + 8-character random part + 1-digit check digit
+  # Note: FIGI excludes vowels (A, E, I, O, U) from valid characters.
+  #
+  # @see https://en.wikipedia.org/wiki/Financial_Instrument_Global_Identifier
+  #
+  # @example Validate a FIGI
+  #   SecId::FIGI.valid?('BBG000BLNQ16')  #=> true
+  #
+  # @example Restore check digit
+  #   SecId::FIGI.restore!('BBG000BLNQ1')  #=> 'BBG000BLNQ16'
   class FIGI < Base
+    # Regular expression for parsing FIGI components.
+    # The third character must be 'G'. Excludes vowels from valid characters.
     ID_REGEX = /\A
       (?<identifier>
         (?<prefix>[B-DF-HJ-NP-TV-Z0-9]{2})
@@ -12,10 +27,16 @@ module SecId
       (?<check_digit>\d)?
     \z/x
 
+    # Country-code prefixes that are restricted from use in FIGI.
     RESTRICTED_PREFIXES = Set.new %w[BS BM GG GB GH KY VG]
 
-    attr_reader :prefix, :random_part
+    # @return [String, nil] the 2-character prefix
+    attr_reader :prefix
 
+    # @return [String, nil] the 8-character random part
+    attr_reader :random_part
+
+    # @param figi [String] the FIGI string to parse
     def initialize(figi)
       figi_parts = parse figi
       @identifier = figi_parts[:identifier]
@@ -24,28 +45,31 @@ module SecId
       @check_digit = figi_parts[:check_digit]&.to_i
     end
 
+    # @return [Boolean]
     def valid_format?
       !identifier.nil? && !RESTRICTED_PREFIXES.include?(prefix)
     end
 
+    # @return [Integer] the calculated check digit (0-9)
+    # @raise [InvalidFormatError] if the FIGI format is invalid
     def calculate_check_digit
-      unless valid_format?
-        raise InvalidFormatError, "FIGI '#{full_number}' is invalid and check-digit cannot be calculated!"
-      end
-
+      validate_format_for_calculation!
       mod10(modified_luhn_sum)
     end
 
     private
 
     # https://en.wikipedia.org/wiki/Luhn_algorithm
+    #
+    # @return [Integer] the modified Luhn sum
     def modified_luhn_sum
       reversed_id_digits.each_with_index.reduce(0) do |sum, (digit, index)|
         digit *= 2 if index.odd?
-        sum + digit.divmod(10).sum
+        sum + div10mod10(digit)
       end
     end
 
+    # @return [Array<Integer>] the identifier digits in reverse order
     def reversed_id_digits
       identifier.each_char.map(&method(:char_to_digit)).reverse!
     end

data/lib/sec_id/iban/country_rules.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+module SecId
+  # Country-specific BBAN validation rules for IBAN
+  # rubocop:disable Metrics/ModuleLength
+  module IBANCountryRules
+    # Country-specific BBAN rules for EU/EEA countries
+    # Each entry defines:
+    #   - :length => total BBAN length
+    #   - :format => regex pattern for BBAN structure validation
+    #   - :components => hash mapping component names to [start, length] positions
+    #
+    # Sources:
+    # - https://en.wikipedia.org/wiki/International_Bank_Account_Number
+    # - https://www.swift.com/standards/data-standards/iban-international-bank-account-number
+    COUNTRY_RULES = {
+      # Austria - 16 chars: 5-digit bank code + 11-digit account
+      'AT' => {
+        length: 16,
+        format: /\A\d{16}\z/,
+        components: { bank_code: [0, 5], account_number: [5, 11] }
+      },
+      # Belgium - 12 chars: 3-digit bank code + 7-digit account + 2-digit national check
+      'BE' => {
+        length: 12,
+        format: /\A\d{12}\z/,
+        components: { bank_code: [0, 3], account_number: [3, 7], national_check: [10, 2] }
+      },
+      # Bulgaria - 18 chars: 4-letter bank code + 4-digit branch + 2-digit account type + 8-digit account
+      'BG' => {
+        length: 18,
+        format: /\A[A-Z]{4}\d{14}\z/,
+        components: { bank_code: [0, 4], branch_code: [4, 4], account_number: [10, 8] }
+      },
+      # Croatia - 17 chars: 7-digit bank code + 10-digit account
+      'HR' => {
+        length: 17,
+        format: /\A\d{17}\z/,
+        components: { bank_code: [0, 7], account_number: [7, 10] }
+      },
+      # Cyprus - 24 chars: 3-digit bank code + 5-digit branch + 16-char account
+      'CY' => {
+        length: 24,
+        format: /\A\d{8}[A-Z0-9]{16}\z/,
+        components: { bank_code: [0, 3], branch_code: [3, 5], account_number: [8, 16] }
+      },
+      # Czech Republic - 20 chars: 4-digit bank code + 16-digit account
+      'CZ' => {
+        length: 20,
+        format: /\A\d{20}\z/,
+        components: { bank_code: [0, 4], account_number: [4, 16] }
+      },
+      # Denmark - 14 chars: 4-digit bank code + 10-digit account
+      'DK' => {
+        length: 14,
+        format: /\A\d{14}\z/,
+        components: { bank_code: [0, 4], account_number: [4, 10] }
+      },
+      # Estonia - 16 chars: 2-digit bank code + 14-digit account
+      'EE' => {
+        length: 16,
+        format: /\A\d{16}\z/,
+        components: { bank_code: [0, 2], account_number: [2, 14] }
+      },
+      # Finland - 14 chars: 3-digit bank code + 11-digit account
+      'FI' => {
+        length: 14,
+        format: /\A\d{14}\z/,
+        components: { bank_code: [0, 3], account_number: [3, 11] }
+      },
+      # France - 23 chars: 5-digit bank + 5-digit branch + 11-char account + 2-digit national check
+      'FR' => {
+        length: 23,
+        format: /\A\d{10}[A-Z0-9]{11}\d{2}\z/,
+        components: { bank_code: [0, 5], branch_code: [5, 5], account_number: [10, 11], national_check: [21, 2] }
+      },
+      # Germany - 18 chars: 8-digit bank code (Bankleitzahl) + 10-digit account
+      'DE' => {
+        length: 18,
+        format: /\A\d{18}\z/,
+        components: { bank_code: [0, 8], account_number: [8, 10] }
+      },
+      # Greece - 23 chars: 3-digit bank code + 4-digit branch + 16-digit account
+      'GR' => {
+        length: 23,
+        format: /\A\d{23}\z/,
+        components: { bank_code: [0, 3], branch_code: [3, 4], account_number: [7, 16] }
+      },
+      # Hungary - 24 chars: 3-digit bank code + 4-digit branch + 16-digit account + 1-digit national check
+      'HU' => {
+        length: 24,
+        format: /\A\d{24}\z/,
+        components: { bank_code: [0, 3], branch_code: [3, 4], account_number: [7, 16], national_check: [23, 1] }
+      },
+      # Iceland - 22 chars: 4-digit bank code + 2-digit branch + 6-digit account + 10-digit holder ID
+      'IS' => {
+        length: 22,
+        format: /\A\d{22}\z/,
+        components: { bank_code: [0, 4], branch_code: [4, 2], account_number: [6, 6] }
+      },
+      # Ireland - 18 chars: 4-letter bank code + 6-digit branch + 8-digit account
+      'IE' => {
+        length: 18,
+        format: /\A[A-Z]{4}\d{14}\z/,
+        components: { bank_code: [0, 4], branch_code: [4, 6], account_number: [10, 8] }
+      },
+      # Italy - 23 chars: 1-letter check + 5-digit bank code + 5-digit branch + 12-char account
+      'IT' => {
+        length: 23,
+        format: /\A[A-Z]\d{10}[A-Z0-9]{12}\z/,
+        components: { national_check: [0, 1], bank_code: [1, 5], branch_code: [6, 5], account_number: [11, 12] }
+      },
+      # Latvia - 17 chars: 4-letter bank code + 13-digit account
+      'LV' => {
+        length: 17,
+        format: /\A[A-Z]{4}[A-Z0-9]{13}\z/,
+        components: { bank_code: [0, 4], account_number: [4, 13] }
+      },
+      # Liechtenstein - 17 chars: 5-digit bank code + 12-char account
+      'LI' => {
+        length: 17,
+        format: /\A\d{5}[A-Z0-9]{12}\z/,
+        components: { bank_code: [0, 5], account_number: [5, 12] }
+      },
+      # Lithuania - 16 chars: 5-digit bank code + 11-digit account
+      'LT' => {
+        length: 16,
+        format: /\A\d{16}\z/,
+        components: { bank_code: [0, 5], account_number: [5, 11] }
+      },
+      # Luxembourg - 16 chars: 3-digit bank code + 13-char account
+      'LU' => {
+        length: 16,
+        format: /\A\d{3}[A-Z0-9]{13}\z/,
+        components: { bank_code: [0, 3], account_number: [3, 13] }
+      },
+      # Malta - 27 chars: 4-letter bank code + 5-digit branch + 18-char account
+      'MT' => {
+        length: 27,
+        format: /\A[A-Z]{4}\d{5}[A-Z0-9]{18}\z/,
+        components: { bank_code: [0, 4], branch_code: [4, 5], account_number: [9, 18] }
+      },
+      # Monaco - 23 chars: same format as France
+      'MC' => {
+        length: 23,
+        format: /\A\d{10}[A-Z0-9]{11}\d{2}\z/,
+        components: { bank_code: [0, 5], branch_code: [5, 5], account_number: [10, 11], national_check: [21, 2] }
+      },
+      # Netherlands - 14 chars: 4-letter bank code + 10-digit account
+      'NL' => {
+        length: 14,
+        format: /\A[A-Z]{4}\d{10}\z/,
+        components: { bank_code: [0, 4], account_number: [4, 10] }
+      },
+      # Norway - 11 chars: 4-digit bank code + 6-digit account + 1-digit national check
+      'NO' => {
+        length: 11,
+        format: /\A\d{11}\z/,
+        components: { bank_code: [0, 4], account_number: [4, 6], national_check: [10, 1] }
+      },
+      # Poland - 24 chars: 3-digit bank code + 4-digit branch + 1-digit check + 16-digit account
+      'PL' => {
+        length: 24,
+        format: /\A\d{24}\z/,
+        components: { bank_code: [0, 3], branch_code: [3, 4], national_check: [7, 1], account_number: [8, 16] }
+      },
+      # Portugal - 21 chars: 4-digit bank code + 4-digit branch + 11-digit account + 2-digit national check
+      'PT' => {
+        length: 21,
+        format: /\A\d{21}\z/,
+        components: { bank_code: [0, 4], branch_code: [4, 4], account_number: [8, 11], national_check: [19, 2] }
+      },
+      # Romania - 20 chars: 4-letter bank code + 16-char account
+      'RO' => {
+        length: 20,
+        format: /\A[A-Z]{4}[A-Z0-9]{16}\z/,
+        components: { bank_code: [0, 4], account_number: [4, 16] }
+      },
+      # San Marino - 23 chars: same format as Italy
+      'SM' => {
+        length: 23,
+        format: /\A[A-Z]\d{10}[A-Z0-9]{12}\z/,
+        components: { national_check: [0, 1], bank_code: [1, 5], branch_code: [6, 5], account_number: [11, 12] }
+      },
+      # Slovakia - 20 chars: 4-digit bank code + 16-digit account
+      'SK' => {
+        length: 20,
+        format: /\A\d{20}\z/,
+        components: { bank_code: [0, 4], account_number: [4, 16] }
+      },
+      # Slovenia - 15 chars: 5-digit bank code + 8-digit account + 2-digit national check
+      'SI' => {
+        length: 15,
+        format: /\A\d{15}\z/,
+        components: { bank_code: [0, 5], account_number: [5, 8], national_check: [13, 2] }
+      },
+      # Spain - 20 chars: 4-digit bank code + 4-digit branch + 2-digit national check + 10-digit account
+      'ES' => {
+        length: 20,
+        format: /\A\d{20}\z/,
+        components: { bank_code: [0, 4], branch_code: [4, 4], national_check: [8, 2], account_number: [10, 10] }
+      },
+      # Sweden - 20 chars: 3-digit bank code + 17-digit account
+      'SE' => {
+        length: 20,
+        format: /\A\d{20}\z/,
+        components: { bank_code: [0, 3], account_number: [3, 17] }
+      },
+      # Switzerland - 17 chars: 5-digit bank code + 12-char account
+      'CH' => {
+        length: 17,
+        format: /\A\d{5}[A-Z0-9]{12}\z/,
+        components: { bank_code: [0, 5], account_number: [5, 12] }
+      },
+      # United Kingdom - 18 chars: 4-letter bank code + 6-digit branch (sort code) + 8-digit account
+      'GB' => {
+        length: 18,
+        format: /\A[A-Z]{4}\d{14}\z/,
+        components: { bank_code: [0, 4], branch_code: [4, 6], account_number: [10, 8] }
+      }
+    }.freeze
+
+    # Countries where only length validation is performed (non-EU/EEA countries)
+    # Format: country_code => expected BBAN length
+    LENGTH_ONLY_COUNTRIES = {
+      'AD' => 20, # Andorra
+      'AE' => 19, # UAE
+      'AL' => 24, # Albania
+      'AZ' => 24, # Azerbaijan
+      'BA' => 16, # Bosnia and Herzegovina
+      'BY' => 24, # Belarus
+      'DO' => 24, # Dominican Republic
+      'EG' => 25, # Egypt
+      'GE' => 18, # Georgia
+      'GI' => 19, # Gibraltar
+      'GT' => 24, # Guatemala
+      'IL' => 19, # Israel
+      'IQ' => 19, # Iraq
+      'JO' => 26, # Jordan
+      'KW' => 26, # Kuwait
+      'KZ' => 16, # Kazakhstan
+      'LB' => 24, # Lebanon
+      'LC' => 28, # Saint Lucia
+      'MD' => 20, # Moldova
+      'ME' => 18, # Montenegro
+      'MK' => 15, # North Macedonia
+      'MR' => 23, # Mauritania
+      'MU' => 26, # Mauritius
+      'PS' => 25, # Palestine
+      'QA' => 25, # Qatar
+      'RS' => 18, # Serbia
+      'SA' => 20, # Saudi Arabia
+      'SC' => 27, # Seychelles
+      'ST' => 21, # Sao Tome and Principe
+      'SV' => 24, # El Salvador
+      'TL' => 19, # Timor-Leste
+      'TN' => 20, # Tunisia
+      'TR' => 22, # Turkey
+      'UA' => 25, # Ukraine
+      'VA' => 18, # Vatican City
+      'VG' => 20, # British Virgin Islands
+      'XK' => 16  # Kosovo
+    }.freeze
+  end
+  # rubocop:enable Metrics/ModuleLength
+end

data/lib/sec_id/iban.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require_relative 'iban/country_rules'
+
+module SecId
+  # International Bank Account Number (IBAN) - an international standard for identifying
+  # bank accounts across national borders (ISO 13616).
+  #
+  # Format: 2-letter country code + 2-digit check digits + BBAN (Basic Bank Account Number, 11-30 chars)
+  # Note: Unlike other SecId identifiers, the check digits are in positions 3-4, not at the end.
+  #
+  # @see https://en.wikipedia.org/wiki/International_Bank_Account_Number
+  # @see https://www.iban.com/structure
+  #
+  # @example Validate an IBAN
+  #   SecId::IBAN.valid?('DE89370400440532013000')  #=> true
+  #
+  # @example Restore check digits
+  #   SecId::IBAN.restore!('DE00370400440532013000')  #=> 'DE89370400440532013000'
+  class IBAN < Base
+    include IBANCountryRules
+
+    # Regular expression for parsing IBAN components.
+    # Note: Check digit positioning is handled in initialize, not in the regex.
+    ID_REGEX = /\A
+      (?<country_code>[A-Z]{2})
+      (?<rest>[A-Z0-9]{13,32})
+    \z/x
+
+    # @return [String, nil] the ISO 3166-1 alpha-2 country code
+    attr_reader :country_code
+
+    # @return [String, nil] the Basic Bank Account Number (country-specific format)
+    attr_reader :bban
+
+    # @return [String, nil] the bank code (extracted from BBAN if country rules define it)
+    attr_reader :bank_code
+
+    # @return [String, nil] the branch code (extracted from BBAN if country rules define it)
+    attr_reader :branch_code
+
+    # @return [String, nil] the account number (extracted from BBAN if country rules define it)
+    attr_reader :account_number
+
+    # @return [String, nil] the national check digit (extracted from BBAN if country rules define it)
+    attr_reader :national_check
+
+    # @param iban [String] the IBAN string to parse
+    def initialize(iban)
+      iban_parts = parse(iban)
+      @country_code = iban_parts[:country_code]
+      rest = iban_parts[:rest]
+
+      if @country_code && rest
+        extract_check_digit_and_bban(rest)
+        @identifier = "#{@country_code}#{@bban}" if @bban
+      end
+
+      extract_bban_components if valid_format?
+    end
+
+    # @return [Integer] the calculated 2-digit check value (1-98)
+    # @raise [InvalidFormatError] if the IBAN format is invalid
+    def calculate_check_digit
+      validate_format_for_calculation!
+      mod97(numeric_string_for_check)
+    end
+
+    # @return [Boolean]
+    def valid_format?
+      return false unless identifier
+
+      valid_bban_format?
+    end
+
+    # @return [Boolean]
+    def valid_bban_format?
+      return false unless bban
+
+      rule = country_rule
+      return valid_bban_length_only? unless rule
+
+      bban.length == rule[:length] && bban.match?(rule[:format])
+    end
+
+    # @return [Hash, nil] the validation rule or nil if country is unknown
+    def country_rule
+      COUNTRY_RULES[country_code]
+    end
+
+    # @return [Boolean]
+    def known_country?
+      COUNTRY_RULES.key?(country_code) || LENGTH_ONLY_COUNTRIES.key?(country_code)
+    end
+
+    # @return [String]
+    def to_s
+      return full_number unless check_digit
+
+      "#{country_code}#{check_digit.to_s.rjust(2, '0')}#{bban}"
+    end
+
+    private
+
+    # @param rest [String] the IBAN string after country code
+    # @return [void]
+    def extract_check_digit_and_bban(rest)
+      expected = expected_bban_length_for_country
+
+      if check_digits?(rest, expected)
+        @check_digit = rest[0, 2].to_i
+        @bban = rest[2..]
+      else
+        @check_digit = nil
+        @bban = rest
+      end
+    end
+
+    # @return [Integer, nil] the expected BBAN length or nil if unknown
+    def expected_bban_length_for_country
+      COUNTRY_RULES.dig(country_code, :length) || LENGTH_ONLY_COUNTRIES[country_code]
+    end
+
+    # @param rest [String] the IBAN string after country code
+    # @param expected_bban_length [Integer, nil] the expected BBAN length for the country
+    # @return [Boolean]
+    def check_digits?(rest, expected_bban_length)
+      return false unless rest[0, 2].match?(/\A\d{2}\z/)
+      return true unless expected_bban_length
+
+      # If we know expected BBAN length, check if rest matches with or without check digits
+      rest.length == expected_bban_length + 2 || rest.length != expected_bban_length
+    end
+
+    # @return [void]
+    def extract_bban_components
+      rule = country_rule
+      return unless rule&.key?(:components)
+
+      rule[:components].each do |name, (start, length)|
+        instance_variable_set(:"@#{name}", bban[start, length])
+      end
+    end
+
+    # @return [Boolean]
+    def valid_bban_length_only?
+      expected_length = LENGTH_ONLY_COUNTRIES[country_code]
+      return true unless expected_length
+
+      bban.length == expected_length
+    end
+
+    # @return [String] the numeric string representation
+    def numeric_string_for_check
+      "#{bban}#{country_code}00".each_char.map { |char| char_to_digit(char) }.join
+    end
+  end
+end