pico_phone 0.3.2 → 0.5.0

data/ext/pico_phone/carrier_mapper.cc

@@ -0,0 +1,127 @@
+// First-party pico_phone file. See carrier_mapper.h.
+
+#include "carrier_mapper.h"
+
+#include <algorithm>
+#include <cstring>
+#include <string>
+
+#include "phonenumbers/geocoding/area_code_map.h"
+#include "phonenumbers/geocoding/carrier_data.h"
+#include "phonenumbers/geocoding/mapping_file_provider.h"
+#include "phonenumbers/phonenumber.pb.h"
+
+#include "absl/synchronization/mutex.h"
+
+namespace i18n {
+namespace phonenumbers {
+
+using std::string;
+
+namespace {
+
+// Returns true if s1 comes strictly before s2 in lexicographic order.
+bool IsLowerThan(const char* s1, const char* s2) {
+  return strcmp(s1, s2) < 0;
+}
+
+}  // namespace
+
+PhoneNumberCarrierMapper::PhoneNumberCarrierMapper() {
+  provider_.reset(new MappingFileProvider(get_carrier_country_calling_codes(),
+                                          get_carrier_country_calling_codes_size(),
+                                          get_carrier_country_languages));
+  prefix_language_code_pairs_ = get_carrier_prefix_language_code_pairs();
+  prefix_language_code_pairs_size_ = get_carrier_prefix_language_code_pairs_size();
+  get_prefix_descriptions_ = get_carrier_prefix_descriptions;
+}
+
+PhoneNumberCarrierMapper::~PhoneNumberCarrierMapper() {
+  // Pointer-taking constructor, not the reference-taking one: this file
+  // compiles against two different Abseil versions depending on build path
+  // (vendored 20260526.0 for the static/native build, whatever Debian/Ubuntu
+  // packages for the dynamic/apt-linked build), and only the older
+  // pointer-taking overload exists in both. The vendored geocoder itself hit
+  // the same tension in the other direction (see build_deps.sh's
+  // absl::MutexLock patch) -- there it's a -Werror'd deprecation inside
+  // libphonenumber's own CMake build; here it's just a harmless warning
+  // since pico_phone's own extension build doesn't set -Werror.
+  absl::MutexLock l(&mu_);
+  for (AreaCodeMaps::const_iterator it = available_maps_.begin();
+       it != available_maps_.end(); ++it) {
+    delete it->second;
+  }
+}
+
+const AreaCodeMap* PhoneNumberCarrierMapper::GetPhonePrefixDescriptions(
+    int prefix, const string& language, const string& script,
+    const string& region) const {
+  string filename;
+  provider_->GetFileName(prefix, language, script, region, &filename);
+  if (filename.empty()) {
+    return NULL;
+  }
+  AreaCodeMaps::const_iterator it = available_maps_.find(filename);
+  if (it == available_maps_.end()) {
+    return LoadAreaCodeMapFromFile(filename);
+  }
+  return it->second;
+}
+
+const AreaCodeMap* PhoneNumberCarrierMapper::LoadAreaCodeMapFromFile(
+    const string& filename) const {
+  const char** const prefix_language_code_pairs_end =
+      prefix_language_code_pairs_ + prefix_language_code_pairs_size_;
+  const char** const prefix_language_code_pair =
+      std::lower_bound(prefix_language_code_pairs_,
+                       prefix_language_code_pairs_end,
+                       filename.c_str(), IsLowerThan);
+  if (prefix_language_code_pair != prefix_language_code_pairs_end &&
+      filename.compare(*prefix_language_code_pair) == 0) {
+    AreaCodeMap* const m = new AreaCodeMap();
+    m->ReadAreaCodeMap(get_prefix_descriptions_(
+            prefix_language_code_pair - prefix_language_code_pairs_));
+    return available_maps_.insert(AreaCodeMaps::value_type(filename, m))
+        .first->second;
+  }
+  return NULL;
+}
+
+const char* PhoneNumberCarrierMapper::GetAreaDescription(
+    const PhoneNumber& number, const string& lang, const string& script,
+    const string& region) const {
+  const int country_calling_code = number.country_code();
+  // NANPA area is not split in C++ code (matches PhoneNumberOfflineGeocoder).
+  const int phone_prefix = country_calling_code;
+  absl::MutexLock l(&mu_);
+  const AreaCodeMap* const descriptions = GetPhonePrefixDescriptions(
+      phone_prefix, lang, script, region);
+  const char* description = descriptions ? descriptions->Lookup(number) : NULL;
+  // When a carrier name is not available in the requested language, fall
+  // back to English.
+  if ((!description || *description == '\0') && MayFallBackToEnglish(lang)) {
+    const AreaCodeMap* default_descriptions = GetPhonePrefixDescriptions(
+        phone_prefix, "en", "", "");
+    if (!default_descriptions) {
+      return "";
+    }
+    description = default_descriptions->Lookup(number);
+  }
+  return description ? description : "";
+}
+
+// Don't fall back to English if the requested language is among the following:
+// - Chinese
+// - Japanese
+// - Korean
+bool PhoneNumberCarrierMapper::MayFallBackToEnglish(const string& lang) const {
+  return lang.compare("zh") && lang.compare("ja") && lang.compare("ko");
+}
+
+string PhoneNumberCarrierMapper::GetNameForNumber(
+    const PhoneNumber& number, const string& lang) const {
+  return GetAreaDescription(number, lang, "", "");
+}
+
+}  // namespace phonenumbers
+}  // namespace i18n

