fips_lookup 0.3.0 → 0.4

data/lib/fips/subdivision.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "csv"
+
+# FIPS::Subdivision
+module FIPS
+  class Subdivision
+    class << self
+      def lookup(**params)
+        fips = params.fetch(:fips, nil)
+        state = params.fetch(:state, nil)
+        county = params.fetch(:county, nil)
+        subdivision = params.fetch(:subdivision, nil)
+
+        unless fips.nil? || (fips.is_a?(String) && fips.match?(/\A(?:\d{2}|\d{3}|\d{5}|\d{10})\z/))
+          raise ArgumentError, "FIPS input must be a 2, 3, 5, or 10 digit string"
+        end
+        raise ArgumentError, "State input must be a non-empty string" unless state.nil? || (state.is_a?(String) && !state.strip.empty?)
+        raise ArgumentError, "County input must be a non-empty string" unless county.nil? || (county.is_a?(String) && !county.strip.empty?)
+        unless subdivision.nil? || (subdivision.is_a?(String) && !subdivision.strip.empty?)
+          raise ArgumentError, "Subdivision input must be a non-empty string"
+        end
+
+        state_abbr = determine_state_abbr(fips, state)
+        raise ArgumentError, "Could not determine state abbreviation from parameters provided: #{params.inspect}" if state_abbr.nil?
+
+        location = identify_with_fips(fips, state, county, subdivision, state_abbr)
+        return location unless location.nil?
+
+        return by_name(state_abbr, county, subdivision) if %i[state county subdivision].all? { |key| !params[key].nil? }
+
+        raise ArgumentError, "cannot determine subdivision: no valid parameters provided"
+      end
+
+      def all(state:, county: nil)
+        raise ArgumentError, "State input must be a non-empty string" unless state.is_a?(String) && !state.strip.empty?
+        raise ArgumentError, "County input must be a non-empty string" unless county.nil? || (county.is_a?(String) && !county.strip.empty?)
+
+        state_abbr = FIPS::State.lookup(state: state)[:abbr]
+        raise ArgumentError, "Could not determine state abbreviation from state: #{state}" if state_abbr.nil?
+
+        county_name = normalize_name(county)
+        records = CSV.read(file_path(state_abbr))
+        records.map do |row|
+          formatted_subdivision(row)
+        end.select { |record| county.nil? || normalize_name(record[:county_name]) == county_name }
+      end
+
+      def file_path(state_abbr)
+        File.expand_path("../data/subdivision/#{state_abbr.upcase}.csv", __dir__)
+      end
+
+      private
+
+      def determine_state_abbr(fips, state)
+        return FIPS::State.lookup(state: state)[:abbr] unless state.nil?
+
+        FIPS::State.fips_to_abbr(fips[0, 2]) unless fips.nil? || fips.length < 2
+      end
+
+      def identify_with_fips(fips, state, county, subdivision, state_abbr = nil)
+        return nil if fips.nil?
+
+        case fips.length
+        when 2
+          return nil if county.nil? || subdivision.nil?
+
+          by_name(FIPS::State.fips_to_abbr(fips), county, subdivision)
+        when 3
+          return nil if state.nil? || subdivision.nil?
+
+          state_abbr = FIPS::State.lookup(state: state)[:abbr]
+          by_county_fips_and_sub_name(state_abbr, fips, subdivision)
+        when 5
+          unless subdivision.nil?
+            state_abbr = FIPS::State.fips_to_abbr(fips[0, 2])
+            return by_county_fips_and_sub_name(state_abbr, fips[2, 3], subdivision)
+          end
+          return nil if state.nil?
+
+          state_abbr = FIPS::State.lookup(state: state)[:abbr]
+          by_state_and_sub_fips(state_abbr, fips)
+        when 10
+          by_fips(fips)
+        end
+      end
+
+      def by_state_and_sub_fips(state_abbr, fips)
+        subdivision = state_index(state_abbr)[:by_subdivision_fips][fips]
+        return subdivision unless subdivision.nil?
+
+        raise FIPS::NotFoundError, "No subdivision found matching fips: #{fips}"
+      end
+
+      def by_fips(fips)
+        state_abbr = FIPS::State.fips_to_abbr(fips[0, 2])
+        subdivision = state_index(state_abbr)[:by_full_fips][fips]
+        return subdivision unless subdivision.nil?
+
+        raise FIPS::NotFoundError, "No subdivision found matching fips: #{fips}"
+      end
+
+      def by_name(state_abbr, county, subdivision)
+        key = [normalize_name(county), normalize_name(subdivision)]
+        match = state_index(state_abbr)[:by_county_and_name][key]
+        return match unless match.nil?
+
+        raise FIPS::NotFoundError, "No subdivision found matching: #{subdivision} in #{county}"
+      end
+
+      def by_county_fips_and_sub_name(state_abbr, county_fips, subdivision)
+        key = [county_fips, normalize_name(subdivision)]
+        match = state_index(state_abbr)[:by_county_fips_and_name][key]
+        return match unless match.nil?
+
+        nil
+      end
+
+      def state_index(state_abbr)
+        indexes = subdivision_indexes
+        indexes[state_abbr] ||= build_state_index(state_abbr)
+      end
+
+      def subdivision_indexes
+        @subdivision_indexes ||= {}
+      end
+
+      def build_state_index(state_abbr)
+        records = CSV.read(file_path(state_abbr)).map { |row| formatted_subdivision(row) }
+        {
+          records: records,
+          by_full_fips: records.to_h { |record| [record[:fips], record] },
+          by_subdivision_fips: records.each_with_object({}) do |record, index|
+            subdivision_fips = record[:fips][5, 5]
+            index[subdivision_fips] ||= record
+          end,
+          by_county_fips_and_name: records.to_h do |record|
+            [[record[:fips][2, 3], normalize_name(record[:name])], record]
+          end,
+          by_county_and_name: records.to_h do |record|
+            [[normalize_name(record[:county_name]), normalize_name(record[:name])], record]
+          end
+        }
+      end
+
+      def normalize_name(name)
+        name.to_s.strip.downcase
+      end
+
+      def formatted_subdivision(row)
+        {
+          state_abbr: row[0],
+          fips: row[1] + row[2] + row[4],
+          county_name: row[3],
+          gnis: row[5],
+          name: row[6],
+          class_code: row[7],
+          status: row[8]
+        }
+      end
+    end
+  end
+end

