Class: SwissMatch::ZipCode

Inherits:
Object
  • Object
show all
Defined in:
lib/swissmatch/zipcode.rb

Overview

Represents an area, commonly identified by zip-code and city-name. A unique zip code is determined by any of these:

  • the postal ordering number

  • zip code + zip code add on

  • zip code + name (city)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(ordering_number, type, code, add_on, name, names, name_short, names_short, region_names, region_names_short, canton, language, language_alternative, sortfile_member, delivery_by, largest_community, communities, valid_from, valid_until = nil) ⇒ ZipCode

Returns a new instance of ZipCode.



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/swissmatch/zipcode.rb', line 102

def initialize(
  ordering_number,
  type,
  code,
  add_on,
  name,
  names,
  name_short,
  names_short,
  region_names,
  region_names_short,
  canton,
  language,
  language_alternative,
  sortfile_member,
  delivery_by,
  largest_community,
  communities,
  valid_from,
  valid_until = nil
)
  @ordering_number      = ordering_number
  @type                 = type
  @code                 = code
  @add_on               = add_on
  @full_code            = code*100 + add_on
  @language             = language
  @language_alternative = language_alternative
  @name                 = name.is_a?(Name) ? name : Name.new(name, language)
  @name_short           = name_short.is_a?(Name) ? name_short : Name.new(name_short, language)
  @names                = (names || [@name]).sort_by(&:sequence_number)
  @names_short          = (names_short || [@name_short]).sort_by(&:sequence_number)
  @all_names            = @names.map(&:to_s) | @names_short.map(&:to_s)
  @region_names         = region_names
  @region_names_short   = region_names_short
  @canton               = canton
  @sortfile_member      = sortfile_member
  @delivery_by          = delivery_by == :self ? self : delivery_by
  @largest_community    = largest_community
  @communities          = communities
  @valid_from           = valid_from
  @valid_until          = valid_until
end

Instance Attribute Details

#add_on ⇒ Integer (readonly)

Returns The 2 digit numeric code addition, to distinguish zip codes with the same 4 digit code.

Returns:

  • (Integer) —

    The 2 digit numeric code addition, to distinguish zip codes with the same 4 digit code.



41
42
43
 
# File 'lib/swissmatch/zipcode.rb', line 41

def add_on
  @add_on
end

#all_names ⇒ String (readonly)

Note:

This method exists mostly for internal purposes

Returns All names, short and long, as strings, without sequence number nor language.

Returns:

  • (String) —

    All names, short and long, as strings, without sequence number nor language.



64
65
66
 
# File 'lib/swissmatch/zipcode.rb', line 64

def all_names
  @all_names
end

#canton ⇒ SwissMatch::Canton (readonly)

Returns The canton this zip code belongs to.

Returns:



50
51
52
 
# File 'lib/swissmatch/zipcode.rb', line 50

def canton
  @canton
end

#code ⇒ Integer (readonly)

Described under “PLZ light”, as field “Postleitzahl”

Returns:

  • (Integer) —

    The 4 digit numeric zip code



37
38
39
 
# File 'lib/swissmatch/zipcode.rb', line 37

def code
  @code
end

#communities ⇒ SwissMatch::Communities (readonly)

Returns The communities which belong to this zip code.

Returns:



88
89
90
 
# File 'lib/swissmatch/zipcode.rb', line 88

def communities
  @communities
end

#delivery_by ⇒ SwissMatch::ZipCode (readonly)

Returns By which postal office delivery of letters is usually taken care of.

Returns:

  • (SwissMatch::ZipCode) —

    By which postal office delivery of letters is usually taken care of.



80
81
82
 
# File 'lib/swissmatch/zipcode.rb', line 80

def delivery_by
  @delivery_by
end

#full_code ⇒ Integer (readonly)

Returns The 6 digit numeric zip code and add-on (first 4 digits are the code, last 2 digits the add-on).

Returns:

  • (Integer) —

    The 6 digit numeric zip code and add-on (first 4 digits are the code, last 2 digits the add-on).



46
47
48
 
# File 'lib/swissmatch/zipcode.rb', line 46

def full_code
  @full_code
