Class: Addressing::Subdivision

Inherits:
Object
  • Object
show all
Defined in:
lib/addressing/subdivision.rb

Overview

Represents administrative subdivisions within countries.

Subdivisions can be hierarchical with up to three levels: Administrative Area -> Locality -> Dependent Locality

Examples:

Get subdivisions for Brazil

states = Addressing::Subdivision.all(['BR'])
states.each do |code, state|
  puts "#{code}: #{state.name}"
  municipalities = state.children
end

Get subdivisions for a Brazilian state

municipalities = Addressing::Subdivision.all(['BR', 'CE'])

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(definition = {}) ⇒ Subdivision

Returns a new instance of Subdivision.



215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/addressing/subdivision.rb', line 215

def initialize(definition = {})
  # Validate the presence of required properties.
  [:country_code, :id, :code, :name].each do |required_property|
    if definition[required_property].nil?
      raise ArgumentError, "Missing required property #{required_property}."
    end
  end

  # Add defaults for properties that are allowed to be empty.
  definition = {
    parent: nil,
    locale: nil,
    local_code: nil,
    local_name: nil,
    postal_code_pattern: nil,
    children: {}
  }.merge(definition)

  @id = definition[:id]
  @parent = definition[:parent]
  @country_code = definition[:country_code]
  @locale = definition[:locale]
  @code = definition[:code]
  @local_code = definition[:local_code]
  @name = definition[:name]
  @local_name = definition[:local_name]
  @postal_code_pattern = definition[:postal_code_pattern]
  @children = definition[:children]
end

Instance Attribute Details

#children ⇒ Object (readonly)

Returns the value of attribute children.



213
214
215
 
# File 'lib/addressing/subdivision.rb', line 213

def children
  @children
end

#code ⇒ Object (readonly)

Returns the value of attribute code.



213
214
215
 
# File 'lib/addressing/subdivision.rb', line 213

def code
  @code
end

#country_code ⇒ Object (readonly)

Returns the value of attribute country_code.



213
214
215
 
# File 'lib/addressing/subdivision.rb', line 213

def country_code
  @country_code
end

#id ⇒ Object (readonly)

Returns the value of attribute id.



213
214
215
 
# File 'lib/addressing/subdivision.rb', line 213

def id
  @id
end

#local_code ⇒ Object (readonly)

Returns the value of attribute local_code.



213
214
215
 
# File 'lib/addressing/subdivision.rb', line 213

def local_code
  @local_code
end

#local_name ⇒ Object (readonly)

Returns the value of attribute local_name.



213
214
215
 
# File 'lib/addressing/subdivision.rb', line 213

def local_name
  @local_name
end

#locale ⇒ Object (readonly)

Returns the value of attribute locale.



213
214
215
 
# File 'lib/addressing/subdivision.rb', line 213

def locale
  @locale
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



213
214
215
 
# File 'lib/addressing/subdivision.rb', line 213

def name
  @name
end

#parent ⇒ Object (readonly)

Returns the value of attribute parent.



213
214
215
 
# File 'lib/addressing/subdivision.rb', line 213

def parent
  @parent
end

#postal_code_pattern ⇒ Object (readonly)

Returns the value of attribute postal_code_pattern.



213
214
215
 
# File 'lib/addressing/subdivision.rb', line 213

def postal_code_pattern
  @postal_code_pattern
end

Class Method Details

.all(parents) ⇒ Hash<String, Subdivision>

Returns all subdivision instances for the provided parents.

Parameters:

  • parents (Array<String>) —

    Parent hierarchy (e.g., [‘BR’] or [‘BR’, ‘CE’])

Returns:

  • (Hash<String, Subdivision>) —

    Hash of subdivision ID => Subdivision instance



34
35
36
37
38
39
40
41
 
# File 'lib/addressing/subdivision.rb', line 34

def all(parents)
  definitions = load_definitions(parents)
  return {} if definitions.empty?

  definitions["subdivisions"].each_with_object({}) do |(id, definition), subdivisions|
    subdivisions[id] = create_subdivision_from_definitions(id, definitions)
  end
end

.get(id, parents) ⇒ Subdivision?

Gets a Subdivision instance by ID and parent hierarchy.

Parameters:

  • id (String) —

    Subdivision ID

  • parents (Array<String>) —

    Parent hierarchy (e.g., [‘BR’] or [‘BR’, ‘CE’])

Returns:

  • (Subdivision, nil) —

    Subdivision instance or nil if not found



25
26
27
28
 
# File 'lib/addressing/subdivision.rb', line 25

def get(id, parents)
  definitions = load_definitions(parents)
  create_subdivision_from_definitions(id, definitions)
end

.list(parents, locale = nil) ⇒ Object

Returns a list of subdivisions for the provided parents.



44
45
46
47
48
49
50
51
52
53
 
# File 'lib/addressing/subdivision.rb', line 44

def list(parents, locale = nil)
  definitions = load_definitions(parents)
  return {} if definitions.empty?

  use_local_name = Locale.match_candidates(locale, definitions["locale"] || "")

  definitions["subdivisions"].each_with_object({}) do |(id, definition), subdivisions|
    subdivisions[id] = use_local_name ? definition["local_name"] : definition["name"]
  end
end

Instance Method Details

#children? ⇒ Boolean

Returns:

  • (Boolean) 


245
246
247
 
# File 'lib/addressing/subdivision.rb', line 245

def children?
  @children.any?
end

#to_h ⇒ Object 



249
250
251
252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/addressing/subdivision.rb', line 249

def to_h
  {
    id: id,
    parent: parent,
    country_code: country_code,
    locale: locale,
    code: code,
    local_code: local_code,
    name: name,
    local_name: local_name,
    postal_code_pattern: postal_code_pattern,
    children: children
  }
end