Class: SecID::CFI

Inherits:
Base
  • Object
show all
Defined in:
lib/sec_id/cfi.rb,
lib/sec_id/cfi/field.rb,
lib/sec_id/cfi/tables.rb,
lib/sec_id/cfi/attribute_set.rb,
lib/sec_id/cfi/classification.rb

Overview

Classification of Financial Instruments (CFI) - a 6-character alphabetic code that classifies financial instruments per ISO 10962:2021.

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, strictly validated per group (X = "not applicable")

Examples:

Validate a CFI code

SecID::CFI.valid?('ESVUFR')  #=> true
SecID::CFI.valid?('ESZZZZ')  #=> false (Z is not a permissible equity attribute)

Access CFI components and decode the classification

cfi = SecID::CFI.new('ESVUFR')
cfi.category                                #=> :equity
cfi.group                                   #=> :common_shares
cfi.decode.category.equity?                 #=> true
cfi.decode.attributes.voting_right.voting?  #=> true
cfi.decode.to_s                             #=> "Equities / Common/Ordinary shares: Voting, ..."

See Also:

Defined Under Namespace

Modules: Tables Classes: AttributeSet, Classification, Field

Constant Summary collapse

FULL_NAME =

Human-readable name of the standard.

'Classification of Financial Instruments'
ID_LENGTH =

Valid length(s) of a normalized identifier.

6
EXAMPLE =

A representative valid identifier.

'ESVUFR'
VALID_CHARS_REGEX =

Pattern matching the identifier's permitted character set.

/\A[A-Z]+\z/
ID_REGEX =

Regular expression for parsing CFI components.

/\A
  (?<identifier>
    (?<category_code>[A-Z])
    (?<group_code>[A-Z])
    (?<attr1>[A-Z])
    (?<attr2>[A-Z])
    (?<attr3>[A-Z])
    (?<attr4>[A-Z]))
\z/x
CATEGORIES =

Category codes per ISO 10962:2021, derived from Tables (letter => symbol).

DeepFreeze.call(Tables::CATEGORIES.transform_values(&:first))
GROUPS =

Group codes per category per ISO 10962:2021, derived from Tables (letter => { letter => symbol }).

DeepFreeze.call(
  Tables::GROUPS.transform_values { |groups| groups.transform_values { |group| group[:symbol] } }
)

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

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

#==, #as_json, example, full_name, has_check_digit?, #hash, id_length, length_specificity, length_values, short_name, #to_h

Methods included from Validatable

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

Methods included from Normalizable

#normalize!, #normalized, #to_pretty_s, #to_str

Constructor Details

#initialize(cfi) ⇒ CFI

Returns a new instance of CFI.

Parameters:

  • cfi (String) —

    the CFI string to parse



92
93
94
95
96
97
98
99
100
101
 
# File 'lib/sec_id/cfi.rb', line 92

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

Instance Attribute Details

#attr1 ⇒ String? (readonly)

Returns attribute 1 (position 3).

Returns:

  • (String, nil) —

    attribute 1 (position 3)



80
81
82
 
# File 'lib/sec_id/cfi.rb', line 80

def attr1
  @attr1
end

#attr2 ⇒ String? (readonly)

Returns attribute 2 (position 4).

Returns:

  • (String, nil) —

    attribute 2 (position 4)



83
84
85
 
# File 'lib/sec_id/cfi.rb', line 83

def attr2
  @attr2
end

#attr3 ⇒ String? (readonly)

Returns attribute 3 (position 5).

Returns:

  • (String, nil) —

    attribute 3 (position 5)



86
87
88
 
# File 'lib/sec_id/cfi.rb', line 86

def attr3
  @attr3
end

#attr4 ⇒ String? (readonly)

Returns attribute 4 (position 6).

Returns:

  • (String, nil) —

    attribute 4 (position 6)



89
90
91
 
# File 'lib/sec_id/cfi.rb', line 89

def attr4
  @attr4
end

#category_code ⇒ String? (readonly)

Returns the category code (position 1).

Returns:

  • (String, nil) —

    the category code (position 1)



74
75
76
 
# File 'lib/sec_id/cfi.rb', line 74

def category_code
  @category_code
end

#group_code ⇒ String? (readonly)

Returns the group code (position 2).

Returns:

  • (String, nil) —

    the group code (position 2)



77
78
79
 
# File 'lib/sec_id/cfi.rb', line 77

def group_code
  @group_code
end

Class Method Details

.categories ⇒ Hash{String => Symbol}

Returns the category codes hash.

Returns:

  • (Hash{String => Symbol}) 


61
62
63
 
# File 'lib/sec_id/cfi.rb', line 61

def self.categories
  CATEGORIES
end

.groups_for(category_code) ⇒ Hash{String => Symbol}?

Returns the groups hash for a given category code.

Parameters:

  • category_code (String) —

    single-letter category code

Returns:

  • (Hash{String => Symbol}, nil) 


69
70
71
 
# File 'lib/sec_id/cfi.rb', line 69

def self.groups_for(category_code)
  GROUPS[category_code.to_s.upcase]
end

Instance Method Details

#category ⇒ Symbol?

Returns the semantic category name.

Returns:

  • (Symbol, nil) —

    category symbol or nil if invalid



106
107
108
 
# File 'lib/sec_id/cfi.rb', line 106

def category
  CATEGORIES[category_code]
end

#decode ⇒ Classification?

Decodes this CFI into its full ISO 10962:2021 classification.

Returns:

  • (Classification, nil) —

    the classification, or nil if this CFI is invalid



120
121
122
123
124
 
# File 'lib/sec_id/cfi.rb', line 120

def decode
  return nil unless valid?

  Classification.new(category_code, group_code, attribute_letters)
end

#group ⇒ Symbol?

Returns the semantic group name.

Returns:

  • (Symbol, nil) —

    group symbol or nil if invalid



113
114
115
 
# File 'lib/sec_id/cfi.rb', line 113

def group
  GROUPS.dig(category_code, group_code)
end

#to_s ⇒ String

Returns:

  • (String) 


127
128
129
 
# File 'lib/sec_id/cfi.rb', line 127

def to_s
  identifier.to_s
end