Class: SecID::CUSIP

Inherits:
Base
  • Object
show all
Includes:
Checkable, Suggestable
Defined in:
lib/sec_id/cusip.rb

Overview

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 checksum

Examples:

Validate a CUSIP

SecID::CUSIP.valid?('037833100')  #=> true

Convert to ISIN

cusip = SecID::CUSIP.new('037833100')
cusip.to_isin('US')  #=> #<SecID::ISIN>

See Also:

Constant Summary collapse

FULL_NAME =

Human-readable name of the standard.

'Committee on Uniform Securities Identification Procedures'
ID_LENGTH =

Valid length(s) of a normalized identifier.

9
EXAMPLE =

A representative valid identifier.

'037833100'
VALID_CHARS_REGEX =

Pattern matching the identifier's permitted character set.

/\A[A-Z0-9*@#]+\z/
ID_REGEX =

Regular expression for parsing CUSIP components.

/\A
  (?<identifier>
    (?<cusip6>[A-Z0-9]{5}[A-Z0-9*@#])
    (?<issue>[A-Z0-9*@#]{2}))
  (?<checksum>\d)?
\z/x

Constants included from Suggestable

Suggestable::HOMOGLYPHS, Suggestable::RANK

Constants included from Checkable

SecID::Checkable::CHAR_TO_DIGIT, SecID::Checkable::CHAR_TO_DIGITS

Constants included from Generatable

Generatable::ALPHA, Generatable::ALPHANUMERIC, Generatable::DIGITS

Constants included from Validatable

Validatable::ERROR_MAP

Constants included from Normalizable

Normalizable::SEPARATORS

Instance Attribute Summary collapse

Attributes inherited from Base

#full_id, #identifier

Instance Method Summary collapse

Methods included from Suggestable

#suggest

Methods included from Checkable

#calculate_check_digit, #check_digit, #restore, #restore!, #to_s, #valid?

Methods inherited from Base

#==, #as_json, #deconstruct_keys, detection_priority, example, full_name, has_check_digit?, has_checksum?, #hash, id_length, length_specificity, length_values, short_name, #to_h, type_key

Methods included from Validatable

#errors, #valid?, #validate, #validate!

Methods included from Normalizable

#normalize!, #normalized, #to_s, #to_str

Constructor Details

#initialize(cusip) ⇒ CUSIP

Returns a new instance of CUSIP.

Parameters:

  • cusip (String) —

    the CUSIP string to parse



45
46
47
48
49
50
51
 
# File 'lib/sec_id/cusip.rb', line 45

def initialize(cusip)
  cusip_parts = parse cusip
  @identifier = cusip_parts[:identifier]
  @cusip6 = cusip_parts[:cusip6]
  @issue = cusip_parts[:issue]
  @checksum = cusip_parts[:checksum]&.to_i
end

Instance Attribute Details

#cusip6 ⇒ String? (readonly)

Returns the 6-character issuer code.

Returns:

  • (String, nil) —

    the 6-character issuer code



39
40
41
 
# File 'lib/sec_id/cusip.rb', line 39

def cusip6
  @cusip6
end

#issue ⇒ String? (readonly)

Returns the 2-character issue number.

Returns:

  • (String, nil) —

    the 2-character issue number



42
43
44
 
# File 'lib/sec_id/cusip.rb', line 42

def issue
  @issue
end

Instance Method Details

#calculate_checksum ⇒ Integer

Returns the calculated checksum (0-9).

Returns:

  • (Integer) —

    the calculated checksum (0-9)

Raises:



62
63
64
65
 
# File 'lib/sec_id/cusip.rb', line 62

def calculate_checksum
  validate_format_for_calculation!
  mod10(luhn_sum_double_add_double(reversed_digits_single(identifier)))
end

#cins? ⇒ Boolean

Returns true if first character is a letter (CINS identifier).

Returns:

  • (Boolean) —

    true if first character is a letter (CINS identifier)



88
89
90
 
# File 'lib/sec_id/cusip.rb', line 88

def cins?
  cusip6[0] < '0' || cusip6[0] > '9'
end

#to_isin(country_code) ⇒ ISIN

Returns a new ISIN instance.

Parameters:

  • country_code (String) —

    the ISO 3166-1 alpha-2 country code (must be CGS country)

Returns:

  • (ISIN) —

    a new ISIN instance

Raises:



79
80
81
82
83
84
85
 
# File 'lib/sec_id/cusip.rb', line 79

def to_isin(country_code)
  unless ISIN::CGS_COUNTRY_CODES.include?(country_code)
    raise(InvalidFormatError, "'#{country_code}' is not a CGS country code!")
  end

  ISIN.new(country_code + restore).restore!
end

#to_pretty_s ⇒ String?

Returns:

  • (String, nil) 


54
55
56
57
58
 
# File 'lib/sec_id/cusip.rb', line 54

def to_pretty_s
  return nil unless valid?

  "#{cusip6} #{issue} #{checksum}"
end