Module: UnitedStates

Defined in:
lib/united_states.rb,
lib/united_states/version.rb,
lib/united_states/state/name.rb,
lib/united_states/state/designation.rb,
lib/united_states/state/postal_code.rb

Overview

Top-level namespace for this gem.

Defined Under Namespace

Modules: State Classes: NoDesignationFoundError

Constant Summary collapse

VERSION = 
'1.2.2'.freeze

Class Method Summary collapse

Class Method Details

.[](name_or_postal_code) ⇒ UnitedStates::State::Desgination

Returns the State Desgination matching the provided name or postal code.

Examples:

UnitedStates['louisiana'] # => UnitedSt...Designation
UnitedStates[:Ms] # => UnitedSt...Designation
UnitedStates[:marx] # => NoDesignationFoundError

Parameters:

  • name_or_postal_code (String)

Returns:

  • (UnitedStates::State::Desgination) —

    the State Desgination matching the provided name or postal code.

Raises:



29
30
31
32
33
34
 
# File 'lib/united_states.rb', line 29

def self.[](name_or_postal_code)
  name_or_postal_code = name_or_postal_code.to_s
  invalid_postal_code = name_or_postal_code.length != 2
  return find_by_name(name_or_postal_code) if invalid_postal_code
  find_by_postal_code(name_or_postal_code)
end

.all ⇒ Array<UnitedStates::State::Designation>

Returns a collection of all U.S. State Designations.

Returns:



38
39
40
 
# File 'lib/united_states.rb', line 38

def self.all
  array_from_yaml_file(path: config_path)
end

.array_from_hashes(*hashes) ⇒ Array<UnitedStates::State::Designation>

Returns a collection of state designations made from the given hash attributes.

Examples:

UnitedStates.array_from_hashes(
  { name: 'Florida', postal_code: 'FL' },
  { name: 'Iowa', postal_code: 'IA'})

Parameters:

  • hashes (Array<Hash>) —

    a collection of attributes as hashes

Returns:



50
51
52
53
54
 
# File 'lib/united_states.rb', line 50

def self.array_from_hashes(*hashes)
  hashes.map do |hash|
    UnitedStates::State::Designation.from_hash(hash)
  end
end

.array_from_yaml(yaml) ⇒ Array<UnitedStates::State::Designation>

Returns a collection of state designations made from the given hash attributes.

Examples:

require 'united_states'

UnitedStates.array_from_yaml(
  { Washington: { postal_code: 'WA' } }.to_yaml)
# => [<UnitedStates::State::Designation...>]

Parameters:

  • yaml (String) —

    a String representation of YAML.

Returns:

Raises:

  • UnitedStates::State::PostalCode::StringTooLongError if a designation has a postal code that too long

  • UnitedStates::State::PostalCode::StringTooShortError if a designation has no postal code defined or is too short



70
71
72
73
74
75
76
 
# File 'lib/united_states.rb', line 70

def self.array_from_yaml(yaml)
  return [] unless YAML.safe_load(yaml)
  YAML.safe_load(yaml).map do |key, value|
    UnitedStates::State::Designation.new(
      name: key, postal_code: value && value.fetch('postal_code', ''))
  end
end

.array_from_yaml_file(path:) ⇒ Array<UnitedStates::State::Designation>

Returns a collection of state designations made from the YAML file.

Examples:

require 'united_states'

UnitedStates.array_from_yaml_file(path: './states.yml')
# => [<UnitedStates::State::Designation...>]

Parameters:

  • path (String) —

    the path to the YAML file

Returns:

Raises:

  • UnitedStates::State::PostalCode::StringTooLongError if a designation has a postal code that too long

  • UnitedStates::State::PostalCode::StringTooShortError if a designation has no postal code defined or is too short



91
92
93
94
95
96
 
# File 'lib/united_states.rb', line 91

def self.array_from_yaml_file(path:)
  pathname = Pathname.new(path)
  return array_from_yaml(pathname.read) if pathname.exist?
  raise "\"#{path}\" does not exist.\n"\
        'Please supply a path to a YAML file.'
end

.config_path ⇒ String

Returns the path to the Designations yaml file.

Returns:

  • (String) —

    the path to the Designations yaml file



100
101
102
 
# File 'lib/united_states.rb', line 100

def self.config_path
  Pathname.new(__FILE__).parent.join('united_states/designations.yml')
end

.find_by_name(name) ⇒ UnitedStates::State::Desgination

Returns the State Desgination matching the provided name.

Examples:

UnitedStates.find_by_name('louisiana') # => UnitedSt...Designation
UnitedStates.find_by_name('marx') # => NoDesignationFoundError

Parameters:

  • name (String)

Returns:

  • (UnitedStates::State::Desgination) —

    the State Desgination matching the provided name.

Raises:



112
113
114
115
116
 
# File 'lib/united_states.rb', line 112

def self.find_by_name(name)
  name = UnitedStates::State::Name.new(name)
  all.find { |designation| designation.name == name } || raise(
    NoDesignationFoundError, "No State named, \"#{name},\" was found.")
end

.find_by_postal_code(postal_code) ⇒ UnitedStates::State::Designation

Returns the state Designation matching the provided postal code.

Examples:

UnitedStates.find_by_postal_code('la') # => UnitedSt...Designation
UnitedStates.find_by_postal_code('xx') # => NoDesignationFoundError

Parameters:

  • postal_code (String)

Returns:

Raises:



126
127
128
129
130
131
 
# File 'lib/united_states.rb', line 126

def self.find_by_postal_code(postal_code)
  postal_code = UnitedStates::State::PostalCode.new(postal_code)
  all.find { |designation| designation.postal_code == postal_code } || raise(
    NoDesignationFoundError,
    "No State with postal code, \"#{postal_code},\" was found.")
end

.names ⇒ Array<UnitedStates::State::Name>

Returns a collection of all U.S. State Names.

Returns:



135
136
137
 
# File 'lib/united_states.rb', line 135

def self.names
  all.map(&:name)
end

.postal_codes ⇒ Array<UnitedStates::State::PostalCode>

Returns a collection of all U.S. State postal codes.

Returns:



141
142
143
 
# File 'lib/united_states.rb', line 141

def self.postal_codes
  all.map(&:postal_code)
end