sec_id 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 374eb5eb544fd34d09e5d5008473b5516c3b9ac13e720dd7ea01062478da5248
-  data.tar.gz: 6b785b97c0bd99c56feb8a500f1376f228077f0d58503cb823af3d2abc790ae6
+  metadata.gz: a3391006ed4c0e135a0e94ef0d43da6aae3146a178f13c6237aec8d940931c52
+  data.tar.gz: a572d9b26de1c8c97476cd954caeefacc9fe44ac8ffff7f25d9b4a72ca058e54
 SHA512:
-  metadata.gz: ca697d5bf5326587d437f6206e91d419ad11aad3166f6d2c75f423afae1fcaf3736860b313545d85761f9575bf85f56120f5d3d74e92158fa3c1ed9fc4d5be5d
-  data.tar.gz: 1c46330ecd6e07192eaf083dc28e41e7b3edbb83a1ee226f76817df4c3182fc20f4e42415350da9bf343b5e89445e1545d79cf1ca02dea15a380fe94f07bef82
+  metadata.gz: 1d380490f4a25d1044734b7724bf7e752e7dbb43097a468d3210e8fd9f4efd185beac207d9b5adfc5cce0cedfd5ea944be269785f444fd7a4bbb449b63ea9962
+  data.tar.gz: 30434ebe94c7f2c7f3a311ab2a3857af1ae0b66b5993c3b659fd9f6852633171cd7e4ce3c73f7d1e554211cbb53259e1e7679236df243f8dfaf311a0a61cebee

data/.github/workflows/main.yml

@@ -35,5 +35,5 @@ jobs:
       continue-on-error:  ${{ matrix.ruby_version == 'ruby-head' }}
 
     - uses: paambaati/codeclimate-action@v8.0.0
-      # Only upload coverage for the latest Ruby
-      if: ${{ matrix.ruby_version == '3.3' }}
+      # Only upload coverage for the latest Ruby and don't run for PRs from forks
+      if: ${{ matrix.ruby_version == '3.3' && github.event.pull_request.head.repo.fork == false }}

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [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)
+
+### Updated
+
+- Small internal refactorings
+
 ## [4.0.0] - 2024-07-09
 
 ### Breaking changes

data/README.md

@@ -11,7 +11,9 @@ Check-digit calculation is also available.
 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)
+[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).
 
 Work in progress:
 [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).
@@ -21,7 +23,7 @@ Work in progress:
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'sec_id', '~> 4.0'
+gem 'sec_id', '~> 4.1'
 ```
 
 And then execute:
@@ -115,6 +117,7 @@ isin.valid?                # => true
 isin.valid_format?         # => true
 isin.restore!              # => 'US5949181045'
 isin.calculate_check_digit # => 5
+isin.to_cusip              # => #<SecId::CUSIP>
 ```
 
 ### SecId::CUSIP full example
@@ -136,6 +139,8 @@ cusip.valid?                # => true
 cusip.valid_format?         # => true
 cusip.restore!              # => '594918104'
 cusip.calculate_check_digit # => 4
+cusip.to_isin('US')         # => #<SecId::ISIN>
+cusip.cins?                 # => true
 ```
 
 ### SecId::SEDOL full example
@@ -157,6 +162,48 @@ cusip.restore!              # => 'B0Z52W5'
 cusip.calculate_check_digit # => 5
 ```
 