data/lib/fips/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FIPS
+  VERSION = "0.4"
+end

data/lib/fips.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+
+module FIPS
+  loader = Zeitwerk::Loader.for_gem
+  loader.inflector.inflect("fips" => "FIPS")
+  loader.setup
+
+  class NotFoundError < StandardError
+  end
+
+  class << self
+    def lookup(**params)
+      fips = params.fetch(:fips, nil)
+      state = params.fetch(:state, nil)
+      county = params.fetch(:county, nil)
+      subdivision = params.fetch(:subdivision, nil)
+      return identify_by_fips(fips, state, county, subdivision) unless fips.nil?
+
+      return FIPS::State.lookup(state: state) if !state.nil? && county.nil? && subdivision.nil?
+      return FIPS::County.lookup(state: state, county: county) if !state.nil? && !county.nil? && subdivision.nil?
+
+      if !state.nil? && !county.nil? && !subdivision.nil?
+        return FIPS::Subdivision.lookup(state: state, county: county,
+                                        subdivision: subdivision)
+      end
+
+      raise ArgumentError, "Insufficient parameters to identify a state, county, or subdivision: #{params.inspect}"
+    end
+
+    private
+
+    def identify_by_fips(fips, state, county, subdivision)
+      raise ArgumentError, "FIPS input must be a string" unless fips.is_a?(String)
+
+      case fips.length
+      when 2
+        return FIPS::Subdivision.lookup(fips: fips, county: county, subdivision: subdivision) if !county.nil? && !subdivision.nil?
+        return FIPS::County.lookup(fips: fips, county: county) if !county.nil? && subdivision.nil?
+        unless county.nil? && subdivision.nil?
+          raise ArgumentError, "A 2-digit FIPS code requires both county and subdivision names for subdivision lookup"
+        end
+
+        FIPS::State.lookup(fips: fips)
+      when 3
+        return FIPS::Subdivision.lookup(fips: fips, state: state, subdivision: subdivision) if !state.nil? && !subdivision.nil?
+        unless !state.nil? && county.nil? && subdivision.nil?
+          raise ArgumentError, "A 3-digit FIPS code requires a state for county lookup, or state and subdivision for subdivision lookup"
+        end
+
+        FIPS::County.lookup(fips: fips, state: state)
+      when 5
+        return FIPS::Subdivision.lookup(fips: fips, subdivision: subdivision) unless subdivision.nil?
+        return FIPS::Subdivision.lookup(fips: fips, state: state) if !state.nil? && county.nil?
+        unless state.nil? && county.nil? && subdivision.nil?
+          raise ArgumentError, "A 5-digit FIPS code accepts either state for subdivision FIPS or subdivision name for county FIPS"
+        end
+
+        FIPS::County.lookup(fips: fips)
+      when 10
+        FIPS::Subdivision.lookup(fips: fips)
+      else
+        raise ArgumentError, "FIPS code (#{fips}) must identify a state, county, or subdivision"
+      end
+    end
+  end
+end

