Skip to content

Commit 3d322d7

Browse files
SeldaekSeldaek
committed
Rename WithOffset to WithOffsets, make $matches mandatory for Pcre::*WithOffset and add isMatch[All]WithOffsets
1 parent a824fd1 commit 3d322d7

File tree

10 files changed

+208
-40
lines changed

10 files changed

+208
-40
lines changed

‎README.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ You can now call these on the `Preg` class:
5555
use Composer\Pcre\Preg;
5656

5757
if (Preg::match('{fo+}', $string, $matches)) { ... }
58-
if (Preg::matchWithOffset('{fo+}', $string, $matches)) { ... }
58+
if (Preg::matchWithOffsets('{fo+}', $string, $matches)) { ... }
5959
if (Preg::matchAll('{fo+}', $string, $matches)) { ... }
6060
$newString = Preg::replace('{fo+}', 'bar', $string);
6161
$newString = Preg::replaceCallback('{fo+}', function ($match) { return strtoupper($match[0]); }, $string);
@@ -90,7 +90,7 @@ $bool = Regex::isMatch('{fo+}', $string);
9090
$result = Regex::match('{fo+}', $string);
9191
if ($result->matched) { something($result->matches); }
9292

93-
$result = Regex::matchWithOffset('{fo+}', $string);
93+
$result = Regex::matchWithOffsets('{fo+}', $string);
9494
if ($result->matched) { something($result->matches); }
9595

