iceland 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 95b30f1477b431842ba1b7aec7b3c6be294c6292
-  data.tar.gz: 60ef980798f7a838bf414d71515102afa83c2f0a
+  metadata.gz: b11f96ebbc86010620fd65728d6c85a8b92a4ec9
+  data.tar.gz: aaa75e67c18e513b6bfbe0f548800d5883c538df
 SHA512:
-  metadata.gz: 7124e9c2324f5d529664e6aac438d2d850a45cee3a0bf683b51b001e499ef9dfb4cf352939c0b683fb5865853564a15896fb833e1d06e091586249d2b443a184
-  data.tar.gz: 31dc4830e351222cc4ad901cddbc9f82d5628fe4bff5250e1ef5d003961d2e50a130fa6d6ea909069fff8bd8c20b40ae37a10b66e962b73931873b7bc8c80917
+  metadata.gz: e9e6b8a66efb724a012b19ebc1e3c9fd9b0920725ca06732254cd723015670fad5c079c50ecbc1986932ae4134c762ccc43539187ac59e20c4f4450a7a2020f9
+  data.tar.gz: 4c9e279e51b271f70dd2441256c92aea3f494e156bff0a2b97604f8a403311ce8ac6e60f6f72ebbe52d2c8ab1f4546ebdfbe96fe7303efa138b7842cd2c2849c

data/.rubocop.yml

@@ -1,2 +1,4 @@
 Metrics/AbcSize:
   Max: 20
+Metrics/ClassLength:
+  Max: 150

data/README.md

@@ -22,6 +22,8 @@ Or install it yourself as:
 
 ### Postal Codes
 
+Icelandic postal codes are 3-digit numeric identifiers, with the first digit indicating a region and the rest identifying a specific locale within the region.
+
 Names of locales are provided in dative form by default as per Icelandic postal convention, but nomative forms can be returned by setting the `force_nominative` parameter to `true` when using the `Iceland.all_postal_codes` and `Iceland.locale_by_postal_code` methods.
 
 (Note that we use the term "locale" as per Universal Postal Union convention to name town, city or other location the postal code is assigned to.)
@@ -52,18 +54,46 @@ Iceland.locale_by_postal_code 311, true
 
 The Iceland Gem provides a class to handle "kennitala" identifier codes. The class can be used to sanitize the identifiers and read information like the date of birth (or date of registration in the case of companies and organization), age and the type of entity.
 
