[Regex] Introduce *_match() functions to fetch captured data groups

[veewee]

This PR introduces a first_match() and every_match() function in which you can specify the shape of the result:

/** @var array{0: string, name: string}|null $matches */
$matches = Regex\first_match(
    'Hello world',
    '/(hello) (?<name>world)/i',
    Regex\capture_groups(['name'])
);

/** @var list<array{0: string, name: string, digit: string}>|null $matches */
$matches = Regex\every_match(
    <<<EODATA
    a: 1
    b: 2
    c: 3
    EODATA,
    '@(?P<name>\w+): (?P<digit>\d+)@i',
    Regex\capture_groups(['name', 'digit'])
);

[coveralls]

Pull Request Test Coverage Report for Build 733281690

• 33 of 33 (100.0%) changed or added relevant lines in 4 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 100.0%

---

Totals
Change from base Build 725317265:	0.0%
Covered Lines:	2982
Relevant Lines:	2982

---

💛 - Coveralls

[veewee]

Introduced the every_match function as well. The failing test is not caused by the code, but by GH actions:

✗ PHP Could not setup PHP 7.4

[veewee]

@azjezz Fixed it without using a psalm plugin. Instead the conditional return types of psalm did the trick together with a fallback to a custom $capture_groups fallback type.

[veewee]

Rebased it to 1.6.X. Let me know if there is anything else I can do in order to finish this one!

[veewee]

@azjezz How do you want to continue with this PR? Is it something you want to include? Because if so, I need to move a part to the new plugin repository.

[azjezz]

yes, let's move things to the new plugin, merge changes there, then we merge this.

[veewee]

Allright, will do it soon - but having some time constraints due to yet another lockdown here.
Hopefully something for next week.

[veewee]

Added the PR to the psalm plugin, but It will conflict with the open issue - so it's not completely done.
php-standard-library/psalm-plugin#5

Next rebased against 1.7.x - shall I keep the psalm plugin changes in here as well or remove it from the PR?

[azjezz]

Next rebased against 1.7.x - shall I keep the psalm plugin changes in here as well or remove it from the PR?

remove it, we don't want to add anything to the old plugin, just keeping it to not break BC.

php-standard-library/psalm-plugin#3 has been merged, so i guess you can rebase php-standard-library/psalm-plugin#5

[azjezz]

overall, this LGTM.

I'll probably do another review later and merge if everything is okay.

we can release this, along side #138 in 1.7 :)