9696
$result = Regex::matchAll('{fo+}', $string);
@@ -104,17 +104,17 @@ $newString = Regex::replaceCallbackArray(['{fo+}' => fn ($match) => strtoupper($
104104
Note that `preg_grep` and `preg_split` are only callable via the `Preg` class as they do not have
105105
complex return types warranting a specific result object.
106106

107-
See the [MatchResult](src/MatchResult.php), [MatchWithOffsetResult](src/MatchWithOffsetResult.php), [MatchAllResult](src/MatchAllResult.php),
108-
[MatchAllWithOffsetResult](src/MatchAllWithOffsetResult.php), and [ReplaceResult](src/ReplaceResult.php) class sources for more details.
107+
See the [MatchResult](src/MatchResult.php), [MatchWithOffsetsResult](src/MatchWithOffsetsResult.php), [MatchAllResult](src/MatchAllResult.php),
108+
[MatchAllWithOffsetsResult](src/MatchAllWithOffsetsResult.php), and [ReplaceResult](src/ReplaceResult.php) class sources for more details.
109109

110110
Restrictions / Limitations
111111
--------------------------
112112

113-
Due to type safety requirements a few restrictions are in place.matchWithOffset
113+
Due to type safety requirements a few restrictions are in place.matchWithOffsets
114114

115-
- matching using `PREG_OFFSET_CAPTURE` is made available via `matchWithOffset` and `matchAllWithOffset`.
115+
- matching using `PREG_OFFSET_CAPTURE` is made available via `matchWithOffsets` and `matchAllWithOffsets`.
116116
You cannot pass the flag to `match`/`matchAll`.
117-
- `Preg::split` will also reject `PREG_SPLIT_OFFSET_CAPTURE` and you should use `splitWithOffset`
117+
- `Preg::split` will also reject `PREG_SPLIT_OFFSET_CAPTURE` and you should use `splitWithOffsets`
118118
instead.
119119
- `matchAll` rejects `PREG_SET_ORDER` as it also changes the shape of the returned matches. There
120120
is no alternative provided as you can fairly easily code around it.

‎src/MatchAllWithOffsetResult.php‎ renamed to ‎src/MatchAllWithOffsetsResult.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111

1212
namespace Composer\Pcre;
1313

14-
final class MatchAllWithOffsetResult
14+
final class MatchAllWithOffsetsResult
1515
{
1616
/**
1717
* An array of match group => list of matches, every match being a pair of string matched + offset in bytes (or -1 if no match)

‎src/MatchWithOffsetResult.php‎ renamed to ‎src/MatchWithOffsetsResult.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111

1212
namespace Composer\Pcre;
1313

14-
final class MatchWithOffsetResult
14+
final class MatchWithOffsetsResult
1515
{
1616
/**
1717
* An array of match group => pair of string matched + offset in bytes (or -1 if no match)

‎src/Preg.php‎

Lines changed: 40 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ class Preg
2626
public static function match($pattern, $subject, &$matches = null, $flags = 0, $offset = 0)
2727
{
2828
if (($flags & PREG_OFFSET_CAPTURE) !== 0) {
29-
throw new \InvalidArgumentException('PREG_OFFSET_CAPTURE is not supported as it changes the type of $matches, use matchWithOffset() instead');
29+
throw new \InvalidArgumentException('PREG_OFFSET_CAPTURE is not supported as it changes the type of $matches, use matchWithOffsets() instead');
3030
}
3131

3232
$result = preg_match($pattern, $subject, $matches, $flags, $offset);
@@ -49,7 +49,7 @@ public static function match($pattern, $subject, &$matches = null, $flags = 0, $
4949
*
5050
* @phpstan-param array<int|string, array{string|null, int<-1, max>}> $matches
5151
*/
52-
public static function matchWithOffset($pattern, $subject, &$matches = null, $flags = 0, $offset = 0)
52+
public static function matchWithOffsets($pattern, $subject, &$matches, $flags = 0, $offset = 0)
5353
{
5454
$result = preg_match($pattern, $subject, $matches, $flags | PREG_OFFSET_CAPTURE, $offset);
5555
if ($result === false) {
@@ -70,7 +70,7 @@ public static function matchWithOffset($pattern, $subject, &$matches = null, $fl
7070
public static function matchAll($pattern, $subject, &$matches = null, $flags = 0, $offset = 0)
7171
{
7272
if (($flags & PREG_OFFSET_CAPTURE) !== 0) {
73-
throw new \InvalidArgumentException('PREG_OFFSET_CAPTURE is not supported as it changes the type of $matches, use matchAllWithOffset() instead');
73+
throw new \InvalidArgumentException('PREG_OFFSET_CAPTURE is not supported as it changes the type of $matches, use matchAllWithOffsets() instead');
7474
}
7575

7676
if (($flags & PREG_SET_ORDER) !== 0) {
@@ -97,7 +97,7 @@ public static function matchAll($pattern, $subject, &$matches = null, $flags = 0
9797
*
9898
* @phpstan-param array<int|string, list<array{string|null, int<-1, max>}>> $matches
9999
*/
100-
public static function matchAllWithOffset($pattern, $subject, &$matches = null, $flags = 0, $offset = 0)
100+
public static function matchAllWithOffsets($pattern, $subject, &$matches, $flags = 0, $offset = 0)
101101
{
102102
$result = preg_match_all($pattern, $subject, $matches, $flags | PREG_OFFSET_CAPTURE, $offset);
103103
if ($result === false || $result === null) {
@@ -195,7 +195,7 @@ public static function replaceCallbackArray(array $pattern, $subject, $limit = -
195195
public static function split($pattern, $subject, $limit = -1, $flags = 0)
196196
{
197197
if (($flags & PREG_SPLIT_OFFSET_CAPTURE) !== 0) {
198-
throw new \InvalidArgumentException('PREG_SPLIT_OFFSET_CAPTURE is not supported as it changes the type of $matches, use splitWithOffset() instead');
198+
throw new \InvalidArgumentException('PREG_SPLIT_OFFSET_CAPTURE is not supported as it changes the type of $matches, use splitWithOffsets() instead');
199199
}
200200

201201
$result = preg_split($pattern, $subject, $limit, $flags);
@@ -214,7 +214,7 @@ public static function split($pattern, $subject, $limit = -1, $flags = 0)
214214
* @return list<array{string, int}>
215215
* @phpstan-return list<array{string, int<0, max>}>
216216
*/
217-
public static function splitWithOffset($pattern, $subject, $limit = -1, $flags = 0)
217+
public static function splitWithOffsets($pattern, $subject, $limit = -1, $flags = 0)
218218
{
219219
$result = preg_split($pattern, $subject, $limit, $flags | PREG_SPLIT_OFFSET_CAPTURE);
220220
if ($result === false) {
@@ -267,4 +267,38 @@ public static function isMatchAll($pattern, $subject, &$matches = null, $flags =
267267
{
268268
return (bool) static::matchAll($pattern, $subject, $matches, $flags, $offset);
269269
}
270+
271+
/**
272+
* Runs preg_match_all with PREG_OFFSET_CAPTURE
273+
*
274+
* @param string $pattern
275+
* @param string $subject
276+
* @param array<int|string, array{string|null, int}> $matches Set by method
277+
* @param int $flags PREG_UNMATCHED_AS_NULL, only available on PHP 7.2+
278+
* @param int $offset
279+
* @return bool
280+
*
281+
* @phpstan-param array<int|string, array{string|null, int<-1, max>}> $matches
282+
*/
283+
public static function isMatchWithOffsets($pattern, $subject, &$matches, $flags = 0, $offset = 0)
284+
{
285+
return (bool) static::matchWithOffsets($pattern, $subject, $matches, $flags, $offset);
286+
}
287+
288+
/**
289+
* Runs preg_match_all with PREG_OFFSET_CAPTURE
290+
*
291+
* @param string $pattern
292+
* @param string $subject
293+
* @param array<int|string, list<array{string|null, int}>> $matches Set by method
294+
* @param int $flags PREG_UNMATCHED_AS_NULL, only available on PHP 7.2+
295+
* @param int $offset
296+
* @return bool
297+
*
298+
* @phpstan-param array<int|string, list<array{string|null, int<-1, max>}>> $matches
299+
*/
300+
public static function isMatchAllWithOffsets($pattern, $subject, &$matches, $flags = 0, $offset = 0)
301+
{
302+
return (bool) static::matchAllWithOffsets($pattern, $subject, $matches, $flags, $offset);
303+
}
270304
}

‎src/Regex.php‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ public static function isMatch($pattern, $subject, $offset = 0)
3434
public static function match($pattern, $subject, $flags = 0, $offset = 0)
3535
{
3636
if (($flags & PREG_OFFSET_CAPTURE) !== 0) {
37-
throw new \InvalidArgumentException('PREG_OFFSET_CAPTURE is not supported as it changes the return type, use matchWithOffset() instead');
37+
throw new \InvalidArgumentException('PREG_OFFSET_CAPTURE is not supported as it changes the return type, use matchWithOffsets() instead');
3838
}
3939

4040
$count = Preg::match($pattern, $subject, $matches, $flags, $offset);
@@ -49,13 +49,13 @@ public static function match($pattern, $subject, $flags = 0, $offset = 0)
4949
* @param string $subject
5050
* @param int $flags PREG_UNMATCHED_AS_NULL, only available on PHP 7.2+
5151
* @param int $offset
52-
* @return MatchWithOffsetResult
52+
* @return MatchWithOffsetsResult
5353
*/
54-
public static function matchWithOffset($pattern, $subject, $flags = 0, $offset = 0)
54+
public static function matchWithOffsets($pattern, $subject, $flags = 0, $offset = 0)
5555
{
56-
$count = Preg::matchWithOffset($pattern, $subject, $matches, $flags, $offset);
56+
$count = Preg::matchWithOffsets($pattern, $subject, $matches, $flags, $offset);
5757

58-
return new MatchWithOffsetResult($count, $matches);
58+
return new MatchWithOffsetsResult($count, $matches);
5959
}
6060

6161
/**
@@ -68,7 +68,7 @@ public static function matchWithOffset($pattern, $subject, $flags = 0, $offset =
6868
public static function matchAll($pattern, $subject, $flags = 0, $offset = 0)
6969
{
7070
if (($flags & PREG_OFFSET_CAPTURE) !== 0) {
71-
throw new \InvalidArgumentException('PREG_OFFSET_CAPTURE is not supported as it changes the return type, use matchAllWithOffset() instead');
71+
throw new \InvalidArgumentException('PREG_OFFSET_CAPTURE is not supported as it changes the return type, use matchAllWithOffsets() instead');
7272
}
7373

7474
if (($flags & PREG_SET_ORDER) !== 0) {
@@ -87,13 +87,13 @@ public static function matchAll($pattern, $subject, $flags = 0, $offset = 0)
8787
* @param string $subject
8888
* @param int $flags PREG_UNMATCHED_AS_NULL, only available on PHP 7.2+
8989
* @param int $offset
90-
* @return MatchAllWithOffsetResult
90+
* @return MatchAllWithOffsetsResult
9191
*/
92-
public static function matchAllWithOffset($pattern, $subject, $flags = 0, $offset = 0)
92+
public static function matchAllWithOffsets($pattern, $subject, $flags = 0, $offset = 0)
9393
{
94-
$count = Preg::matchAllWithOffset($pattern, $subject, $matches, $flags, $offset);
94+
$count = Preg::matchAllWithOffsets($pattern, $subject, $matches, $flags, $offset);
9595

96-
return new MatchAllWithOffsetResult($count, $matches);
96+
return new MatchAllWithOffsetsResult($count, $matches);
9797
}
9898
/**
9999
* @param string|string[] $pattern

‎tests/PregTests/IsMatchAllWithOffsetsTest.php‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
<?php
2+
3+
/*
4+
* This file is part of composer/pcre.
5+
*
6+
* (c) Composer <https://github.com/composer>
7+
*
8+
* For the full copyright and license information, please view
9+
* the LICENSE file that was distributed with this source code.
10+
*/
11+
12+
namespace Composer\Pcre\PregTests;
13+
14+
use Composer\Pcre\BaseTestCase;
15+
use Composer\Pcre\Preg;
16+
17+
class IsMatchAllWithOffsetsTest extends BaseTestCase
18+
{
19+
/**
20+
* This can be replaced with a setUp() method when appropriate
21+
*
22+
* @before
23+
* @return void
24+
*/
25+
public function registerFunctionName()
26+
{
27+
$this->pregFunction = 'preg_match_all()';
28+
}
29+
30+
/**
31+
* @return void
32+
*/
33+
public function testSuccess()
34+
{
35+
$result = Preg::isMatchAllWithOffsets('{[aei]}', 'abcdefghijklmnopqrstuvwxyz', $matches);
36+
self::assertSame(true, $result);
37+
self::assertSame(array(0 => array(array('a', 0), array('e', 4), array('i', 8))), $matches);
38+
}
39+
40+
/**
41+
* @return void
42+
*/
43+
public function testFailure()
44+
{
45+
$result = Preg::isMatchAllWithOffsets('{abc}', 'def', $matches);
46+
self::assertSame(false, $result);
47+
self::assertSame(array(array()), $matches);
48+
}
49+
50+
/**
51+
* @return void
52+
*/
53+
public function testBadPatternThrowsIfWarningsAreNotThrowing()
54+
{
55+
$this->expectPcreException($pattern = '{[aei]');
56+
@Preg::isMatchAllWithOffsets($pattern, 'abcdefghijklmnopqrstuvwxyz', $matches);
57+
}
58+
59+
/**
60+
* @return void
61+
*/
62+
public function testBadPatternTriggersWarningByDefault()
63+
{
64+
$this->expectPcreWarning();
65+
Preg::isMatchAllWithOffsets('{[aei]', 'abcdefghijklmnopqrstuvwxyz', $matches);
66+
}
67+
}

‎tests/PregTests/IsMatchWithOffsetsTest.php‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
<?php
2+
3+
/*
4+
* This file is part of composer/pcre.
5+
*
6+
* (c) Composer <https://github.com/composer>
7+
*
8+
* For the full copyright and license information, please view
9+
* the LICENSE file that was distributed with this source code.
10+
*/
11+
12+
namespace Composer\Pcre\PregTests;
13+
14+
use Composer\Pcre\BaseTestCase;
15+
use Composer\Pcre\Preg;
16+
17+
class IsMatchWithOffsetsTest extends BaseTestCase
18+
{
19+
/**
20+
* This can be replaced with a setUp() method when appropriate
21+
*
22+
* @before
23+
* @return void
24+
*/
25+
public function registerFunctionName()
26+
{
27+
$this->pregFunction = 'preg_match()';
28+
}
29+
30+
/**
31+
* @return void
32+
*/
33+
public function testSuccess()
34+
{
35+
$result = Preg::isMatchWithOffsets('{(?P<m>[io])}', 'abcdefghijklmnopqrstuvwxyz', $matches);
36+
self::assertSame(true, $result);
37+
self::assertSame(array(0 => array('i', 8), 'm' => array('i', 8), 1 => array('i', 8)), $matches);
38+
}
39+
40+
/**
41+
* @return void
42+
*/
43+
public function testFailure()
44+
{
45+
$result = Preg::isMatchWithOffsets('{abc}', 'def', $matches);
46+
self::assertSame(false, $result);
47+
self::assertSame(array(), $matches);
48+
}
49+
50+
/**
51+
* @return void
52+
*/
53+
public function testBadPatternThrowsIfWarningsAreNotThrowing()
54+
{
55+
$this->expectPcreException($pattern = '{(?P<m>[io])');
56+
@Preg::isMatchWithOffsets($pattern, 'abcdefghijklmnopqrstuvwxyz', $matches);
57+
}
58+
59+
/**
60+
* @return void
61+
*/
62+
public function testBadPatternTriggersWarningByDefault()
63+
{
64+
$this->expectPcreWarning();
65+
Preg::isMatchWithOffsets('{(?P<m>[io])', 'abcdefghijklmnopqrstuvwxyz', $matches);
66+
}
67+
}

‎tests/PregTests/SplitWithOffsetTest.php‎ renamed to ‎tests/PregTests/SplitWithOffsetsTest.php‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
use Composer\Pcre\BaseTestCase;
1515
use Composer\Pcre\Preg;
1616

17-
class SplitWithOffsetTest extends BaseTestCase
17+
class SplitWithOffsetsTest extends BaseTestCase
1818
{
1919
/**
2020
* This can be replaced with a setUp() method when appropriate
@@ -32,7 +32,7 @@ public function registerFunctionName()
3232
*/
3333
public function testSuccess()
3434
{
35-
$result = Preg::splitWithOffset('{[\s,]+}', 'a, b, c');
35+
$result = Preg::splitWithOffsets('{[\s,]+}', 'a, b, c');
3636
self::assertSame(array(array('a', 0), array('b', 3), array('c', 6)), $result);
3737
}
3838

@@ -41,7 +41,7 @@ public function testSuccess()
4141
*/
4242
public function testFailure()
4343
{
44-
$result = Preg::splitWithOffset('{[\s,]+}', 'abc');
44+
$result = Preg::splitWithOffsets('{[\s,]+}', 'abc');
4545
self::assertSame(array(array('abc', 0)), $result);
4646
}
4747

@@ -51,7 +51,7 @@ public function testFailure()
5151
public function testBadPatternThrowsIfWarningsAreNotThrowing()
5252
{
5353
$this->expectPcreException($pattern = '{[\s,]+');
54-
@Preg::splitWithOffset($pattern, 'a, b, c');
54+
@Preg::splitWithOffsets($pattern, 'a, b, c');
5555
}
5656

5757
/**
@@ -60,6 +60,6 @@ public function testBadPatternThrowsIfWarningsAreNotThrowing()
6060
public function testBadPatternTriggersWarningByDefault()
6161
{
6262
$this->expectPcreWarning();
63-
Preg::splitWithOffset('{[\s,]+', 'a, b, c');
63+
Preg::splitWithOffsets('{[\s,]+', 'a, b, c');
6464
}
6565
}

0 commit comments

Comments
 (0)