Heey, there!

Quick summary of changes in this release:

• Every exception extending PregException (so MalformedPatternException, CatastrophicBacktrackingPregException, etc.) have received new method getPregPattern():

  try {

  pattern('foo')->...

  } catch (\TRegx\SafeRegex\Exception\PregException $exception) {

  $exception->getPregPattern(); // '/foo/'

  }

  Copy

  Some methods still throw \InvalidArgumentException, and of course that exception is unchanged.

• We brought back Pattern::prepare() (see ChangeLog.md)

• We added Match.tail() method, which works like offset() but returns the position of the end of the occurrence in the subject (not the start like offset()).

• tail() also works for MatchGroup and ReplaceMatch.

• There's also byteTail(), which returns the position in bytes, instead of characters (like byteOffset()).

• Fixed inconsistencies

  • Duplicated pattern exception message changes offset after PHP 7.3. Since now, the messages will be identical on every PHP version.

• Added null-safety to some replace methods. Returning null from any of those methods:

  • replace()->callback()
  • replace()->otherwise()
  • replace()->by()->group()->orElse()

  throws InvalidReturnValueException.

• Renamed some or methods. Previously, what was used to handle the missing first value (result of findFirst()), was also used to specify the replacement of an optional, unmatched group. Sorry to say that, we made a bad decision unifying this interface, since it turns out they're not even remotely connected. What fooled us, was we referred to each as "optional" (even tough one was "optional first match", and the second was "replacement of an optional group).

  In this release, we separate the interfaces, and assign new, better names for the specification of unmatched, optional groups:

  • Renamed pattern()->replace()->by()->group() methods:
    • Renamed orThrow(string) to orElseThrow(string).
    • Renamed orIgnore() to orElseIgnore().
    • Renamed orEmpty() to orElseEmpty().
    • Renamed orReturn(string) to orElseWith(string).
    • Renamed orElse(callable) to orElseCalling(callable).
  • Renamed and added pattern()->replace()->by()->group()->map() methods:
    • Renamed orThrow(string) to orElseThrow(string).
    • Added orElseIgnore().
    • Added orElseEmpty().
    • Renamed orReturn(string) to orElseWith(string).
    • Renamed orElse(callable) to orElseCalling(callable).

As always, everything is described in ChangeLog.md on github.