Match offsets

There are several ways to read offsets of your matched occurrences and your capturing groups.

Using `Match` details

If you use Match details object (like the one passed to first(), forEach() or map() callback) you can just use offset() method.

pattern('\d+')->match('I was born in 1996')->first(function (Match $match) {
    return 'Match was found at ' . $match->offset();
});

'Match was found at 14'

Remember that offset() is UTF-8 safe and returns offsets in characters, not bytes. For bytes, consider using byteOffset() method.

Use offset() with methods like mb_substr(), and byteOffset() with methods like substr().

Use inline methods to simply return the offsets - when there is no need for using Match details or any other operations.

If you only want to get offsets of your matches, use offsets()->all().

pattern('[0-9]+')->match("I'm 19 years old. I was born in 1999, May 12")->offsets()->all();

[4, 32, 42]

You can also limit your matches.

pattern('[0-9]+')->match("I'm 19 years old. I was born in 1999, May 12")->offsets()->only(2);

[4, 32]

To only get offset of the first occurrence of a matched pattern, call offsets()->first().

pattern('\d+')->match("I was born in 1999")->offsets()->first();

As any other first() method, it throws SubjectNotMatchedException if the subject isn't matched by your pattern.

In a similar manner you can get offsets of your capturing groups, either using Match details or an inline method.

These two snippets below are equal to each other.

pattern('(?<capital>[A-Z])[a-z]+')->match('my name is John Cena')->first(function (Match $match) {
    return $match->group('capital')->offset();
});

Can also be written as...

pattern('(?<capital>[A-Z])[a-z]+')->match('my name is John Cena')->group('capital')->offsets()->first();

Both offsets()->first() and group()->offsets()->first() throw SubjectNotMatchedException if the subject isn't matched by your pattern.

Also, both Match.group() details and inline match()->group()->offsets() throw GroupNotMatchedException, when used with an unmatched group.