sztheory/mini_phone

[mirror] A fast phone number lib for Ruby (binds go native libphonenumber)

MiniPhone

A Ruby gem which plugs directly into Google's native C++ libphonenumber for extremely fast and robust phone number parsing, validation, and formatting. On average, most methods are 70x to 80x faster than other Ruby phone number libraries.

Usage

Checking if a phone number is valid

MiniPhone.valid?('[phone]')                     # true
MiniPhone.valid_for_country?('[phone]', 'US') # true
MiniPhone.valid_for_country?('[phone]', 'GB') # false

Formatting a number

MiniPhone.default_country = 'US'

phone_number = MiniPhone.parse('404-384-1399')

phone_number.e164                 # [phone]
phone_number.national             # [phone]
phone_number.raw_national         # 4043841399
phone_number.dasherized_national  # 404-384-1399
phone_number.international        # [phone]
phone_number.rfc3966              # tel:[phone]

Checking if a phone number is possible

phone_number = MiniPhone.parse('-12')

phone_number.possible? # false

Getting the type of a phone number

MiniPhone.parse('[phone]').type # :mobile
MiniPhone.parse('[phone]').type # :fixed_line

The possible types are directly mapped from this enum:

:fixed_line
:mobile
:fixed_line_or_mobile
:toll_free
:premium_rate
:shared_cost
:voip
:personal_number
:pager
:uan
:voicemail
:unknown

Compatibility with PhoneLib

MiniPhone aims to be compatible with Phonelib. In many cases it can be a drop in replacement. It has a smaller feature set, so it is not a replacement for every use case. If there is a feature you need, open an issue and we will try to support it.

Benchmarks

On average, most methods are 40x to 50x faster than other libraries. To run the benchmarks locally, execute: bundle exec rake bench

# Results from my Linux (5.10.6-arch1-10)

Comparison:
    Phonelib: valid?:      426.0 i/s
   MiniPhone: valid?:    34707.9 i/s - 81.47x faster

Comparison:
      Phonelib: e164:      580.3 i/s
     MiniPhone: e164:    43385.9 i/s - 74.76x faster

Installation

1. Install libphonenumber

   brew install libphonenumber # mac

   apt-get install -y libphonenumber-dev # debian / ubuntu

2. Add this line to your application's Gemfile:

   gem 'mini_phone'

3. And then execute:

   bundle install

   Or install it yourself as:

   gem install mini_phone

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.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/ianks/mini_phone. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the MiniPhone project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.