end

#language ⇒ Symbol (readonly)

Returns The main language in the area of this zip code. One of :de, :fr, :it or :rt.

Returns:

  • (Symbol) —

    The main language in the area of this zip code. One of :de, :fr, :it or :rt.



68
69
70
 
# File 'lib/swissmatch/zipcode.rb', line 68

def language
  @language
end

#language_alternative ⇒ SwissMatch::Canton (readonly)

Returns The second most used language in the area of this zip code. One of :de, :fr, :it or :rt.

Returns:

  • (SwissMatch::Canton) —

    The second most used language in the area of this zip code. One of :de, :fr, :it or :rt.



72
73
74
 
# File 'lib/swissmatch/zipcode.rb', line 72

def language_alternative
  @language_alternative
end

#largest_community ⇒ SwissMatch::Community (readonly)

Returns The largest community which belongs to this zip code.

Returns:



84
85
86
 
# File 'lib/swissmatch/zipcode.rb', line 84

def largest_community
  @largest_community
end

#name ⇒ SwissMatch::Name (readonly)

Returns The official name of this zip code (max. 27 characters).

Returns:

  • (SwissMatch::Name) —

    The official name of this zip code (max. 27 characters)



54
55
56
 
# File 'lib/swissmatch/zipcode.rb', line 54

def name
  @name
end

#name_short ⇒ SwissMatch::Name (readonly)

Returns The official name of this zip code (max. 18 characters).

Returns:

  • (SwissMatch::Name) —

    The official name of this zip code (max. 18 characters)



58
59
60
 
# File 'lib/swissmatch/zipcode.rb', line 58

def name_short
  @name_short
end

#ordering_number ⇒ Integer (readonly)

Returns The postal ordering number, also known as ONRP.

Returns:

  • (Integer) —

    The postal ordering number, also known as ONRP



20
21
22
 
# File 'lib/swissmatch/zipcode.rb', line 20

def ordering_number
  @ordering_number
end

#sortfile_member ⇒ Boolean (readonly)

Returns Whether this ZipCode instance is included in the MATsort sortfile.

Returns:

  • (Boolean) —

    Whether this ZipCode instance is included in the MATsort sortfile



76
77
78
 
# File 'lib/swissmatch/zipcode.rb', line 76

def sortfile_member
  @sortfile_member
end

#type ⇒ Integer (readonly)

Described under “PLZ light”, as field “PLZ-Typ”

  • 10 = Domizil- und Fachadressen

  • 20 = Nur Domiziladressen

  • 30 = Nur Fach-PLZ

  • 40 = Firmen-PLZ

  • 80 = Postinterne PLZ (Angabe Zustellpoststelle auf Bundzetteln oder auf Sackanschriften)

Returns:

  • (Integer) —

    The type of the zip code in a numeric code, one of the values 10, 20, 30, 40 or 80.



31
32
33
 
# File 'lib/swissmatch/zipcode.rb', line 31

def type
  @type
end

#valid_from ⇒ Date? (readonly)

Returns The date from which on this zip code starts to be in use.

Returns:

  • (Date, nil) —

    The date from which on this zip code starts to be in use

See Also:



94
95
96
 
# File 'lib/swissmatch/zipcode.rb', line 94

def valid_from
  @valid_from
end

#valid_until ⇒ Date? (readonly)

Returns The date until which on this zip code is in use.

Returns:

  • (Date, nil) —

    The date until which on this zip code is in use

See Also:



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

def valid_until
  @valid_until
end

Instance Method Details

#<=>(other) ⇒ Integer

Compare two zip codes by their ordering number (ONRP)

Returns:

  • (Integer) —

    Returns -1, 0 or 1.



262
263
264
 
# File 'lib/swissmatch/zipcode.rb', line 262

def <=>(other)
  @ordering_number <=> other.ordering_number
end

#eql?(other) ⇒ Boolean

Returns:

  • (Boolean)

See Also:

  • Object#eql?


324
325
326
 
# File 'lib/swissmatch/zipcode.rb', line 324

def eql?(other)
  self.class.eql?(other.class) && @ordering_number.eql?(other.ordering_number)