data/sig/fips.rbs

@@ -0,0 +1,50 @@
+module FIPS
+  VERSION: String
+
+  type state_record = {
+    fips: String,
+    abbr: String,
+    name: String,
+    ansi: String
+  }
+
+  type county_record = {
+    state_abbr: String,
+    fips: String,
+    gnis: String,
+    name: String,
+    class_code: String,
+    status: String
+  }
+
+  type subdivision_record = {
+    state_abbr: String,
+    fips: String,
+    county_name: String,
+    gnis: String,
+    name: String,
+    class_code: String,
+    status: String
+  }
+
+  type lookup_record = state_record | county_record | subdivision_record
+  class NotFoundError < StandardError
+  end
+
+  def self.lookup: (?fips: String?, ?state: String?, ?county: String?, ?subdivision: String?) -> lookup_record
+
+  class State
+    def self.lookup: (?fips: String?, ?state: String?) -> state_record
+    def self.all: () -> Array[state_record]
+  end
+
+  class County
+    def self.lookup: (?fips: String?, ?state: String?, ?county: String?) -> county_record
+    def self.all: (state: String state) -> Array[county_record]
+  end
+
+  class Subdivision
+    def self.lookup: (?fips: String?, ?state: String?, ?county: String?, ?subdivision: String?) -> subdivision_record
+    def self.all: (state: String state, ?county: String?) -> Array[subdivision_record]
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fips_lookup
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: '0.4'
 platform: ruby
 authors:
 - Erik Barroso
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
 - !ruby/object:Gem::Dependency
   name: irb
   requirement: !ruby/object:Gem::Requirement
@@ -51,6 +65,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: benchmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -222,16 +250,17 @@ files:
 - lib/data/subdivision/WI.csv
 - lib/data/subdivision/WV.csv
 - lib/data/subdivision/WY.csv
-- lib/fips_lookup.rb
-- lib/fips_lookup/county.rb
-- lib/fips_lookup/state.rb
-- lib/fips_lookup/subdivision.rb
-- lib/fips_lookup/version.rb
-- sig/fips_lookup.rbs
+- lib/fips.rb
+- lib/fips/county.rb
+- lib/fips/state.rb
+- lib/fips/subdivision.rb
+- lib/fips/version.rb
+- sig/fips.rbs
 homepage: https://github.com/3barroso/fips_lookup
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -239,7 +268,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/lib/fips_lookup/county.rb

