sec_id 4.3.0 → 4.4.0

data/lib/sec_id/cfi.rb

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+
+module SecId
+  # Classification of Financial Instruments (CFI) - a 6-character alphabetic code
+  # that classifies financial instruments per ISO 10962.
+  #
+  # Format: 6 uppercase letters A-Z
+  # - Position 1: Category code (14 valid values)
+  # - Position 2: Group code (varies by category)
+  # - Positions 3-6: Attribute codes (A-Z, with X meaning "not applicable")
+  #
+  # @see https://en.wikipedia.org/wiki/ISO_10962
+  #
+  # @example Validate a CFI code
+  #   SecId::CFI.valid?('ESXXXX')  #=> true
+  #   SecId::CFI.valid?('ESVUFR')  #=> true
+  #
+  # @example Access CFI components
+  #   cfi = SecId::CFI.new('ESVUFR')
+  #   cfi.category        #=> :equity
+  #   cfi.group           #=> :common_shares
+  #   cfi.voting?         #=> true
+  class CFI < Base
+    # Regular expression for parsing CFI components.
+    ID_REGEX = /\A
+      (?<identifier>
+        (?<category_code>[A-Z])
+        (?<group_code>[A-Z])
+        (?<attr1>[A-Z])
+        (?<attr2>[A-Z])
+        (?<attr3>[A-Z])
+        (?<attr4>[A-Z]))
+    \z/x
+
+    # Category codes per ISO 10962.
+    CATEGORIES = {
+      'E' => :equity,
+      'C' => :collective_investment_vehicles,
+      'D' => :debt_instruments,
+      'R' => :entitlements,
+      'O' => :listed_options,
+      'F' => :futures,
+      'S' => :swaps,
+      'H' => :non_listed_options,
+      'I' => :spot,
+      'J' => :forwards,
+      'K' => :strategies,
+      'L' => :financing,
+      'T' => :referential_instruments,
+      'M' => :miscellaneous
+    }.freeze
+
+    # Group codes per category per ISO 10962.
+    GROUPS = {
+      'E' => { # Equity
+        'S' => :common_shares,
+        'P' => :preferred_shares,
+        'C' => :convertible_common_shares,
+        'F' => :convertible_preferred_shares,
+        'L' => :limited_partnership_units,
+        'D' => :depositary_receipts,
+        'Y' => :structured_instruments,
+        'M' => :miscellaneous
+      },
+      'C' => { # Collective Investment Vehicles
+        'I' => :standard_investment_funds,
+        'H' => :hedge_funds,
+        'B' => :real_estate_investment_trusts,
+        'E' => :exchange_traded_funds,
+        'S' => :pension_funds,
+        'F' => :funds_of_funds,
+        'P' => :private_equity_funds,
+        'M' => :miscellaneous
+      },
+      'D' => { # Debt Instruments
+        'B' => :bonds,
+        'C' => :convertible_bonds,
+        'W' => :bonds_with_warrants,
+        'T' => :medium_term_notes,
+        'Y' => :money_market_instruments,
+        'S' => :structured_instruments,
+        'E' => :mortgage_backed_securities,
+        'G' => :asset_backed_securities,
+        'A' => :municipal_bonds,
+        'N' => :municipal_notes,
+        'D' => :depositary_receipts,
+        'M' => :miscellaneous
+      },
+      'R' => { # Entitlements (Rights)
+        'A' => :allotment_rights,
+        'S' => :subscription_rights,
+        'P' => :purchase_rights,
+        'W' => :warrants,
+        'F' => :mini_future_certificates,
+        'D' => :depositary_receipts,
+        'M' => :miscellaneous
+      },
+      'O' => { # Listed Options
+        'C' => :call_options,
+        'P' => :put_options,
+        'M' => :miscellaneous
+      },
+      'F' => { # Futures
+        'F' => :financial_futures,
+        'C' => :commodities_futures,
+        'M' => :miscellaneous
+      },
+      'S' => { # Swaps
+        'R' => :rates,
+        'T' => :commodities,
+        'E' => :equity,
+        'C' => :credit,
+        'F' => :foreign_exchange,
+        'M' => :miscellaneous
+      },
+      'H' => { # Non-Listed (Complex) Options
+        'C' => :call_options,
+        'P' => :put_options,
+        'M' => :miscellaneous
+      },
+      'I' => { # Spot
+        'F' => :foreign_exchange,
+        'T' => :commodities,
+        'M' => :miscellaneous
+      },
+      'J' => { # Forwards
+        'F' => :foreign_exchange,
+        'R' => :rates,
+        'T' => :commodities,
+        'E' => :equity,
+        'C' => :credit,
+        'M' => :miscellaneous
+      },
+      'K' => { # Strategies
+        'R' => :rates,
+        'T' => :commodities,
+        'E' => :equity,
+        'C' => :credit,
+        'F' => :foreign_exchange,
+        'Y' => :mixed,
+        'M' => :miscellaneous
+      },
+      'L' => { # Financing
+        'S' => :loan_lease,
+        'R' => :repurchase_agreements,
+        'P' => :securities_lending,
+        'M' => :miscellaneous
+      },
+      'T' => { # Referential Instruments
+        'I' => :currencies,
+        'C' => :commodities,
+        'R' => :interest_rates,
+        'N' => :indices,
+        'B' => :baskets,
+        'D' => :stock_dividends,
+        'M' => :miscellaneous
+      },
+      'M' => { # Miscellaneous
+        'C' => :combined_instruments,
+        'M' => :miscellaneous
+      }
+    }.freeze
+
+    # @return [String, nil] the category code (position 1)
+    attr_reader :category_code
+
+    # @return [String, nil] the group code (position 2)
+    attr_reader :group_code
+
+    # @return [String, nil] attribute 1 (position 3)
+    attr_reader :attr1
+
+    # @return [String, nil] attribute 2 (position 4)
+    attr_reader :attr2
+
+    # @return [String, nil] attribute 3 (position 5)
+    attr_reader :attr3
+
+    # @return [String, nil] attribute 4 (position 6)
+    attr_reader :attr4
+
+    # @param cfi [String] the CFI string to parse
+    def initialize(cfi)
+      cfi_parts = parse(cfi)
+      @identifier = cfi_parts[:identifier]
+      @category_code = cfi_parts[:category_code]
+      @group_code = cfi_parts[:group_code]
+      @attr1 = cfi_parts[:attr1]
+      @attr2 = cfi_parts[:attr2]
+      @attr3 = cfi_parts[:attr3]
+      @attr4 = cfi_parts[:attr4]
+    end
+
+    # Validates format including category and group codes.
+    #
+    # @return [Boolean]
+    def valid_format?
+      super && valid_category? && valid_group?
+    end
+
+    # Returns the semantic category name.
+    #
+    # @return [Symbol, nil] category symbol or nil if invalid
+    def category
+      CATEGORIES[category_code]
+    end
+
+    # Returns the semantic group name.
+    #
+    # @return [Symbol, nil] group symbol or nil if invalid
+    def group
+      GROUPS.dig(category_code, group_code)
+    end
+
+    # @return [Boolean] true if category is equity
+    def equity?
+      category_code == 'E'
+    end
+
+    # Voting rights (position 3 = V). Only meaningful for equity.
+    #
+    # @return [Boolean]
+    def voting?
+      equity? && attr1 == 'V'
+    end
+
+    # Non-voting (position 3 = N). Only meaningful for equity.
+    #
+    # @return [Boolean]
+    def non_voting?
+      equity? && attr1 == 'N'
+    end
+
+    # Restricted voting (position 3 = R). Only meaningful for equity.
+    #
+    # @return [Boolean]
+    def restricted_voting?
+      equity? && attr1 == 'R'
+    end
+
+    # Enhanced voting (position 3 = E). Only meaningful for equity.
+    #
+    # @return [Boolean]
+    def enhanced_voting?
+      equity? && attr1 == 'E'
+    end
+
+    # Ownership restrictions exist (position 4 = T). Only meaningful for equity.
+    #
+    # @return [Boolean]
+    def restrictions?
+      equity? && attr2 == 'T'
+    end
+
+    # No ownership restrictions (position 4 = U). Only meaningful for equity.
+    #
+    # @return [Boolean]
+    def no_restrictions?
+      equity? && attr2 == 'U'
+    end
+
+    # Fully paid shares (position 5 = F). Only meaningful for equity.
+    #
+    # @return [Boolean]
+    def fully_paid?
+      equity? && attr3 == 'F'
+    end
+
+    # Nil paid shares (position 5 = O). Only meaningful for equity.
+    #
+    # @return [Boolean]
+    def nil_paid?
+      equity? && attr3 == 'O'
+    end
+
+    # Partly paid shares (position 5 = P). Only meaningful for equity.
+    #
+    # @return [Boolean]
+    def partly_paid?
+      equity? && attr3 == 'P'
+    end
+
+    # Bearer form (position 6 = B). Only meaningful for equity.
+    #
+    # @return [Boolean]
+    def bearer?
+      equity? && attr4 == 'B'
+    end
+
+    # Registered form (position 6 = R). Only meaningful for equity.
+    #
+    # @return [Boolean]
+    def registered?
+      equity? && attr4 == 'R'
+    end
+
+    # @return [String]
+    def to_s
+      identifier.to_s
+    end
+
+    private
+
+    # @return [Boolean]
+    def valid_category?
+      CATEGORIES.key?(category_code)
+    end
+
+    # @return [Boolean]
+    def valid_group?
+      GROUPS.dig(category_code, group_code) != nil
+    end
+  end
+end