end

#hash ⇒ Object

See Also:

  • Object#hash


318
319
320
 
# File 'lib/swissmatch/zipcode.rb', line 318

def hash
  [self.class, @ordering_number].hash
end

#in_use?(at = Date.today) ⇒ Boolean

Returns Whether the zip code is in active use at the given date.

Parameters:

  • at (Date) (defaults to: Date.today) —

    The date for which to check the

Returns:

  • (Boolean) —

    Whether the zip code is in active use at the given date.



271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/swissmatch/zipcode.rb', line 271

def in_use?(at=Date.today)
  if @valid_from then
    if @valid_until then
      at.between?(@valid_from, @valid_until)
    else
      at >= @valid_from
    end
  elsif @valid_until
    at <= @valid_until
  else
    true
  end
end

#inspect ⇒ String

Returns:

  • (String)

See Also:

  • Object#inspect


336
337
338
 
# File 'lib/swissmatch/zipcode.rb', line 336

def inspect
  sprintf "\#<%s:%014x %s>", self.class, object_id, self
end

#names(language = nil) ⇒ Array<SwissMatch::Name>

Returns All official names (max. 27 chars) of this zip code.

Parameters:

  • language (Symbol, nil) (defaults to: nil) —

    One of nil, :de, :fr, :it or :rt

Returns:

  • (Array<SwissMatch::Name>) —

    All official names (max. 27 chars) of this zip code.



219
220
221
 
# File 'lib/swissmatch/zipcode.rb', line 219

def names(language=nil)
  language ? @names.select { |name| name.language == language } : @names
end

#names_short(language = nil) ⇒ Array<SwissMatch::Name>

Returns All official short names (max. 18 chars) of this zip code.

Parameters:

  • language (Symbol, nil) (defaults to: nil) —

    One of nil, :de, :fr, :it or :rt

Returns:

  • (Array<SwissMatch::Name>) —

    All official short names (max. 18 chars) of this zip code.



228
229
230
 
# File 'lib/swissmatch/zipcode.rb', line 228

def names_short(language=nil)
  language ? @names_short.select { |name| name.language == language } : @names_short
end

#region_names(language = nil) ⇒ Array<SwissMatch::Name>

A region name is a name that can be used along a zip code and city, but must not replace the city. For more information, read the section about the PLZ_P2 file, “Bezeichnungstyp” with value “3”.

Parameters:

  • language (Symbol, nil) (defaults to: nil) —

    One of nil, :de, :fr, :it or :rt

Returns:

  • (Array<SwissMatch::Name>) —

    All official region names (max. 27 chars) of this zip code.



241
242
243
 
# File 'lib/swissmatch/zipcode.rb', line 241

def region_names(language=nil)
  language ? @region_names.select { |name| name.language == language } : @region_names
end

#region_names_short(language = nil) ⇒ Array<SwissMatch::Name>

A region name is a name that can be used along a zip code and city, but must not replace the city. For more information, read the section about the PLZ_P2 file, “Bezeichnungstyp” with value “3”.

Parameters:

  • language (Symbol, nil) (defaults to: nil) —

    One of nil, :de, :fr, :it or :rt

Returns:

  • (Array<SwissMatch::Name>) —

    All official short region names (max. 18 chars) of this zip code.



254
255
256
 
# File 'lib/swissmatch/zipcode.rb', line 254

def region_names_short(language=nil)
  language ? @region_names_short.select { |name| name.language == language } : @region_names_short
end

#reverse_name_transliteration_map ⇒ Hash<String, String>

Returns A map to get the names which match a transliteration.

Returns:

  • (Hash<String, String>) —

    A map to get the names which match a transliteration



163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/swissmatch/zipcode.rb', line 163

def reverse_name_transliteration_map
  result = {}
  @all_names.map { |name|
    trans_name1 = SwissMatch.transliterate1(name)
    trans_name2 = SwissMatch.transliterate2(name)
    result[trans_name1] ||= []
    result[trans_name2] ||= []
    result[trans_name1] << name
    result[trans_name2] << name
  }
  result.each_value(&:uniq!)

  result
end