+The class does not access external APIs or databases such National Registry or the Company Registry, so names and status (death, bankruptcy, credit rating etc.) cannot be accessed using the class. However, it can be used to sanitize and validate such data before being sent to external APIs, as such services are provided by private companies, which often charge a specific amount for each query.
+
+#### Uses of kennitala
+
+Unlike the US Social Security number and equivalents, the kennitala is only used for identification of persons and companies (as well as other registered organizations) — and is often used internally by educational institutions, companies and other organization as a primary identifier for persons (e.g. school, employee, customer and frequent flyer ID). It is not to be used for authentication (i.e. a password) and is not considered a secret per se. While a kennitala can be kept unencrypted in a database, publishing a kennitala or a list of them is generally not considered good practice and might cause liability.
+
+A kennitala is assigned to every newborn person and foreign nationals residing in Iceland as well as organizations and companies operating there. It is statically assigned and can not be changed.
+
+Article II, paragraph 10 of the 77/2000 Act on Data Protection (http://www.althingi.is/lagas/nuna/2000077.html) provides the legal framework regarding the use and processing of the kennitala in Iceland:
+
+> The use of a kennitala is allowed if it has a an objective cause and is necessary to ensure reliable identification of persons. The Data Protection Authority may ban or order the use of kennitala.
+
+#### Technicalities
+
+The kennitala (`DDMMYY-RRCM`) is a 10-digit numeric string consisting on a date (date of birth for persons, date of registration for companies) in the form of `DDMMYY`, three two random digits (`RR`) a check digit (`C`) and a century identifier (`M`). A hyphen or space is often added between the year and random values (Example: `010130-2989`).
+
+The number 40 is added to the registration day of companies and organizations. Hence, a kennitala for a company registered at January 1 1990 starts with `410190` as opposed to `010190` for a person born that day.
+
+The century identifier has 3 legal values. `8` for the 19th century, `9` for the 20th century and `0` for the 21st century.
+
+The check digit is described
+
 #### Examples
 
+##### Working with Kennitala objects
+
 ```ruby
 # Initialize a Kennitala object.
 # The string provided may include spaces and hyphens.
 k = Kennitala.new('010130-2989')
 # => #<Kennitala:0x007fe35d041bc0 @value="0101302989">
 
-# Invalid strings are rejected
+# Invalid strings are rejected with an argument error
 f = Kennitala.new('010130-2979')
 # ArgumentError: Kennitala is invalid
 
+# If no kennitala string is specified, a random one will be generated
+r = Kennitala.new
+# => #<Kennitala:0x007fc589339f18 @value="2009155509">
+
 # Retrieve the kennitala as a string.
 # This is a sanitized string, without any non-numeric characters.
 k.to_s
@@ -89,10 +119,22 @@ k.age
 # => 86
 ```
 
+####
+
+```ruby
+# Casting a string to a Kennitala object
+'0101302989'.to_kt
+# => #<Kennitala:0x007fc5893286a0 @value="0101302989">
+
+# Get the current age based on a String
+'0101302989'.to_kt.age
+# => 86
+```
+
 ## Todo
 
 * Administrative Divisions
-* A Kennitala faker, similar to ffaker and ffaker
+* Bank accounts
 
 ## About the data
 
@@ -110,7 +152,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/stefanvignir/iceland_gem.
 
-Do make sure that the `rspec` unit tests run before sending a pull request and write tests for any new functionality you add.
+Do make sure that the `rspec` unit tests run before sending a pull request (hint: try running `rspec` a couple of times in a row as some tests might fail randomly) and write tests for any new functionality you add. Also run `rubocop` to check if your code adheres to the Ruby Style Guide.
 
 ## License
 

data/lib/iceland/kennitala.rb

@@ -0,0 +1,217 @@
+# The Kennitala Class
+class Kennitala
+  def initialize(kt_string = false, is_company = false)
+    kt_string = fake_kt_string(is_company) if kt_string == false
+    unless kt_string.class == String
+      raise ArgumentError, 'Kennitala needs to be provided as a string'
+    end
+    sanitised_kt = sanitize(kt_string)
+    raise ArgumentError, 'Kennitala is invalid' if sanitised_kt.nil?
+    @value = sanitised_kt
+  end
+
+  # Get the type of entity - If it is a person or an organization
+  #
+  # @return [String] Either 'person' or 'company'
+  def entity_type
+    date_integer = @value[0, 2].to_i
+    return 'person' if date_integer < 32
+    return 'company' if (date_integer > 40) && (date_integer < 71)
+    false
+  end
+
+  # Check if the entity is a company
+  #
+  # @return [Boolean]
+  def company?
+    date_integer = @value[0, 2].to_i
+    return true if (date_integer > 40) && (date_integer < 71)
+    false
+  end
+
+  # Check if the entity is a person
+  #
+  # @return [Type] description of returned object
+  def person?
+    date_integer = @value[0, 2].to_i
+    return true if date_integer < 32
+    false
+  end
+
+  # Get the year of birth or registration
+  #
+  # @return [Fixnum]
+  def year
+    century = (10 + @value[9].to_i) * 100
+    year = @value[4, 2].to_i
+    return century + year if (1800..1900).cover?(century)
+    return 2000 + year if century == 1000
+  end
+
+  # Get the day of the month of birth or registration
+  #
+  # @return [Fixnum]
+  def day
+    date_integer = @value[0, 2].to_i
+    return @value[0, 2].to_i if date_integer < 32
+    return @value[0, 2].to_i - 40 if (date_integer > 40) && (date_integer < 71)
+  end
+
+  # Get a numeric representation of the month of birth or registration
+  #
+  # @return [Fixnum]
+  def month
+    @value[2, 2].to_i
+  end
+
+  # Get the age of entity in years. Useful when dealing with age restrictions.
+  #
+  # @return [Fixnum]
+  def age
+    year_diff = Date.today.year - to_date.year
+    month_diff = Date.today.month - to_date.month
+    day_diff = Date.today.month - to_date.month
+
+    return year_diff -= 1 if month_diff < 0 || (month_diff == 0 && day_diff < 0)
+    year_diff
+  end
+
+  # Cast the kennitala to a Date object
+  #
+  # @return [Date]
+  def to_date
+    Date.new(year, month, day)
+  end
+
+  # Cast the kennitala to a String object
+  #
+  # @return [Date]
+  def to_s
+    @value.to_s
+  end
+
+  private
+
+  # Generate fake a birth number and check digit based on the first 6 digits
+  #
+  # @param [String] The first six digits is a kennitala
+  # @return [Hash, nil]
+  def fake_randoms(date_hash)
+    first_six = date_hash[:day] + date_hash[:month] + date_hash[:year]
+    loop do
+      birth_number = Random.rand(1..99).to_s.rjust(2, '0')
+      first_eight = "#{first_six}#{birth_number}"
+      check_digit = calculate_check_digit(first_eight)
+      if check_checksum(first_eight)
+        return { check_digit: check_digit, birth_number: birth_number }
+      end
+    end
+  end
+
+  # Generate a fake year and century Hash
+  #
+  # @return [Hash] description of returned object
+  def fake_year
+    century = [9, 9, 9, 8, 0, 0].sample
+    current_year = Date.today.strftime('%y').to_i
+    if century == 0
+      return { year: Random.rand(0..current_year), century: century }
+    else
+      return { year: Random.rand(0..99), century: century }
+    end
+  end
+
+  # Generate a fake hash that includes randomly generated date elements
+  #
+  # @param [Boolean] is_company true if the day string is for a company
+  # @return [Hash]
+  def fake_date_hash(is_company = false)
+    year_hash = fake_year
+
+    month_days = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
+    month = Random.rand(1..12)
+
+    day = Random.rand(1..month_days[month - 1])
+    day = (day.to_i + 40).to_s.rjust(2, '0') if is_company == true
+
+    { century: year_hash[:century].to_s,
+      year: year_hash[:year].to_s.rjust(2, '0'),
+      month: month.to_s.rjust(2, '0'), day: day.to_s.rjust(2, '0') }
+  end
+
+  def fake_kt_string(is_company = false)
+    date_hash = fake_date_hash(is_company)
+    randoms_hash = fake_randoms(date_hash)
+
+    first_six = date_hash[:day] + date_hash[:month] + date_hash[:year]
+    randoms = randoms_hash[:birth_number].to_s + randoms_hash[:check_digit].to_s
+
+    first_six + randoms + date_hash[:century]
+  end
+
+  def get_year_from_string(kt_string)
+    century_code = kt_string[9, 1].to_i
+    case century_code
+    when 0
+      return "20#{kt_string[4, 2]}".to_i
+    when 8..9
+      return "1#{century_code}#{kt_string[4, 2]}".to_i
+    end
+  end
+
+  # Sanitize the kennitala
+  #
+  # @param [String] kt_string Unsanitised string representing a kennitala
+  # @return [String, nil] Sanitized kennitala, nil if invalid
+  def sanitize(kt_string)
+    sanitized_kt = kt_string.gsub(/\D/, '')
+    checks = check_checksum(sanitized_kt)
+
+    year = get_year_from_string(sanitized_kt)
+    day = sanitized_kt[0, 2].to_i
+    day -= 40 if day > 40
+    month = sanitized_kt[2, 2].to_i
+    date = Date.new(year, month, day)
+
+    return sanitized_kt if checks == true && date.class == Date
+
+  rescue ArgumentError, 'invalid date'
+    nil
+  end
+
+  # Calculate the checksum
+  #
+  # @param [String] kt_string Sanitized kennitala
+  # @return [Fixnum] The checksum
+  def checksum(kt_string)
+    checksum = 0
+    multipliers = [3, 2, 7, 6, 5, 4, 3, 2]
+    multipliers.each_with_index do |multiplier, index|
+      checksum += multiplier * kt_string[index].to_i
+    end
+    checksum
+  end
+
+  def calculate_check_digit(kt_string)
+    remainder = checksum(kt_string).modulo(11)
+
+    # A kennitala with a remainder of 10 is always considered to be invalid
+    return nil if remainder == 10
+
+    # The check digit should be 11 minus the remainder,
+    # unless the remainder is 0, then the theck digit becomes 0.
+    return 0 if remainder == 0
+    11 - remainder
+  end
+
+  # Check validity of the check digit
+  #
+  # @param [String] kt_string Sanitized kennitala
+  # @return [Boolean, nil] true on success, false if the check digit is invalid
+  def check_checksum(kt_string)
+    expected_check_digit = calculate_check_digit(kt_string)
+    actual_check_digit = kt_string[8].to_i
+    return true if expected_check_digit == actual_check_digit
+    false
+  end
+end

data/lib/iceland/kennitala_string.rb

@@ -0,0 +1,9 @@
+# Monkey patch for the String class
+class String
+  # Converts a String to a Kennitala object
+  #
+  # @return [Kennitala]
+  def to_kt
+    Kennitala.new(self)
+  end
+end

data/lib/iceland/postal_codes.rb

@@ -0,0 +1,41 @@
+# Postal Codes
+module Iceland
+  POSTAL_CODES = YAML.load_file(File.expand_path('../../postcodes.yml',
+                                                 __FILE__))
+
+  # Get an array of hashes with postal_code and locale attributes
+  #
+  # @param [Boolean] include_po_boxes Include postal codes for P.O. boxes
+  # @param [Boolean] force_nominative Use the nomative version of locale name
+  # @return [Array]
+  def all_postal_codes(include_po_boxes = false, force_nominative = false)
+    pairs = []
+    POSTAL_CODES.each do |postal_code, p|
+      # Skip P.O. boxes
+      next if (include_po_boxes == false) && (p['is_po_box'] == true)
+      # Retun the dative form of the locale by default
+      pairs << if p['dative'].nil? || force_nominative == true
+                 { postal_code: postal_code, locale: p['locale'] }
+               else
+                 { postal_code: postal_code, locale: p['dative'] }
+               end
+    end
+    pairs
+  end
+
+  # Find the name of locale (city/town/village) by postal code
+  #
+  # @param [Integer, String] postal_code The postal code
+  # @param [Boolean] force_nominative Display locale name in nomative form
+  # @return [String] description of returned object
+  def locale_by_postal_code(postal_code, force_nominative = false)
+    postal_code = postal_code.to_i
+    postal_code_hash = POSTAL_CODES[postal_code]
+    unless postal_code_hash.nil?
+      if postal_code_hash['dative'].nil? || force_nominative == true
+        return postal_code_hash['locale']
+      end
+      postal_code_hash['dative']
+    end
+  end
+end

data/lib/iceland/version.rb

@@ -1,3 +1,3 @@
 module Iceland
-  VERSION = '0.1.3'.freeze
+  VERSION = '0.1.4'.freeze
 end

data/lib/iceland.rb

@@ -2,181 +2,6 @@ require 'date'
 require 'yaml'
 
 require 'iceland/version'
-
-# The Iceland Module
-module Iceland
-  POSTAL_CODES = YAML.load_file(File.expand_path('../postcodes.yml', __FILE__))
-
-  # Get an array of hashes with postal_code and locale attributes
-  #
-  # @param [Boolean] include_po_boxes Include postal codes for P.O. boxes
-  # @param [Boolean] force_nominative Use the nomative version of locale name
-  # @return [Array]
-  def all_postal_codes(include_po_boxes = false, force_nominative = false)
-    pairs = []
-    POSTAL_CODES.each do |postal_code, p|
-      # Skip P.O. boxes
-      next if (include_po_boxes == false) && (p['is_po_box'] == true)
-      # Retun the dative form of the locale by default
-      pairs << if p['dative'].nil? || force_nominative == true
-                 { postal_code: postal_code, locale: p['locale'] }
-               else
-                 { postal_code: postal_code, locale: p['dative'] }
-               end
-    end
-    pairs
-  end
-
-  # Find the name of locale (city/town/village) by postal code
-  #
-  # @param [Integer, String] postal_code The postal code
-  # @param [Boolean] force_nominative Display locale name in nomative form
-  # @return [String] description of returned object
-  def locale_by_postal_code(postal_code, force_nominative = false)
-    postal_code = postal_code.to_i
-    postal_code_hash = POSTAL_CODES[postal_code]
-    unless postal_code_hash.nil?
-      if postal_code_hash['dative'].nil? || force_nominative == true
-        return postal_code_hash['locale']
-      end
-      postal_code_hash['dative']
-    end
-  end
-end
-
-# The Kennitala Class
-class Kennitala
-  def initialize(kt_string)
-    unless kt_string.class == String
-      raise ArgumentError, 'Kennitala needs to be provided as a string'
-    end
-    sanitised_kt = sanitize(kt_string)
-    raise ArgumentError, 'Kennitala is invalid' if sanitised_kt.nil?
-    @value = sanitised_kt
-  end
-
-  # Get the type of entity - If it is a person or an organization
-  #
-  # @return [String] Either 'person' or 'company'
-  def entity_type
-    date_integer = @value[0, 2].to_i
-    return 'person' if date_integer < 32
-    return 'company' if (date_integer > 40) && (date_integer < 71)
-    false
-  end
-
-  # Check if the entity is a company
-  #
-  # @return [Boolean]
-  def company?
-    date_integer = @value[0, 2].to_i
-    return true if (date_integer > 40) && (date_integer < 71)
-    false
-  end
-
-  # Check if the entity is a person
-  #
-  # @return [Type] description of returned object
-  def person?
-    date_integer = @value[0, 2].to_i
-    return true if date_integer < 32
-    false
-  end
-
-  # Get the year of birth or registration
-  #
-  # @return [Fixnum]
-  def year
-    century = (10 + @value[9].to_i) * 100
-    year = @value[4, 2].to_i
-    return century + year if (1800..1900).cover?(century)
-    return 2000 + year if century == 1000
-  end
-
-  # Get the day of the month of birth or registration
-  #
-  # @return [Fixnum]
-  def day
-    date_integer = @value[0, 2].to_i
-    return @value[0, 2].to_i if date_integer < 32
-    return @value[0, 2].to_i - 40 if (date_integer > 40) && (date_integer < 71)
-  end
-
-  # Get a numeric representation of the month of birth or registration
-  #
-  # @return [Fixnum]
-  def month
-    @value[2, 2].to_i
-  end
-
-  # Get the age of entity in years. Useful when dealing with age restrictions.
-  #
-  # @return [Fixnum]
-  def age
-    year_diff = Date.today.year - to_date.year
-    month_diff = Date.today.month - to_date.month
-    day_diff = Date.today.month - to_date.month
-
-    return year_diff -= 1 if month_diff < 0 || (month_diff == 0 && day_diff < 0)
-    year_diff
-  end
-
-  # Cast the kennitala to a Date object
-  #
-  # @return [Date]
-  def to_date
-    Date.new(year, month, day)
-  end
-
-  # Cast the kennitala to a String object
-  #
-  # @return [Date]
-  def to_s
-    @value.to_s
-  end
-
-  private
-
-  # Sanitize the kennitala
-  #
-  # @param [String] kt_string Unsanitised string representing a kennitala
-  # @return [String] Sanitized kennitala
-  def sanitize(kt_string)
-    sanitized_kt = kt_string.gsub(/\D/, '')
-    checks = check_checksum(sanitized_kt)
-    return sanitized_kt if (/\A\d{10}\z/ =~ sanitized_kt) && (checks == true)
-  end
-
-  # Calculate the checksum
-  #
-  # @param [String] kt_string Sanitized kennitala
-  # @return [Fixnum] The checksum
-  def checksum(kt_string)
-    checksum = 0
-    multipliers = [3, 2, 7, 6, 5, 4, 3, 2]
-    multipliers.each_with_index do |multiplier, index|
-      checksum += multiplier * kt_string[index].to_i
-    end
-    checksum
-  end
-
-  # Calculate remainder and check validity of the check digit
-  #
-  # @param [String] kt_string Sanitized kennitala
-  # @return [Boolean, nil] true on success, nil if the check digit is invalid
-  def check_checksum(kt_string)
-    remainder = checksum(kt_string).modulo(11)
-
-    # A kennitala with a remainder of 10 is always considered to be invalid
-    return nil if remainder == 10
-
-    # The check digit should be 11 minus the remainder,
-    # unless the remainder is 0, then the theck digit becomes 0.
-    expected_check_digit = 11 - remainder
-    expected_check_digit = 0 if remainder == 0
-
-    actual_check_digit = kt_string[8].to_i
-
-    return true if expected_check_digit == actual_check_digit
-  end
-end
+require 'iceland/postal_codes'
+require 'iceland/kennitala'
+require 'iceland/kennitala_string'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: iceland
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Stefan Vignir
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-05-13 00:00:00.000000000 Z
+date: 2016-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -86,6 +86,9 @@ files:
 - bin/setup
 - iceland.gemspec
 - lib/iceland.rb
+- lib/iceland/kennitala.rb
+- lib/iceland/kennitala_string.rb
+- lib/iceland/postal_codes.rb
 - lib/iceland/version.rb
 - lib/postcodes.yml
 homepage: https://github.com/stefanvignir/iceland_gem