module SwissMatch::Location

This module only contains the version of the swissmatch-location gem

Constants

Version

The version of the swissmatch-location gem.

Attributes

data[R]

@return [SwissMatch::Location::DataFiles, nil] The data source used

Public Class Methods

canton(name_or_plate) click to toggle source

@param [String] name_or_plate

The name or license_tag of the canton

@return [SwissMatch::Canton]

The canton with the given name or license_tag
# File lib/swissmatch/location.rb, line 50
def self.canton(name_or_plate)
  @data.cantons[name_or_plate]
end
cantons() click to toggle source

@return [SwissMatch::Cantons]

All known cantons
# File lib/swissmatch/location.rb, line 56
def self.cantons
  @data.cantons
end
cities_for_zip_code(code, only_types=nil, locale=nil) click to toggle source

@param [String, Integer] code

The 4 digit zip code

@param [nil, Array<Integer>] only_types

An array of zip code types (see ZipCode#type) which the returned zip codes must match.

@param [nil, Symbol] locale

Return the names in the given locale, defaults to nil/:native (nil and :native are
treated the same and will return the native names)

@return [Array<String>]

A list of unique names matching the parameters (4 digit code, type, locale).
# File lib/swissmatch/location.rb, line 185
def self.cities_for_zip_code(code, only_types=nil, locale=nil)
  codes = @data.zip_codes.by_code(code.to_i)
  return [] unless codes
  codes = codes.select { |code| only_types.include?(code.type) } if only_types
  names = case locale
    when :native,nil then codes.map(&:name)
    when :de then codes.map(&:name_de)
    when :fr then codes.map(&:name_fr)
    when :it then codes.map(&:name_it)
    when :rt then codes.map(&:name_rt)
    else raise ArgumentError, "Invalid locale #{locale}"
  end

  names.uniq
end
city(name) click to toggle source

@param [String] name

The name for which to return matching zip codes

@return [Array<SwissMatch::ZipCode>]

Zip codes whose name equals the given name
# File lib/swissmatch/location.rb, line 171
def self.city(name)
  @data.zip_codes.by_name(name)
end
communities() click to toggle source

@return [SwissMatch::Communities]

All communities
# File lib/swissmatch/location.rb, line 93
def self.communities
  @data.communities
end
community(key) click to toggle source

@param [Integer, String] key

The name or community number of the community

@return [SwissMatch::Community]

The community with the given name or community number
# File lib/swissmatch/location.rb, line 80
def self.community(key)
  case key
    when Integer
      @data.communities.by_community_number(key)
    when String
      @data.communities.by_name(key)
    else
      raise TypeError, "Expected Integer or String, but got #{key.inspect}:#{key.class}"
  end
end
district(district_number_or_name) click to toggle source

@param [String] district_number_or_name

The district_number or name of the district

@return [SwissMatch::District]

The district with the given district_number or name
# File lib/swissmatch/location.rb, line 65
def self.district(district_number_or_name)
  @data.districts[district_number_or_name]
end
districts() click to toggle source

@return [SwissMatch::Districts]

All known districts
# File lib/swissmatch/location.rb, line 71
def self.districts
  @data.districts
end
load(data_source=nil) click to toggle source

Loads the swissmatch data

@param [SwissMatch::Location::DataFiles] data_source

A valid data-source.

@return [self]

Returns self
# File lib/swissmatch/location.rb, line 208
def self.load(data_source=nil)
  @data = data_source || DataFiles.new
  @data.load!

  self
end
zip_code(code, city_or_add_on=nil) click to toggle source

Returns a single zip code. A zip code can be uniquely identified by any of:

  • Its ordering_number (ONRP, a 4 digit Integer)

  • Its zip code (4 digit Integer) and add-on (2 digit Integer)

  • Its zip code (4 digit Integer) and any official name (String)

The data can be passed in different ways, e.g. all numbers can be passed either as a String or as an Integer. The identification by zip code and add-on can be done by either using a combined 6 digit number (e.g. 800000 for “8000 Zürich”), or by passing 2 arguments, passing the zip code and the add-on separately.

IMPORTANT

You must be aware, that passing a single 4-digit code to SwissMatch::zip_code uses the ONRP, and NOT the zip-code. The 4 digit zip code alone does NOT uniquely identify a zip code.

@example Get a zip code by ONRP

SwissMatch.zip_code(4384)           # => #<SwissMatch::ZipCode:003ff996cf8d3c 8000 Zürich>

@example Get a zip code by 4-digit code and add-on

SwissMatch.zip_code(8000, 0)        # => #<SwissMatch::ZipCode:003ff996cf8d3c 8000 Zürich>
SwissMatch.zip_code("8000", "00")   # => #<SwissMatch::ZipCode:003ff996cf8d3c 8000 Zürich>
SwissMatch.zip_code(800000)         # => #<SwissMatch::ZipCode:003ff996cf8d3c 8000 Zürich>
SwissMatch.zip_code("800000")       # => #<SwissMatch::ZipCode:003ff996cf8d3c 8000 Zürich>

@example Get a zip code by 4-digit code and name

SwissMatch.zip_code(8000, "Zürich") # => #<SwissMatch::ZipCode:003ff996cf8d3c 8000 Zürich>
SwissMatch.zip_code(8000, "Zurigo") # => #<SwissMatch::ZipCode:003ff996cf8d3c 8000 Zürich>

@param [String, Integer] code

The 4 digit zip code as Integer or String

@param [String, Integer] city_or_add_on

Either the 2 digit zip-code add-on as string or integer, or the city name as a
String in utf-8.

@return [SwissMatch::ZipCode]

The zip codes with the given code and the given add-on or name.
# File lib/swissmatch/location.rb, line 153
def self.zip_code(code, city_or_add_on=nil)
  case city_or_add_on
    when nil
      @data.zip_codes.by_ordering_number(code.to_i)
    when Integer, /\A\d\d\z/
      @data.zip_codes.by_code_and_add_on(code.to_i, city_or_add_on.to_i)
    when String
      @data.zip_codes.by_code_and_name(code.to_i, city_or_add_on)
    else
      raise ArgumentError, "Invalid second argument, must be nil, ZipCode#add_on or ZipCode#name"
  end
end
zip_codes(code_or_name=nil) click to toggle source

@param [String, Integer] code_or_name

Either the 4 digit zip code as Integer or String, or the city name as a String in
utf-8.

@return [Array<SwissMatch::ZipCode>]

A list of zip codes with the given code or name.
# File lib/swissmatch/location.rb, line 103
def self.zip_codes(code_or_name=nil)
  case code_or_name
    when Integer, /\A\d{4}\z/
      @data.zip_codes.by_code(code_or_name.to_i)
    when String
      @data.zip_codes.by_name(code_or_name)
    when nil
      @data.zip_codes
    else
      raise ArgumentError, "Invalid argument, must be a ZipCode#code (Integer or String) or ZipCode#name (String)"
  end
end