Flutter Libphonenumber

https://pub.dev/documentation/flutter_libphonenumber/
Admin
Flutter Libphonenumber is a wrapper around libphonenumber that provides synchronous phone number...
Tokens:14,879
Snippets:104
Trust Score:9.9
Update:7 months ago
Show doc for...
Tokens:
Raw
### API Reference Examples

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/index.html

Provides examples for fetching supported regions and formatting phone numbers asynchronously using the library's API.

```dart
// Fetch supported regions
final regions = {
  "UK": [CountryWithPhoneCode()],
  "US": [CountryWithPhoneCode()]
};

// Asynchronous formatting
final result = await format("+14145556666", "US");
// Returns: { formatted: "1 (414) 444-4444" }
```

--------------------------------

### GET /getAllSupportedRegions

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber

Retrieves a map of all supported regions and their corresponding phone code information.

```APIDOC
## GET /getAllSupportedRegions

### Description
Fetches a collection of all regions supported by the library, including their phone codes and metadata.

### Method
GET

### Endpoint
/getAllSupportedRegions

### Response
#### Success Response (200)
- **data** (Map<String, CountryWithPhoneCode>) - A map where keys are region codes and values are CountryWithPhoneCode objects.

#### Response Example
{
  "US": { "name": "United States", "phoneCode": "1" },
  "GB": { "name": "United Kingdom", "phoneCode": "44" }
}
```

--------------------------------

### Get All Supported Regions

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/index.html

Retrieves a map of all supported regions with their associated phone metadata.

```APIDOC
## GET /getAllSupportedRegions

### Description
Asynchronously retrieves a map containing all supported regions. Each key in the map is a region code, and the value is a `CountryWithPhoneCode` object with detailed phone metadata.

### Method
GET

### Endpoint
/getAllSupportedRegions

### Parameters
None

### Request Example
```dart
final regions = await getAllSupportedRegions();
```

### Response
#### Success Response (200)
- **regions** (Map<String, CountryWithPhoneCode>) - A map where keys are region codes (e.g., 'UK', 'US') and values are `CountryWithPhoneCode` objects.

#### Response Example
```json
{
  "UK": [
    {
      "phoneCode": "44",
      "countryCode": "GB",
      "exampleNumberMobileNational": "07400 123456",
      "exampleNumberFixedLineNational": "0121 234 5678",
      "phoneMaskMobileNational": "00000 000000",
      "phoneMaskFixedLineNational": "0000 000 0000",
      "exampleNumberMobileInternational": "+44 7400 123456",
      "exampleNumberFixedLineInternational": "+44 121 234 5678",
      "phoneMaskMobileInternational": "+00 0000 000000",
      "phoneMaskFixedLineInternational": "+00 000 000 0000",
      "countryName": "United Kingdom"
    }
  ],
  "US": [
    {
      "phoneCode": "1",
      "countryCode": "US",
      "exampleNumberMobileNational": "(415) 555-2671",
      "exampleNumberFixedLineNational": "(415) 555-2671",
      "phoneMaskMobileNational": "(000) 000-0000",
      "phoneMaskFixedLineNational": "(000) 000-0000",
      "exampleNumberMobileInternational": "+1 415 555 2671",
      "exampleNumberFixedLineInternational": "+1 415 555 2671",
      "phoneMaskMobileInternational": "+0 000 000 0000",
      "phoneMaskFixedLineInternational": "+0 000 000 0000",
      "countryName": "United States"
    }
  ]
}
```
```

--------------------------------

### Example Country Name Output

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryWithPhoneCode/countryName.html

This snippet shows an example of the output for the countryName property. It represents the name of the country to which the phone number belongs. This is a simple string output.

```text
United Kingdom

```

--------------------------------

### Example Mobile Number National Format (Plain Text)

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryWithPhoneCode/exampleNumberMobileNational.html

This snippet provides an example of a mobile number formatted in the national standard. It is a simple string representation.

```plaintext
07400 123456

```

--------------------------------

### Example Mobile Number (International Format) - Dart

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryWithPhoneCode/exampleNumberMobileInternational.html

The `exampleNumberMobileInternational` property is a final String that holds an example mobile number formatted for international use. It is part of the Flutter libphonenumber library and serves as a reference for testing or display purposes.

```dart
final String exampleNumberMobileInternational;

```

--------------------------------

### Example Fixed Line Number (National Format) - Dart

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryWithPhoneCode/exampleNumberFixedLineNational.html

Demonstrates the `exampleNumberFixedLineNational` property, which holds an example of a fixed-line phone number formatted for national use. This property is declared as a String and is final, meaning its value is assigned once and cannot be changed.

```dart
String exampleNumberFixedLineNational
final
0121 234 5678
```

```dart
final String exampleNumberFixedLineNational;
```

--------------------------------

### Get All Supported Regions

Source: https://pub.dev/documentation/flutter_libphonenumber

Asynchronously fetches all supported phone regions from the device. It returns a map where keys are region codes and values are CountryWithPhoneCode objects, providing comprehensive phone number mask and metadata for each region.

```dart
Future<Map<String, CountryWithPhoneCode>> getAllSupportedRegions()
```

--------------------------------

### CountryWithPhoneCode Class

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryWithPhoneCode-class.html

Provides detailed information about a country's phone code, including various formats and examples.

