sec_id 4.1.0 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3391006ed4c0e135a0e94ef0d43da6aae3146a178f13c6237aec8d940931c52
-  data.tar.gz: a572d9b26de1c8c97476cd954caeefacc9fe44ac8ffff7f25d9b4a72ca058e54
+  metadata.gz: 227ed0f22f9d18523b28c4553fd0ce5765a3367eae8e39017a8ce006d9f161fa
+  data.tar.gz: e46b18732147a27e2cdd0d74728619c4ba10bfd8210982a45d40358ee3f7c06a
 SHA512:
-  metadata.gz: 1d380490f4a25d1044734b7724bf7e752e7dbb43097a468d3210e8fd9f4efd185beac207d9b5adfc5cce0cedfd5ea944be269785f444fd7a4bbb449b63ea9962
-  data.tar.gz: 30434ebe94c7f2c7f3a311ab2a3857af1ae0b66b5993c3b659fd9f6852633171cd7e4ce3c73f7d1e554211cbb53259e1e7679236df243f8dfaf311a0a61cebee
+  metadata.gz: ddca4d991fcacd93520d36b87697a39d8121cbad2c8d70002c4dcc56334a6d8f3d6f58138b34d1ef2eb3f3b2e4eae284e10e1a8a2adb5d10d858aa956d809b94
+  data.tar.gz: 766cc6f3bacd4210c52364e2c5972b0311a2a0d3f9c20c6cac02735a7eb36b9b9a601bd21a01a1e69b0a7346c44079e59bd6ac0ecf377be4e880bee80731e27d

data/CHANGELOG.md

@@ -1,13 +1,56 @@
 # Changelog
 