#suggested_name(language = nil) ⇒ SwissMatch::Name

Since a zip code can - for any given language - have no name, exactly one name, or even multiple names, it is sometimes difficult to write good code to automatically provide well localized addresses. This method helps with that, in that it guarantees a single name, as well chosen as possible. It returns the name for the given language, and with the lowest running number, if no name can be found for the given language, the primary name (@see #name) is returned.

Parameters:

  • language (Symbol, nil) (defaults to: nil) —

    One of nil, :de, :fr, :it or :rt

Returns:

  • (SwissMatch::Name) —

    A single name for the zip code, chosen by a ‘best fit’ algorithm.



192
193
194
 
# File 'lib/swissmatch/zipcode.rb', line 192

def suggested_name(language=nil)
  (language && @names.find { |name| name.language == language }) || @name
end

#suggested_short_name(language = nil) ⇒ SwissMatch::Name

Since a zip code can - for any given language - have no name, exactly one name, or even multiple names, it is sometimes difficult to write good code to automatically provide well localized addresses. This method helps with that, in that it guarantees a single name, as well chosen as possible. It returns the name for the given language, and with the lowest running number, if no name can be found for the given language, the primary name (@see #name) is returned.

Parameters:

  • language (Symbol, nil) (defaults to: nil) —

    One of nil, :de, :fr, :it or :rt

Returns:

  • (SwissMatch::Name) —

    A single short name for the zip code, chosen by a ‘best fit’ algorithm.



210
211
212
 
# File 'lib/swissmatch/zipcode.rb', line 210

def suggested_short_name(language=nil)
  (language && @short_name.find { |name| name.language == language }) || @short_name
end

#to_hash(retain_references = false) ⇒ Hash

Returns All properties of the zip code as a hash.

Parameters:

  • retain_references (Boolean) (defaults to: false) —

    If set to false, :delivery_by will be set to the ordering number, :largest_community to the community_number, :communities to their respective community numbers and :canton to the canton’s license_tag.

Returns:

  • (Hash) —

    All properties of the zip code as a hash.



292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
 
# File 'lib/swissmatch/zipcode.rb', line 292

def to_hash(retain_references=false)
  delivery_by       = retain_references ? @delivery_by : (@delivery_by && @delivery_by.ordering_number)
  largest_community = retain_references ? @largest_community : (@largest_community && @largest_community.community_number)
  communities       = retain_references ? @communities : @communities.map(&:community_number)
  canton            = retain_references ? @canton : (@canton && @canton.license_tag)
  {
    :ordering_number      => @ordering_number,
    :type                 => @type,
    :code                 => @code,
    :add_on               => @add_on,
    :name                 => @name,
    :name_short           => @name_short,
    :canton               => canton,
    :language             => @language,
    :language_alternative => @language_alternative,
    :sortfile_member      => @sortfile_member,
    :delivery_by          => delivery_by,
    :largest_community    => largest_community,
    :communities          => communities,
    :valid_from           => @valid_from,
    :valid_until          => @valid_until,
  }
end

#to_s ⇒ String

Returns The 4 digit code, followed by the name.

Returns:

  • (String) —

    The 4 digit code, followed by the name



330
331
332
 
# File 'lib/swissmatch/zipcode.rb', line 330

def to_s
  "#{@code} #{@name}"
end

#transliterated_names ⇒ Array<String>

Returns The name of this zip code in all languages and normalizations (only unique values).

Returns:

  • (Array<String>) —

    The name of this zip code in all languages and normalizations (only unique values)



154
155
156
157
158
159
 
# File 'lib/swissmatch/zipcode.rb', line 154

def transliterated_names
  (
    @all_names.map { |name| SwissMatch.transliterate1(name) } |
    @all_names.map { |name| SwissMatch.transliterate2(name) }
  ).uniq
end

#two_digit_add_on ⇒ String

Returns The zip code add-on as 2 digit string, with leading zeros if necessary.

Returns:

  • (String) —

    The zip code add-on as 2 digit string, with leading zeros if necessary



148
149
150
 
# File 'lib/swissmatch/zipcode.rb', line 148

def two_digit_add_on
  "%02d" % @add_on
end