```APIDOC
## Class: CountryWithPhoneCode

### Description
Represents a country with its associated phone code, including example numbers and masks for different formats and types.

### Constructors

*   **CountryWithPhoneCode**({required String phoneCode, required String countryCode, required String exampleNumberMobileNational, required String exampleNumberFixedLineNational, required String phoneMaskMobileNational, required String phoneMaskFixedLineNational, required String exampleNumberMobileInternational, required String exampleNumberFixedLineInternational, required String phoneMaskMobileInternational, required String phoneMaskFixedLineInternational, required String? countryName})
    *   Creates an instance of `CountryWithPhoneCode` with all specified properties.

*   **CountryWithPhoneCode.gb()**
    *   Creates a `CountryWithPhoneCode` instance for the GB (United Kingdom) locale, useful for dummy data.

*   **CountryWithPhoneCode.us()**
    *   Creates a `CountryWithPhoneCode` instance for the US (United States) locale, useful for dummy data.

### Properties

*   **countryCode** (String) - The country locale code (e.g., 'US', 'GB').
*   **countryName** (String?) - The name of the country.
*   **exampleNumberFixedLineInternational** (String) - An example fixed-line number in international format.
*   **exampleNumberFixedLineNational** (String) - An example fixed-line number in national format.
*   **exampleNumberMobileInternational** (String) - An example mobile number in international format.
*   **exampleNumberMobileNational** (String) - An example mobile number in national format.
*   **phoneCode** (String) - The country's phone code (e.g., '+1', '+44').
*   **phoneMaskFixedLineInternational** (String) - The phone mask for fixed-line numbers in international format.
*   **phoneMaskFixedLineNational** (String) - The phone mask for fixed-line numbers in national format.
*   **phoneMaskMobileInternational** (String) - The phone mask for mobile numbers in international format.
*   **phoneMaskMobileNational** (String) - The phone mask for mobile numbers in national format.

### Methods

*   **getPhoneMask**({required PhoneNumberFormat format, required PhoneNumberType type, bool removeCountryCodeFromMask = false}) → String
    *   Retrieves the phone mask based on the specified number format and type. If `removeCountryCodeFromMask` is true, the country code will be excluded from the mask.

### Static Methods

*   **getCountryDataByPhone**(String phone, {int? subscringLength}) → CountryWithPhoneCode?
    *   Attempts to determine the `CountryWithPhoneCode` based on a given phone number. An optional `subscringLength` can be provided to limit the portion of the phone number used for matching.
```

--------------------------------

### Declare exampleNumberMobileNational Property (Dart)

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryWithPhoneCode/exampleNumberMobileNational.html

This snippet shows the declaration of the `exampleNumberMobileNational` property in Dart. It is a final String that holds an example mobile number in national format.

```dart
final String exampleNumberMobileNational;

```

--------------------------------

### Initialize CountryWithPhoneCode for GB in Dart

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryWithPhoneCode/CountryWithPhoneCode.gb.html

This Dart code snippet demonstrates the implementation of the `CountryWithPhoneCode.gb` constructor. It initializes properties such as `phoneCode`, `countryCode`, example phone numbers, and phone masks for national and international formats specific to the United Kingdom. This is useful for generating dummy data.

```dart
const CountryWithPhoneCode.gb()
    : phoneCode = '44',
      countryCode = 'GB',
      exampleNumberMobileNational = '07400 123456',
      exampleNumberFixedLineNational = '0121 234 5678',
      phoneMaskMobileNational = '+00 00000 000000',
      phoneMaskFixedLineNational = '+00 0000 000 0000',
      exampleNumberMobileInternational = '+44 7400 123456',
      exampleNumberFixedLineInternational = '+44 121 234 5678',
      phoneMaskMobileInternational = '+00 0000 000000',
      phoneMaskFixedLineInternational = '+00 000 000 0000',
      countryName = 'United Kingdom';
```

--------------------------------

### CountryWithPhoneCode Constructor Definition (Dart)

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryWithPhoneCode/CountryWithPhoneCode.html

Defines the CountryWithPhoneCode constructor, specifying all required parameters for phone code, country code, example numbers, and phone masks. It also includes an optional country name parameter.

```dart
CountryWithPhoneCode({
  required this.phoneCode,
  required this.countryCode,
  required this.exampleNumberMobileNational,
  required this.exampleNumberFixedLineNational,
  required this.phoneMaskMobileNational,
  required this.phoneMaskFixedLineNational,
  required this.exampleNumberMobileInternational,
  required this.exampleNumberFixedLineInternational,
  required this.phoneMaskMobileInternational,
  required this.phoneMaskFixedLineInternational,
  required this.countryName,
});
```

--------------------------------

### Get Phone Code String - Dart

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryWithPhoneCode/phoneCode.html

Retrieves the country code as a String. This property is final and declared within the Country class.

```dart
String phoneCode
```

```dart
final String phoneCode;
```

--------------------------------

### Get All Supported Regions (Dart)

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/getAllSupportedRegions.html

Retrieves a map of all regions supported by the libphonenumber library, including their country codes and phone codes. This function relies on the FlutterLibphonenumberPlatform.instance to perform the operation.

```dart
@override
Future<Map<String, CountryWithPhoneCode>> getAllSupportedRegions() async {
  return FlutterLibphonenumberPlatform.instance.getAllSupportedRegions();
}
```

--------------------------------

### Define exampleNumberFixedLineInternational property

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryWithPhoneCode/exampleNumberFixedLineInternational.html

This property stores a fixed-line phone number in international format as a string. It is used as a reference or example value within the library's data structures.

```dart
final String exampleNumberFixedLineInternational;
```

```text
+44 121 234 5678
```

--------------------------------

### CountryWithPhoneCode Data Structure

Source: https://pub.dev/documentation/flutter_libphonenumber

Defines the structure for storing country-specific phone number metadata, including phone codes, country codes, example numbers for national and international formats, and corresponding masks. This class is used internally by the CountryManager.

```dart
class CountryWithPhoneCode {
  final String phoneCode;
  final String countryCode;
  final String exampleNumberMobileNational;
  final String exampleNumberFixedLineNational;
  final String phoneMaskMobileNational;
  final String phoneMaskFixedLineNational;
  final String exampleNumberMobileInternational;
  final String exampleNumberFixedLineInternational;
  final String phoneMaskMobileInternational;
  final String phoneMaskFixedLineInternational;
  final String countryName;
}
```