data/lib/sec_id/cik.rb

@@ -31,12 +31,6 @@ module SecId
       cik_parts = parse(cik)
       @padding = cik_parts[:padding]
       @identifier = cik_parts[:identifier]
-      @check_digit = nil
-    end
-
-    # @return [Boolean] always false
-    def has_check_digit?
-      false
     end
 
     # Normalizes the CIK to a 10-digit zero-padded format.

data/lib/sec_id/concerns/checkable.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module SecId
+  # Provides check-digit validation and calculation for securities identifiers.
+  # Include this module in classes that have a check digit as part of their format.
+  #
+  # Including classes must implement:
+  # - `calculate_check_digit` method that returns the calculated check digit value
+  #
+  # This module provides:
+  # - Character-to-digit mapping constants
+  # - Luhn algorithm variants for check-digit calculation
+  # - `valid?` override that validates the check digit
+  # - `restore!` method to calculate and set the check digit
+  # - `check_digit` attribute
+  # - Class-level convenience methods: `restore!`, `check_digit`
+  #
+  # @example Including in an identifier class
+  #   class MyIdentifier < Base
+  #     include Checkable
+  #
+  #     def calculate_check_digit
+  #       validate_format_for_calculation!
+  #       mod10(luhn_sum_standard(reversed_digits_multi(identifier)))
+  #     end
+  #   end
+  #
+  # @see https://en.wikipedia.org/wiki/Luhn_algorithm
+  module Checkable
+    # 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,
+      'A' => [1, 0], 'B' => [1, 1], 'C' => [1, 2], 'D' => [1, 3], 'E' => [1, 4],
+      'F' => [1, 5], 'G' => [1, 6], 'H' => [1, 7], 'I' => [1, 8], 'J' => [1, 9],
+      'K' => [2, 0], 'L' => [2, 1], 'M' => [2, 2], 'N' => [2, 3], 'O' => [2, 4],
+      'P' => [2, 5], 'Q' => [2, 6], 'R' => [2, 7], 'S' => [2, 8], 'T' => [2, 9],
+      'U' => [3, 0], 'V' => [3, 1], 'W' => [3, 2], 'X' => [3, 3], 'Y' => [3, 4], 'Z' => [3, 5],
+      '*' => [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,
+      'A' => 10, 'B' => 11, 'C' => 12, 'D' => 13, 'E' => 14,
+      'F' => 15, 'G' => 16, 'H' => 17, 'I' => 18, 'J' => 19,
+      'K' => 20, 'L' => 21, 'M' => 22, 'N' => 23, 'O' => 24,
+      'P' => 25, 'Q' => 26, 'R' => 27, 'S' => 28, 'T' => 29,
+      'U' => 30, 'V' => 31, 'W' => 32, 'X' => 33, 'Y' => 34, 'Z' => 35,
+      '*' => 36, '@' => 37, '#' => 38
+    }.freeze
+
+    # @api private
+    def self.included(base)
+      base.attr_reader :check_digit
+      base.extend(ClassMethods)
+    end
+
+    # Class methods added when Checkable is included.
+    module ClassMethods
+      # 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
+
+    # Validates format and check digit.
+    #
+    # @return [Boolean]
+    def valid?
+      return false unless valid_format?
+
+      check_digit == calculate_check_digit
+    end
+
+    # Calculates and sets the check digit, updating full_number.
+    #
+    # @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 to implement their check-digit algorithm.
+    #
+    # @return [Integer] the calculated check digit
+    # @raise [NotImplementedError] if subclass doesn't implement
+    # @raise [InvalidFormatError] if the identifier format is invalid
+    def calculate_check_digit
+      raise NotImplementedError
+    end
+
+    # @return [String]
+    def to_s
+      "#{identifier}#{check_digit}"
+    end
+    alias to_str to_s
+
+    # CUSIP/CEI style: "Double Add Double" algorithm.
+    # Processes pairs of digits, doubling the first (even-positioned from right),
+    # then summing both digit's div10mod10 values.
+    #
+    # @param digits [Array<Integer>] reversed array of digit values
+    # @return [Integer] the Luhn sum
+    def luhn_sum_double_add_double(digits)
+      digits.each_slice(2).reduce(0) do |sum, (even, odd)|
+        double_even = (even || 0) * 2
+        sum + div10mod10(double_even) + div10mod10(odd || 0)
+      end
+    end
+
+    # FIGI style: index-based doubling algorithm.
+    # Doubles odd-indexed digits (from right), then sums div10mod10 values.
+    #
+    # @param digits [Array<Integer>] reversed array of digit values
+    # @return [Integer] the Luhn sum
+    def luhn_sum_indexed(digits)
+      digits.each_with_index.reduce(0) do |sum, (digit, index)|
+        digit *= 2 if index.odd?
+        sum + div10mod10(digit)
+      end
+    end
+
+    # ISIN style: standard Luhn with subtract-9 for values > 9.
+    # Processes pairs of digits, doubling the first (even-positioned from right),
+    # subtracting 9 if result > 9.
+    #
+    # @param digits [Array<Integer>] reversed array of digit values
+    # @return [Integer] the Luhn sum
+    def luhn_sum_standard(digits)
+      digits.each_slice(2).reduce(0) do |sum, (even, odd)|
+        double_even = (even || 0) * 2
+        double_even -= 9 if double_even > 9
+        sum + double_even + (odd || 0)
+      end
+    end
+
+    # Converts identifier characters to reversed digit array using single-digit mapping.
+    # Used by CUSIP, CEI, FIGI, and SEDOL.
+    #
+    # @param id [String] the identifier string
+    # @return [Array<Integer>] reversed array of digit values
+    def reversed_digits_single(id)
+      id.each_char.map { |c| CHAR_TO_DIGIT.fetch(c) }.reverse!
+    end
+
+    # Converts identifier characters to reversed digit array using multi-digit mapping.
+    # Used by ISIN where letters expand to two digits.
+    #
+    # @param id [String] the identifier string
+    # @return [Array<Integer>] reversed array of digit values
+    def reversed_digits_multi(id)
+      id.each_char.flat_map { |c| CHAR_TO_DIGITS.fetch(c) }.reverse!
+    end
+
+    private
+
+    # @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
+
+    # @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