data/ext/pico_phone/carrier_mapper.h

@@ -0,0 +1,88 @@
+// First-party pico_phone file. A trimmed mirror of libphonenumber's
+// PhoneNumberOfflineGeocoder (phonenumbers/geocoding/
+// phonenumber_offline_geocoder.h in the vendored source), reusing the same
+// AreaCodeMap/MappingFileProvider machinery -- lazy per (country calling
+// code, language) file loading, cached for the life of the process -- but
+// backed by carrier_data.cc instead of geocoding_data.cc, and with the
+// ICU-based country-name fallback removed: carrier data has no natural
+// "fall back to the country name" concept (unlike geocoding), so an
+// unmapped prefix returns an empty string, matching phonelib's carrier
+// semantics. This also means, unlike the geocoder, this class has no ICU
+// dependency at all.
+
+#ifndef PICO_PHONE_CARRIER_MAPPER_H_
+#define PICO_PHONE_CARRIER_MAPPER_H_
+
+#include <map>
+#include <string>
+
+#include "absl/synchronization/mutex.h"
+#include "phonenumbers/base/memory/scoped_ptr.h"
+
+namespace i18n {
+namespace phonenumbers {
+
+class AreaCodeMap;
+class MappingFileProvider;
+class PhoneNumber;
+struct CountryLanguages;
+struct PrefixDescriptions;
+
+class PhoneNumberCarrierMapper {
+ private:
+  typedef std::map<std::string, const AreaCodeMap*> AreaCodeMaps;
+
+ public:
+  PhoneNumberCarrierMapper();
+
+  PhoneNumberCarrierMapper(const PhoneNumberCarrierMapper&) = delete;
+  PhoneNumberCarrierMapper& operator=(const PhoneNumberCarrierMapper&) = delete;
+
+  ~PhoneNumberCarrierMapper();
+
+  // Returns the carrier name for the given phone number in the given
+  // language, or an empty string if no carrier mapping is available for
+  // this prefix. lang is a two or three-letter lowercase ISO 639 language
+  // code, as with PhoneNumberOfflineGeocoder.
+  //
+  // The carrier name is the one the number was originally allocated to,
+  // however if the country supports mobile number portability the number
+  // might not belong to the returned carrier anymore (same caveat as
+  // upstream's Java-only PhoneNumberToCarrierMapper.getNameForNumber,
+  // verbatim -- see java/carrier/src/.../PhoneNumberToCarrierMapper.java
+  // in the vendored source tree).
+  std::string GetNameForNumber(const PhoneNumber& number,
+                               const std::string& lang) const;
+
+ private:
+  typedef const PrefixDescriptions* (*prefix_descriptions_getter)(int index);
+
+  const AreaCodeMap* LoadAreaCodeMapFromFile(
+      const std::string& filename) const ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_);
+
+  const AreaCodeMap* GetPhonePrefixDescriptions(
+      int prefix, const std::string& language, const std::string& script,
+      const std::string& region) const ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_);
+
+  const char* GetAreaDescription(const PhoneNumber& number,
+                                 const std::string& lang,
+                                 const std::string& script,
+                                 const std::string& region) const
+      ABSL_LOCKS_EXCLUDED(mu_);
+
+  bool MayFallBackToEnglish(const std::string& lang) const;
+
+  scoped_ptr<const MappingFileProvider> provider_;
+
+  const char** prefix_language_code_pairs_;
+  int prefix_language_code_pairs_size_;
+  prefix_descriptions_getter get_prefix_descriptions_;
+
+  mutable absl::Mutex mu_;
+  mutable AreaCodeMaps available_maps_ ABSL_GUARDED_BY(mu_);
+};
+
+}  // namespace phonenumbers
+}  // namespace i18n
+
+#endif  // PICO_PHONE_CARRIER_MAPPER_H_

