From fe6d2217276c4d5f5f57888e3e916bf1384e56d6 Mon Sep 17 00:00:00 2001 From: Dominique Flabbi Date: Wed, 18 Nov 2026 13:00:03 -0600 Subject: [PATCH] Add zone matching helpers to Worldwide::Region Match subdivision codes, names, handles, neighboring zones, and postal prefixes. Normalize a postal code once before comparing the prefixes and keep country-level validation unchanged. --- CHANGELOG.md | 2 + lib/worldwide/region.rb | 197 +++++++++++++- lib/worldwide/util.rb | 101 ++++++++ test/worldwide/region_zone_test.rb | 404 +++++++++++++++++++++++++++++ test/worldwide/util_test.rb | 150 +++++++++++ 5 files changed, 851 insertions(+), 3 deletions(-) create mode 100644 test/worldwide/region_zone_test.rb create mode 100644 test/worldwide/util_test.rb diff --git a/CHANGELOG.md b/CHANGELOG.md index 4121fac6b..5700467f1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), ## [Unreleased] +- Add `Region#has_code?`, `Region#has_name?`, `Region#has_handle?`, `Region#neighbor?` and `Region#valid_zone_zip?`, for matching a zone by code, by name and by zip, and `Util.utf8_handle` and `Util.ascii_casecmp_substring?`, which they use. `valid_zone_zip?` checks a province's own `zip_prefixes`. `valid_zip?` is unchanged: it infers one province from the zip, so it can differ for a shared prefix or a zip shorter than a prefix. [#682](https://github.com/Shopify/worldwide/pull/682) + --- ## [2.3.0] - 2026-11-18 diff --git a/lib/worldwide/region.rb b/lib/worldwide/region.rb index 8905d9dfb..8538c4674 100644 --- a/lib/worldwide/region.rb +++ b/lib/worldwide/region.rb @@ -17,6 +17,12 @@ class Region ).to_set.freeze private_constant :ISO_3166_ASSIGNED_COUNTRY_CODES + CODE_SEPARATOR = "-" + private_constant :CODE_SEPARATOR + + BLANK_CODE = /\A[[:space:]]*\z/ + private_constant :BLANK_CODE + # Accpetable format types of the postal code. FORMAT_TYPES = { ALPHANUMERIC: "ALPHANUMERIC", @@ -164,10 +170,10 @@ class Region # Other names that may be used to refer to this region. # E.g., "Czech Republic" is also known as "Czechia". - attr_accessor :name_alternates + attr_reader :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. + # legacy_code values of regions (subdivisions) within the same country that border this region. + # E.g., for CA-ON, the neighbouring zones are "QC" and "MB". attr_accessor :neighbours alias_method :neighbors, :neighbours @@ -336,6 +342,12 @@ def initialize( @zones_by_code = {} end + def name_alternates=(names) + @name_alternates = names + @handle = nil + @handle_alternates = nil + end + def inspect "#<#{self.class.name}:#{object_id} #{inspected_fields}>" end @@ -557,6 +569,114 @@ def valid_zip?(zip, partial_match: false) valid_normalized_zip?(normalized, partial_match: partial_match) end + # Is the given postal code value valid for this region, judging a province by its own zip prefixes? + # + # For a region that is not a province, this gives the same result as {#valid_zip?}. + # + # For a province, {#valid_zip?} infers one province from the zip, and accepts the zip only when that is + # this province or when `zips_crossing_provinces` lists it. This method instead accepts the zip when + # the country accepts it and one of this province's own `zip_prefixes` matches it. The two differ when: + # + # - the province has no `zip_prefixes`, but other provinces of its country do: this method accepts + # any zip that the country accepts, and {#valid_zip?} accepts only a zip that infers this province; + # - the prefixes of two provinces both match the zip, for example a partial zip such as "CH6" or a + # shared prefix such as "K1A": this method accepts the zip for each of them, and {#valid_zip?} + # accepts it for the first one that it finds, and for the others only through `zips_crossing_provinces`. + # + # @example + # Worldwide.region(code: "CA-ON").valid_zone_zip?("K2A") == false + # Worldwide.region(code: "CA-ON").valid_zone_zip?("K2A", partial_match: true) == true + # + # @param zip [String] + # @param partial_match [Boolean] also accept the first part of a zip, as `valid_zip?` does + # @return [Boolean] + def valid_zone_zip?(zip, partial_match: false) + return valid_zip?(zip, partial_match: partial_match) unless province? + + country = associated_country + return false if country.nil? || country.iso_code.nil? + + country_code = country.iso_code + normalized = Zip.normalize(country_code: country_code, zip: zip) + adjusted = Zip.strip_optional_country_prefix(country_code: country_code, zip: normalized) + + return false unless country.send(:valid_normalized_zip?, adjusted, partial_match: partial_match) + return true if Util.blank?(zip) && !country.zip_required? + return true if Util.blank?(zip_prefixes) + return true if country.send(:cross_border_zip_includes_province?, zip: adjusted, province_code: legacy_code) + + zip_prefixes.any? { |prefix| adjusted.start_with?(prefix) || prefix.start_with?(adjusted) } + end + + # Does the given code identify this region? + # + # The code may be the region's `legacy_code`, one of its `code_alternates`, or its `iso_code`. + # For a region within a country, the code may also carry the country's code in place of + # the hyphen-less part: "CA-NL" matches the region with legacy code "NL" in Canada. + # And, for a region whose legacy code has a hyphen, the part after the hyphen alone is enough: + # "13" matches the region with legacy code "JP-13". + # + # The comparison ignores the case of ASCII letters. + # Callers may look a region up by code very often, so this allocates no strings. + # + # @example + # Worldwide.region(code: "CA-QC").has_code?("PQ") == true + # Worldwide.region(code: "CA-QC").has_code?("ca-qc") == true + # Worldwide.region(code: "JP-13").has_code?("13") == true + # + # @param code [String, Symbol] + # @return [Boolean] + def has_code?(code) + return false if code.nil? + + code = code.to_s unless code.is_a?(String) + return false if code.empty? || BLANK_CODE.match?(code) + + return true if legacy_code&.casecmp(code)&.zero? + return true if code_alternates&.any? { |code_alternate| code_alternate.casecmp(code)&.zero? } + return true if iso_code&.casecmp(code)&.zero? + + match_unprefixed_code?(code) || match_suffix_only_code?(code) + end + + # Does the given name identify this region? + # + # The name is compared with the region's `legacy_name` and its `name_alternates`, after + # {Util.utf8_handle} simplifies each of them, so that "Fayyum" matches "Fayyūm". + # It is not compared with the localized {#full_name}. + # + # @param name [String] + # @return [Boolean] + def has_name?(name) + has_handle?(name.nil? ? nil : Util.utf8_handle(name)) + end + + # Does the given handle identify this region? + # + # A handle is the result of {Util.utf8_handle}. It is compared with the handle of the region's + # `legacy_name` and with the handles of its `name_alternates`. + # + # @param handle [String] + # @return [Boolean] + def has_handle?(handle) + return false if handle.nil? + + handle == name_handle || name_alternate_handles.include?(handle) + end + + # Is the region with the given legacy code one of the regions that border this region? + # + # @example + # Worldwide.region(code: "CA-ON").neighbor?("QC") == true + # + # @param code [String] a legacy code, as found in {#neighbours} + # @return [Boolean] + def neighbor?(code) + return false if neighbours.nil? + + neighbours.include?(code) + end + # are zones optional for this region? def province_optional? province_optional || !@zones&.any?(&:province?) @@ -571,6 +691,77 @@ def has_zip_prefixes? private + def name_handle + return if legacy_name.nil? + + @handle ||= Util.utf8_handle(legacy_name) + end + + def name_alternate_handles + @handle_alternates ||= (name_alternates || []).map { |name| Util.utf8_handle(name) }.freeze + end + + # Matches a code that has this region's country code, a hyphen, and then this region's legacy code + # or one of its code alternates. E.g., "CA-NL", to match just the "NL" part. + # + # This avoids String#split, so that it allocates no strings. + def match_unprefixed_code?(code) + return false unless province? + + hyphen_index = code.byteindex(CODE_SEPARATOR) + return false unless hyphen_index && hyphen_index != 0 && hyphen_index + 1 < code.bytesize + + country_code = parent_country&.iso_code + return false if country_code.nil? || country_code.empty? + + return false unless Util.ascii_casecmp_substring?( + country_code, + code, + start1: 0, + length1: country_code.bytesize, + start2: 0, + length2: hyphen_index, + ) + + suffix_start = hyphen_index + 1 + suffix_length = code.bytesize - suffix_start + + return true if suffix_matches?(legacy_code, code, suffix_start, suffix_length) + + !!code_alternates&.any? { |code_alternate| suffix_matches?(code_alternate, code, suffix_start, suffix_length) } + end + + def suffix_matches?(candidate, code, suffix_start, suffix_length) + return false if candidate.nil? || candidate.empty? + + Util.ascii_casecmp_substring?( + candidate, + code, + start1: 0, + length1: candidate.bytesize, + start2: suffix_start, + length2: suffix_length, + ) + end + + # Matches a code that is only the part of this region's legacy code after the hyphen, + # e.g., "13" for "JP-13". Code alternates do not take part, to avoid matching by accident. + def match_suffix_only_code?(code) + return false if legacy_code.nil? + + hyphen_index = legacy_code.byteindex(CODE_SEPARATOR) + return false if hyphen_index.nil? || hyphen_index == legacy_code.bytesize - 1 + + Util.ascii_casecmp_substring?( + legacy_code, + code, + start1: hyphen_index + 1, + length1: legacy_code.bytesize - hyphen_index - 1, + start2: 0, + length2: code.bytesize, + ) + end + def add_zone_to_hash(zone) @zones_by_code[subdivision_code(zone.iso_code)] = zone if Util.present?(subdivision_code(zone.iso_code)) @zones_by_code[zone.alpha_three] = zone if Util.present?(zone.alpha_three) diff --git a/lib/worldwide/util.rb b/lib/worldwide/util.rb index c148970ba..bfd07ee08 100644 --- a/lib/worldwide/util.rb +++ b/lib/worldwide/util.rb @@ -2,6 +2,40 @@ module Worldwide class Util + # Characters in U+00C0..U+017F that have no decomposition into a base letter and a mark, + # mapped to an ASCII approximation. + HANDLE_APPROXIMATIONS = { + "ß" => "ss", + "æ" => "ae", + "ð" => "d", + "ø" => "o", + "þ" => "th", + "đ" => "d", + "ħ" => "h", + "ı" => "i", + "ij" => "ij", + "ĸ" => "k", + "ŀ" => "l", + "ł" => "l", + "ʼn" => "'n", + "ŋ" => "ng", + "œ" => "oe", + "ŧ" => "t", + }.freeze + private_constant :HANDLE_APPROXIMATIONS + + HANDLE_LATIN_RANGE = /[\u00C0-\u017F]/ + private_constant :HANDLE_LATIN_RANGE + + HANDLE_QUOTES_AND_BRACKETS = "'\"()[]" + private_constant :HANDLE_QUOTES_AND_BRACKETS + + HANDLE_SEPARATOR = /(?:(?!\p{Word}|\u200D|\p{Extended_Pictographic}|\p{Emoji_Modifier}).)+/m + private_constant :HANDLE_SEPARATOR + + HANDLE_EDGE_HYPHENS = /\A-+|-+\z/ + private_constant :HANDLE_EDGE_HYPHENS + class << self def blank?(value) value.nil? || @@ -12,6 +46,73 @@ def blank?(value) def present?(value) !blank?(value) end + + # Reduces a name to a simplified, lowercase form that is suitable for comparing names. + # Latin letters with diacritics become their base letters, quotes and brackets are dropped, and each + # run of other punctuation or whitespace becomes a single hyphen. + # Letters of other scripts are kept. + # + # @example + # Worldwide::Util.utf8_handle("Al Fayyūm") == "al-fayyum" + # Worldwide::Util.utf8_handle("Ærøskøbing 日本") == "aeroskobing-日本" + # + # @param input [String] + # @return [String] a new, frozen string + def utf8_handle(input) + string = input.to_s + string = string.dup.force_encoding(Encoding::UTF_8) unless string.encoding == Encoding::UTF_8 + string = ActiveSupport::Multibyte::Unicode.tidy_bytes(string) unless string.valid_encoding? + + result = string.downcase.unicode_normalize(:nfc) + result = result.gsub(HANDLE_LATIN_RANGE) do |char| + HANDLE_APPROXIMATIONS[char] || char.unicode_normalize(:nfd).delete("\u0300-\u036F") + end + result.delete!(HANDLE_QUOTES_AND_BRACKETS) + result.gsub!(HANDLE_SEPARATOR, "-") + result.gsub!(HANDLE_EDGE_HYPHENS, "") + result.freeze + end + + # Compares a part of one string with a part of another string, ignoring the case of ASCII letters. + # This allocates no objects, because it compares bytes with `getbyte`. + # A comparison that involves a byte outside of ASCII is always false. + # + # @param str1 [String] + # @param str2 [String] + # @param start1 [Integer] the byte offset of the part of `str1` + # @param length1 [Integer] the byte length of the part of `str1`; it must be greater than 0 + # @param start2 [Integer] the byte offset of the part of `str2` + # @param length2 [Integer] the byte length of the part of `str2`; it must be greater than 0 + # @return [Boolean] + # @raise [ArgumentError] when a string is nil, a length is not positive, or a start is negative + def ascii_casecmp_substring?(str1, str2, start1:, length1:, start2:, length2:) + raise ArgumentError, "str1 and str2 must not be nil" if str1.nil? || str2.nil? + raise ArgumentError, "Length must be greater than 0" if length1 <= 0 || length2 <= 0 + raise ArgumentError, "Start indices must not be negative" if start1 < 0 || start2 < 0 + + return false if length1 != length2 + + length = length1 + return false if start1 + length > str1.bytesize || start2 + length > str2.bytesize + + # A while loop avoids allocating a Range + i = 0 + while i < length + b1 = str1.getbyte(start1 + i) + b2 = str2.getbyte(start2 + i) + + return false if b1 >= 128 || b2 >= 128 + + b1 += 32 if b1.between?(65, 90) + b2 += 32 if b2.between?(65, 90) + + return false if b1 != b2 + + i += 1 + end + + true + end end end end diff --git a/test/worldwide/region_zone_test.rb b/test/worldwide/region_zone_test.rb new file mode 100644 index 000000000..36d284ed4 --- /dev/null +++ b/test/worldwide/region_zone_test.rb @@ -0,0 +1,404 @@ +# frozen_string_literal: true + +require "test_helper" + +module Worldwide + # Behaviours that a Region has when it is a zone (province, state, ...) of a country. + class RegionZoneTest < ActiveSupport::TestCase + def region(code) + Worldwide.region(code: code) + end + + def allocated_objects + yield + GC.start + GC.disable + before = GC.stat(:total_allocated_objects) + yield + GC.stat(:total_allocated_objects) - before + ensure + GC.enable + end + + # #has_code? + + test "#has_code? accepts any of the legacy code, a code alternate, or the ISO 3166-2 code" do + [ + ["CA", "nl", "CA-NL"], + ["CA", "CA-NL", "CA-NL"], + ["CA", "qc", "CA-QC"], + ["CA", "pq", "CA-QC"], + ["CA", "CA-QC", "CA-QC"], + ["CA", "ca-qc", "CA-QC"], + ["ZA", "kzn", "ZA-KZN"], + ["ZA", "nl", "ZA-KZN"], + ["ZA", "ZA-KZN", "ZA-KZN"], + ["ZA", "ZA-NL", "ZA-KZN"], + ["CR", "CR-C", "CR-C"], + ["IT", "su", "IT-CI"], + ["IT", "ci", "IT-CI"], + ["IT", "IT-SU", "IT-CI"], + ].each do |country_code, input, expected_iso_code| + zone = region(country_code).zones.find { |candidate| candidate.has_code?(input) } + + assert_equal expected_iso_code, zone&.iso_code, "Lookup iso code did not match expected" + assert zone.has_code?(input), "Zone #{zone.iso_code} should has_code?(#{input.inspect})" + assert zone.has_code?(expected_iso_code), "Zone #{zone.iso_code} should has_code?(#{expected_iso_code.inspect})" + end + end + + test "#has_code? finds Sulcis Iglesiente by SU or CI, with or without the country code" do + italy = region("IT") + + ["SU", "CI", "IT-SU", "IT-CI"].each do |code| + assert_equal "SU", italy.zones.find { |zone| zone.has_code?(code) }&.legacy_code, "has_code?(#{code.inspect})" + end + assert_includes italy.zones.map(&:legacy_code), "SU" + refute_includes italy.zones.map(&:legacy_code), "CI" + end + + test "#has_code? accepts a code that is the part of the legacy code after the hyphen" do + tokyo = region("JP-13") + + assert_equal "JP-13", tokyo.iso_code + assert tokyo.has_code?("13") + assert tokyo.has_code?("JP-13") + assert tokyo.has_code?("jp-13") + refute tokyo.has_code?("14") + refute region("JP-14").has_code?("13") + end + + test "#has_code? accepts a symbol" do + assert region("CA-QC").has_code?(:qc) + assert region("CA-QC").has_code?(:pq) + refute region("CA-QC").has_code?(:on) + end + + test "#has_code? returns false for a blank code" do + [nil, "", " ", "\t"].each do |code| + refute region("CA-QC").has_code?(code), "has_code?(#{code.inspect})" + end + end + + test "#has_code? handles the case where a code without a country is passed in" do + refute region("CA-QC").has_code?("-ON") + refute region("CA-QC").has_code?("-QC") + refute region("CA-QC").has_code?("CA-") + refute region("CA-QC").has_code?("-") + end + + test "#has_code? does not accept the code of a different zone or country" do + refute region("CA-QC").has_code?("ON") + refute region("CA-QC").has_code?("CA-ON") + refute region("CA-QC").has_code?("US-QC") + refute region("CA-QC").has_code?("QCX") + refute region("CA-QC").has_code?("XQC") + end + + test "#has_code? does not accept ISO codes for a different country" do + [ + ["AR", "CR-A"], + ["CR", "AR-A"], + ].each do |country_code, zone_code| + assert_nil( + region(country_code).zones.find { |zone| zone.has_code?(zone_code) }, + "Country #{country_code} code #{zone_code}", + ) + end + end + + test "#has_code? matches the legacy code, code alternates and ISO code of a country, but never a prefixed code" do + canada = region("CA") + + assert canada.has_code?("CA") + assert canada.has_code?("ca") + refute canada.has_code?("CA-ON") + end + + test "#has_code? does not allocate" do + allocated_objects { nil } + + [ + ["CA-QC", "qc"], + ["CA-QC", "PQ"], + ["CA-QC", "CA-QC"], + ["CA-QC", "ca-pq"], + ["CA-QC", "CA-ON"], + ["CA-QC", "unknown"], + ["JP-13", "13"], + ["JP-13", "14"], + ["CA", "CA-ON"], + ].each do |iso_code, input| + zone = region(iso_code) + zone.has_code?(input) + + assert_equal 0, allocated_objects { 10.times { zone.has_code?(input) } }, "#{iso_code} has_code?(#{input.inspect})" + end + end + + # #has_name? and #has_handle? + + test "#has_name? returns true if the zone has the given name" do + assert region("EG-FYM").has_name?("Faiyum") + assert region("EG-FYM").has_name?("FAIYUM") + assert region("EG-FYM").has_name?("Al Fayyūm") + end + + test "#has_name? ignores diacritics, case and punctuation" do + assert region("EG-FYM").has_name?("Al Fayyum") + assert region("EG-FYM").has_name?("al-fayyum") + assert region("EG-FYM").has_name?(" (Al) Fayyūm ") + assert region("CA-QC").has_name?("Québec") + assert region("CA-QC").has_name?("Quebec") + end + + test "#has_name? returns false when the zone does not have the given name" do + refute region("EG-FYM").has_name?("Fayyūm") + refute region("EG-FYM").has_name?("Quebec") + refute region("EG-FYM").has_name?(nil) + refute region("EG-FYM").has_name?("") + end + + test "#has_name? does not change the string that it is given" do + name = +"Al Fayyūm" + region("EG-FYM").has_name?(name) + + assert_equal "Al Fayyūm", name + end + + test "#has_handle? returns true if the zone has the given handle" do + assert region("EG-FYM").has_handle?("faiyum") + assert region("EG-FYM").has_handle?("al-fayyum") + end + + test "#has_handle? returns false when the zone does not have the given handle" do + refute region("EG-FYM").has_handle?("fayyum") + refute region("EG-FYM").has_handle?(nil) + refute Region.new(iso_code: "ZZ").has_handle?(nil) + end + + test "#name_alternates= replaces the handles that #has_handle? compares" do + zone = Region.new(iso_code: "XX-YY", legacy_name: "Yy") + zone.name_alternates = ["Zeta"] + + assert zone.has_handle?("zeta") + + zone.name_alternates = ["Éta"] + + refute zone.has_handle?("zeta") + assert zone.has_handle?("eta") + end + + # #neighbor? + + test "#neighbor? returns true for matching neighbours" do + assert_equal true, region("CA-ON").neighbor?("QC") + end + + test "#neighbor? returns false for non-matching neighbours" do + assert_equal false, region("CA-ON").neighbor?("BC") + end + + test "#neighbor? returns false when a zone does not have neighbours" do + assert_equal false, region("US-AK").neighbor?("BC") + assert_equal false, Region.new(iso_code: "XX-YY").tap { |zone| zone.neighbours = nil }.neighbor?("BC") + end + + # #valid_zone_zip? + + test "#valid_zone_zip? returns false for nil" do + refute region("CA-ON").valid_zone_zip?(nil) + end + + test "#valid_zone_zip? returns expected results" do + ["X0E1A1", "X0G2A2", "X1A3A3"].each do |zip| + assert region("CA-NT").valid_zone_zip?(zip) + end + refute region("CA-NT").valid_zone_zip?("K1A444") + end + + test "#valid_zone_zip? returns expected results for AL, USA" do + al = region("US-AL") + + assert_equal false, al.valid_zone_zip?("00000") + assert_equal true, al.valid_zone_zip?("35004") + assert_equal false, al.valid_zone_zip?("h3w2h5") + end + + test "#valid_zone_zip? returns expected results for the weird forward sortation area K1A" do + assert region("CA-ON").valid_zone_zip?("K1A9A6") + assert region("CA-QC").valid_zone_zip?("K1A0H4") + end + + test "#valid_zone_zip? is case-insensitive" do + ["k1s 1a1", "K1s 1a1", "k1S 1A1", "k1s1a1", "k1S1a1"].each do |zip| + assert region("CA-ON").valid_zone_zip?(zip) + end + + ["d0g 3e3", "d0g3e3", "degfcb", "a1aa1a"].each do |zip| + assert_equal false, region("CA-NL").valid_zone_zip?(zip) + end + end + + test "#valid_zone_zip? accepts certain popular English postcodes" do + other_uk_zones = ["GB-BFP", "GB-NIR", "GB-SCT", "GB-WLS"] + ["DE12 6DT", "FY1 4JH", "N3 2QS", "PR9 7HA", "S5 9GA"].each do |zip| + assert_equal true, region("GB-ENG").valid_zone_zip?(zip) + + other_uk_zones.each do |zone_code| + assert_equal false, region(zone_code).valid_zone_zip?(zip), "'#{zip}' should not be a valid postcode for #{zone_code}" + end + end + end + + test "#valid_zone_zip? accepts certain Scottish postcodes" do + other_uk_zones = ["GB-BFP", "GB-ENG", "GB-NIR", "GB-WLS"] + ["AB35 5TB", "DD1 3JA", "EH16 5BQ", "G4 0QZ", "ZE1 0HB"].each do |zip| + assert_equal true, region("GB-SCT").valid_zone_zip?(zip) + + other_uk_zones.each do |zone_code| + assert_equal false, region(zone_code).valid_zone_zip?(zip), "'#{zip}' should not be a valid postcode for #{zone_code}" + end + end + end + + test "#valid_zone_zip? is flexible about spaces and capitalization in GB" do + ["Ab355tb", "dD1 3Ja", "eh16 5bq", "g40Qz", "ZE10HB"].each do |zip| + assert_equal true, region("GB-SCT").valid_zone_zip?(zip) + end + end + + test "#valid_zone_zip? accepts the first part of a zip only when partial_match is true" do + assert_equal false, region("CA-ON").valid_zone_zip?("K2A") + assert_equal true, region("CA-ON").valid_zone_zip?("K2A", partial_match: true) + assert_equal false, region("CA-ON").valid_zone_zip?("V6B", partial_match: true) + end + + test "#valid_zone_zip? accepts a zip with an optional country prefix" do + ["15001", "ES-15001", "E-15001", "es 15001"].each do |zip| + assert_equal true, region("ES-C").valid_zone_zip?(zip), zip + assert_equal false, region("ES-M").valid_zone_zip?(zip), zip + end + end + + test "#valid_zone_zip? treats a blank zip like valid_zip? in a country that does not require one" do + zone = region("HK-HK") + + refute_predicate zone.associated_country, :zip_required? + [nil, "", " "].each do |zip| + assert_equal true, zone.valid_zone_zip?(zip), "valid_zone_zip?(#{zip.inspect})" + assert_equal true, zone.valid_zip?(zip), "valid_zip?(#{zip.inspect})" + end + end + + test "#valid_zone_zip? returns false for a blank zip in a country that requires one" do + [nil, "", " "].each do |zip| + assert_equal false, region("CA-ON").valid_zone_zip?(zip) + end + end + + test "#valid_zone_zip? accepts a zip for a zone without prefixes when the country has a zone for the zip" do + zone = region("CA-ON") + zone.stubs(:zip_prefixes).returns([]) + + assert_equal true, zone.valid_zone_zip?("V6B 4A2") + assert_equal false, zone.valid_zip?("V6B 4A2") + assert_equal false, zone.valid_zone_zip?("0000000") + end + + test "#valid_zone_zip? accepts a zip whose zone shares a prefix with another zone" do + # "K1A" is a prefix of both CA-ON and CA-QC, and valid_zip? infers only one of them + assert_equal true, region("CA-ON").valid_zone_zip?("K1A ", partial_match: true) + assert_equal true, region("CA-QC").valid_zone_zip?("K1A ", partial_match: true) + assert_equal false, region("CA-QC").valid_zip?("K1A ", partial_match: true) + end + + test "#valid_zone_zip? accepts a zip that is shorter than the prefix of the zone" do + zone = region("TR-02") + + assert_includes zone.zip_prefixes, "02" + assert_equal true, zone.valid_zone_zip?("0") + assert_equal false, zone.valid_zip?("0") + end + + test "#valid_zone_zip? gives the same result as valid_zip? for a region that is not a province" do + ["V6B 4A2", "K1A", "nonsense", "", nil].each do |zip| + assert_equal region("CA").valid_zip?(zip), region("CA").valid_zone_zip?(zip), "CA #{zip.inspect}" + end + end + + test "#valid_zone_zip? does not change valid_zip?" do + assert_equal true, region("CA-ON").valid_zip?("K1A9A6") + assert_equal true, region("CA-QC").valid_zip?("K1A0H4") + assert_equal true, region("CA-NT").valid_zip?("X0E1A1") + assert_equal false, region("CA-NT").valid_zip?("K1A444") + end + + # Zone attributes and lookups + + test "zones have the expected attribute values" do + assert_equal ["PQ"], region("CA-QC").code_alternates + assert_equal "Ontario", region("CA-ON").legacy_name + assert_equal ["Al Fayyūm"], region("EG-FYM").name_alternates + assert_equal ["QC", "MB"], region("CA-ON").neighbours + assert_equal ["T"], region("CA-AB").zip_prefixes + assert_empty region("AE-AZ").zip_prefixes + assert_equal 47, region("JP-01").priority + assert_in_delta(0.13, region("CA-ON").tax_rate) + assert_equal "HST", region("CA-ON").tax_name + assert_equal "harmonized", region("CA-ON").tax_type + assert_equal "Huntsville", region("US-AL").example_city + assert_equal "35801", region("US-AL").example_city_zip + assert_nil region("NZ").zones.first.example_city + assert_nil region("NZ").zones.first.example_city_zip + assert_equal "England", region("GB-ENG").full_name(locale: :en) + assert_equal "Angleterre", region("GB-ENG").full_name(locale: :fr) + end + + test "#zone finds a province by zip" do + assert_equal "Quebec", region("CA").zone(zip: "K1A 1C9").legacy_name + assert_equal "Ontario", region("CA").zone(zip: "K1A0H2").legacy_name + assert_same Worldwide.unknown_region, region("CA").zone(zip: "123 456") + end + + test "#zone finds a province in GB even with extra spaces in the zip" do + assert_equal "England", region("GB").zone(zip: "SW1 1AA").legacy_name + assert_equal "England", region("GB").zone(zip: "Sw1 1aa").legacy_name + end + + test "#zone does not find a province by an invalid zip" do + assert_same Worldwide.unknown_region, region("CA").zone(zip: "BOGUS") + assert_same Worldwide.unknown_region, region("CA").zone(zip: "A1A A1A") + end + + test "#zone finds a province by a partial zip if the country hides provinces" do + assert_equal "England", region("GB").zone(zip: "SW1").legacy_name + assert_equal "England", region("GB").zone(zip: "CH4").legacy_name + assert_equal "Wales", region("GB").zone(zip: "CH6").legacy_name + assert_equal "Scotland", region("GB").zone(zip: "AB1").legacy_name + assert_equal "Scotland", region("GB").zone(zip: "TD1").legacy_name + assert_equal "England", region("GB").zone(zip: "TD12").legacy_name + assert_equal "Northern Ireland", region("GB").zone(zip: "BT1").legacy_name + end + + test "#zone does not find a province by a partial zip if the country does not hide provinces" do + assert_same Worldwide.unknown_region, region("CA").zone(zip: "K1S") + assert_same Worldwide.unknown_region, region("JE").zone(zip: "JE1") + assert_same Worldwide.unknown_region, region("SH").zone(zip: "STHL") + assert_same Worldwide.unknown_region, region("US").zone(zip: "90") + end + + test "#zone finds the same province by an alternate code as by the code" do + assert_same region("CA").zone(code: "QC"), region("CA").zone(code: "PQ") + assert_same region("CA").zone(code: "NL"), region("CA").zone(code: "NF") + end + + test "#iso_code of a zone is the ISO code, including where the legacy code differs" do + assert_equal "COR", region("CO").zone(code: "COR").legacy_code + assert_equal "CO-COR", region("CO").zone(code: "COR").iso_code + assert_equal "CA-ON", region("CA").zone(code: "ON").iso_code + assert_equal "JP-13", region("JP").zone(code: "JP-13").iso_code + assert_equal "JP-13", region("JP").zone(code: "13").iso_code + end + end +end diff --git a/test/worldwide/util_test.rb b/test/worldwide/util_test.rb new file mode 100644 index 000000000..2afd27e44 --- /dev/null +++ b/test/worldwide/util_test.rb @@ -0,0 +1,150 @@ +# frozen_string_literal: true + +require "test_helper" + +module Worldwide + class UtilTest < ActiveSupport::TestCase + test ".utf8_handle lowercases and replaces runs of punctuation and spaces with a hyphen" do + assert_equal "al-fayyum", Util.utf8_handle("Al Fayyūm") + assert_equal "new-south-wales", Util.utf8_handle("New South Wales") + assert_equal "a-b", Util.utf8_handle("A / B") + assert_equal "a_b", Util.utf8_handle("a_b") + assert_equal "a-b", Util.utf8_handle("--a--b--") + end + + test ".utf8_handle drops quotes and brackets" do + assert_equal "obrien-test", Util.utf8_handle("O'Brien (Test)") + assert_equal "ab", Util.utf8_handle("\"a\"[b]") + end + + test ".utf8_handle replaces Latin letters that have diacritics with the base letter" do + assert_equal "quebec", Util.utf8_handle("Québec") + assert_equal "sao-paulo", Util.utf8_handle("São Paulo") + assert_equal "nandu", Util.utf8_handle("ñandú") + assert_equal "zurich", Util.utf8_handle("Zürich") + end + + test ".utf8_handle keeps letters with diacritics that are outside of Latin-1 and Latin Extended-A" do + assert_equal "ḥasakah", Util.utf8_handle("Ḥasakah") + end + + test ".utf8_handle approximates Latin letters that have no base letter" do + assert_equal "aeroskobing", Util.utf8_handle("Ærøskøbing") + assert_equal "strasse", Util.utf8_handle("Straße") + assert_equal "lodz", Util.utf8_handle("Łódź") + assert_equal "dong-nai", Util.utf8_handle("Đông Nai") + assert_equal "thor", Util.utf8_handle("Þór") + assert_equal "oe", Util.utf8_handle("œ") + assert_equal "n", Util.utf8_handle("ʼn") + end + + test ".utf8_handle gives the same result for composed and decomposed letters" do + assert_equal Util.utf8_handle("Québec"), Util.utf8_handle("Que\u0301bec") + end + + test ".utf8_handle keeps letters of other scripts and emoji" do + assert_equal "日本", Util.utf8_handle("日本") + assert_equal "москва", Util.utf8_handle("Москва") + assert_equal "йошкар-ола", Util.utf8_handle("Йошкар-Ола") + assert_equal "ελλάδα", Util.utf8_handle("Ελλάδα") + assert_equal "aeroskobing-日本-👴🏾", Util.utf8_handle("Ærøskøbing 日本 👴🏾") + end + + test ".utf8_handle returns an empty string for a string without letters" do + assert_equal "", Util.utf8_handle("") + assert_equal "", Util.utf8_handle(" - ") + end + + test ".utf8_handle returns a frozen string and does not change its argument" do + input = +"Al Fayyūm" + result = Util.utf8_handle(input) + + assert_predicate result, :frozen? + assert_equal "Al Fayyūm", input + assert_equal Encoding::UTF_8, input.encoding + end + + test ".utf8_handle repairs a string with invalid bytes" do + assert_equal "ebc", Util.utf8_handle((+"\xE9bc").force_encoding(Encoding::BINARY)) + assert_equal "cafe", Util.utf8_handle((+"caf\xC3\xA9").force_encoding(Encoding::BINARY)) + end + + test ".ascii_casecmp_substring? with basic functionality" do + assert_equal(true, Util.ascii_casecmp_substring?("example", "example", start1: 0, length1: 7, start2: 0, length2: 7)) + assert_equal(true, Util.ascii_casecmp_substring?("AbCdEf", "abcdef", start1: 0, length1: 6, start2: 0, length2: 6)) + assert_equal(false, Util.ascii_casecmp_substring?("hello", "world", start1: 0, length1: 7, start2: 0, length2: 5)) + + assert_equal(true, Util.ascii_casecmp_substring?("start", "finishstart", start1: 0, length1: 5, start2: 6, length2: 5)) + assert_equal(true, Util.ascii_casecmp_substring?("full", "full", start1: 0, length1: 4, start2: 0, length2: 4)) + assert_equal(true, Util.ascii_casecmp_substring?("a", "a", start1: 0, length1: 1, start2: 0, length2: 1)) + + assert_equal(false, Util.ascii_casecmp_substring?("", "", start1: 0, length1: 1, start2: 0, length2: 1)) + end + + test ".ascii_casecmp_substring? with a difference in the case of ASCII letters only" do + assert_equal(true, Util.ascii_casecmp_substring?("[@`{", "[@`{", start1: 0, length1: 4, start2: 0, length2: 4)) + assert_equal(false, Util.ascii_casecmp_substring?("@", "`", start1: 0, length1: 1, start2: 0, length2: 1)) + assert_equal(false, Util.ascii_casecmp_substring?("[", "{", start1: 0, length1: 1, start2: 0, length2: 1)) + assert_equal(true, Util.ascii_casecmp_substring?("Z", "z", start1: 0, length1: 1, start2: 0, length2: 1)) + end + + test ".ascii_casecmp_substring? with length exceeding string size" do + assert_equal(false, Util.ascii_casecmp_substring?("short", "longer", start1: 0, length1: 10, start2: 0, length2: 10)) + end + + test ".ascii_casecmp_substring? with non-ASCII characters" do + assert_equal(false, Util.ascii_casecmp_substring?("ñandú", "nandu", start1: 0, length1: 5, start2: 0, length2: 5)) + end + + test ".ascii_casecmp_substring? counts bytes, not characters" do + assert_equal(true, Util.ascii_casecmp_substring?("ñ-ON", "ñ-on", start1: 3, length1: 2, start2: 3, length2: 2)) + assert_equal(false, Util.ascii_casecmp_substring?("ñ-ON", "ñ-on", start1: 3, length1: 3, start2: 3, length2: 3)) + end + + test ".ascii_casecmp_substring? with boundary ASCII characters" do + assert_equal(true, Util.ascii_casecmp_substring?("\x00\x7F", "\x00\x7F", start1: 0, length1: 2, start2: 0, length2: 2)) + end + + test ".ascii_casecmp_substring? throws for nil comparison" do + assert_raises(ArgumentError) do + Util.ascii_casecmp_substring?(nil, "test", start1: 1, length1: 1, start2: 1, length2: 1) + end + assert_raises(ArgumentError) do + Util.ascii_casecmp_substring?("test", nil, start1: 1, length1: 1, start2: 1, length2: 2) + end + end + + test ".ascii_casecmp_substring? throws for zero length" do + assert_raises(ArgumentError) do + Util.ascii_casecmp_substring?("test", "test", start1: 1, length1: 1, start2: 1, length2: 0) + end + assert_raises(ArgumentError) do + Util.ascii_casecmp_substring?("test", "test", start1: 1, length1: 0, start2: 1, length2: 1) + end + end + + test ".ascii_casecmp_substring? throws for negative start1 or start2" do + assert_raises(ArgumentError) do + Util.ascii_casecmp_substring?("test", "test", start1: -1, length1: 1, start2: 1, length2: 1) + end + assert_raises(ArgumentError) do + Util.ascii_casecmp_substring?("test", "test", start1: 1, length1: 1, start2: -1, length2: 1) + end + end + + test ".ascii_casecmp_substring? does not allocate" do + measure = -> do + GC.start + GC.disable + before = GC.stat(:total_allocated_objects) + 10.times { Util.ascii_casecmp_substring?("start", "finishSTART", start1: 0, length1: 5, start2: 6, length2: 5) } + GC.stat(:total_allocated_objects) - before + ensure + GC.enable + end + measure.call + + assert_equal 0, measure.call + end + end +end