+## [Unreleased]
+
+## [4.3.0] - 2025-01-13
+
+### Added
+
+- LEI support (Legal Entity Identifier, ISO 17442)
+- IBAN support (International Bank Account Number, ISO 13616) with EU/EEA country validation
+
+### Updated
+
+- Improved README: better formatting, navigation, and clear API distinction between check-digit and normalization identifiers
+
+### Internal
+
+- Refactored CIK and OCC to inherit from Base class with `has_check_digit?` hook for cleaner architecture
+- Added `Normalizable` module for consistent `normalize!` class method across identifiers
+- Added `validate_format_for_calculation!` helper method to Base class to reduce code duplication
+- Added comprehensive YARD documentation to all classes (public and private methods)
+- Applied Stepdown Rule to method ordering throughout codebase
+- Created shared RSpec examples for edge cases (nil, empty, whitespace inputs)
+- Created shared RSpec examples for check-digit and normalization identifiers
+- Applied shared examples to all identifier specs, removing ~350 lines of duplicate test code
+- Improved test maintainability with 582 tests covering all identifier types
+
+## [4.2.0] - 2025-01-12
+
+### Added
+
+- OCC support ([@wtn](https://github.com/wtn), [#93](https://github.com/svyatov/sec_id/pull/93))
+
+### Fixed
+
+- CUSIP#cins? usage example in README ([@wtn](https://github.com/wtn), [#91](https://github.com/svyatov/sec_id/pull/91))
+
+### Updated
+
+- Separate CIK from Base for cleaner architecture ([@wtn](https://github.com/wtn), [#92](https://github.com/svyatov/sec_id/pull/92))
+- Use rubocop-rspec plugin ([@wtn](https://github.com/wtn), [#90](https://github.com/svyatov/sec_id/pull/90))
+- Replace CodeClimate with Codecov
+- Add permissions to CI workflow
+- Clean up gemspec: update description and simplify files list
+
 ## [4.1.0] - 2024-09-23
 
 ### Added
 
-- FIGI support ([@wtn][], #84)
-- CIK support ([@wtn][], #85)
-- Convert between CUSIPs and ISINs ([@wtn][], #86, #88)
-- CINS check method for CUSIPs ([@wtn][], #87)
+- FIGI support ([@wtn](https://github.com/wtn), [#84](https://github.com/svyatov/sec_id/pull/84))
+- CIK support ([@wtn](https://github.com/wtn), [#85](https://github.com/svyatov/sec_id/pull/85))
+- Convert between CUSIPs and ISINs ([@wtn](https://github.com/wtn), [#86](https://github.com/svyatov/sec_id/pull/86), [#88](https://github.com/svyatov/sec_id/pull/88))
+- CINS check method for CUSIPs ([@wtn](https://github.com/wtn), [#87](https://github.com/svyatov/sec_id/pull/87))
 
 ### Updated
 

data/README.md

@@ -1,104 +1,62 @@
-# SecId
-[![Gem Version](https://badge.fury.io/rb/sec_id.svg)](https://badge.fury.io/rb/sec_id)
-![Build Status](https://github.com/svyatov/sec_id/actions/workflows/main.yml/badge.svg?branch=main)
-[![Maintainability](https://api.codeclimate.com/v1/badges/a4759963a5ddc4d55b24/maintainability)](https://codeclimate.com/github/svyatov/sec_id/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/a4759963a5ddc4d55b24/test_coverage)](https://codeclimate.com/github/svyatov/sec_id/test_coverage)
+# SecId [![Gem Version](https://img.shields.io/gem/v/sec_id)](https://rubygems.org/gems/sec_id) [![Codecov](https://img.shields.io/codecov/c/github/svyatov/sec_id)](https://app.codecov.io/gh/svyatov/sec_id) [![CI](https://github.com/svyatov/sec_id/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/svyatov/sec_id/actions?query=workflow%3ACI) [![License](https://img.shields.io/github/license/svyatov/sec_id)](LICENSE.txt)
 
-Validate securities identification numbers with ease!
+> Validate securities identification numbers with ease!
 
-Check-digit calculation is also available.
+## Table of Contents
 
-Currently supported standards:
-[ISIN](https://en.wikipedia.org/wiki/International_Securities_Identification_Number),
-[CUSIP](https://en.wikipedia.org/wiki/CUSIP),
-[SEDOL](https://en.wikipedia.org/wiki/SEDOL),
-[FIGI](https://en.wikipedia.org/wiki/Financial_Instrument_Global_Identifier),
-[CIK](https://en.wikipedia.org/wiki/Central_Index_Key).
+- [Supported Ruby Versions](#supported-ruby-versions)
+- [Installation](#installation)
+- [Supported Standards and Usage](#supported-standards-and-usage)
+  - [ISIN](#isin) - International Securities Identification Number
+  - [CUSIP](#cusip) - Committee on Uniform Securities Identification Procedures
+  - [SEDOL](#sedol) - Stock Exchange Daily Official List
+  - [FIGI](#figi) - Financial Instrument Global Identifier
+  - [LEI](#lei) - Legal Entity Identifier
+  - [IBAN](#iban) - International Bank Account Number
+  - [CIK](#cik) - Central Index Key
+  - [OCC](#occ) - Options Clearing Corporation Symbol
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
 
-Work in progress:
-[IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).
+## Supported Ruby Versions
+
+Ruby 3.1+ is required.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'sec_id', '~> 4.1'
+gem 'sec_id', '~> 4.3'
 ```
 
 And then execute:
 
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install sec_id
-
-## Usage
-
-### Base API
-
-Base API has 4 main methods which can be used both on class level and on instance level:
-
-* `valid?` - never raises any errors, always returns `true` or `false`,
-  numbers without the check-digit will return `false`
-
-  ```ruby
-  # class level
-  SecId::ISIN.valid?('US5949181045') # => true
-  SecId::ISIN.valid?('US594918104')  # => false
-
-  # instance level
-  isin = SecId::ISIN.new('US5949181045')
-  isin.valid? # => true
-  ```
-
-* `valid_format?` - never raises any errors, always returns `true` or `false`,
-  numbers without the check-digit but in valid format will return `true`
-
-  ```ruby
-  # class level
-  SecId::ISIN.valid_format?('US5949181045') # => true
-  SecId::ISIN.valid_format?('US594918104') # => true
-
-  # instance level
-  isin = SecId::ISIN.new('US594918104')
-  isin.valid_format? # => true
-  ```
+```bash
+bundle install
+```
 
-* `restore!` - restores check-digit and returns the full number,
-  raises an error if number's format is invalid and thus check-digit is impossible to calculate
+Or install it yourself:
 
-  ```ruby
-  # class level
-  SecId::ISIN.restore!('US594918104') # => 'US5949181045'
+```bash
+gem install sec_id
+```
 
-  # instance level
-  isin = SecId::ISIN.new('US5949181045')
-  isin.restore! # => 'US5949181045'
-  ```
+## Supported Standards and Usage
 
-* `check_digit` and `calculate_check_digit` - these are the same,
-  but the former is used at class level for bravity,
-  and the latter is used at instance level for clarity;
-  it calculates and returns the check-digit if the number is valid
-  and raises an error otherwise.
+All identifier classes provide `valid?` and `valid_format?` methods at both class and instance levels.
 
-  ```ruby
-  # class level
-  SecId::ISIN.check_digit('US594918104') # => 5
+**Check-digit based identifiers** (ISIN, CUSIP, SEDOL, FIGI, LEI, IBAN) also provide:
+- `restore!` - restores check-digit and returns the full number
+- `check_digit` / `calculate_check_digit` - calculates and returns the check-digit
 
-  # instance level
-  isin = SecId::ISIN.new('US594918104')
-  isin.calculate_check_digit # => 5
-  isin.check_digit # => nil
-  ```
+**Normalization based identifiers** (CIK, OCC) provide instead:
+- `normalize!` - pads/formats the identifier to its standard form
 
-  :exclamation: Please note that `isin.check_digit` returns `nil` because `#check_digit`
-  at instance level represents original check-digit of the number passed to `new`,
-  which in this example is missing and thus it's `nil`.
+### ISIN
 
-### SecId::ISIN full example
+> [International Securities Identification Number](https://en.wikipedia.org/wiki/International_Securities_Identification_Number) - a 12-character alphanumeric code that uniquely identifies a security.
 
 ```ruby
 # class level
@@ -120,14 +78,16 @@ isin.calculate_check_digit # => 5
 isin.to_cusip              # => #<SecId::CUSIP>
 ```
 
-### SecId::CUSIP full example
+### CUSIP
+
+> [Committee on Uniform Securities Identification Procedures](https://en.wikipedia.org/wiki/CUSIP) - a 9-character alphanumeric code that identifies North American securities.
 
 ```ruby
 # class level
 SecId::CUSIP.valid?('594918104')       # => true
 SecId::CUSIP.valid_format?('59491810') # => true
 SecId::CUSIP.restore!('59491810')      # => '594918104'
-SecId::CUSIP.check_digit('59491810')   # => 5
+SecId::CUSIP.check_digit('59491810')   # => 4
 
 # instance level
 cusip = SecId::CUSIP.new('594918104')
@@ -140,10 +100,12 @@ cusip.valid_format?         # => true
 cusip.restore!              # => '594918104'
 cusip.calculate_check_digit # => 4
 cusip.to_isin('US')         # => #<SecId::ISIN>
-cusip.cins?                 # => true
+cusip.cins?                 # => false
 ```
 
-### SecId::SEDOL full example
+### SEDOL
+
+> [Stock Exchange Daily Official List](https://en.wikipedia.org/wiki/SEDOL) - a 7-character alphanumeric code used in the United Kingdom and Ireland.
 
 ```ruby
 # class level
@@ -153,16 +115,18 @@ SecId::SEDOL.restore!('B0Z52W')      # => 'B0Z52W5'
 SecId::SEDOL.check_digit('B0Z52W')   # => 5
 
 # instance level
-cusip = SecId::SEDOL.new('B0Z52W5')
-cusip.full_number           # => 'B0Z52W5'
-cusip.check_digit           # => 5
-cusip.valid?                # => true
-cusip.valid_format?         # => true
-cusip.restore!              # => 'B0Z52W5'
-cusip.calculate_check_digit # => 5
+sedol = SecId::SEDOL.new('B0Z52W5')
+sedol.full_number           # => 'B0Z52W5'
+sedol.check_digit           # => 5
+sedol.valid?                # => true
+sedol.valid_format?         # => true
+sedol.restore!              # => 'B0Z52W5'
+sedol.calculate_check_digit # => 5
 ```
 
-### SecId::FIGI full example
+### FIGI
+
+> [Financial Instrument Global Identifier](https://en.wikipedia.org/wiki/Financial_Instrument_Global_Identifier) - a 12-character alphanumeric code that provides unique identification of financial instruments.
 
 ```ruby
 # class level
@@ -183,25 +147,116 @@ figi.restore!              # => 'BBG000DMBXR2'
 figi.calculate_check_digit # => 2
 ```
 
-### SecId::CIK full example
+### LEI
+
+> [Legal Entity Identifier](https://en.wikipedia.org/wiki/Legal_Entity_Identifier) - a 20-character alphanumeric code that uniquely identifies legal entities participating in financial transactions.
+
+```ruby
+# class level
+SecId::LEI.valid?('5493006MHB84DD0ZWV18')       # => true
+SecId::LEI.valid_format?('5493006MHB84DD0ZWV')  # => true
+SecId::LEI.restore!('5493006MHB84DD0ZWV')       # => '5493006MHB84DD0ZWV18'
+SecId::LEI.check_digit('5493006MHB84DD0ZWV')    # => 18
+
+# instance level
+lei = SecId::LEI.new('5493006MHB84DD0ZWV18')
+lei.full_number           # => '5493006MHB84DD0ZWV18'
+lei.lou_id                # => '5493'
+lei.reserved              # => '00'
+lei.entity_id             # => '6MHB84DD0ZWV'
+lei.check_digit           # => 18
+lei.valid?                # => true
+lei.valid_format?         # => true
+lei.restore!              # => '5493006MHB84DD0ZWV18'
+lei.calculate_check_digit # => 18
+```
+
+### IBAN
+
+> [International Bank Account Number](https://en.wikipedia.org/wiki/International_Bank_Account_Number) - an internationally standardized system for identifying bank accounts across national borders (ISO 13616).
+
+```ruby
+# class level
+SecId::IBAN.valid?('DE89370400440532013000')       # => true
+SecId::IBAN.valid_format?('DE370400440532013000')  # => true
+SecId::IBAN.restore!('DE370400440532013000')       # => 'DE89370400440532013000'
+SecId::IBAN.check_digit('DE370400440532013000')    # => 89
+
+# instance level
+iban = SecId::IBAN.new('DE89370400440532013000')
+iban.full_number           # => 'DE89370400440532013000'
+iban.country_code          # => 'DE'
+iban.bban                  # => '370400440532013000'
+iban.bank_code             # => '37040044'
+iban.account_number        # => '0532013000'
+iban.check_digit           # => 89
+iban.valid?                # => true
+iban.valid_format?         # => true
+iban.restore!              # => 'DE89370400440532013000'
+iban.calculate_check_digit # => 89
+iban.known_country?        # => true
+```
+
+Full BBAN structural validation is supported for EU/EEA countries. Other countries have length-only validation.
+
+### CIK
+
+> [Central Index Key](https://en.wikipedia.org/wiki/Central_Index_Key) - a 10-digit number used by the SEC to identify corporations and individuals who have filed disclosures.
 
 ```ruby
 # class level
 SecId::CIK.valid?('0001094517')        # => true
 SecId::CIK.valid_format?('0001094517') # => true
-SecId::CIK.restore!('1094517')         # => '0001094517'
-SecId::CIK.check_digit('0001094517')   # raises NotImplementedError
+SecId::CIK.normalize!('1094517')       # => '0001094517'
 
 # instance level
 cik = SecId::CIK.new('0001094517')
-cik.full_number           # => '0001094517'
-cik.padding               # => '000'
-cik.identifier            # => '1094517'
-cik.valid?                # => true
-cik.valid_format?         # => true
-cik.restore!              # => '0001094517'
-cik.calculate_check_digit # raises NotImplementedError
-cik.check_digit           # => nil
+cik.full_number   # => '0001094517'
+cik.padding       # => '000'
+cik.identifier    # => '1094517'
+cik.valid?        # => true
+cik.valid_format? # => true
+cik.normalize!    # => '0001094517'
+cik.to_s          # => '0001094517'
+```
+
+### OCC
+
+> [Options Clearing Corporation Symbol](https://en.wikipedia.org/wiki/Option_symbol#The_OCC_Option_Symbol) - a 21-character code used to identify equity options contracts.
+
+```ruby
+# class level
+SecId::OCC.valid?('BRKB  100417C00090000')        # => true
+SecId::OCC.valid_format?('BRKB  100417C00090000') # => true
+SecId::OCC.normalize!('BRKB100417C00090000')      # => 'BRKB  100417C00090000'
+SecId::OCC.build(
+  underlying: 'BRKB',
+  date: Date.new(2010, 4, 17),
+  type: 'C',
+  strike: 90,
+)                                                 # => #<SecId::OCC>
+
+# instance level
+occ = SecId::OCC.new('BRKB  100417C00090000')
+occ.full_symbol   # => 'BRKB  100417C00090000'
+occ.underlying    # => 'BRKB'
+occ.date_str      # => '100417'
+occ.date_obj      # => #<Date: 2010-04-17>
+occ.type          # => 'C'
+occ.strike        # => 90.0
+occ.valid?        # => true
+occ.valid_format? # => true
+occ.normalize!    # => 'BRKB  100417C00090000'
+
+occ = SecId::OCC.new('BRKB 2010-04-17C00090000')
+occ.valid_format? # => false
+occ.normalize!    # raises SecId::InvalidFormatError
+
+occ = SecId::OCC.new('X 250620C00050000')
+occ.full_symbol   # => 'X 250620C00050000'
+occ.valid?        # => true
+occ.normalize!    # => 'X     250620C00050000'
+occ.full_symbol   # => 'X     250620C00050000'
 ```
 
 ## Development

data/lib/sec_id/base.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module SecId
+  # Character-to-digit mapping for Luhn algorithm variants.
+  # Maps alphanumeric characters to digit arrays for multi-digit expansion.
+  # Used by ISIN for check-digit calculation.
   CHAR_TO_DIGITS = {
     '0' => 0,      '1' => 1,      '2' => 2,      '3' => 3,      '4' => 4,
     '5' => 5,      '6' => 6,      '7' => 7,      '8' => 8,      '9' => 9,
@@ -12,6 +15,9 @@ module SecId
     '*' => [3, 6], '@' => [3, 7], '#' => [3, 8]
   }.freeze
 
+  # Character-to-digit mapping for single-digit conversion.
+  # Maps alphanumeric characters to values 0-38 (A=10, B=11, ..., Z=35, *=36, @=37, #=38).
+  # Used by CUSIP, FIGI, SEDOL, LEI, and IBAN for check-digit calculations.
   CHAR_TO_DIGIT = {
     '0' => 0,  '1' => 1,  '2' => 2,  '3' => 3,  '4' =>  4,
     '5' => 5,  '6' => 6,  '7' => 7,  '8' => 8,  '9' =>  9,
@@ -23,50 +29,128 @@ module SecId
     '*' => 36, '@' => 37, '#' => 38
   }.freeze
 
+  # Base class for securities identifiers that provides a common interface
+  # for validation, check-digit calculation, and parsing.
+  #
+  # Subclasses must implement:
+  # - ID_REGEX constant with named capture groups for parsing
+  # - initialize method that calls parse and extracts components
+  # - calculate_check_digit method (only if has_check_digit? returns true)
+  #
+  # Subclasses may override:
+  # - has_check_digit? to return false for identifiers without check digits (e.g., CIK, OCC)
+  # - valid_format? for additional format validation beyond regex matching
+  # - to_s for custom string representation
+  #
+  # @example Implementing a check-digit identifier
+  #   class MyIdentifier < Base
+  #     ID_REGEX = /\A(?<identifier>[A-Z]{6})(?<check_digit>\d)?\z/x
+  #
+  #     def initialize(id)
+  #       parts = parse(id)
+  #       @identifier = parts[:identifier]
+  #       @check_digit = parts[:check_digit]&.to_i
+  #     end
+  #
+  #     def calculate_check_digit
+  #       validate_format_for_calculation!
+  #       mod10(some_algorithm)
+  #     end
+  #   end
+  #
+  # @example Implementing a non-check-digit identifier
+  #   class SimpleId < Base
+  #     def has_check_digit?
+  #       false
+  #     end
+  #   end
   class Base
-    attr_reader :full_number, :identifier, :check_digit
+    # @return [String] the original input after normalization (stripped and uppercased)
+    attr_reader :full_number
+
+    # @return [String, nil] the main identifier portion (without check digit)
+    attr_reader :identifier
+
+    # @return [Integer, nil] the check digit value
+    attr_reader :check_digit
 
     class << self
+      # @param id [String] the identifier to validate
+      # @return [Boolean]
       def valid?(id)
         new(id).valid?
       end
 
+      # @param id [String] the identifier to check
+      # @return [Boolean]
       def valid_format?(id)
         new(id).valid_format?
       end
 
+      # Restores (calculates) the check digit and returns the full identifier.
+      #
+      # @param id_without_check_digit [String] identifier without or with incorrect check digit
+      # @return [String] the full identifier with correct check digit
+      # @raise [InvalidFormatError] if the identifier format is invalid
       def restore!(id_without_check_digit)
         new(id_without_check_digit).restore!
       end
 
+      # @param id [String] the identifier to calculate check digit for
+      # @return [Integer] the calculated check digit
+      # @raise [InvalidFormatError] if the identifier format is invalid
       def check_digit(id)
         new(id).calculate_check_digit
       end
     end
 
+    # Subclasses must override this method.
+    #
+    # @param _sec_id_number [String] the identifier string to parse
+    # @raise [NotImplementedError] always raised in base class
     def initialize(_sec_id_number)
       raise NotImplementedError
     end
 
+    # Override in subclasses to return false for identifiers without check digits.
+    #
+    # @return [Boolean]
+    def has_check_digit?
+      true
+    end
+
+    # @return [Boolean]
     def valid?
+      return valid_format? unless has_check_digit?
       return false unless valid_format?
 
       check_digit == calculate_check_digit
     end
 
+    # Override in subclasses for additional format validation.
+    #
+    # @return [Boolean]
     def valid_format?
-      identifier ? true : false
+      !identifier.nil?
     end
 
+    # @return [String] the full identifier with correct check digit
+    # @raise [InvalidFormatError] if the identifier format is invalid
     def restore!
       @check_digit = calculate_check_digit
       @full_number = to_s
     end
 
+    # Subclasses must override this method.
+    #
+    # @return [Integer] the calculated check digit
+    # @raise [NotImplementedError] always raised in base class
+    # @raise [InvalidFormatError] if the identifier format is invalid (in subclasses)
     def calculate_check_digit
       raise NotImplementedError
     end
 
+    # @return [String]
     def to_s
       "#{identifier}#{check_digit}"
     end
@@ -74,29 +158,57 @@ module SecId
 
     private
 
-    def id_digits
-      raise NotImplementedError
+    # @raise [InvalidFormatError] if valid_format? returns false
+    # @return [void]
+    def validate_format_for_calculation!
+      return if valid_format?
+
+      raise InvalidFormatError, "#{self.class.name} '#{full_number}' is invalid and check-digit cannot be calculated!"
     end
 
-    def parse(sec_id_number)
-      @full_number = sec_id_number.to_s.strip.upcase
+    # @param sec_id_number [String, #to_s] the identifier to parse
+    # @param upcase [Boolean] whether to upcase the input
+    # @return [MatchData, Hash] the regex match data or empty hash if no match
+    def parse(sec_id_number, upcase: true)
+      @full_number = sec_id_number.to_s.strip
+      @full_number.upcase! if upcase
       @full_number.match(self.class::ID_REGEX) || {}
     end
 
+    # @return [Array<Integer>] array of digit values
+    # @raise [NotImplementedError] always raised in base class
+    def id_digits
+      raise NotImplementedError
+    end
+
+    # @param char [String] single character to convert
+    # @return [Integer, Array<Integer>] single digit or array of digits
     def char_to_digits(char)
       SecId::CHAR_TO_DIGITS.fetch(char)
     end
 
+    # @param char [String] single character to convert
+    # @return [Integer] numeric value (0-38)
     def char_to_digit(char)
       SecId::CHAR_TO_DIGIT.fetch(char)
     end
 
+    # @param sum [Integer] the sum to calculate check digit from
+    # @return [Integer] check digit (0-9)
     def mod10(sum)
       (10 - (sum % 10)) % 10
     end
 
+    # @param number [Integer] number to split
+    # @return [Integer] sum of tens and units digits
     def div10mod10(number)
       (number / 10) + (number % 10)
     end
+
+    # @param numeric_string [String] numeric string representation
+    # @return [Integer] check digit value (1-98)
+    def mod97(numeric_string)
+      98 - (numeric_string.to_i % 97)
+    end
   end
 end