--------------------------------

### Get Formatted Parse Result Asynchronously

Source: https://pub.dev/documentation/flutter_libphonenumber

Asynchronously formats a phone number and checks its validity using libphonenumber's parse function. Returns the formatted number and the E.164 value if valid.

```APIDOC
## POST /getFormattedParseResult

### Description
Asynchronously formats a phone number and checks its validity using libphonenumber's parse function. Returns the formatted number and the E.164 value if valid.

### Method
POST

### Endpoint
/getFormattedParseResult

### Parameters
#### Query Parameters
- **phoneNumber** (String) - Required - The phone number to format and parse.
- **country** (CountryWithPhoneCode) - Required - The country object to use for formatting.
- **phoneNumberType** (PhoneNumberType) - Optional - The type of phone number to format (e.g., 'mobile', 'fixedLine'). Defaults to 'mobile'.
- **phoneNumberFormat** (PhoneNumberFormat) - Optional - The desired format (e.g., 'international', 'national'). Defaults to 'international'.

### Request Body
```json
{
  "phoneNumber": "+14144444444",
  "country": {
    "name": "United States",
    "regionCode": "US",
    "phoneCode": 1
  },
  "phoneNumberType": "mobile",
  "phoneNumberFormat": "international"
}
```

### Response
#### Success Response (200)
- **formattedNumber** (String) - The formatted phone number.
- **e164** (String?) - The E.164 formatted phone number, or null if the number is not valid.

#### Response Example
```json
{
  "formattedNumber": "1 (414) 444-4444",
  "e164": "+14144444444"
}
```
```

--------------------------------

### CountryWithPhoneCode.us Constructor - Dart

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryWithPhoneCode/CountryWithPhoneCode.us.html

Defines the CountryWithPhoneCode.us constructor for the United States. It initializes properties like phoneCode, countryCode, example numbers, and phone masks for mobile and fixed-line national and international formats. This is useful for generating dummy data specific to the US.

```dart
const CountryWithPhoneCode.us() 
    : phoneCode = '1',
      countryCode = 'US',
      exampleNumberMobileNational = '(201) 555-0123',
      exampleNumberFixedLineNational = '(201) 555-0123',
      phoneMaskMobileNational = '(000) 000-0000',
      phoneMaskFixedLineNational = '(000) 000-0000',
      exampleNumberMobileInternational = '+1 201-555-0123',
      exampleNumberFixedLineInternational = '+1 201-555-0123',
      phoneMaskMobileInternational = '+0 000-000-0000',
      phoneMaskFixedLineInternational = '+0 000-000-0000',
      countryName = 'United States';
```

--------------------------------

### Get Phone Mask with Flutter libphonenumber

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryWithPhoneCode/getPhoneMask.html

Retrieves a phone mask based on the provided PhoneNumberFormat and PhoneNumberType. The `removeCountryCodeFromMask` parameter allows for excluding the country code from the returned mask, which is useful for real-time input formatting.

```dart
String getPhoneMask({
  required final PhoneNumberFormat format,
  required final PhoneNumberType type,
  final bool removeCountryCodeFromMask = false,
}) {
  late String returnMask;
  if (type == PhoneNumberType.mobile) {
    if (format == PhoneNumberFormat.international) {
      returnMask = phoneMaskMobileInternational;
    } else {
      returnMask = phoneMaskMobileNational;
    }
  } else {
    if (format == PhoneNumberFormat.international) {
      returnMask = phoneMaskFixedLineInternational;
    } else {
      returnMask = phoneMaskFixedLineNational;
    }
  }

  /// If we want to get the mask without the country code, strip
  /// out the country code from the mask now.
  if (removeCountryCodeFromMask && returnMask.startsWith('+')) {
    /// Return the mask after the country code and 2 characters,
    /// one for the leading + and the other for the space between
    /// country code and number.
    returnMask = returnMask.substring(phoneCode.length + 2);
  }

  return returnMask;
}
```

--------------------------------

### Define phoneMaskMobileInternational Property (Dart)

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryWithPhoneCode/phoneMaskMobileInternational.html

This snippet shows the declaration of the `phoneMaskMobileInternational` property in Dart. It is a final String intended to hold the international format mask for mobile phone numbers, with an example format provided.

```dart
String phoneMaskMobileInternational
final
// Phone mask for mobile number in international format.
// +00 0000 000000

final String phoneMaskMobileInternational;
```

--------------------------------

### Get Country Name from Phone Number (Dart)

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryWithPhoneCode/countryName.html

This snippet demonstrates how to access the countryName property in Dart for the libphonenumber Flutter package. It retrieves the country name associated with a phone number. No external dependencies are required beyond the library itself.

```dart
final String? countryName;

```

--------------------------------

### Define additionalDigits property in libphonenumber

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/LibPhonenumberTextFormatter/additionalDigits.html

The additionalDigits property is an integer that specifies how many extra digits are permitted at the end of a phone number mask. This is essential for handling regional variations where standard example numbers may not cover all valid formatting possibilities.

```Dart
final int additionalDigits;
```

--------------------------------

### Dart: phoneMaskFixedLineInternational Property Declaration

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryWithPhoneCode/phoneMaskFixedLineInternational.html

This snippet shows the declaration of the `phoneMaskFixedLineInternational` property in Dart. It is a final String used to define the mask for fixed-line phone numbers in an international format. The example format provided is '+00 000 000 0000'.

```dart
String phoneMaskFixedLineInternational
final
Phone mask for fixed line number in international format.
```
+00 000 000 0000

```

## Implementation
```
final String phoneMaskFixedLineInternational;
```
```

--------------------------------

### Format Text Input with formatEditUpdate in Flutter

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/LibPhonenumberTextFormatter/formatEditUpdate.html

