Skip to content

Add zone code, name and zip matching to Worldwide::Region - #682

Open
DominiqueFlaaa wants to merge 6 commits into
mainfrom
torrent/atlas-16-add-countrydb-zone-behaviour-to-worldwid
Open

DominiqueFlaaa wants to merge 6 commits into
mainfrom
torrent/atlas-16-add-countrydb-zone-behaviour-to-worldwid

Conversation

@DominiqueFlaaa

@DominiqueFlaaa DominiqueFlaaa commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

What changes

Worldwide::Region gets methods to match a zone by code, by name and by zip.

  • Region#has_code?(code) is true when the code is the region's legacy_code, one of its code_alternates, or its iso_code. It is also true for the country code, a hyphen and the legacy code ("CA-NL" for the Newfoundland and Labrador zone), and for the part of a hyphenated legacy code after the hyphen ("13" for JP-13). It ignores the case of ASCII letters. It accepts a symbol. It allocates no strings, and a test checks this.
  • Region#has_name?(name) and Region#has_handle?(handle) compare a name, or a handle, with the region's legacy_name and name_alternates. They ignore case, diacritics and punctuation, so "Fayyum" matches "Al Fayyūm".
  • Region#neighbor?(code) is true when the legacy code is in neighbours.
  • Region#valid_zone_zip?(zip, partial_match: false) checks a zip against the zip prefixes of one province. See below.
  • Util.utf8_handle(string) makes a lowercase handle from a name. Latin letters with diacritics become their base letters. Letters such as ø, ß and ł become ASCII approximations. Quotes and brackets are removed. Each other run of punctuation or space becomes one hyphen. Letters of other scripts and emoji stay. It repairs a string with invalid bytes, and it does not change its argument.
  • Util.ascii_casecmp_substring? compares a part of one string with a part of another string, ignoring the case of ASCII letters. It compares bytes and allocates no objects.

Region#name_alternates is now a reader and an explicit name_alternates= writer. The writer clears the cached handles. The doc comment of neighbours now says that it holds legacy codes such as "QC", which is what the data holds.

valid_zip? is unchanged

On a province, valid_zip? infers one province from the zip prefixes of the whole country. It accepts the zip when that province is the one asked about, or when zips_crossing_provinces lists it. valid_zone_zip? instead accepts the zip when the country accepts it and one of the province's own zip_prefixes matches it. Because valid_zip? keeps its behaviour for existing callers, this is a new method. The results differ in these cases:

Region Zip partial_match valid_zip? valid_zone_zip?
CA-QC "K1A " (a prefix of both CA-ON and CA-QC) true false true
TR-02 "0" (shorter than the prefix "02") false false true
A province without zip_prefixes, in a country whose other provinces have prefixes a zip that the country accepts false false true

For a region that is not a province, valid_zone_zip? returns what valid_zip? returns. A blank zip is valid in a country that does not require a zip, and invalid in a country that does. A zip with an optional country prefix, such as "ES-15001", is handled as valid_zip? handles it.

Architecture

The new methods are part of Region. The two helpers are in Util. valid_zone_zip? uses the same country-level checks as valid_zip?.

flowchart LR
  Region["Worldwide::Region<br/>has_code? has_name? has_handle?<br/>neighbor? valid_zone_zip?<br/>valid_zip? (unchanged)"] --> Util["Worldwide::Util<br/>utf8_handle<br/>ascii_casecmp_substring?"]
  Region --> Zip["Worldwide::Zip<br/>normalize<br/>strip_optional_country_prefix"]
Loading

Requested by dominique.flabbi dominique.flabbi@shopify.com

CountryDb::Zone still holds logic that Region lacks. Add it to Region so
that a later change can make CountryDb::Zone delegate to it.

- Region#has_code?: matches the legacy code, a code alternate, the ISO
  code, "CA-NL" for NL and "13" for JP-13. It allocates no strings.
- Region#has_name? and #has_handle?: compare simplified names, so
  "Fayyum" matches "Fayyūm". Worldwide::Util.utf8_handle does the
  simplifying, so that worldwide needs no Shopify-internal gem.
- Region#neighbor?.
- Region#valid_zone_zip?: country_db's postal_code_valid?. It differs
  from valid_zip? for a province, which infers one province from the
  zip. valid_zip? is unchanged.
- Worldwide::Util.ascii_casecmp_substring?, which has_code? uses.

Co-authored-by: dominique.flabbi <dominique.flabbi@shopify.com>
Co-authored-by: dominique.flabbi <dominique.flabbi@shopify.com>
Ruby 3.4 warns about the character class that listed \p{Word} and
\p{Extended_Pictographic} together, because the two overlap. A negative
lookahead with alternatives says the same without the warning.

Co-authored-by: dominique.flabbi <dominique.flabbi@shopify.com>
…to-worldwid

Co-authored-by: dominique.flabbi <dominique.flabbi@shopify.com>
@DominiqueFlaaa
DominiqueFlaaa marked this pull request as ready for review November 16, 2026 23:21
@DominiqueFlaaa
DominiqueFlaaa requested a review from a team as a code owner November 16, 2026 23:21

@o-benz o-benz left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm, reran the comparison the other way and has_code?/has_name?/neighbor?/valid_zone_zip? match CountryDb::Zone across all 1,209 zones

Reword the CHANGELOG entry, a test name and two comments so that they
say what Region does now.

Co-authored-by: dominique.flabbi <dominique.flabbi@shopify.com>
@DominiqueFlaaa DominiqueFlaaa changed the title Add zone lookup and validation behaviour to Worldwide::Region Add zone code, name and zip matching to Worldwide::Region Nov 17, 2026
Co-authored-by: dominique.flabbi <dominique.flabbi@shopify.com>

# Conflicts:
#	CHANGELOG.md

@ananyaneogi ananyaneogi left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just some non blocking comments

Comment thread lib/worldwide/region.rb
#
# @param code [String, Symbol]
# @return [Boolean]
def has_code?(code)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: This byte matching path (match_unprefixed_code?, suffix_matches?, match_suffix_only_code? and Util.ascii_casecmp_substring?) is a lot of code for a few short ASCII codes. Could we build each region's accepted codes once and compare them with casecmp? In a quick check across all zones it gave the same results.

Comment thread lib/worldwide/region.rb
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.valid_zip?(adjusted, partial_match: partial_match)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nits: adjusted is already normalized here, but country.valid_zip? normalizes it again. Checking adjusted directly would skip the repeat.
The return false if zip.nil? below also looks unreachable: a blank zip would always return here.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants