pico_phone 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b484e1d4028dcaf1cd1a8ef45092853a111df96ce88c2b23a1a5d0adb95292bd
-  data.tar.gz: acd5433d7b8c973c10d1c01560e4c4367c4d5a2828178de8cd9970b4d8fc32cf
+  metadata.gz: bac62c280ce5ac633b95536c04c0bc7bb0672beaa0a44928ba128b367c845b93
+  data.tar.gz: b567f397b99d3a93b9309c19c6797eb6b96a4db3e7c3860d2c5e9d0a9033fc41
 SHA512:
-  metadata.gz: f4612e8029c13f8498e4f78a15913641ecb46e6f2e2864844209a5e6f962cad7168f83aaa412fc948e6520ff6709bb45eb9f9fd30ac275c37d6ee5596947b1f5
-  data.tar.gz: c255297aba501623563ca3132b30f6ae7fec878de5f41a8938b9b86bd11f5780d4258f5e095c2c24695bbc02b9ffab796bf0ce0dd6b4d428367d157bf0b38adc
+  metadata.gz: 17a4f165dc820b929d587401ab31c895701d74d4802cfb414e1c044345e7e733b787a7956e02e5dd55228ab83f9bbf917c575b0550f62597120577c5bcc2df05
+  data.tar.gz: 4aa9e0e6507d71f14fcaf11242d2a0b666707eebb60afffbf85988414a771bc6596d13638cbe8e9ea5ffb66e0bd08720d1064e3fa799683eb87c1d34340f3724

data/ext/pico_phone/pico_phone.cpp

@@ -14,13 +14,18 @@
 // any ICU header is reachable.
 #undef UChar
 #include <phonenumbers/geocoding/phonenumber_offline_geocoder.h>
+#include <phonenumbers/phonenumbermatcher.h>
+#include <phonenumbers/phonenumbermatch.h>
 #include "carrier_mapper.h"
 #include "timezone_mapper.h"
 
+#include <climits>
+
 using namespace Rice;
 using namespace i18n::phonenumbers;
 
 static VALUE rb_cPhoneNumber;
+static VALUE rb_cPhoneNumberMatch;
 static VALUE rb_mPicoPhone;
 
 size_t phone_number_size(const void *data) { return sizeof(PhoneNumber); }
@@ -195,6 +200,112 @@ Object pico_phone_is_alpha_number(Object self, String str) {
   return phone_util.IsAlphaNumber(str.c_str()) ? Qtrue : Qfalse;
 }
 
+int pico_phone_country_calling_code(Object self, String region) {
+  const PhoneNumberUtil &phone_util(*PhoneNumberUtil::GetInstance());
+  return phone_util.GetCountryCodeForRegion(std::string(region.c_str()));
+}
+
+static VALUE match_type_to_symbol(PhoneNumberUtil::MatchType match_type) {
+  switch (match_type) {
+    case PhoneNumberUtil::INVALID_NUMBER:  return rb_id2sym(rb_intern("invalid_number"));
+    case PhoneNumberUtil::NO_MATCH:        return rb_id2sym(rb_intern("no_match"));
+    case PhoneNumberUtil::SHORT_NSN_MATCH: return rb_id2sym(rb_intern("short_nsn_match"));
+    case PhoneNumberUtil::NSN_MATCH:       return rb_id2sym(rb_intern("nsn_match"));
+    case PhoneNumberUtil::EXACT_MATCH:     return rb_id2sym(rb_intern("exact_match"));
+    default:                               return rb_id2sym(rb_intern("no_match"));
+  }
+}
+
+Object pico_phone_number_match(Object self, String first, String second) {
+  const PhoneNumberUtil &phone_util(*PhoneNumberUtil::GetInstance());
+  return match_type_to_symbol(phone_util.IsNumberMatchWithTwoStrings(first.c_str(), second.c_str()));
+}
+
+Object parsed_number_match_type(Object self, Object other) {
+  PhoneNumber *phone_number;
+  TypedData_Get_Struct(self, PhoneNumber, &phone_number_type, phone_number);
+  const PhoneNumberUtil &phone_util(*PhoneNumberUtil::GetInstance());
+
+  if (RTEST(rb_obj_is_kind_of(other, rb_cPhoneNumber))) {
+    PhoneNumber *other_number;
+    TypedData_Get_Struct(other, PhoneNumber, &phone_number_type, other_number);
+    return match_type_to_symbol(phone_util.IsNumberMatch(*phone_number, *other_number));
+  }
+
+  VALUE other_val = other.value();
+  std::string other_str(StringValuePtr(other_val), RSTRING_LEN(other_val));
+  return match_type_to_symbol(phone_util.IsNumberMatchWithOneString(*phone_number, other_str));
+}
+
+static PhoneNumberMatcher::Leniency symbol_to_leniency(VALUE sym) {
+  ID id = rb_to_id(sym);
+  if (id == rb_intern("possible"))        return PhoneNumberMatcher::POSSIBLE;
+  if (id == rb_intern("strict_grouping")) return PhoneNumberMatcher::STRICT_GROUPING;
+  if (id == rb_intern("exact_grouping"))  return PhoneNumberMatcher::EXACT_GROUPING;
+  return PhoneNumberMatcher::VALID;
+}
+
+Object phone_number_match_start(Object self) {
+  return rb_ivar_get(self, rb_intern("@start"));
+}
+
+Object phone_number_match_end_index(Object self) {
+  return rb_ivar_get(self, rb_intern("@end_index"));
+}
+
+Object phone_number_match_raw_string(Object self) {
+  return rb_ivar_get(self, rb_intern("@raw_string"));
+}
+
+Object phone_number_match_number(Object self) {
+  return rb_ivar_get(self, rb_intern("@number"));
+}
+
+VALUE pico_phone_find_numbers(int argc, VALUE *argv, VALUE self) {
+  VALUE text, region, kwargs;
+  rb_scan_args(argc, argv, "2:", &text, &region, &kwargs);
+
+  ID kwarg_ids[1] = { rb_intern("leniency") };
+  VALUE kwarg_vals[1];
+  rb_get_kwargs(kwargs, kwarg_ids, 0, 1, kwarg_vals);
+
+  PhoneNumberMatcher::Leniency leniency = PhoneNumberMatcher::VALID;
+  if (kwarg_vals[0] != Qundef) {
+    leniency = symbol_to_leniency(kwarg_vals[0]);
+  }
+
+  std::string text_str(StringValuePtr(text), RSTRING_LEN(text));
+  std::string region_str(StringValuePtr(region), RSTRING_LEN(region));
+
+  const PhoneNumberUtil &phone_util(*PhoneNumberUtil::GetInstance());
+  PhoneNumberMatcher matcher(phone_util, text_str, region_str, leniency, INT_MAX);
+
+  Array result;
+  PhoneNumberMatch match;
+  while (matcher.HasNext()) {
+    matcher.Next(&match);
+
+    int start_pos = match.start();
+    int end_pos = match.end();
+    std::string raw = match.raw_string();
+
+    std::string e164;
+    phone_util.Format(match.number(), PhoneNumberUtil::E164, &e164);
+    VALUE num_args[1] = { rb_str_new(e164.c_str(), e164.size()) };
+    VALUE number_obj = rb_class_new_instance(1, num_args, rb_cPhoneNumber);
+
+    VALUE match_obj = rb_obj_alloc(rb_cPhoneNumberMatch);
+    rb_ivar_set(match_obj, rb_intern("@start"), INT2FIX(start_pos));
+    rb_ivar_set(match_obj, rb_intern("@end_index"), INT2FIX(end_pos));
+    rb_ivar_set(match_obj, rb_intern("@raw_string"), rb_str_new(raw.c_str(), raw.size()));
+    rb_ivar_set(match_obj, rb_intern("@number"), number_obj);
+
+    result.push(Object(match_obj));
+  }
+
+  return result;
+}
+
 static const ShortNumberInfo& GetShortNumberInfo() {
   static ShortNumberInfo instance;
   return instance;
@@ -850,6 +961,24 @@ Object parsed_number_possible_for_type(Object self, Object type_sym) {
   return phone_util.IsPossibleNumberForType(*phone_number, type) ? Qtrue : Qfalse;
 }
 
+Object parsed_number_truncate(Object self) {
+  PhoneNumber *phone_number;
+  TypedData_Get_Struct(self, PhoneNumber, &phone_number_type, phone_number);
+  const PhoneNumberUtil &phone_util(*PhoneNumberUtil::GetInstance());
+
+  // TruncateTooLongNumber returns true for already-valid numbers without
+  // modifying them. Guard so callers get nil for the "nothing to do" case.
+  if (phone_util.IsValidNumber(*phone_number)) return Qnil;
+
+  PhoneNumber copy(*phone_number);
+  if (!phone_util.TruncateTooLongNumber(&copy)) return Qnil;
+
+  std::string formatted;
+  phone_util.Format(copy, PhoneNumberUtil::E164, &formatted);
+  VALUE args[1] = { rb_str_new(formatted.c_str(), formatted.size()) };
+  return rb_class_new_instance(1, args, rb_cPhoneNumber);
+}
+
 extern "C"
 void Init_pico_phone() {
   rb_mPicoPhone = define_module("PicoPhone")
@@ -863,12 +992,16 @@ void Init_pico_phone() {
     .define_singleton_method("supported_regions", &pico_phone_supported_regions)
     .define_singleton_method("convert_alpha_characters", &pico_phone_convert_alpha_characters)
     .define_singleton_method("alpha_number?", &pico_phone_is_alpha_number)
+    .define_singleton_method("number_match", &pico_phone_number_match)
     .define_singleton_method("emergency_number?", &pico_phone_is_emergency_number)
     .define_singleton_method("short_number_valid?", &pico_phone_is_short_number_valid)
     .define_singleton_method("short_number_cost", &pico_phone_short_number_cost)
     .define_singleton_method("supported_types_for_region", &pico_phone_supported_types_for_region)
     .define_singleton_method("example_number", &pico_phone_example_number)
-    .define_singleton_method("example_number_for_type", &pico_phone_example_number_for_type);
+    .define_singleton_method("example_number_for_type", &pico_phone_example_number_for_type)
+    .define_singleton_method("country_calling_code", &pico_phone_country_calling_code);
+
+    rb_define_singleton_method(rb_mPicoPhone, "find_numbers", reinterpret_cast<VALUE (*)(...)>(pico_phone_find_numbers), -1);
 
     rb_define_module_function(rb_mPicoPhone, "default_country=", reinterpret_cast<VALUE (*)(...)>(pico_phone_set_default_country), 1);
     rb_define_module_function(rb_mPicoPhone, "default_extension_prefix=", reinterpret_cast<VALUE (*)(...)>(pico_phone_set_default_extension_prefix), 1);
@@ -909,7 +1042,15 @@ void Init_pico_phone() {
     .define_method("geographical?", &parsed_number_geographical)
     .define_method("can_be_internationally_dialled?", &parsed_number_can_be_internationally_dialled)
     .define_method("possible_for_type?", &parsed_number_possible_for_type)
-    .define_method("timezones", &parsed_number_timezones);
+    .define_method("timezones", &parsed_number_timezones)
+    .define_method("truncate", &parsed_number_truncate)
+    .define_method("match_type", &parsed_number_match_type);
+
+    rb_cPhoneNumberMatch = define_class_under(rb_mPicoPhone, "PhoneNumberMatch")
+      .define_method("start", &phone_number_match_start)
+      .define_method("end_index", &phone_number_match_end_index)
+      .define_method("raw_string", &phone_number_match_raw_string)
+      .define_method("number", &phone_number_match_number);
 
     rb_define_alloc_func(rb_cPhoneNumber, rb_phone_number_alloc);
     rb_define_method(rb_cPhoneNumber, "initialize", reinterpret_cast<VALUE (*)(...)>(phone_number_initialize), -1);

data/lib/pico_phone/phone_number.rb

@@ -79,6 +79,46 @@ module PicoPhone
   #   @param string [String]
   #   @return [Boolean]
 
+  # @!method self.country_calling_code(region)
+  #   Returns the international calling code for a region.
+  #   Returns 0 for unknown or invalid region codes.
+  #   @param region [String] ISO 3166-1 alpha-2 region code (e.g. "US")
+  #   @return [Integer] e.g. 1 for "US", 33 for "FR", 0 for unknown
+
+  # @!method self.number_match(first, second)
+  #   Compare two phone number strings and return how closely they match.
+  #   Neither string requires a region hint; E.164 input gives the most precise result.
+  #   @param first [String]
+  #   @param second [String]
+  #   @return [Symbol] :exact_match, :nsn_match, :short_nsn_match, :no_match, or :invalid_number
+
+  # @!method self.find_numbers(text, region, leniency: :valid)
+  #   Scan a block of text and return every phone number found in it.
+  #   @param text [String] arbitrary text to search (must be valid UTF-8)
+  #   @param region [String] ISO 3166-1 alpha-2 default region for numbers without a country code
+  #   @param leniency [Symbol] :possible, :valid (default), :strict_grouping, or :exact_grouping
+  #   @return [Array<PhoneNumberMatch>]
+
+  # Represents a single phone number match found by {PicoPhone.find_numbers}.
+  class PhoneNumberMatch
+    # Byte offset of the match start within the searched text.
+    # @return [Integer]
+    def start; end
+
+    # Exclusive byte offset of the match end within the searched text.
+    # The matched substring is text[start...end_index].
+    # @return [Integer]
+    def end_index; end
+
+    # The substring of the searched text that was matched.
+    # @return [String]
+    def raw_string; end
+
+    # The parsed phone number.
+    # @return [PhoneNumber]
+    def number; end
+  end
+
   class PhoneNumber
     # @param string [String, nil] raw phone number input
     # @param region [String, nil] ISO 3166-1 alpha-2 region hint (e.g. "US")
@@ -226,6 +266,14 @@ module PicoPhone
     # @return [Boolean]
     def geographical?; end
 
+    # Compare this number against another and return how closely they match.
+    # Pass a String or a PhoneNumber. When passed a PhoneNumber, the country code
+    # stored in the proto is used for comparison, giving more precise results than
+    # a bare national-format string.
+    # @param other [String, PhoneNumber]
+    # @return [Symbol] :exact_match, :nsn_match, :short_nsn_match, :no_match, or :invalid_number
+    def match_type(other); end
+
     # True when the number's digit count is consistent with the given type in its region.
     # More permissive than {#type}: a 10-digit US number is possible for both
     # :fixed_line_or_mobile and :toll_free since they share the same digit count.
@@ -236,5 +284,11 @@ module PicoPhone
     # False for numbers that only work within their own country.
     # @return [Boolean]
     def can_be_internationally_dialled?; end
+
+    # Removes trailing digits until the number is valid, returning the truncated
+    # number as a new PhoneNumber. Returns nil if the number was not too long or
+    # if no valid truncation exists. Does not mutate the receiver.
+    # @return [PhoneNumber, nil]
+    def truncate; end
   end
 end

data/lib/pico_phone/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PicoPhone
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pico_phone
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Gabi Jack
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-17 00:00:00.000000000 Z
+date: 2026-07-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rice