data/ext/pico_phone/extconf.rb

@@ -2,6 +2,14 @@ require "mkmf-rice"
 
 $CXXFLAGS << ' -std=c++17'
 
+# carrier_mapper.cc needs AreaCodeMap/MappingFileProvider/the
+# CountryLanguages+PrefixDescriptions structs, none of which libphonenumber
+# installs publicly (only phonenumber_offline_geocoder.h is installed) in
+# either build path below. Headers vendored verbatim under
+# vendor_headers/phonenumbers/geocoding/ -- see that directory's own
+# comments. Needed unconditionally, regardless of NATIVE_BUILD.
+$INCFLAGS << " -I#{File.expand_path("vendor_headers", __dir__)}"
+
 VENDOR_INSTALL = File.expand_path("vendor/install", __dir__)
 NATIVE_BUILD = ENV["PICO_PHONE_NATIVE_BUILD"] == "1"
 
@@ -11,14 +19,30 @@ if NATIVE_BUILD
   $INCFLAGS << " -I#{VENDOR_INSTALL}/include"
 
   static_libs = []
+  # geocoding depends on symbols from phonenumber, so it must precede it in
+  # the static link order.
+  static_libs << "#{VENDOR_INSTALL}/lib/libgeocoding.a"
   static_libs << "#{VENDOR_INSTALL}/lib/libphonenumber.a"
   static_libs << "#{VENDOR_INSTALL}/lib/libprotobuf.a"
+  # protobuf's own transitive static deps (UTF-8 validation, upb). Whole-archive
+  # linking (below) force-includes every object in libprotobuf.a, including
+  # members that reference these, so they must be present even though nothing
+  # in our own code calls them directly. libutf8_range and libutf8_validity are
+  # two CMake target names for the exact same compiled object (utf8_range.c.o)
+  # in this protobuf version — link only one, or whole-archive pulls in both
+  # copies and the linker sees duplicate symbols.
+  %w[libutf8_range libupb].each do |lib|
+    path = "#{VENDOR_INSTALL}/lib/#{lib}.a"
+    static_libs << path if File.exist?(path)
+  end
   static_libs += Dir["#{VENDOR_INSTALL}/lib/libabsl_*.a"].sort
 
   if RUBY_PLATFORM.include?("darwin")
     boost_prefix = `brew --prefix boost 2>/dev/null`.strip
     icu_prefix   = `brew --prefix icu4c@78 2>/dev/null`.strip
 
+    $INCFLAGS << " -I#{icu_prefix}/include"
+
     %w[libboost_date_time libboost_thread libboost_atomic].each do |lib|
       static_libs << "#{boost_prefix}/lib/#{lib}.a"
     end
@@ -31,18 +55,37 @@ if NATIVE_BUILD
     # Ubuntu's libicu-dev static archives are not compiled with -fPIC and cannot
     # be linked into a shared object. Link ICU dynamically instead — libicu74 is
     # part of the Ubuntu 24.04 base system and is present in the target environment.