data/lib/sec_id/cusip.rb

@@ -15,6 +15,8 @@ module SecId
   #   cusip = SecId::CUSIP.new('037833100')
   #   cusip.to_isin('US')  #=> #<SecId::ISIN>
   class CUSIP < Base
+    include Checkable
+
     # Regular expression for parsing CUSIP components.
     ID_REGEX = /\A
       (?<identifier>
@@ -42,7 +44,7 @@ module SecId
     # @raise [InvalidFormatError] if the CUSIP format is invalid
     def calculate_check_digit
       validate_format_for_calculation!
-      mod10(modified_luhn_sum)
+      mod10(luhn_sum_double_add_double(reversed_digits_single(identifier)))
     end
 
     # @param country_code [String] the ISO 3166-1 alpha-2 country code (must be CGS country)
@@ -63,21 +65,5 @@ module SecId
     def cins?
       cusip6[0] < '0' || cusip6[0] > '9'
     end
-
-    private
-
-    # @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
-        sum + div10mod10(double_even) + div10mod10(odd || 0)
-      end
-    end
-
-    # @return [Array<Integer>] the reversed digit array
-    def reversed_id_digits
-      identifier.each_char.map(&method(:char_to_digit)).reverse!
-    end
   end
 end

data/lib/sec_id/figi.rb

@@ -17,6 +17,8 @@ module SecId
   # @example Restore check digit
   #   SecId::FIGI.restore!('BBG000BLNQ1')  #=> 'BBG000BLNQ16'
   class FIGI < Base
+    include Checkable
+
     # Regular expression for parsing FIGI components.
     # The third character must be 'G'. Excludes vowels from valid characters.
     ID_REGEX = /\A
@@ -54,24 +56,7 @@ module SecId
     # @raise [InvalidFormatError] if the FIGI format is invalid
     def calculate_check_digit
       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 + 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!
+      mod10(luhn_sum_indexed(reversed_digits_single(identifier)))
     end
   end
 end

data/lib/sec_id/fisn.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SecId
+  # Financial Instrument Short Name (FISN) - a human-readable short name for financial
+  # instruments per ISO 18774.
+  #
+  # Format: Issuer Name/Abbreviated Instrument Description
+  # - Total length: 1-35 characters
+  # - Issuer: 1-15 characters (uppercase A-Z, digits 0-9, space)
+  # - Separator: forward slash (/)
+  # - Description: 1-19 characters (uppercase A-Z, digits 0-9, space)
+  #
+  # @see https://en.wikipedia.org/wiki/ISO_18774
+  #
+  # @example Validate a FISN
+  #   SecId::FISN.valid?('APPLE INC/SH')  #=> true
+  #   SecId::FISN.valid?('apple inc/sh')  #=> true (normalized to uppercase)
+  #
+  # @example Access FISN components
+  #   fisn = SecId::FISN.new('APPLE INC/SH')
+  #   fisn.issuer       #=> 'APPLE INC'
+  #   fisn.description  #=> 'SH'
+  class FISN < Base
+    # Regular expression for parsing FISN components.
+    # Issuer: 1-15 chars, Description: 1-19 chars, Total: max 35 chars
+    ID_REGEX = %r{\A
+      (?<identifier>
+        (?<issuer>[A-Z0-9 ]{1,15})
+        /
+        (?<description>[A-Z0-9 ]{1,19}))
+    \z}x
+
+    # @return [String, nil] the issuer name portion (before the slash)
+    attr_reader :issuer
+
+    # @return [String, nil] the abbreviated instrument description (after the slash)
+    attr_reader :description
+
+    # @param fisn [String] the FISN string to parse
+    def initialize(fisn)
+      fisn_parts = parse(fisn)
+      @identifier = fisn_parts[:identifier]
+      @issuer = fisn_parts[:issuer]
+      @description = fisn_parts[:description]
+    end
+
+    # @return [String]
+    def to_s
+      identifier.to_s
+    end
+  end
+end

data/lib/sec_id/iban.rb

@@ -18,6 +18,7 @@ module SecId
   # @example Restore check digits
   #   SecId::IBAN.restore!('DE00370400440532013000')  #=> 'DE89370400440532013000'
   class IBAN < Base
+    include Checkable
     include IBANCountryRules
 
     # Regular expression for parsing IBAN components.
@@ -152,7 +153,7 @@ module SecId
 
     # @return [String] the numeric string representation
     def numeric_string_for_check
-      "#{bban}#{country_code}00".each_char.map { |char| char_to_digit(char) }.join
+      "#{bban}#{country_code}00".each_char.map { |char| CHAR_TO_DIGIT.fetch(char) }.join
     end
   end
 end