PhoneNumberUtil

rlibphonenumber

Struct PhoneNumberUtil 

Source 
pub struct PhoneNumberUtil { /* private fields */ }
Expand description

The main struct for all phone number-related operations.

It encapsulates the library’s core logic and provides a public API for parsing, formatting, and validating phone numbers. An instance of this struct is the primary entry point for using the library’s features.

Implementations§

Source§

impl PhoneNumberUtil

Source

pub fn new() -> Self

Creates new PhoneNumberUtil instance

Source

pub fn can_be_internationally_dialled(&self, phone_number: &PhoneNumber) -> bool

Checks if a PhoneNumber can be dialed internationally.

§Parameters
  • phone_number: A reference to the PhoneNumber object to be checked.
§Returns

true if the number can be dialed from another country, false otherwise.

§Panics

This method panics if the underlying metadata contains an invalid regular expression, which indicates a critical library bug.

Source

pub fn convert_alpha_characters_in_number<'a>( &self, number: impl AsRef<str>, ) -> String

Converts all alpha characters in a phone number string to their corresponding digits.

For example, an input of “1-800-FLOWERS” will be converted to “1-800-3569377”.

§Parameters
  • number: A string slice or String representing the phone number.
§Returns

A String containing the phone number with all alphabetic characters converted to digits.

Source

pub fn format<'a>( &self, phone_number: &'a PhoneNumber, number_format: PhoneNumberFormat, ) -> Cow<'a, str>

Formats a PhoneNumber into a standardized format.

§Parameters
  • phone_number: The PhoneNumber to be formatted.
  • number_format: The PhoneNumberFormat to be applied (e.g., E164, INTERNATIONAL, NATIONAL).
§Returns

A Cow<'a, str> which is either a borrowed reference to a pre-formatted string or a newly allocated String with the formatted number.

§Panics

This method panics if the underlying metadata contains an invalid regular expression, indicating a library bug.

Source

pub fn format_in_original_format<'a>( &self, phone_number: &'a PhoneNumber, region_calling_from: impl AsRef<str>, ) -> Cow<'a, str>

Formats a PhoneNumber, attempting to preserve original formatting and punctuation.

The number is formatted in the national format of the region it is from.

§Parameters
  • phone_number: The PhoneNumber to be formatted.
  • region_calling_from: The two-letter region code (ISO 3166-1) from where the call is being made.
§Returns

A Cow<'a, str> containing the formatted number.

§Panics

This method panics if metadata is invalid, which indicates a library bug.

Source

pub fn format_national_number_with_carrier_code<'a>( &self, phone_number: &'a PhoneNumber, carrier_code: impl AsRef<str>, ) -> String

Formats a national number with a specified carrier code.

§Parameters
  • phone_number: The PhoneNumber to format.
  • carrier_code: The carrier code to prepend to the number.
§Returns

A String containing the formatted number.

§Panics

Panics if metadata is invalid, indicating a library bug.

Source

pub fn format_number_for_mobile_dialing<'a>( &self, phone_number: &'a PhoneNumber, region_calling_from: impl AsRef<str>, with_formatting: bool, ) -> Cow<'a, str>

Formats a PhoneNumber for dialing from a mobile device.

§Parameters
  • phone_number: The PhoneNumber to format.
  • region_calling_from: The two-letter region code (ISO 3166-1) where the user is.
  • with_formatting: If true, the number is formatted with punctuation; otherwise, only digits are returned.
§Returns

A Cow<'a, str> with the dialable number.

§Panics

Panics if formatting fails due to a library bug.

Source

pub fn format_out_of_country_calling_number<'a>( &self, phone_number: &'a PhoneNumber, region_calling_from: impl AsRef<str>, ) -> Cow<'a, str>

Formats a PhoneNumber for out-of-country calling.

§Parameters
  • phone_number: The PhoneNumber to format.
  • region_calling_from: The two-letter region code (ISO 3166-1) of the calling location.
§Returns

A Cow<'a, str> representing the number formatted for international dialing.

§Panics

Panics on invalid metadata, indicating a library bug.

Source

pub fn format_out_of_country_keeping_alpha_chars<'a>( &self, phone_number: &'a PhoneNumber, region_calling_from: impl AsRef<str>, ) -> Cow<'a, str>