@@ -1,65 +0,0 @@
-# frozen_string_literal: true
-
-# County related section of FipsLookup module
-module FipsLookup
-  class << self
-    def county(state_param:, county_param:, return_nil: false)
-      state_code = find_state_code(state_param: state_param, return_nil: return_nil)
-      return {} if state_code.nil?
-
-      lookup = [state_code, county_param.upcase]
-      @county_fips ||= {}
-      @county_fips[lookup] ||= county_lookup(state_code, county_param, return_nil)
-    end
-
-    def fips_county(fips:, return_nil: false)
-      unless fips.is_a?(String) && fips.length == 5
-        return_nil ? (return nil) : (raise StandardError, "FIPS input must be 5 digit string")
-      end
-
-      state_code = find_state_code(state_param: fips[0..1], return_nil: return_nil)
-      return nil if state_code.nil?
-
-      CSV.foreach(county_file(state_code: state_code)) do |county_row|
-        # state_code (AL), state fips (01), county fips (001), name (Augtauga County), county gnis(00161526), class code (H1), status (A)
-        return [county_row[3], state_code] if county_row[2] == fips[2..4]
-      end
-
-      raise StandardError, "Could not find county with fips: #{fips[2..4]}, in: #{state_code}" unless return_nil
-    end
-
-    def county_file(state_code:)
-      file_path = "#{File.expand_path("..", __dir__)}/data/county/#{state_code}.csv"
-      file_path if File.exist?(file_path)
-    end
-
-    private
-
-    def county_lookup(state_code, county_param, return_nil)
-      upcase_param = county_param.upcase
-      CSV.foreach(county_file(state_code: state_code)) do |row|
-        return formatted_county(row) if match_county?(row, upcase_param)
-
-        # keep? Memoize as file is being read but match isn't found ~ loses lookup flexiblity in county param + increases performacne?
-        @county_fips[[row[0], row[3].upcase]] = formatted_county(row) unless @county_fips.key?([row[0], row[3].upcase])
-      end
-      return_nil ? (return {}) : (raise StandardError, "No county found matching: #{county_param}" unless return_nil)
-    end
-
-    def match_county?(row, param)
-      # row => state (AL), state fips (01), county fips (001), name (Augtauga County), county gnis (00161526),  class code (H1), status (A)
-      row[3].upcase == param || row[4] == param || row[2] == param || "#{row[1]}#{row[2]}" == param
-    end
-
-    def formatted_county(row)
-      {
-        state_code: row[0],
-        fips: (row[1] + row[2]),
-        gnis: row[4],
-        name: row[3],
-        class_code: row[5],
-        status: row[6]
-      }
-    end
-  end
-end

data/lib/fips_lookup/state.rb

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-# State related section of FipsLookup module
-module FipsLookup
-  class << self
-    def state(state_param:, return_nil: false)
-      @state_fips ||= {}
-      @state_fips[state_param] ||= state_lookup(state_param, return_nil)
-    end
-
-    def find_state_code(state_param:, return_nil: false)
-      return state_param.upcase if STATE_CODES.key?(state_param.upcase)
-      return STATE_CODES.key(state_param) if STATE_CODES.value?(state_param)
-
-      state(state_param: state_param, return_nil: return_nil)[:code]
-    end
-
-    def state_file
-      "#{File.expand_path("..", __dir__)}/data/state.csv"
-    end
-
-    private
-
-    def state_lookup(state_param, return_nil = false)
-      upstate_param = state_param.upcase
-      CSV.foreach(state_file) do |state_row|
-        return formatted_state(state_row) if state_match_row?(state_row, upstate_param)
-      end
-      return_nil ? (return {}) : (raise StandardError, "No state found matching: #{state_param}")
-    end
-
-    def state_match_row?(row, param)
-      # row => state fips (01), state code (AL), state name (Alabama), ansi (01779775)
-      row[0] == param || row[1] == param || row[2].upcase == param || row[3] == param
-    end
-
-    def formatted_state(row)
-      {
-        fips: row[0],
-        code: row[1],
-        name: row[2],
-        ansi: row[3]
-      }
-    end
-  end
-end

