module UnitedStates
Top-level namespace for this gem.
Constants
- VERSION
Public Class Methods
@example
UnitedStates['louisiana'] # => UnitedSt...Designation UnitedStates[:Ms] # => UnitedSt...Designation UnitedStates[:marx] # => NoDesignationFoundError
@param name_or_postal_code [String] @return [UnitedStates::State::Desgination]
the State Desgination matching the provided name or postal code.
@raise [NoDesignationFoundError]
if no state Designation exists with the given name or postal code
# 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
@return [Array<UnitedStates::State::Designation>]
a collection of all U.S. State Designations.
# File lib/united_states.rb, line 38 def self.all array_from_yaml_file(path: config_path) end
@example
UnitedStates.array_from_hashes( { name: 'Florida', postal_code: 'FL' }, { name: 'Iowa', postal_code: 'IA'})
@param hashes [Array<Hash>]
a collection of attributes as hashes
@return [Array<UnitedStates::State::Designation>]
a collection of state designations made from the given hash attributes
# 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
@example
require 'united_states' UnitedStates.array_from_yaml( { Washington: { postal_code: 'WA' } }.to_yaml) # => [<UnitedStates::State::Designation...>]
@param yaml [String]
a String representation of YAML.
@return [Array<UnitedStates::State::Designation>]
a collection of state designations made from the given hash attributes
@raise UnitedStates::State::PostalCode::StringTooLongError
if a designation has a postal code that too long
@raise UnitedStates::State::PostalCode::StringTooShortError
if a designation has no postal code defined or is too short
# 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
@example
require 'united_states' UnitedStates.array_from_yaml_file(path: './states.yml') # => [<UnitedStates::State::Designation...>]
@param path [String]
the path to the YAML file
@return [Array<UnitedStates::State::Designation>]
a collection of state designations made from the YAML file
@raise UnitedStates::State::PostalCode::StringTooLongError
if a designation has a postal code that too long
@raise UnitedStates::State::PostalCode::StringTooShortError
if a designation has no postal code defined or is too short
# 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
@return [String]
the path to the Designations yaml file
# File lib/united_states.rb, line 100 def self.config_path Pathname.new(__FILE__).parent.join('united_states/designations.yml') end
@example
UnitedStates.find_by_name('louisiana') # => UnitedSt...Designation UnitedStates.find_by_name('marx') # => NoDesignationFoundError
@param name [String] @return [UnitedStates::State::Desgination]
the State Desgination matching the provided name.
@raise [NoDesignationFoundError]
if no state Designation exists with the given name
# 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
@example
UnitedStates.find_by_postal_code('la') # => UnitedSt...Designation UnitedStates.find_by_postal_code('xx') # => NoDesignationFoundError
@param postal_code [String] @return [UnitedStates::State::Designation]
the state Designation matching the provided postal code.
@raise [NoDesignationFoundError]
if no state Designation exists with the given postal code
# 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
@return [Array<UnitedStates::State::Name>]
a collection of all U.S. State Names.
# File lib/united_states.rb, line 135 def self.names all.map(&:name) end
@return [Array<UnitedStates::State::PostalCode>]
a collection of all U.S. State postal codes.
# File lib/united_states.rb, line 141 def self.postal_codes all.map(&:postal_code) end