formatOutOfCountryCallingNumber method

String formatOutOfCountryCallingNumber(PhoneNumber number, String regionCallingFrom)

Formats a phone number for out-of-country dialing purposes. If no regionCallingFrom is supplied, we format the number in its international format. If the country calling code is the same as that of the region where the number is from, then national formatting will be applied.

If the number itself has a country calling code of zero or an otherwise invalid country calling code, then we return the number with no formatting applied.

Note this function takes care of the case for calling inside of NANPA and between Russia and Kazakhstan (who share the same country calling code). In those cases, no international prefix is used. For regions which have multiple international prefixes, the number in its [international] format will be returned instead.

number the phone number to be formatted. regionCallingFrom the region where the call is being placed.

Implementation

String formatOutOfCountryCallingNumber(
    PhoneNumber number, String regionCallingFrom) {
  if (!_isValidRegionCode(regionCallingFrom)) {
    return format(number, PhoneNumberFormat.international);
  }

  int countryCallingCode = number.countryCode;

  String nationalSignificantNumber = getNationalSignificantNumber(number);
  if (!_hasValidCountryCallingCode(countryCallingCode)) {
    return nationalSignificantNumber;
  }
  if (countryCallingCode == _nanpaCountryCode) {
    if (isNANPACountry(regionCallingFrom)) {
      // For NANPA regions, return the national format for these regions but
      // prefix it with the country calling code.
      return '$countryCallingCode ${format(number, PhoneNumberFormat.national)}';
    }
  } else if (countryCallingCode ==
      _getCountryCodeForValidRegion(regionCallingFrom)) {
    // If regions share a country calling code, the country calling code need
    // not be dialled. This also applies when dialling within a region, so this
    // if clause covers both these cases. Technically this is the case for
    // dialling from La Reunion to other overseas departments of France (French
    // Guiana, Martinique, Guadeloupe), but not vice versa - so we don't cover
    // this edge case for now and for those cases return the version including
    // country calling code. Details here:
    // http://www.petitfute.com/voyage/225-info-pratiques-reunion
    return format(number, PhoneNumberFormat.national);
  }
  // Metadata cannot be null because we checked 'isValidRegionCode()' above.
  PhoneMetadata metadataForRegionCallingFrom =
      getMetadataForRegion(regionCode: regionCallingFrom)!;

  String internationalPrefix =
      metadataForRegionCallingFrom.internationalPrefix;

  // For regions that have multiple international prefixes, the international
  // format of the number is returned, unless there is a preferred international
  // prefix.
  String internationalPrefixForFormatting = '';
  if (metadataForRegionCallingFrom.hasPreferredInternationalPrefix()) {
    internationalPrefixForFormatting =
        metadataForRegionCallingFrom.preferredInternationalPrefix;
  } else if (matchesEntirely(
      _singleInternationalPrefix, internationalPrefix)) {
    internationalPrefixForFormatting = internationalPrefix;
  }

  String regionCode = getRegionCodeForCountryCode(countryCallingCode);
  // Metadata cannot be null because the country calling code is valid.
  PhoneMetadata metadataForRegion =
      _getMetadataForRegionOrCallingCode(countryCallingCode, regionCode)!;

  String formattedNationalNumber = _formatNsn(
    nationalSignificantNumber,
    metadataForRegion,
    PhoneNumberFormat.international,
  );

  String formattedExtension = _maybeGetFormattedExtension(
    number,
    metadataForRegion,
    PhoneNumberFormat.international,
  );

  return internationalPrefixForFormatting.isNotEmpty
      ? '$internationalPrefixForFormatting $countryCallingCode $formattedNationalNumber$formattedExtension'
      : _prefixNumberWithCountryCallingCode(
          countryCallingCode,
          PhoneNumberFormat.international,
          formattedNationalNumber,
          formattedExtension,
        );
}