Formats a PhoneNumber for out-of-country calling while preserving any alphabetic characters.

§Parameters
  • phone_number: The PhoneNumber to format.
  • region_calling_from: The two-letter region code (ISO 3166-1) of the calling location.
§Returns

A Cow<'a, str> with the formatted number.

§Panics

Panics on invalid metadata, indicating a library bug.

Source

pub fn get_country_code_for_region( &self, region_code: impl AsRef<str>, ) -> Option<i32>

Retrieves the country calling code for a given region.

§Parameters
  • region_code: The two-letter region code (ISO 3166-1).
§Returns

An Option<i32> containing the country code, or None if the region code is invalid.

Source

pub fn get_example_number( &self, region_code: impl AsRef<str>, ) -> Result<PhoneNumber, GetExampleNumberError>

Gets a valid example PhoneNumber for a specific region.

§Parameters
  • region_code: The two-letter region code (ISO 3166-1).
§Returns

A Result containing a valid PhoneNumber on success, or a GetExampleNumberError on failure.

Source

pub fn get_example_number_for_type( &self, number_type: PhoneNumberType, ) -> Result<PhoneNumber, GetExampleNumberError>

Gets a valid example PhoneNumber for a specific number type.

§Parameters
  • number_type: The desired PhoneNumberType (e.g., MOBILE, TOLL_FREE).
§Returns

A Result containing a PhoneNumber on success, or GetExampleNumberError if no example exists.

Source

pub fn get_invalid_example_number( &self, region_code: impl AsRef<str>, ) -> Result<PhoneNumber, GetExampleNumberError>

Gets an invalid but plausible example PhoneNumber for a specific region.

§Parameters
  • region_code: The two-letter region code (ISO 3166-1).
§Returns

A Result containing an invalid PhoneNumber on success, or a GetExampleNumberError on failure.

Source

pub fn get_length_of_geographical_area_code( &self, phone_number: &PhoneNumber, ) -> usize

Gets the length of the geographical area code from a PhoneNumber.

§Parameters
  • phone_number: The PhoneNumber to examine.
§Returns

The length of the area code, or 0 if it cannot be determined.

§Panics

Panics on invalid metadata, indicating a library bug.

Source

pub fn get_length_of_national_destination_code( &self, phone_number: &PhoneNumber, ) -> usize

Gets the length of the national destination code from a PhoneNumber.

§Parameters
  • phone_number: The PhoneNumber to examine.
§Returns

The length of the national destination code.

§Panics

Panics on invalid metadata, indicating a library bug.

Source

pub fn get_national_significant_number<'a>( &self, phone_number: &'a PhoneNumber, ) -> String

Gets the National Significant Number (NSN) from a PhoneNumber.

The NSN is the part of the number that follows the country code.

§Parameters
  • phone_number: The PhoneNumber from which to extract the NSN.
§Returns

A String containing the NSN.

Source

pub fn get_number_type(&self, phone_number: &PhoneNumber) -> PhoneNumberType

Determines the PhoneNumberType of a given PhoneNumber.

§Parameters
  • phone_number: The PhoneNumber to be categorized.
§Returns

The PhoneNumberType (e.g., MOBILE, FIXED_LINE, UNKNOWN).

§Panics

Panics on invalid metadata, indicating a library bug.

Source

pub fn get_region_code_for_country_code(&self, country_code: i32) -> &str

Gets the primary region code for a given country calling code.

Note: Some country codes are shared by multiple regions (e.g., +1 for USA, Canada). This returns the main region for that code (e.g., “US” for +1).

§Parameters
  • country_code: The country calling code.
§Returns

A string slice with the corresponding two-letter region code. Returns “ZZ” for invalid codes.

Source

pub fn get_region_code_for_number(&self, phone_number: &PhoneNumber) -> &str

Gets the region code for a PhoneNumber.

§Parameters
  • phone_number: The PhoneNumber to identify.
§Returns

A string slice with the two-letter region code.

§Panics

Panics on invalid metadata, indicating a library bug.

Source

pub fn get_region_codes_for_country_code( &self, country_code: i32, ) -> Option<impl ExactSizeIterator<Item = &str>>

Gets all region codes associated with a country calling code.

§Parameters
  • country_code: The country calling code.
§Returns

An Option containing an iterator over all associated region codes, or None if the country code is invalid.

