worldwide 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c3c323e57e56b609ebdc7fe5d7965a2d5348fede9b72110627528529b3b7ab5
-  data.tar.gz: f4007e0986bc9702af7d95f3c352a11937292d9f6fbbd8c21e8a1a635fcc7993
+  metadata.gz: 4dca8f095b6020792ecd6186606db9cd6159d03414b735b0c2d4b30f0746b680
+  data.tar.gz: 7e40cbbd862960354faf241a3320c03b1a081fa005f42063bf27951ca94f3c1d
 SHA512:
-  metadata.gz: 333628df88179b5d2696634f3dadec1a548a5a2ef4baebcac86832077565f5f826036da107cdf8d5d4ed84323563235265df4b0bf37648f7d7691ef120e81216
-  data.tar.gz: cdbad17228b52fc39d188fdbf2e13800aa4015caf18cd314d9cdfcd7f3a7b63f585c2cbd69eec36bb8c450dae83e649c35a0c661c651e55293c626582e03a785
+  metadata.gz: 1c385197a1a3239d1d1251a0cb7b45fe3f04f4d9e75dc3ed02227fe9692184b12dc5754c4c5292bfbd24e4a079df48b2ea63689e63b11511ec1f7017627ac15a
+  data.tar.gz: 666f0e760f82cfab270d47328a9600204e7c93c04bd16106b5f6d46cadefcd15f90dc64ea5663f0eeefc2827458aa2b47147468b45da059a57c37dd146893444

data/CHANGELOG.md

@@ -28,6 +28,21 @@ Nil.
 
 ---
 
