Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/svyatov/sec_id
Validate securities identification numbers (ISIN, CUSIP, SEDOL, FIGI, CIK) with ease!
https://github.com/svyatov/sec_id
cik cusip figi iban isin ruby ruby-gem sedol validation
Last synced: about 1 month ago
JSON representation
Validate securities identification numbers (ISIN, CUSIP, SEDOL, FIGI, CIK) with ease!
- Host: GitHub
- URL: https://github.com/svyatov/sec_id
- Owner: svyatov
- License: mit
- Created: 2019-02-03T12:29:17.000Z (almost 6 years ago)
- Default Branch: main
- Last Pushed: 2024-09-24T12:54:08.000Z (about 2 months ago)
- Last Synced: 2024-10-03T09:44:41.920Z (about 2 months ago)
- Topics: cik, cusip, figi, iban, isin, ruby, ruby-gem, sedol, validation
- Language: Ruby
- Homepage:
- Size: 46.9 KB
- Stars: 8
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# SecId
[](https://badge.fury.io/rb/sec_id)
[](https://codeclimate.com/github/svyatov/sec_id/maintainability)
[](https://codeclimate.com/github/svyatov/sec_id/test_coverage)
Validate securities identification numbers with ease!
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),
[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).
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'sec_id', '~> 4.1'
```
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
```
* `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
```ruby
# class level
SecId::ISIN.restore!('US594918104') # => 'US5949181045'
# instance level
isin = SecId::ISIN.new('US5949181045')
isin.restore! # => 'US5949181045'
```
* `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.
```ruby
# class level
SecId::ISIN.check_digit('US594918104') # => 5
# instance level
isin = SecId::ISIN.new('US594918104')
isin.calculate_check_digit # => 5
isin.check_digit # => nil
```
: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`.
### SecId::ISIN full example
```ruby
# class level
SecId::ISIN.valid?('US5949181045') # => true
SecId::ISIN.valid_format?('US594918104') # => true
SecId::ISIN.restore!('US594918104') # => 'US5949181045'
SecId::ISIN.check_digit('US594918104') # => 5
# instance level
isin = SecId::ISIN.new('US5949181045')
isin.full_number # => 'US5949181045'
isin.country_code # => 'US'
isin.nsin # => '594918104'
isin.check_digit # => 5
isin.valid? # => true
isin.valid_format? # => true
isin.restore! # => 'US5949181045'
isin.calculate_check_digit # => 5
isin.to_cusip # => #
```
### SecId::CUSIP full example
```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
# instance level
cusip = SecId::CUSIP.new('594918104')
cusip.full_number # => '594918104'
cusip.cusip6 # => '594918'
cusip.issue # => '10'
cusip.check_digit # => 4
cusip.valid? # => true
cusip.valid_format? # => true
cusip.restore! # => '594918104'
cusip.calculate_check_digit # => 4
cusip.to_isin('US') # => #
cusip.cins? # => true
```
### SecId::SEDOL full example
```ruby
# class level
SecId::SEDOL.valid?('B0Z52W5') # => true
SecId::SEDOL.valid_format?('B0Z52W') # => true
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
```
### 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.
Then, run `rake spec` to run the tests. You can also run `bin/console`
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run `bundle exec rake install`.
## Contributing
Bug reports and pull requests are welcome on
GitHub at https://github.com/svyatov/sec_id.
## License
The gem is available as open source under the terms of
the [MIT License](LICENSE.txt).