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

- (ZipCode) initialize(ordering_number, type, code, add_on, name, names, name_short, names_short, canton, language, language_alternative, sortfile_member, delivery_by, community, valid_from, valid_until = nil)

Returns a new instance of ZipCode



92
93
94
95
96
97
98
99
100
101
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
# File 'lib/swissmatch/zipcode.rb', line 92

def initialize(
  ordering_number,
  type,
  code,
  add_on,
  name,
  names,
  name_short,
  names_short,
  canton,
  language,
  language_alternative,
  sortfile_member,
  delivery_by,
  community,
  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)
  @canton               = canton
  @sortfile_member      = sortfile_member
  @delivery_by          = delivery_by == :self ? self : delivery_by
  @community            = community
  @valid_from           = valid_from
  @valid_until          = valid_until
end

Instance Attribute Details

- (Integer) add_on (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

- (SwissMatch::Canton) 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

- (Integer) code (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

- (SwissMatch::Community) community (readonly)

Returns The community this zip code belongs to.

Returns:



78
79
80
# File 'lib/swissmatch/zipcode.rb', line 78

def community
  @community
end

- (SwissMatch::ZipCode) delivery_by (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.



74
75
76
# File 'lib/swissmatch/zipcode.rb', line 74

def delivery_by
  @delivery_by
end

- (Integer) full_code (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

- (Symbol) language (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.



62
63
64
# File 'lib/swissmatch/zipcode.rb', line 62

def language
  @language
end

- (SwissMatch::Canton) language_alternative (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.



66
67
68
# File 'lib/swissmatch/zipcode.rb', line 66

def language_alternative
  @language_alternative
end

- (SwissMatch::Name) 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

- (SwissMatch::Name) name_short (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

- (Integer) ordering_number (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

- (Boolean) sortfile_member (readonly)

Returns Whether this ZipCode instance is included in the MAT[CH]sort sortfile

Returns:

  • (Boolean)

    Whether this ZipCode instance is included in the MAT[CH]sort sortfile



70
71
72
# File 'lib/swissmatch/zipcode.rb', line 70

def sortfile_member
  @sortfile_member
end

- (Integer) type (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

- (Date?) valid_from (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:



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

def valid_from
  @valid_from
end

- (Date?) valid_until (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:



90
91
92
# File 'lib/swissmatch/zipcode.rb', line 90

def valid_until
  @valid_until
end

Instance Method Details

- (Integer) <=>(other)

Compare two zip codes by their ordering number (ONRP)

Returns:

  • (Integer)

    Returns -1, 0 or 1.



198
199
200
# File 'lib/swissmatch/zipcode.rb', line 198

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

- (Boolean) eql?(other)

Returns:

  • (Boolean)

See Also:

  • Object#eql?


257
258
259
# File 'lib/swissmatch/zipcode.rb', line 257

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

- (Object) hash

See Also:

  • Object#hash


251
252
253
# File 'lib/swissmatch/zipcode.rb', line 251

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

- (Boolean) in_use?(at = Date.today)

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.



207
208
209
210
211
212
213
214
215
216
217
218
219
# File 'lib/swissmatch/zipcode.rb', line 207

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

- (String) inspect

Returns:

  • (String)

See Also:

  • Object#inspect


269
270
271
# File 'lib/swissmatch/zipcode.rb', line 269

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

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

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.



181
182
183
# File 'lib/swissmatch/zipcode.rb', line 181

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

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

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.



190
191
192
# File 'lib/swissmatch/zipcode.rb', line 190

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

- (SwissMatch::Name) suggested_name(language = nil)

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.



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

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

- (SwissMatch::Name) suggested_short_name(language = nil)

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.



172
173
174
# File 'lib/swissmatch/zipcode.rb', line 172

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

- (Hash) to_hash(retain_references = false)

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, :community to the community_number and :canton to the canton's license_tag.

Returns:

  • (Hash)

    All properties of the zip code as a hash.



227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
# File 'lib/swissmatch/zipcode.rb', line 227

def to_hash(retain_references=false)
  delivery_by = retain_references ? @delivery_by : (@delivery_by && @delivery_by.ordering_number)
  community   = retain_references ? @community : (@community && @community.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,
    :community            => community,
    :valid_from           => @valid_from,
    :valid_until          => @valid_until,
  }
end

- (String) to_s

Returns The 4 digit code, followed by the name

Returns:

  • (String)

    The 4 digit code, followed by the name



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

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

- (Array<String>) transliterated_names

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)



131
132
133
134
135
136
137
138
139
# File 'lib/swissmatch/zipcode.rb', line 131

def transliterated_names
  names.flat_map { |name, ary|
    name = name.to_s # convert from SwissMatch::Name
    [
      SwissMatch.transliterate1(name),
      SwissMatch.transliterate2(name)  # TODO: use transliterate gem
    ]
  }.uniq
end