To use XRegExp, first create a regular expression object with var myre = XRegExp('regex', 'flags') where flags is a combination of the letters g (global), i (case insensitive), m (anchors match at line breaks), s (dot matches line breaks), x (free-spacing), and n (explicit capture). XRegExp 3 adds the A (astral) flag which includes Unicode characters beyond U+FFFF when matching Unicode properties and blocks. The ECMAScript 6 flags y (sticky) and u (Unicode) can also be used in modern browsers that support them natively, but they’ll throw errors in browsers that don’t have built-in support for these flags.
XRegExp.test(str, regex, [pos=0], [sticky=false]) tests whether the regex can match part of a string. The pos argument is a zero-based index in the string where the match attempt should begin. If you pass true or 'sticky' for the sticky parameter, then the match is only attempted at pos. This is similar to adding the start-of-attempt anchor \G (which XRegExp doesn’t support) to the start of your regex in other flavors.
XRegExp.exec(str, regex, [pos=0], [sticky=false]) does the same as XRegExp.test() but returns null or an array instead of false or true. Index 0 in the array holds the overall regex match. Indexes 1 and beyond hold the text matched by capturing groups, if any. If the regex has named capturing groups, their matches are available as properties on the array. XRegExp.exec() does not rely on the lastIndex property and thus avoids cross-browser problems with that property.
XRegExp.forEach(str, regex, callback) makes it easy to iterate over all matches of the regex in a string. It always iterates over all matches, regardless of the global flag an the lastIndex property. The callback is called with four arguments. The first two are an array like returned by exec() and the index in the string that the match starts at. The last two are str and regex exactly as you passed them to forEach().
XRegExp.replace(str, regex, replacement, [scope]) returns a string with the matches of regex in str replaced with replacement. Pass 'one' or 'all' as the scope argument to replace only the first match or all matches. If you omit the scope argument then the regex.global flag determines whether only the first or all matches are replaced.
If you pass a function as the replacement parameter, then it will be called with three or more arguments. The first argument is the string that was matched, with named capturing groups available through properties on that string. The second and following arguments are the strings matched by each of the capturing groups in the regex, if any. The final two arguments are the index in the string at which the match was found and the original subject string.
Did this website just save you a trip to the bookstore? Please make a donation to support this site, and you'll get a lifetime of advertisement-free access to this site!
Page URL: https://www.regular-expressions.info/xregexp.html
Page last updated: 22 November 2019
Site last updated: 05 October 2020
Copyright © 2003-2021 Jan Goyvaerts. All rights reserved.
|Languages & Libraries|
|Visual Basic 6|
|XQuery & XPath|
|Regular Expressions Quick Start|
|Regular Expressions Tutorial|
|Replacement Strings Tutorial|
|Applications and Languages|
|Regular Expressions Examples|
|Regular Expressions Reference|
|Replacement Strings Reference|
|About This Site|
|RSS Feed & Blog|