https://github.com/joallard/ca-postal-code
A toolbox for Canadian postal codes: validating, normalizing and guessing their region.
https://github.com/joallard/ca-postal-code
canada canada-post postalcode ruby
Last synced: 7 months ago
JSON representation
A toolbox for Canadian postal codes: validating, normalizing and guessing their region.
- Host: GitHub
- URL: https://github.com/joallard/ca-postal-code
- Owner: joallard
- License: mit
- Created: 2018-04-10T21:57:51.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2023-03-08T18:15:30.000Z (almost 3 years ago)
- Last Synced: 2025-06-16T04:37:15.858Z (8 months ago)
- Topics: canada, canada-post, postalcode, ruby
- Language: Ruby
- Homepage:
- Size: 18.6 KB
- Stars: 5
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# CAPostalCode
A toolbox for Canadian postal codes: validating, normalizing and guessing their region.
```ruby
CAPostalCode.valid?("h1b2p3")
# => true
CAPostalCode.normalize("e3b.4k5 ")
# => "E3B 4K5"
CAPostalCode.guess_region("K1A 0B3")
# => "ON"
CAPostalCode.guess_region("X0C 1A1")
# => "NU"
```
## Usage
### Validity
After normalizing the string, verifies if it fits the format for a postal code.
Strings containing letters D, F, I, O, Q, and those starting with W or Z are invalid.
```ruby
CAPostalCode.valid?("h1b2p3")
# => true
CAPostalCode.valid?("F8G 1A1")
# => false
CAPostalCode.valid?("potato")
# => false
CAPostalCode.valid?("P0T 4T0")
# => true
```
### Normalization
Normalize the string to look like a postal code.
It does not check for validity. Rather, the `.valid?` method relies on this one to make its work easier.
```ruby
CAPostalCode.normalize("e3b.4k5 ")
# => "E3B 4K5"
CAPostalCode.normalize("g1c 4z9")
# => "G1C 4Z9"
CAPostalCode.normalize("potato")
# => "POT ATO"
```
### Region guessing
Guesses the Canadian province or territory (*region*) based on the postal code.
For provinces and Yukon, it will guess based on the first letter. For Northwest Territories and Nunavut, it will check the first two or three characters.
```ruby
CAPostalCode.guess_region("G1A 1A1")
# => "QC"
CAPostalCode.guess_region("X0C 1A1")
# => "NU"
CAPostalCode.guess_region("B6A 1A1")
# => "NS"
```
## Installation
In your Gemfile:
gem "ca_postal_code"
Or install it yourself:
gem install ca_postal_code
## Development
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/joallard/ca-postal-code.