+### SecId::FIGI full example
+
+```ruby
+# class level
+SecId::FIGI.valid?('BBG000DMBXR2')        # => true
+SecId::FIGI.valid_format?('BBG000DMBXR2') # => true
+SecId::FIGI.restore!('BBG000DMBXR')       # => 'BBG000DMBXR2'
+SecId::FIGI.check_digit('BBG000DMBXR')    # => 2
+
+# instance level
+figi = SecId::FIGI.new('BBG000DMBXR2')
+figi.full_number           # => 'BBG000DMBXR2'
+figi.prefix                # => 'BB'
+figi.random_part           # => '000DMBXR'
+figi.check_digit           # => 2
+figi.valid?                # => true
+figi.valid_format?         # => true
+figi.restore!              # => 'BBG000DMBXR2'
+figi.calculate_check_digit # => 2
+```
+
+### SecId::CIK full example
+
+```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
+
+# 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
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies.

data/lib/sec_id/cik.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SecId
+  # https://en.wikipedia.org/wiki/Central_Index_Key
+  class CIK < Base
+    ID_REGEX = /\A
+      (?=\d{1,10}\z)(?<padding>0*)(?<identifier>[1-9]\d{0,9})
+    \z/x
+
+    attr_reader :padding
+
+    def initialize(cik)
+      cik_parts = parse cik
+      @padding = cik_parts[:padding]
+      @identifier = cik_parts[:identifier]
+    end
+
+    def valid?
+      valid_format?
+    end
+
+    def valid_format?
+      !identifier.nil?
+    end
+
+    def restore!
+      raise InvalidFormatError, "CIK '#{full_number}' is invalid and cannot be restored!" unless valid_format?
+
+      @padding = '0' * (10 - @identifier.length)
+      @full_number = @identifier.rjust(10, '0')
+    end
+  end
+end

data/lib/sec_id/cusip.rb

@@ -21,27 +21,41 @@ module SecId
     end
 
     def calculate_check_digit
-      return mod10(modified_luhn_sum) if valid_format?
+      unless valid_format?
+        raise InvalidFormatError, "CUSIP '#{full_number}' is invalid and check-digit cannot be calculated!"
+      end
+
+      mod10(modified_luhn_sum)
+    end
+
+    def to_isin(country_code)
+      unless ISIN::CGS_COUNTRY_CODES.include?(country_code)
+        raise(InvalidFormatError, "'#{country_code}' is not a CGS country code!")
+      end
 
-      raise InvalidFormatError, "CUSIP '#{full_number}' is invalid and check-digit cannot be calculated!"
+      restore!
+      isin = ISIN.new(country_code + full_number)
+      isin.restore!
+      isin
+    end
+
+    # CUSIP International Numbering System
+    def cins?
+      cusip6[0] < '0' || cusip6[0] > '9'
     end
 
     private
 
     # https://en.wikipedia.org/wiki/Luhn_algorithm
     def modified_luhn_sum
-      sum = 0
-
-      id_digits.reverse.each_slice(2) do |even, odd|
+      reversed_id_digits.each_slice(2).reduce(0) do |sum, (even, odd)|
         double_even = (even || 0) * 2
-        sum += div10mod10(double_even) + div10mod10(odd || 0)
+        sum + div10mod10(double_even) + div10mod10(odd || 0)
       end
-
-      sum
     end
 
-    def id_digits
-      @id_digits ||= identifier.each_char.map(&method(:char_to_digit))
+    def reversed_id_digits
+      identifier.each_char.map(&method(:char_to_digit)).reverse!
     end
   end
 end

data/lib/sec_id/figi.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module SecId
+  class FIGI < Base
+    ID_REGEX = /\A
+      (?<identifier>
+        (?<prefix>[B-DF-HJ-NP-TV-Z0-9]{2})
+        G
+        (?<random_part>[B-DF-HJ-NP-TV-Z0-9]{8}))
+      (?<check_digit>\d)?
+    \z/x
+
+    RESTRICTED_PREFIXES = Set.new %w[BS BM GG GB GH KY VG]
+
+    attr_reader :prefix, :random_part
+
+    def initialize(figi)
+      figi_parts = parse figi
+      @identifier = figi_parts[:identifier]
+      @prefix = figi_parts[:prefix]
+      @random_part = figi_parts[:random_part]
+      @check_digit = figi_parts[:check_digit]&.to_i
+    end
+
+    def valid_format?
+      !identifier.nil? && !RESTRICTED_PREFIXES.include?(prefix)
+    end
+
+    def calculate_check_digit
+      unless valid_format?
+        raise InvalidFormatError, "FIGI '#{full_number}' is invalid and check-digit cannot be calculated!"
+      end
+
+      mod10(modified_luhn_sum)
+    end
+
+    private
+
+    # https://en.wikipedia.org/wiki/Luhn_algorithm
+    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
+      end
+    end
+
+    def reversed_id_digits
+      identifier.each_char.map(&method(:char_to_digit)).reverse!
+    end
+  end
+end

data/lib/sec_id/isin.rb

@@ -10,6 +10,14 @@ module SecId
       (?<check_digit>\d)?
     \z/x
 
+    CGS_COUNTRY_CODES = Set.new(
+      %w[
+        US CA AG AI AN AR AS AW BB BL BM BO BQ BR BS BZ CL CO CR CW DM DO EC FM
+        GD GS GU GY HN HT JM KN KY LC MF MH MP MX NI PA PE PH PR PW PY SR SV SX
+        TT UM UY VC VE VG VI YT
+      ]
+    ).freeze
+
     attr_reader :country_code, :nsin
 
     def initialize(isin)
@@ -21,28 +29,37 @@ module SecId
     end
 
     def calculate_check_digit
-      return mod10(luhn_sum) if valid_format?
+      unless valid_format?
+        raise InvalidFormatError, "ISIN '#{full_number}' is invalid and check-digit cannot be calculated!"
+      end
 
-      raise InvalidFormatError, "ISIN '#{full_number}' is invalid and check-digit cannot be calculated!"
+      mod10(luhn_sum)
+    end
+
+    # CUSIP Global Services
+    def cgs?
+      CGS_COUNTRY_CODES.include?(country_code)
+    end
+
+    def to_cusip
+      raise InvalidFormatError, "'#{country_code}' is not a CGS country code!" unless cgs?
+
+      CUSIP.new(nsin)
     end
 
     private
 
     # https://en.wikipedia.org/wiki/Luhn_algorithm
     def luhn_sum
-      sum = 0
-
-      id_digits.reverse.each_slice(2) do |even, odd|
+      reversed_id_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)
+        sum + double_even + (odd || 0)
       end
-
-      sum
     end
 
-    def id_digits
-      @id_digits ||= identifier.each_char.flat_map(&method(:char_to_digits))
+    def reversed_id_digits
+      identifier.each_char.flat_map(&method(:char_to_digits)).reverse!
     end
   end
 end

data/lib/sec_id/sedol.rb

@@ -17,9 +17,11 @@ module SecId
     end
 
     def calculate_check_digit
-      return mod10(weighted_sum) if valid_format?
+      unless valid_format?
+        raise InvalidFormatError, "SEDOL '#{full_number}' is invalid and check-digit cannot be calculated!"
+      end
 
-      raise InvalidFormatError, "SEDOL '#{full_number}' is invalid and check-digit cannot be calculated!"
+      mod10(weighted_sum)
     end
 
     private

data/lib/sec_id/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SecId
-  VERSION = '4.0.0'
+  VERSION = '4.1.0'
 end

data/lib/sec_id.rb

@@ -6,6 +6,8 @@ require 'sec_id/base'
 require 'sec_id/isin'
 require 'sec_id/cusip'
 require 'sec_id/sedol'
+require 'sec_id/figi'
+require 'sec_id/cik'
 
 module SecId
   Error = Class.new(StandardError)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sec_id
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Leonid Svyatov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-07-09 00:00:00.000000000 Z
+date: 2024-09-23 00:00:00.000000000 Z
 dependencies: []
 description: 'Validate securities identification numbers with ease! Currently supported
   standards: ISIN, CUSIP, SEDOL.'
@@ -32,7 +32,9 @@ files:
 - bin/setup
 - lib/sec_id.rb
 - lib/sec_id/base.rb
+- lib/sec_id/cik.rb
 - lib/sec_id/cusip.rb
+- lib/sec_id/figi.rb
 - lib/sec_id/isin.rb
 - lib/sec_id/sedol.rb
 - lib/sec_id/version.rb
@@ -57,7 +59,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.14
+rubygems_version: 3.5.15
 signing_key:
 specification_version: 4
 summary: Validate securities identification numbers with ease!