The formatEditUpdate method is an overrideable function in Flutter's libphonenumber library. It allows developers to intercept and modify text input within an EditableText widget. The method receives the previous TextEditingValue and the new TextEditingValue, enabling custom formatting logic before the text is updated. When formatters are chained, 'oldValue' represents the initial state of the TextEditingValue at the start of the chain.

```dart
 @override
 TextEditingValue formatEditUpdate(
   TextEditingValue oldValue,
   TextEditingValue newValue,
 ) {
   // Custom formatting logic here
   return newValue; // Return the potentially modified newValue
 }
```

--------------------------------

### Initialize Library and Synchronous Formatting

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/index.html

Demonstrates how to initialize the library to load phone masks and perform synchronous number formatting. Initialization is required to enable the synchronous formatting functionality.

```dart
await init();

final rawNumber = '+14145556666';
final formattedNumber = formatNumberSync(rawNumber); // +1 414-555-6666
```

--------------------------------

### Initialization

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/index.html

Initializes the flutter_libphonenumber package by loading country data. This must be called before using formatting functions.

```APIDOC
## POST /init

### Description
Initializes the library by loading all available countries and their phone metadata from libphonenumber to build formatting masks. This function should be called before any formatting operations.

### Method
POST

### Endpoint
/init

### Parameters
#### Query Parameters
- **overrides** (Map<String, CountryWithPhoneCode>) - Optional - A map to override default country data with custom `CountryWithPhoneCode` objects.

### Request Example
```dart
await init();
```

### Response
#### Success Response (200)
- **void** - Indicates successful initialization.

#### Response Example
```json
// No response body for void return type
```
```

--------------------------------

### Initialize Libphonenumber Platform

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/init.html

The init function initializes the underlying platform for phone number parsing. It accepts an optional map of country overrides to customize phone code behavior and returns a Future that completes when initialization is finished.

```dart
@override
Future<void> init({
  final Map<String, CountryWithPhoneCode> overrides = const {},
}) async {
  return FlutterLibphonenumberPlatform.instance.init(overrides: overrides);
}
```

--------------------------------

### Instantiate PhoneMask Class (Dart)

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/PhoneMask-class.html

Demonstrates how to create an instance of the PhoneMask class. It requires a 'mask' string and a 'CountryWithPhoneCode' object. This is the primary way to set up phone number masking for a specific country.

```dart
final phoneMask = PhoneMask(mask: '+1 (###) ###-####', country: CountryWithPhoneCode(name: 'United States', code: 'US', dialCode: '1'));
```

--------------------------------

### Initialize LibPhonenumberTextFormatter

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/LibPhonenumberTextFormatter-class.html

Constructs a new formatter instance to handle phone number input masking. It requires a country configuration and allows customization of formatting rules like number type, display format, and cursor behavior.

```dart
final formatter = LibPhonenumberTextFormatter(
  country: country,
  phoneNumberType: PhoneNumberType.mobile,
  phoneNumberFormat: PhoneNumberFormat.international,
  shouldKeepCursorAtEndOfInput: true
);
```

--------------------------------

### Initialize flutter_libphonenumber

Source: https://pub.dev/documentation/flutter_libphonenumber

Initializes the flutter_libphonenumber package by loading all available regions and their phone number masks. This must be called before using synchronous formatting functions. It can be called during app initialization or with a FutureBuilder.

```dart
await init();
```

--------------------------------

### Country Manager

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/index.html

Provides access to a list of countries and their associated phone metadata.

```APIDOC
## GET /countries

### Description
Provides access to the `CountryManager` which holds a list of `CountryWithPhoneCode` objects, containing details like phone codes, country codes, and formatting masks for various regions.

### Method
GET

### Endpoint
/countries

### Parameters
None

### Request Example
```dart
final countries = CountryManager().countries;
```

### Response
#### Success Response (200)
- **countries** (List<CountryWithPhoneCode>) - A list of `CountryWithPhoneCode` objects, each containing detailed phone metadata for a country.

#### Response Example
```json
[
  {
    "phoneCode": "44",
    "countryCode": "GB",
    "exampleNumberMobileNational": "07400 123456",
    "exampleNumberFixedLineNational": "0121 234 5678",
    "phoneMaskMobileNational": "00000 000000",
    "phoneMaskFixedLineNational": "0000 000 0000",
    "exampleNumberMobileInternational": "+44 7400 123456",
    "exampleNumberFixedLineInternational": "+44 121 234 5678",
    "phoneMaskMobileInternational": "+00 0000 000000",
    "phoneMaskFixedLineInternational": "+00 000 000 0000",
    "countryName": "United Kingdom"
  }
  // ... other countries
]
```
```

--------------------------------

### POST /format

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber

Formats a raw phone number string into a standard international or national format.

```APIDOC
## POST /format

### Description
Formats a given phone number string based on the specified region context.

### Method
POST

### Endpoint
/format

### Parameters
#### Request Body
- **phone** (String) - Required - The phone number to format.
- **region** (String) - Required - The region context for formatting.

### Request Example
{
  "phone": "6502530000",
  "region": "US"
}

### Response
#### Success Response (200)
- **formatted** (Map<String, String>) - The formatted phone number result.

#### Response Example
{
  "formatted": "(650) 253-0000"
}
```

--------------------------------

### Initialize FormatPhoneResult in Dart

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/FormatPhoneResult/FormatPhoneResult.html

The FormatPhoneResult constructor is used to create an instance containing the E.164 representation and the human-readable formatted version of a phone number. It requires both parameters to be provided as non-null strings.

```dart
FormatPhoneResult({
  required this.e164,
  required this.formattedNumber,
});
```

--------------------------------

### FormatPhoneResult Class Constructor and Properties (Dart)

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/FormatPhoneResult-class.html

This snippet demonstrates the constructor and key properties of the FormatPhoneResult class in Dart. It shows how to initialize a FormatPhoneResult object with E.164 and formatted phone number strings, and how to access these properties.

```dart
class FormatPhoneResult {
  final String e164;
  final String formattedNumber;

  FormatPhoneResult({
    required this.e164,
    required this.formattedNumber,
  });

  // Properties are directly accessible via the final fields.
  // Example usage:
  // final result = FormatPhoneResult(e164: '+12125551212', formattedNumber: '(212) 555-1212');
  // print(result.e164);
  // print(result.formattedNumber);
}

```

--------------------------------

### Asynchronous Number Formatting

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/index.html

Formats a phone number asynchronously using libphonenumber's AsYouType formatter.

```APIDOC
## POST /format

### Description
Formats a phone number asynchronously using libphonenumber's AsYouType formatter. This method might be preferred when complex formatting logic is involved or when the synchronous formatter is not suitable.

### Method
POST

### Endpoint
/format

### Parameters
#### Request Body
- **phone** (String) - Required - The phone number string to format.
- **region** (String) - Required - The region code (e.g., 'US', 'GB') to aid in formatting.

### Request Example
```dart
final formatted = await format('+14144444444', 'US');
```

### Response
#### Success Response (200)
- **formatted** (String) - The asynchronously formatted phone number.

#### Response Example
```json
{
  "formatted": "1 (414) 444-4444"
}
```
```

--------------------------------

### Country Metadata Model and Access

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/index.html

Defines the CountryWithPhoneCode data structure used to store phone metadata and demonstrates how to retrieve the list of supported countries via the CountryManager.

```dart
class CountryWithPhoneCode {
  final String phoneCode;
  final String countryCode;
  final String exampleNumberMobileNational;
  final String exampleNumberFixedLineNational;
  final String phoneMaskMobileNational;
  final String phoneMaskFixedLineNational;
  final String exampleNumberMobileInternational;
  final String exampleNumberFixedLineInternational;
  final String phoneMaskMobileInternational;
  final String phoneMaskFixedLineInternational;
  final String countryName;
}

final countries = CountryManager().countries; // List<CountryWithPhoneCode>
```

--------------------------------

### Format Phone Number Synchronously

Source: https://pub.dev/documentation/flutter_libphonenumber

Formats a phone number synchronously using predefined masks. Requires `init()` to be called first. Allows specifying phone number type and format, and optionally removing the country code.

```APIDOC
## POST /formatNumberSync

### Description
Formats a phone number synchronously using predefined masks. Requires `init()` to be called first. Allows specifying phone number type and format, and optionally removing the country code.

### Method
POST

### Endpoint
/formatNumberSync

### Parameters
#### Query Parameters
- **number** (String) - Required - The phone number to format.
- **country** (CountryWithPhoneCode?) - Optional - The country object to use for formatting.
- **phoneNumberType** (PhoneNumberType) - Optional - The type of phone number to format (e.g., 'mobile', 'fixedLine'). Defaults to 'mobile'.
- **phoneNumberFormat** (PhoneNumberFormat) - Optional - The desired format (e.g., 'international', 'national'). Defaults to 'international'.
- **removeCountryCodeFromResult** (bool) - Optional - Whether to remove the country code from the result. Defaults to false.
- **inputContainsCountryCode** (bool) - Optional - Whether the input number contains the country code. Defaults to true.

### Request Body
```json
{
  "number": "+14144444444",
  "country": {
    "name": "United States",
    "regionCode": "US",
    "phoneCode": 1
  },
  "phoneNumberType": "mobile",
  "phoneNumberFormat": "international",
  "removeCountryCodeFromResult": false,
  "inputContainsCountryCode": true
}
```

### Response
#### Success Response (200)
- **formattedNumber** (String) - The formatted phone number.

#### Response Example
```json
"1 (414) 444-4444"
```
```

--------------------------------

### Synchronous Number Formatting

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/index.html

Formats a phone number synchronously using pre-loaded masks, avoiding asynchronous platform calls.

```APIDOC
## POST /formatNumberSync

### Description
Formats a given phone number synchronously using the pre-loaded country masks. This is useful for immediate UI updates without asynchronous operations.

### Method
POST

### Endpoint
/formatNumberSync

### Parameters
#### Request Body
- **rawNumber** (String) - Required - The raw phone number string to format.

### Request Example
```dart
final rawNumber = '+14145556666';
final formattedNumber = formatNumberSync(rawNumber);
```

### Response
#### Success Response (200)
- **formattedNumber** (String) - The synchronously formatted phone number.

#### Response Example
```json
{
  "formattedNumber": "+1 414-555-6666"
}
```
```

--------------------------------

### Initialize CountryManager Singleton

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryManager/CountryManager.html

The CountryManager class uses a factory constructor to ensure that only a single instance of the manager is created throughout the application lifecycle. This pattern provides a centralized point for accessing country-related phone number configurations.

```dart
factory CountryManager() => _instance;
```

--------------------------------

### Format Phone Number As You Type

Source: https://pub.dev/documentation/flutter_libphonenumber

Formats a phone number using the libphonenumber's AsYouType formatter. This function is asynchronous and returns a map containing the formatted number. For synchronous formatting, consider using formatNumberSync.

```dart
Future<Map<String, String>> format(String phone, String region)
```

--------------------------------

### POST /parse

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber

Parses a raw phone number string into a structured format based on the provided region.

```APIDOC
## POST /parse

### Description
Parses a phone number string to extract components like country code, national number, and validation status.

### Method
POST

### Endpoint
/parse

### Parameters
#### Request Body
- **phone** (String) - Required - The raw phone number string to parse.
- **region** (String) - Optional - The ISO 3166-1 alpha-2 country code.

### Request Example
{
  "phone": "+16502530000",
  "region": "US"
}

### Response
#### Success Response (200)
- **result** (Map<String, dynamic>) - Parsed phone number components.

#### Response Example
{
  "type": "fixed_line",
  "e164": "+16502530000",
  "national": "6502530000"
}
```