data/lib/fips_lookup/subdivision.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-# Subdivision related section of FIPS module
-module FipsLookup
-  class << self
-    def subdivision(state_param:, subdivision_param:, return_nil: false)
-      state_code = find_state_code(state_param: state_param, return_nil: return_nil)
-      return {} if state_code.nil?
-
-      lookup = [state_code, subdivision_param.upcase]
-      @subdivision_fips ||= {}
-      @subdivision_fips[lookup] ||= subdivision_lookup(state_code, subdivision_param, return_nil)
-    end
-
-    def subdivision_file(state_code:)
-      file_path = "#{File.expand_path("..", __dir__)}/data/subdivision/#{state_code}.csv"
-      file_path if File.exist?(file_path)
-    end
-
-    private
-
-    def subdivision_lookup(state_code, subdivision_param, return_nil)
-      upcase_param = subdivision_param.upcase
-      CSV.foreach(subdivision_file(state_code: state_code)) do |subdivision_row|
-        return formatted_subdivision(subdivision_row) if match_subdivision?(subdivision_row, upcase_param)
-      end
-      return_nil ? (return {}) : (raise StandardError, "No subdivision found matching: #{subdivision_param}" unless return_nil)
-    end
-
-    def match_subdivision?(row, param)
-      # row => state_code (AL), state fips (01), county fips (001), county name (Augtauga County)
-      #   row => subdivision name(Autaugaville CCD), class code (Z5), status (S)
-      row[6].upcase == param || row[4] == param || row[5] == param
-    end
-
-    def formatted_subdivision(row)
-      {
-        state_code: row[0],
-        fips: row[1] + row[2] + row[4],
-        county_name: row[3],
-        gnis: row[5],
-        name: row[6],
-        class_code: row[7],
-        status: row[8]
-      }
-    end
-  end
-end

data/lib/fips_lookup/version.rb

@@ -1,5 +0,0 @@
-# frozen_string_literal: true
-
-module FipsLookup
-  VERSION = "0.3.0"
-end

data/lib/fips_lookup.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-require "csv"
-require_relative "fips_lookup/version"
-require_relative "fips_lookup/subdivision"
-require_relative "fips_lookup/county"
-require_relative "fips_lookup/state"
-
-# parent section of module defining constants, requiring relative worker methods
-module FipsLookup
-  STATE_CODES = { "AL" => "01", "AK" => "02", "AZ" => "04", "AR" => "05", "CA" => "06", "CO" => "08",
-                  "CT" => "09", "DE" => "10", "DC" => "11", "FL" => "12", "GA" => "13", "HI" => "15",
-                  "ID" => "16", "IL" => "17", "IN" => "18", "IA" => "19", "KS" => "20", "KY" => "21",
-                  "LA" => "22", "ME" => "23", "MD" => "24", "MA" => "25", "MI" => "26", "MN" => "27",
-                  "MS" => "28", "MO" => "29", "MT" => "30", "NE" => "31", "NV" => "32", "NH" => "33",
-                  "NJ" => "34", "NM" => "35", "NY" => "36", "NC" => "37", "ND" => "38", "OH" => "39",
-                  "OK" => "40", "OR" => "41", "PA" => "42", "RI" => "44", "SC" => "45", "SD" => "46",
-                  "TN" => "47", "TX" => "48", "UT" => "49", "VT" => "50", "VA" => "51", "WA" => "53",
-                  "WV" => "54", "WI" => "55", "WY" => "56", "AS" => "60", "GU" => "66", "MP" => "69",
-                  "PR" => "72", "UM" => "74", "VI" => "78" }.freeze
-
-  class << self
-    attr_accessor :county_fips, :state_fips, :subdivision_fips
-  end
-end

data/sig/fips_lookup.rbs

@@ -1,4 +0,0 @@
-module FipsLookup
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end