+    # ICU headers (for the geocoder) come from the system libicu-dev package.
     $LOCAL_LIBS << " -licui18n -licuuc -licudata -lpthread -ldl"
   end
 
-  $LOCAL_LIBS << " " + static_libs.join(" ")
+  # Adding the geocoder introduces a circular reference among several small
+  # Abseil static archives (e.g. synchronization <-> log_internal). A plain
+  # left-to-right static link only pulls in archive members that satisfy an
+  # already-outstanding undefined symbol, which for a -bundle target isn't
+  # even validated until dlopen time — so a missing member surfaces as a
+  # runtime "symbol not found in flat namespace" error, not a link failure.
+  # Force-load every member of our own vendored archives so nothing gets
+  # silently dropped.
+  if RUBY_PLATFORM.include?("darwin")
+    $LOCAL_LIBS << " -Wl,-all_load " + static_libs.join(" ")
+  else
+    $LOCAL_LIBS << " -Wl,--whole-archive " + static_libs.join(" ") + " -Wl,--no-whole-archive"
+  end
 
   unless find_header("phonenumbers/phonenumberutil.h")
     abort "Could not find phonenumberutil.h in #{VENDOR_INSTALL}/include — run build_deps.sh first"
   end
+
+  unless find_header("phonenumbers/geocoding/phonenumber_offline_geocoder.h")
+    abort "Could not find the geocoding header in #{VENDOR_INSTALL}/include — run build_deps.sh first"
+  end
 else
   # Dynamic linking against system/Homebrew libraries (default developer workflow).
   if RUBY_PLATFORM.include?("darwin")
-    %w[libphonenumber protobuf abseil].each do |pkg|
+    # icu4c@78 is already a transitive dependency of Homebrew's libphonenumber
+    # formula (which itself ships geocoding), so no extra install step needed.
+    %w[libphonenumber protobuf abseil icu4c@78].each do |pkg|
       prefix = `brew --prefix #{pkg} 2>/dev/null`.strip
       next if prefix.empty?
       $INCFLAGS << " -I#{prefix}/include"
@@ -50,17 +93,26 @@ else
     end
   end
 
-  $LOCAL_LIBS << " -lphonenumber"
+  $LOCAL_LIBS << " -lphonenumber -lgeocoding"
 
   unless find_header("phonenumbers/phonenumberutil.h")
     abort <<~MSG
 
       Could not find libphonenumber. Please install it before installing this gem:
         macOS:  brew install libphonenumber
-        Ubuntu: sudo apt-get install libphonenumber-dev
+        Ubuntu: sudo apt-get install libphonenumber-dev libicu-dev
         Fedora: sudo dnf install libphonenumber-devel
     MSG
   end
+
+  unless find_header("phonenumbers/geocoding/phonenumber_offline_geocoder.h")
+    abort <<~MSG
+
+      Found libphonenumber but not its geocoding headers/library. On Debian/Ubuntu
+      this also needs ICU development headers:
+        sudo apt-get install libphonenumber-dev libicu-dev
+    MSG
+  end
 end
 
 create_makefile("pico_phone/pico_phone")

data/ext/pico_phone/pico_phone.cpp

@@ -3,10 +3,20 @@
 #include <string.h>
 #include <list>
 #include <set>
+#include <vector>
 #include <phonenumbers/phonenumber.pb.h>
 #include <phonenumbers/phonenumberutil.h>
 #include <phonenumbers/shortnumberinfo.h>
 
+// Ruby's regex engine (onigmo.h, pulled in via rice.hpp above) #defines UChar
+// as unsigned char; ICU (pulled in transitively by the geocoding header)
+// typedefs UChar as char16_t. We don't use Ruby's macro, so drop it before
+// any ICU header is reachable.
+#undef UChar
+#include <phonenumbers/geocoding/phonenumber_offline_geocoder.h>
+#include "carrier_mapper.h"
+#include "timezone_mapper.h"
+
 using namespace Rice;
 using namespace i18n::phonenumbers;
 
@@ -190,6 +200,77 @@ static const ShortNumberInfo& GetShortNumberInfo() {
   return instance;
 }
 
+// PhoneNumberOfflineGeocoder lazily loads its area-code-to-description data
+// one (country calling code, language) file at a time on first lookup, and
+// caches each loaded file for the life of this instance -- unlike phonelib's
+// extended data, nothing gets pulled into memory until it's actually queried.
+static const PhoneNumberOfflineGeocoder& GetGeocoder() {
+  static PhoneNumberOfflineGeocoder instance;
+  return instance;
+}
+
+VALUE parsed_number_geo_name(int argc, VALUE *argv, VALUE self) {
+  VALUE language;
+  rb_scan_args(argc, argv, "01", &language);
+
+  std::string language_code = RB_NIL_P(language)
+    ? "en"
+    : std::string(StringValuePtr(language), RSTRING_LEN(language));
+
+  PhoneNumber *phone_number;
+  TypedData_Get_Struct(self, PhoneNumber, &phone_number_type, phone_number);
+
+  Locale locale(language_code.c_str());
+  std::string description = GetGeocoder().GetDescriptionForNumber(*phone_number, locale);
+
+  return rb_str_new(description.c_str(), description.size());
+}
+
+// PhoneNumberCarrierMapper mirrors PhoneNumberOfflineGeocoder's lazy
+// per-(prefix, language) file loading and caching -- see carrier_mapper.h.
+static const PhoneNumberCarrierMapper& GetCarrierMapper() {
+  static PhoneNumberCarrierMapper instance;
+  return instance;
+}
+
+VALUE parsed_number_carrier_name(int argc, VALUE *argv, VALUE self) {
+  VALUE language;
+  rb_scan_args(argc, argv, "01", &language);
+
+  std::string language_code = RB_NIL_P(language)
+    ? "en"
+    : std::string(StringValuePtr(language), RSTRING_LEN(language));
+
+  PhoneNumber *phone_number;
+  TypedData_Get_Struct(self, PhoneNumber, &phone_number_type, phone_number);
+
+  std::string name = GetCarrierMapper().GetNameForNumber(*phone_number, language_code);
+
+  return rb_str_new(name.c_str(), name.size());
+}
+
+// PhoneNumberTimeZonesMapper eagerly loads its single flat prefix table
+// once at construction (unlike the geocoder/carrier mappers, there's no
+// per-language dimension or lazy per-file loading to do here) -- see
+// timezone_mapper.h.
+static const PhoneNumberTimeZonesMapper& GetTimeZonesMapper() {
+  static PhoneNumberTimeZonesMapper instance;
+  return instance;
+}
+
+Array parsed_number_timezones(Object self) {
+  PhoneNumber *phone_number;
+  TypedData_Get_Struct(self, PhoneNumber, &phone_number_type, phone_number);
+
+  std::vector<std::string> zones = GetTimeZonesMapper().GetTimeZonesForNumber(*phone_number);
+
+  Array result;
+  for (const auto& zone : zones) {
+    result.push(Object(rb_str_new(zone.c_str(), zone.size())));
+  }
+  return result;
+}
+
 Object pico_phone_is_emergency_number(Object self, String number, String region) {
   return GetShortNumberInfo().IsEmergencyNumber(number.c_str(), region.c_str()) ? Qtrue : Qfalse;
 }
@@ -827,8 +908,11 @@ void Init_pico_phone() {
     .define_method("possible_with_reason", &parsed_number_possible_with_reason)
     .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("possible_for_type?", &parsed_number_possible_for_type)
+    .define_method("timezones", &parsed_number_timezones);
 
     rb_define_alloc_func(rb_cPhoneNumber, rb_phone_number_alloc);
     rb_define_method(rb_cPhoneNumber, "initialize", reinterpret_cast<VALUE (*)(...)>(phone_number_initialize), -1);
+    rb_define_method(rb_cPhoneNumber, "geo_name", reinterpret_cast<VALUE (*)(...)>(parsed_number_geo_name), -1);
+    rb_define_method(rb_cPhoneNumber, "carrier_name", reinterpret_cast<VALUE (*)(...)>(parsed_number_carrier_name), -1);
 }