Source

pub fn get_supported_regions(&self) -> impl ExactSizeIterator<Item = &str>

Gets an iterator over all supported two-letter region codes.

§Returns

An ExactSizeIterator that yields string slices of all supported region codes.

Source

pub fn is_alpha_number(&self, number: impl AsRef<str>) -> bool

Checks if a number string contains alphabetic characters.

§Parameters
  • number: The phone number string to check.
§Returns

true if the string contains letters, false otherwise.

Source

pub fn is_nanpa_country(&self, region_code: impl AsRef<str>) -> bool

Checks if a region is part of the North American Numbering Plan (NANPA).

§Parameters
  • region_code: The two-letter region code (ISO 3166-1) to check.
§Returns

true if the region is a NANPA country, false otherwise.

Source

pub fn is_number_geographical(&self, phone_number: &PhoneNumber) -> bool

Checks if a PhoneNumber is geographical.

§Parameters
  • phone_number: The PhoneNumber to check.
§Returns

true if the number corresponds to a specific geographic area.

§Panics

Panics on invalid metadata, indicating a library bug.

Source

pub fn is_number_match( &self, first_number: &PhoneNumber, second_number: &PhoneNumber, ) -> MatchType

Compares two phone numbers and returns their MatchType.

§Parameters
  • first_number: The first PhoneNumber to compare.
  • second_number: The second PhoneNumber to compare.
§Returns

The MatchType indicating the level of similarity (e.g., EXACT_MATCH, NSN_MATCH).

Source

pub fn is_possible_number(&self, phone_number: &PhoneNumber) -> bool

Performs a fast check to determine if a PhoneNumber is possibly valid.

This method is less strict than is_valid_number.

§Parameters
  • phone_number: The PhoneNumber to check.
§Returns

true if the number has a valid length, false otherwise.

Source

pub fn is_possible_number_with_reason( &self, phone_number: &PhoneNumber, ) -> Result<NumberLengthType, ValidationError>

Checks if a PhoneNumber is possibly valid and provides a reason if not.

§Parameters
  • phone_number: The PhoneNumber to check.
§Returns

A Result which is Ok(NumberLengthType) on success or a ValidationError on failure.

Source

pub fn is_valid_number(&self, phone_number: &PhoneNumber) -> bool

Performs a full validation of a PhoneNumber.

This is a more comprehensive check than is_possible_number.

§Parameters
  • phone_number: The PhoneNumber to validate.
§Returns

true if the number is valid, false otherwise.

§Panics

Panics on invalid metadata, indicating a library bug.

Source

pub fn is_valid_number_for_region( &self, phone_number: &PhoneNumber, region: impl AsRef<str>, ) -> bool

Validates a PhoneNumber for a specific region.

§Parameters
  • phone_number: The PhoneNumber to validate.
  • region: The two-letter region code (ISO 3166-1) to validate against.
§Returns

true if the number is valid for the given region, false otherwise.

Source

pub fn parse_and_keep_raw_input( &self, number_to_parse: impl AsRef<str>, default_region: impl AsRef<str>, ) -> Result<PhoneNumber, ParseError>

Parses a string into a PhoneNumber, keeping the raw input string.

§Parameters
  • number_to_parse: The phone number string.
  • default_region: The two-letter region code (ISO 3166-1) to use if the number is not in international format.
§Returns

A Result containing the parsed PhoneNumber on success, or a ParseError on failure.

Source

pub fn parse( &self, number_to_parse: impl AsRef<str>, default_region: impl AsRef<str>, ) -> Result<PhoneNumber, ParseError>

Parses a string into a PhoneNumber.

This is the primary method for converting a string representation of a number into a structured PhoneNumber object.

§Parameters
  • number_to_parse: The phone number string.
  • default_region: The two-letter region code (ISO 3166-1) to use if the number is not in international format.
§Returns

A Result containing the parsed PhoneNumber on success, or a ParseError on failure.

Source

pub fn truncate_too_long_number(&self, phone_number: &mut PhoneNumber) -> bool

Truncates a PhoneNumber that is too long to a valid length.

§Parameters
  • phone_number: A mutable reference to the PhoneNumber to truncate.
§Returns

true if the number was truncated, false otherwise.

§Panics

Panics on invalid metadata, indicating a library bug.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.