->replace->callback(), some methods receive a callback that accepts
object. These methods are:
The details can be used to get concise information about the matched occurrence, such as its value (i.e. "the whole match"), capturing groups and their UTF-8 safe offsets, limits, indexes, other matches as well as the used subject (although it could also be pass as a closure parameter).
Match details, you gain access to:
textLength()- value of a matched occurrence
isInt()which allow you to handle integers safely
subject()- subject against which the pattern was matched
index()- ordinal value of a matched occurrence
limit()- limit which was put on the matches
- offsets of matched values in the subject:
all()- other matched occurrences
- User data - sharing custom data between callbacks
- details about capturing groups, in the next chapter: Capturing groups
There are 6 similar ways to get the value of the matched occurrence.
or you can just accept
string in the callback signature.
All of them are redundant and equal to each other. Their redundancy comes from the fact the there are a few ways of
casting an object to string in PHP, casting
Match to string is the same as getting
text() in T-Regx, and that the
whole match is also group
0 in regular expressions.
There's also UTF8-safe method
textLength() which, you guessed it, returns the length of a matched text.
true if, and only if, the matched occurrence is numeric. And by "numeric", we mean "real" numeric,
not PHP numeric:
- String values considered valid integers:
- Strings that aren't treated as valid integers:
The string is considered a valid integer if:
- contains only
0-9characters, and more than 1 of them (so
00is also a valid integer, but
- optionally starts with only one
- its numeric representation is:
- higher than
- lower than
- higher than
- doesn't contain any other characters
Checking and parsing
There are two methods regarding integers:
false depending on whether the matched occurrence is numeric.
returns said numeric occurrence as an integer, or throws
PS: It's implemented with
filter_var(), but you can think of it as
/^-?\d+$/with max/min values check.
To get the subject in your callback, use
This is equivalent to storing the subject in a variable and using it in your closure.
Ordinal value (index)
Match.index() returns the ordinal number of a matched occurrence.
In this example, we'll modify every second word:
Match.index() are always continuous integer numbers, going from
3..., even when filtered.
Depending on whether you used [
first() or [
only(int)] - method
limit() will return
1 or an
argument given to
Match.offset() can be used to get the offset of the matched occurrence in the subject.
Match.offset() is multi-byte
character safe and returns offset in characters, whereas
Match.byteOffset() returns the offset in bytes.
Here's what the numbers mean:
In other words,
offset() treats bytes
[226, 130, 172] as one multi-byte character (euro sign
€) and counts them as
byteOffset() would count them as three.
Match has access to other matched occurrences:
Match.all()- for whole matches (like
Match.group().all()- for capturing groups (like
Even if you use
Match.all() always returns unlimited occurrences.
To most users this functionality will occur as redundant - it's only use case are multiple calls to callbacks, for example
when using chained
filter()->map(). With user data, it's possible to perform an operation in
filter(), store its
value in user data, and then use the value in
map() without reference closure variables.
There were ideas of adding structures for user data, like
getUserData('key'), but we decided to give more control to the user about it's structure. That's why user data is
Match.group(string|int), you can easily retrieve capturing groups.
Just like with
Match, retrieving matched occurrence value is done with
text() method or by casting it to
More about capturing groups can be found in the next section: Capturing groups.