+[0.4.0] - 2023-11-08
+- Add region name alternates [#32](https://github.com/Shopify/worldwide/pull/32)
+- Cache `Region#parent_name` [#33](https://github.com/Shopify/worldwide/pull/33)
+- Use hash tables to look up regions by code [#36](https://github.com/Shopify/worldwide/pull/36)
+
+[0.3.0] - 2023-11-03
+- Add code alternates for Japan [#23](https://github.com/Shopify/worldwide/pull/23)
+- Add code alternates for Puerto Rico [#24](https://github.com/Shopify/worldwide/pull/24)
+- Record multiple parents per region [#27](https://github.com/Shopify/worldwide/pull/27)
+- Add region.building_number_may_be_in_address2 [#28](https://github.com/Shopify/worldwide/pull/28)
+- Lookup by parent-child ISO and CLDR codes for dual-status territories
+  [#29](https://github.com/Shopify/worldwide/pull/29)
+- Handle ISO_CODE only zones lookup [#26](https://github.com/Shopify/worldwide/pull/26)
+
+
 [0.2.0] - 2023-11-01
 
 - Add Region#group and Region#group_name [#15](https://github.com/Shopify/worldwide/pull/15)

data/Gemfile.lock

@@ -13,7 +13,7 @@ GIT
 PATH
   remote: .
   specs:
-    worldwide (0.2.0)
+    worldwide (0.4.0)
       activesupport (~> 7.0)
       i18n (~> 1.12.0)
       phonelib (~> 0.8)

data/db/data/regions/IT.yml

@@ -14,6 +14,7 @@ zip_regex: "^(IT?-?)?\\d{5}$"
 zip_example: '00144'
 phone_number_prefix: 39
 building_number_required: true
+building_number_may_be_in_address2: true
 week_start_day: monday
 languages:
   - it

data/db/data/regions/US.yml

@@ -7,6 +7,8 @@ unit_system: imperial
 tax_name: Federal Tax
 group: North American Countries
 group_name: North America
+name_alternates:
+- United States of America
 zip_label: Zip code
 zip_regex: "(?-mix:\\A\\d{5}(-\\d{4})?\\z)|(?i-mx:\\AFPO\\s*A[A-Z]\\s*\\d{5}-\\d{4}\\z)"
 zip_example: '90210'

data/lib/worldwide/region.rb

@@ -34,7 +34,9 @@ module Worldwide
       :zip_requirement,
     ]
 
-    attr_accessor :parent
+    # A region may have more than one parent.
+    # For example, Puerto Rico (PR/US-PR) is associated with both the US and the Caribbean (029)
+    attr_accessor :parents
 
     # ISO-3166 three-letter code for this region, if there is one.
     # Otherwise, nil.
@@ -45,6 +47,10 @@ module Worldwide
     # If we require a building number in an address, then this will be true.
     attr_accessor :building_number_required
 
+    # In some countries, an address may have the building number in address2.
+    # If we are allowed to have a building number in address2, then this will be true.
+    attr_accessor :building_number_may_be_in_address2
+
     # Alternate codes which may be used to designate this region
     attr_accessor :code_alternates
 
@@ -104,6 +110,10 @@ module Worldwide
     # This name is the name that was traditionally returned by "country_db".
     attr_reader :legacy_name
 
+    # Other names that may be used to refer to this region.
+    # E.g., "Czech Republic" is also known as "Czechia".
+    attr_accessor :name_alternates
+
     # iso_code values of regions (subdivisions) within the same country that border this region.
     # E.g., for CA-ON, the neighbouring zones are CA-MB, CA-NU and CA-QC.
     attr_accessor :neighbours
@@ -217,6 +227,7 @@ module Worldwide
       @use_zone_code_as_short_name = use_zone_code_as_short_name
 
       @building_number_required = false
+      @building_number_may_be_in_address2 = false
       @currency = nil
       @flag = nil
       @format = {}
@@ -236,7 +247,7 @@ module Worldwide
       @zip_prefixes = []
       @zip_regex = nil
 
-      @parent = nil
+      @parents = [].to_set
       @zones = []
     end
 
@@ -249,12 +260,18 @@ module Worldwide
     def add_zone(region)
       return if @zones.include?(region)
 
-      region.parent = self
+      region.parents << self
       @zones.append(region)
     end
 
     # Attributes
 
+    def associated_country
+      return self if country?
+
+      parent_country
+    end
+
     # The value with which to autofill the zip, if this region has zip autofill active;
     # otherwise, nil.
     def autofill_zip
@@ -333,7 +350,8 @@ module Worldwide
 
         zones.find do |region|
           [search_code, alt_search_code].any? do |candidate|
-            candidate == region.alpha_three ||
+            candidate == subdivision_code(region.iso_code) ||
+              candidate == region.alpha_three ||
               candidate == region.iso_code ||
               candidate == region.legacy_code ||
               candidate == region.numeric_three ||
@@ -371,7 +389,7 @@ module Worldwide
     # is the given postal code value valid for this region?
     def valid_zip?(zip, partial_match: false)
       normalized = Zip.normalize(
-        country_code: province? && parent.iso_code ? parent.iso_code : iso_code,
+        country_code: province? && associated_country.iso_code ? associated_country.iso_code : iso_code,
         zip: zip,
       )
       valid_normalized_zip?(normalized, partial_match: partial_match)
@@ -384,6 +402,21 @@ module Worldwide
 
     private
 
+    def answers_to_cldr_code(search_code)
+      return false if Util.blank?(search_code) || Util.blank?(cldr_code)
+      return true if search_code.casecmp(cldr_code).zero?
+
+      pc = parent_country
+      "#{pc&.cldr_code&.downcase}#{cldr_code.downcase}" == search_code.downcase
+    end
+
+    def answers_to_iso_code(search_code)
+      return true if search_code == iso_code
+
+      pc = parent_country
+      "#{pc&.iso_code}-#{iso_code}" == search_code
+    end
+
     def cross_border_zip_includes_province?(zip:, province_code:)
       return false unless country?
 
@@ -408,11 +441,17 @@ module Worldwide
       INSPECTION_FIELDS.map { |field_name| "@#{field_name}=#{send(field_name).inspect}" }.join(", ")
     end
 
+    def parent_country
+      @parent_country ||= parents.find(&:country?)
+    end
+
     # Checks whether the given value is acceptable according to the regular expression defined for the country.
     # @param value [String] for the postal code
     # @return [Boolean]
     def passes_country_zip_regexp?(value:, partial_match: false)
-      return parent.send(:passes_country_zip_regexp?, value: value, partial_match: partial_match) if province?
+      if province?
+        return associated_country.send(:passes_country_zip_regexp?, value: value, partial_match: partial_match)
+      end
 
       return false if partial_match && partial_zip_regex.nil?
 
@@ -445,11 +484,18 @@ module Worldwide
       end&.first
     end
 
+    def subdivision_code(iso_code)
+      return iso_code if iso_code.nil? || iso_code.length < 3
+
+      country_code, subdivision_code = iso_code.split("-")
+      return subdivision_code if country_code.casecmp(associated_country.iso_code).zero?
+    end
+
     def valid_normalized_zip?(normalized, province_code: nil, partial_match: false)
       if country?
         country = self
       elsif province?
-        country = parent
+        country = associated_country
         province_code ||= legacy_code
       end
 

data/lib/worldwide/regions.rb

@@ -16,7 +16,7 @@ module Worldwide
     end
 
     def initialize
-      @regions = RegionsLoader.new.load_regions
+      @regions, @regions_by_cldr_code, @regions_by_iso_code = RegionsLoader.new.load_regions
     end
 
     def all
@@ -29,17 +29,9 @@ module Worldwide
       end
 
       result = if cldr
-        search_code = cldr.to_s.upcase
-
-        @regions.find do |r|
-          r.cldr_code.upcase == search_code
-        end
+        @regions_by_cldr_code[cldr.to_s.upcase]
       elsif code
-        search_code = code.to_s.upcase
-
-        @regions.find do |r|
-          r.iso_code == search_code || r.alpha_three == search_code || r.numeric_three == search_code
-        end
+        @regions_by_iso_code[code.to_s.upcase]
       else # search by name
         search_name = name.upcase
 

data/lib/worldwide/regions_loader.rb

@@ -9,6 +9,9 @@ module Worldwide
     WORLD_CODE = "001" # UN code for the whole world
 
     def load_regions
+      @regions_by_cldr_code = {}
+      @regions_by_iso_code = {}
+
       # Load country/region definitions out of the db/data/regions/??.yml files
       @regions = Dir["#{Worldwide::Paths::REGIONS_ROOT}/*.yml"].map do |filename|
         load_territory(filename)
@@ -25,11 +28,39 @@ module Worldwide
 
       construct_unknown
 
-      @regions.freeze
+      @regions.each do |region|
+        construct_lookup_info(region)
+      end
+
+      [@regions.freeze, @regions_by_cldr_code, @regions_by_iso_code]
     end
 
     private
 
+    def construct_lookup_info(region)
+      pc = region.send(:parent_country)
+
+      # Remember CLDR code(s) for later use during lookup
+
+      search_code = region.cldr_code.to_s.upcase
+      @regions_by_cldr_code[search_code] = region if Util.present?(search_code)
+
+      @regions_by_cldr_code["#{pc.cldr_code.upcase}#{search_code}"] = region if Util.present?(pc&.cldr_code)
+
+      # Remember ISO 3166 code(s) for later use during lookup
+
+      iso_code = region.iso_code
+      @regions_by_iso_code[iso_code] = region if Util.present?(iso_code)
+
+      @regions_by_iso_code["#{pc.iso_code}-#{iso_code}"] = region if Util.present?(pc)
+
+      alpha_three = region.alpha_three
+      @regions_by_iso_code[alpha_three] = region if Util.present?(alpha_three)
+
+      numeric_three = region.numeric_three
+      @regions_by_iso_code[numeric_three] = region if Util.present?(numeric_three)
+    end
+
     def apply_hierarchy(parent:, code:, children:)
       current_region = find_region(code: code)
       if current_region.nil?
@@ -46,9 +77,7 @@ module Worldwide
         @regions << current_region
       end
 
-      if parent.present? && current_region.parent != parent
-        current_region.parent = parent
-      end
+      current_region.parents << parent if Util.present?(parent)
       parent&.add_zone(current_region)
       return current_region if children.nil?
 
@@ -61,6 +90,7 @@ module Worldwide
 
     def apply_territory_attributes(region, spec)
       region.building_number_required = spec["building_number_required"] || true
+      region.building_number_may_be_in_address2 = spec["building_number_may_be_in_address2"] || false
       currency_code = spec["currency"]
       region.currency = Worldwide.currency(code: currency_code) unless currency_code.nil?
       region.flag = spec["emoji"]
@@ -83,10 +113,12 @@ module Worldwide
       region.zip_requirement = spec["zip_requirement"]
       region.zip_regex = spec["zip_regex"]
       region.zips_crossing_provinces = spec["zips_crossing_provinces"]
+      region.name_alternates = spec["name_alternates"] || []
     end
 
     def apply_zone_attributes(region, zone)
       region.code_alternates = zone["code_alternates"] || []
+      region.name_alternates = zone["name_alternates"] || []
       region.example_city = zone["example_city"]
       region.neighbours = zone["neighboring_zones"]
       region.zip_prefixes = zone["zip_prefixes"] || []

data/lib/worldwide/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Worldwide
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: worldwide
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Shopify
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-11-01 00:00:00.000000000 Z
+date: 2023-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport