The matchAll() method in JavaScript is used to search a string for all matches against a regular expression (regexp) and returns an iterator of all matched results. This method is particularly useful for obtaining all matches from a string, including capturing groups, in a more straightforward way than using the match() method with the global (g) flag.

Syntax:

string.matchAll(regexp)

• regexp: A regular expression object that specifies the pattern to search for. It must have the global (g) flag to find all matches.

Return Value:

• Returns an iterator (of type Iterator<RegExpMatchArray>) containing RegExpMatchArray objects for each match found in the string.
• Each RegExpMatchArray contains the full match as well as any capturing groups.

Example 1: Basic Usage

Here's a simple example of using matchAll() to find all occurrences of a substring.

let text = "The rain in Spain stays mainly in the plain.";
let regex = /in/g; // Regular expression with the global flag

let matches = text.matchAll(regex);

for (let match of matches) {
    console.log(match); // Logs each match found
}

Output:

[ 'in', index: 5, input: 'The rain in Spain stays mainly in the plain.', groups: undefined ]
[ 'in', index: 25, input: 'The rain in Spain stays mainly in the plain.', groups: undefined ]

Example 2: Capturing Groups

If you include capturing groups in the regular expression, matchAll() will return each match along with the values of those groups.

let text = "John Doe, age 25; Jane Smith, age 30";
let regex = /(\w+) (\w+), age (\d+)/g;

let matches = text.matchAll(regex);

for (let match of matches) {
    console.log(match);
}

Output:

[
  'John Doe, age 25', // Full match
  'John',              // First capturing group
  'Doe',               // Second capturing group
  '25',                // Third capturing group
  index: 0,
  input: 'John Doe, age 25; Jane Smith, age 30',
  groups: undefined
]
[
  'Jane Smith, age 30', // Full match
  'Jane',                // First capturing group
  'Smith',               // Second capturing group
  '30',                  // Third capturing group
  index: 27,
  input: 'John Doe, age 25; Jane Smith, age 30',
  groups: undefined
]

Example 3: Using Array.from()

You can convert the iterator returned by matchAll() into an array using Array.from() or the spread operator.

let text = "123-456-7890, 987-654-3210";
let regex = /(\d{3})-(\d{3})-(\d{4})/g;

let matchesArray = Array.from(text.matchAll(regex));

console.log(matchesArray);

Output:

[
  [ '123-456-7890', '123', '456', '7890', index: 0, input: '123-456-7890, 987-654-3210', groups: undefined ],
  [ '987-654-3210', '987', '654', '3210', index: 16, input: '123-456-7890, 987-654-3210', groups: undefined ]
]

Example 4: Performance Considerations

Using matchAll() is generally more efficient than calling match() in a loop when dealing with global matches, especially for large strings, as it retrieves all matches in a single pass.

Example 5: When Not to Use

If you do not need capturing groups or are only interested in the first match, it may be simpler to use the match() method.

let text = "The quick brown fox jumps over the lazy dog.";
let regex = /quick/;

console.log(text.match(regex)); // Returns first match
console.log(Array.from(text.matchAll(regex))); // Returns an iterator, but only one match will be found

Summary:

• The matchAll() method is used to find all matches of a regular expression in a string and returns an iterator of all matched results.
• It must use a regular expression with the global (g) flag to find all matches.
• Each match returned includes the full match and any capturing groups, making it more versatile than match().
• You can easily convert the iterator to an array using Array.from() or the spread operator.
• It’s particularly useful for working with multiple matches and capturing groups without needing to manage the state of the search manually.