--------------------------------

### Format phone numbers synchronously with flutter_libphonenumber

Source: https://pub.dev/documentation/flutter_libphonenumber

Formats a phone number string synchronously using predefined masks. Requires the init() function to be called beforehand to populate mask data.

```dart
String formatNumberSync(String number, {CountryWithPhoneCode? country, PhoneNumberType phoneNumberType = PhoneNumberType.mobile, phoneNumberFormat = PhoneNumberFormat.international, bool removeCountryCodeFromResult = false, bool inputContainsCountryCode = true});
```

--------------------------------

### FormatPhoneResult Class Methods and Operators (Dart)

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/FormatPhoneResult-class.html

This snippet illustrates the methods and operators available for the FormatPhoneResult class in Dart, including the `toString` method for string representation and the equality operator (`==`) for comparing instances. These are standard Dart object functionalities.

```dart
@override
String toString() {
  return 'FormatPhoneResult(e164: \'$e164\', formattedNumber: \'$formattedNumber\')';
}

@override
bool operator ==(Object other) {
  if (identical(this, other)) return true;

  return other is FormatPhoneResult &&
      other.e164 == e164 &&
      other.formattedNumber == formattedNumber;
}

@override
int get hashCode => e164.hashCode ^ formattedNumber.hashCode;

```

--------------------------------

### LibPhonenumberTextFormatter Constructor - Dart

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/LibPhonenumberTextFormatter/LibPhonenumberTextFormatter.html

The LibPhonenumberTextFormatter constructor initializes a new instance of the formatter. It takes several parameters to customize phone number formatting, including the country, phone number type, and desired format. The implementation sets up the phone mask based on these configurations.

```dart
LibPhonenumberTextFormatter({
  required this.country,
  this.phoneNumberType = PhoneNumberType.mobile,
  this.phoneNumberFormat = PhoneNumberFormat.international,
  this.onFormatFinished,

  /// When true, mask will be applied assuming the input contains
  /// a country code in it.
  final bool inputContainsCountryCode = false,

  /// Additional digits to include
  this.additionalDigits = 0,

  /// Force cursor the end of input when formatting.
  this.shouldKeepCursorAtEndOfInput = true,
}) : super() {
  var m = country.getPhoneMask(
    format: phoneNumberFormat,
    type: phoneNumberType,
    removeCountryCodeFromMask: !inputContainsCountryCode,
  );

  /// Allow additional digits on the mask
  if (additionalDigits > 0) {
    m += List.filled(additionalDigits, '0')
        .reduce((final a, final b) => a + b);
  }

  _mask = PhoneMask(
    mask: m,
    country: country,
  );
}
```

--------------------------------

### Apply Phone Mask (Dart)

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/PhoneMask-class.html

Shows how to use the 'apply' method of the PhoneMask class to format an input phone number string according to the defined mask. This method takes the raw phone number string as input and returns the formatted string.

```dart
String formattedNumber = phoneMask.apply('1234567890');
// formattedNumber will be '+1 (123) 456-7890'
```

--------------------------------

### Retrieve Country Data by Phone Number in Dart

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryWithPhoneCode/getCountryDataByPhone.html

This static method attempts to identify a country by matching the prefix of a given phone number against a list of known country codes. It uses a recursive approach, shortening the substring length until a match is found or the input is exhausted.

```Dart
static CountryWithPhoneCode? getCountryDataByPhone(
  final String phone, {
  int? subscringLength,
}) {
  /// If number is empty, return null
  if (phone.isEmpty) {
    return null;
  }

  /// Unless otherwise specified, start trying to match from the
  /// end of the inputted phone string.
  subscringLength = subscringLength ?? phone.length;

  /// Must provide valid offset to start searching from
  if (subscringLength < 1) {
    return null;
  }

  final phoneCode = phone.substring(0, subscringLength);

  try {
    final countries = CountryManager().countries;
    final retCountry = countries.firstWhere((final data) {
      final res =
          _toNumericString(data.phoneCode) == _toNumericString(phoneCode);
      return res;
    });

    return retCountry;
  } catch (_) {
    return getCountryDataByPhone(phone, subscringLength: subscringLength - 1);
  }
}
```

--------------------------------

### Initialize Country Data with loadCountries in Dart

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryManager/loadCountries.html

The loadCountries method populates the internal country list from a provided map of phone codes. It supports optional overrides for specific country data and handles initialization state to prevent redundant processing.

```dart
Future<void> loadCountries({
  required final Map<String, CountryWithPhoneCode> phoneCodesMap,
  final Map<String, CountryWithPhoneCode> overrides = const {},
}) async {
  if (_initialized) {
    return;
  }

  try {
    /// Apply any overrides to masks / country data
    overrides.forEach((final key, final value) {
      phoneCodesMap[key] = value;
    });

    /// Save list of the countries
    _countries = phoneCodesMap.values.toList();

    _initialized = true;
  } catch (err) {
    _countries = overrides.values.toList();
  }
}
```

--------------------------------

### Format and validate phone numbers asynchronously

Source: https://pub.dev/documentation/flutter_libphonenumber

Asynchronously formats a phone number and verifies its validity. Returns a FormatPhoneResult object containing the formatted string and the E.164 representation.

```dart
Future<FormatPhoneResult?> getFormattedParseResult(String phoneNumber, CountryWithPhoneCode country, {PhoneNumberType phoneNumberType = PhoneNumberType.mobile, PhoneNumberFormat phoneNumberFormat = PhoneNumberFormat.international});
```

--------------------------------

### Synchronously Format Phone Number

Source: https://pub.dev/documentation/flutter_libphonenumber

