README

The Jitsu\RegexUtil class is a collection of static methods for dealing with regular expressions in PHP. These helper functions simplify the creation of new patterns, escaping literal strings, handling errors, and accessing match offsets.

This package is part of Jitsu.

Installation

Install this package with Composer:

composer require jitsu/regex

Namespace

The class is defined under the namespace Jitsu.

API

class Jitsu\RegexUtil

A collection of static methods for dealing with regular expressions.

RegexUtil::create($pat, $flags = '', $start = null, $end = null)

Create a regular expression from a PCRE pattern.

This converts a string containing a PCRE pattern to a value compatible for use with this module. Do not include the delimiters; they will be added and escaped automatically. You can specify any flags in a separate string. If you know that your PCRE is already properly escaped with respect to a certain set of deliters, you can optionally provide the start and ending delimiters to use and avoid the overhead of escaping the pattern.

RegexUtil::errorString($code)

Get an error string for a PREG_ error code.

RegexUtil::match($regex, $str, $offset = 0)

Try to match a regular expression against a string.

Tests a regular expression against a string and returns a RegexUtilMatch object, or null if there was no match.

The match at index 0 is the part of the string which matched the whole pattern.

RegexUtil::matchWithOffsets($regex, $str, $offset = 0)

Like match, but also include the starting indices of the matches.

If the string matches the regular expression, the return value includes the starting indices of the matches as well. A starting index of -1 indicates that the group was not matched.

RegexUtil::matchAll($regex, $str, $offset = 0)

Get all non-overlapping matches of a regular expression in a string.

RegexUtil::matchAllWithOffsets($regex, $str, $offset = 0)

Get all non-overlapping matches of a regular expression in a string along with offset information.

RegexUtil::escape($str, $delim = null)

Escape a string for interpolation in a regular expression.

If used with a pattern where the delimiter is being explicitly set, you must provide that delimiter as the second argument.

RegexUtil::replace($regex, $str, $replacement, $limit = null)

Replace the portion of a string which matches a regular expression with another string.

The replacement string may use backreferences in the form \n, $n, or ${n}. Optionally specify a limit for the number of replacements which may be made (pass null for unlimited).

Stores the number of replacements made in the optional $count variable.

If $replacement is not a string or array, it will be interpreted as a callback with the signature function($matches) whose return value will be used to generate the replacement strings. The $matches parameter is an array containing the matched groups.

Any one of the arguments $regex, $replacement, or $str may be an array of multiple values. Whenever each is a scalar, it applies to all the values in the other arguments, be they scalars or arrays. Whenever each is an array, it applies pairwise to the other array arguments.

When $regex is an array tested against a scalar $str, all of the patterns are tested as a logical "or".

When $replacement is an array with too few elements for the other array arguments, the missing values are assumed to be the empty string. If it is an array, it may contain only strings, not callbacks.

When $str is an array, an array of the replaced strings is returned.

RegexUtil::replaceAndCount($regex, $str, $replacement, $limit = null)

Like replace, but include the number of replacements as a second return value.

RegexUtil::replaceWith($regex, $str, $callback, $limit = null)

Like replace, except that the second parameter is always interpreted as a callback.

This allows function names, etc. to be passed.

RegexUtil::replaceAndCountWith($regex, $str, $callback, $limit = null)

Like replaceWith but with the number of replacements included.

RegexUtil::replaceAndFilter($regex, $strs, $replacement, $limit = null)

Same behavior as replace, except that when $strs is an array, only strings which had a replacement performed are returned in the resulting array.

RegexUtil::replaceAndFilterAndCount($regex, $strs, $replacement, $limit = null)

Like replaceAndFilter but with the number of replacements included.

RegexUtil::grep($regex, $strs)

Test a regular expression against an array of strings and return those strings which match.

RegexUtil::invertedGrep($regex, $strs)

Same as grep, except that all of the strings which do not match the regular expression are returned.

RegexUtil::split($regex, $str, $limit = null)

Split a string by a regular expression. Optionally provide a limit to the number of splits.

RegexUtil::splitWithOffsets($regex, $str, $limit = null)

Like split but with offsets included as a second return value.

RegexUtil::splitAndFilter($regex, $str, $limit = null)

Like split, but filters out empty strings from the result.

RegexUtil::splitAndFilterWithOffsets($regex, $str, $limit = null)

Like splitAndFilter but with offsets included as a second return value.

RegexUtil::inclusiveSplit($regex, $str, $limit = null)

Like split, except include group 1 of the splitting pattern in the results as well.

RegexUtil::inclusiveSplitWithOffsets($regex, $str, $limit = null)

Like inclusiveSplit but with offsets included as a second return value.

class Jitsu\RegexUtilMatch

An object representing a regular expression match.

new RegexUtilMatch($groups)

$regex_util_match->__toString()

$regex_util_match->groups()

Get the array of matched groups.

$regex_util_match->group($i)

Get a certain group.

$regex_util_match->offsets()

Get the array of match offsets.

$regex_util_match->offset($i)

Get the offset for a certain group.

class Jitsu\RegexUtilMatchWithOffsets

Extends RegexUtilMatch.

A regular expression match with match offset data.

new RegexUtilMatchWithOffsets($groups, $offsets)

$regex_util_match_with_offsets->offsets()

$regex_util_match_with_offsets->offset($i)