Formats a given phone number synchronously using pre-loaded masks. This avoids asynchronous platform calls, making it suitable for UI updates. The input is an e164 formatted number, and the output is the formatted number string.

```dart
final rawNumber = '+14145556666';
final formattedNumber = formatNumberSync(rawNumber); // +1 414-555-6666
```

--------------------------------

### PhoneNumberType Enum Definition

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/PhoneNumberType.html

Details the available values and properties for the PhoneNumberType enumeration.

```APIDOC
## Enum: PhoneNumberType

### Description
Used for phone masks to determine how to format phone numbers within the library.

### Values
- **mobile**: Represents a mobile phone number type.
- **fixedLine**: Represents a fixed-line (landline) phone number type.

### Properties
- **index** (int) - A numeric identifier for the enumerated value.
- **hashCode** (int) - The hash code for this object.

### Constants
- **values** (List<PhoneNumberType>) - A constant list of all available enum values in order of declaration.

### Usage Example
```dart
var type = PhoneNumberType.mobile;
print(type.index); // Outputs the index of the mobile type
```
```

--------------------------------

### LibPhonenumber Text Formatter

Source: https://pub.dev/documentation/flutter_libphonenumber

A TextInputFormatter for automatically formatting phone numbers within a TextField as the user types. Requires a country code.

```APIDOC
## POST /LibPhonenumberTextFormatter

### Description
A TextInputFormatter for automatically formatting phone numbers within a TextField as the user types. Requires a country code.

### Method
POST

### Endpoint
/LibPhonenumberTextFormatter

### Parameters
#### Request Body
- **country** (String) - Required - The country code used to format the text accurately (e.g., 'GB', 'US').
- **phoneNumberType** (PhoneNumberType?) - Optional - Specify whether to format using the mobile or fixed line mask. Defaults to 'mobile'.
- **phoneNumberFormat** (PhoneNumberFormat?) - Optional - Specify the format (national or international). Defaults to 'international'.
- **onFormatFinished** (Function(String)?) - Optional - A callback function that is notified with the final formatted value after formatting is completed.
- **inputContainsCountryCode** (bool?) - Optional - When true, the mask is applied assuming the input contains a country code. Defaults to false.
- **additionalDigits** (int?) - Optional - Allows additional digits at the end of the mask. Defaults to 0.
- **shouldKeepCursorAtEndOfInput** (bool?) - Optional - Whether the cursor should remain at the end of the input after formatting. Defaults to true.

### Request Example
```dart
TextField(
  inputFormatters: [
    LibPhonenumberTextFormatter(
      country: 'GB',
      phoneNumberType: PhoneNumberType.mobile,
      phoneNumberFormat: PhoneNumberFormat.international,
      onFormatFinished: (formattedValue) => print('Formatted: $formattedValue'),
      inputContainsCountryCode: false,
      additionalDigits: 3,
      shouldKeepCursorAtEndOfInput: true,
    )
  ],
)
```

### Response
This is a `TextInputFormatter` and does not return a direct response in the traditional API sense. It modifies the input within a `TextField`.
```

--------------------------------

### Implement formatEditUpdate

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/LibPhonenumberTextFormatter-class.html

Overrides the TextInputFormatter method to process text changes. This method is triggered whenever the user types, pastes, or deletes text, ensuring the input adheres to the defined phone number format.

```dart
@override
TextEditingValue formatEditUpdate(TextEditingValue oldValue, TextEditingValue newValue) {
  // Logic to format the input based on the country and format settings
  return super.formatEditUpdate(oldValue, newValue);
}
```

--------------------------------

### Parse Phone Number

Source: https://pub.dev/documentation/flutter_libphonenumber

Parses a phone number and returns metadata if it's a valid and complete E.164 formatted number. Throws an error for invalid numbers.

```APIDOC
## POST /parse

### Description
Parses a phone number and returns metadata if it's a valid and complete E.164 formatted number. Throws an error for invalid numbers.

### Method
POST

### Endpoint
/parse

### Parameters
#### Query Parameters
- **phone** (String) - Required - The phone number to parse.
- **region** (String?) - Optional - The region code to use for parsing.

### Request Body
```json
{
  "phone": "+14144444444",
  "region": "US"
}
```

### Response
#### Success Response (200)
- **country_code** (int) - The country calling code.
- **e164** (String) - The E.164 formatted phone number.
- **national** (String) - The national format of the phone number.
- **type** (String) - The type of the phone number (e.g., 'mobile', 'fixedLine').
- **international** (String) - The international format of the phone number.
- **region_code** (String) - The region code of the phone number.
- **national_number** (String) - The national number part of the phone number.

#### Response Example
```json
{
    "country_code": 49,
    "e164": "+4930123123123",
    "national": "030 123 123 123",
    "type": "mobile",
    "international": "+49 30 123 123 123",
    "region_code": "DE",
    "national_number": "030123123123"
}
```
```

--------------------------------

### PhoneNumberFormat Enum

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/PhoneNumberFormat.html

Defines the available formatting options for phone numbers within the library.

```APIDOC
## PhoneNumberFormat Enum

### Description
Used to specify the formatting style for phone numbers. This enum is used by formatting methods to determine whether to output a national or international format.

### Values
- **national**: Formats the phone number in the local national format.
- **international**: Formats the phone number in the standard international format.

### Properties
- **index** (int) - The numeric identifier for the enumerated value.
- **hashCode** (int) - The hash code for this object.

### Constants
- **values** (List<PhoneNumberFormat>) - A constant list of all available enum values in order of declaration.

### Usage Example
```dart
PhoneNumberFormat format = PhoneNumberFormat.international;
```
```

--------------------------------

### Apply phone number formatting to TextField

Source: https://pub.dev/documentation/flutter_libphonenumber

Uses the LibPhonenumberTextFormatter to mask user input in a TextField. Requires a country code and supports various configuration options like number type, format, and cursor behavior.

```dart
TextField(inputFormatters: [LibPhonenumberTextFormatter(
  country: 'GB',
)])
```

--------------------------------

### Retrieve supported countries list in Dart

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryManager/countries.html

Accesses the internal list of supported countries with their associated phone code metadata. This property returns a List of CountryWithPhoneCode objects.

```dart
List<CountryWithPhoneCode> get countries => _countries;
```

--------------------------------

### Access CountryManager Countries

Source: https://pub.dev/documentation/flutter_libphonenumber

Retrieves a list of all available countries and their associated phone metadata from the CountryManager. This list contains objects of type CountryWithPhoneCode, which can be used to access formatting masks and other details.

```dart
final countries = CountryManager().countries; // List<CountryWithPhoneCode>
```

--------------------------------

### Apply Phone Mask to Input String (Dart)

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/PhoneMask/apply.html

Applies a phone mask to an input string. It cleans the input by removing non-digit characters and handles country code logic. The method iterates through the mask and the cleaned input to construct the formatted phone number. Dependencies include the 'mask' and 'country' variables, assumed to be accessible within the scope.

```dart
String apply(final String inputString) {
  /// If mask is empty, return input string
  if (mask.isEmpty) {
    return inputString;
  }

  var cleanedInput = inputString.replaceAll(RegExp(r'\D'), '');

  /// If phone mask doesn't contain country code but input does,
  /// remove the country code from the input
  if (!mask.startsWith('+') && inputString.startsWith('+')) {
    cleanedInput = 
        cleanedInput.replaceFirst(RegExp('^${country.phoneCode}'), '');
  }

  final chars = cleanedInput.split('');

  final result = <String>[];
  var index = 0;
  for (var i = 0; i < mask.length; i++) {
    if (index >= chars.length) {
      break;
    }
    final curChar = chars[index];
    if (mask[i] == '0') {
      /// If it's a digit in the mask, add the digit to the output
      if (_isDigit(curChar)) {
        result.add(curChar);
        index++;
      } else {
        break;
      }
    } else {
      /// Add the non-digit value from the mask to the output
      result.add(mask[i]);
    }
  }
  return result.join();
}
```

--------------------------------

### PhoneMask Constructor in Dart (Flutter)

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/PhoneMask/PhoneMask.html

The PhoneMask constructor initializes a PhoneMask object with a required mask string and a CountryWithPhoneCode object. This is essential for defining how phone numbers should be formatted according to specific country conventions.

```dart
PhoneMask({
  required this.mask,
  required this.country,
});
```

--------------------------------

### Override toString method in Dart

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/CountryWithPhoneCode/toString.html

This implementation overrides the default toString method to return a detailed string representation of the CountryWithPhoneCode object. It is primarily used for debugging and logging to inspect the internal state of the object's phone metadata fields.

```dart
@override
String toString() =>
    '[CountryWithPhoneCode(countryName: $countryName, regionCode: $countryCode, phoneCode: $phoneCode, exampleNumberMobileNational: $exampleNumberMobileNational, exampleNumberFixedLineNational: $exampleNumberFixedLineNational, phoneMaskMobileNational: $phoneMaskMobileNational, phoneMaskFixedLineNational: $phoneMaskFixedLineNational, exampleNumberMobileInternational: $exampleNumberMobileInternational, exampleNumberFixedLineInternational: $exampleNumberFixedLineInternational, phoneMaskMobileInternational: $phoneMaskMobileInternational, phoneMaskFixedLineInternational: $phoneMaskFixedLineInternational)]';
```

--------------------------------

### Format phone numbers synchronously using FlutterLibphonenumber

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/formatNumberSync.html

The formatNumberSync function provides a synchronous way to format a raw phone number string into a specific format. It requires the input number and accepts optional parameters for country context, phone number type, and desired output format.

```dart
String formatNumberSync(
  final String number, {
  final CountryWithPhoneCode? country,
  final PhoneNumberType phoneNumberType = PhoneNumberType.mobile,
  final PhoneNumberFormat phoneNumberFormat = PhoneNumberFormat.international,
  final bool removeCountryCodeFromResult = false,
  final bool inputContainsCountryCode = true,
}) {
  return FlutterLibphonenumberPlatform.instance.formatNumberSync(
    number,
    country: country,
    phoneNumberType: phoneNumberType,
    phoneNumberFormat: phoneNumberFormat,
    removeCountryCodeFromResult: removeCountryCodeFromResult,
    inputContainsCountryCode: inputContainsCountryCode,
  );
}
```

--------------------------------

### Parse phone numbers with flutter_libphonenumber

Source: https://pub.dev/documentation/flutter_libphonenumber

Parses a phone number string into a metadata map. Requires a valid E.164 formatted number and throws an error if the input is invalid.

```dart
Future<Map<String, dynamic>> parse(String phone, {String? region});
```

--------------------------------

### Format Phone Number (Dart)

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/format.html

The format function takes a phone number string and a region string to format the phone number according to the specified region's conventions. It relies on the FlutterLibphonenumberPlatform.instance to perform the formatting.

```dart
@override
Future<Map<String, String>> format(
  final String phone,
  final String region,
) async {
  return FlutterLibphonenumberPlatform.instance.format(phone, region);
}
```

--------------------------------

### Override toString method for FormatPhoneResult

Source: https://pub.dev/documentation/flutter_libphonenumber/latest/flutter_libphonenumber/FormatPhoneResult/toString.html

This method overrides the default toString implementation to return a formatted string containing the formattedNumber and e164 properties. It is primarily used for debugging and logging purposes to inspect the state of the object.

```dart
@override
String toString() {
  return 'FormatPhoneResult[formattedNumber: $formattedNumber, e164: $e164]';
}
```
Tokens:
Raw