regextras

Array extras for regular expressions.

Also provides optional String and RegExp prototype extensions.

No more writing the implementation-detail-leaking, non-semantic, and
otherwise ugly:

``js
let matches;
while ((matches = regex.exec(str)) !== null) {
// Do something
if (condition) {
break;
}
}
`

While all of the array extras could be useful, some, might be the most
general purpose as it (as with every) allows short-circuiting (breaking).

The following is equivalent to that above (though with matches as local):

`js
RegExtras(regex).some(str, (matches) => {
// Do something
if (condition) {
return true;
}
return false;
});
`

And if the condition is at the end of the loop, just this:

`js
RegExtras(regex).some(str, (matches) => {
// Do something
return condition;
});
`

Installation

Node:

`js
const RegExtras = require('regextras');
`

Modern browsers:

`js
import {RegExtras} from './node_modules/regextras/dist/index-es.js';
`

Older browsers:

`html

`

The prototype versions must be required or included separately.

If you need the generator methods, you should also add the following:

`html

`

API

$3

new RegExtras(regex, flags, newLastIndex)

Example:

`js
const piglatinArray = RegExtras(/\w*w?ay/).reduce('ouyay areway illysay', function (arr, i, word) {
if (word.endsWith('way')) { arr.push(word.replace(/way$/, '')); } else { arr.push(word.slice(-3, -2) + word.slice(0, -3)); }
return arr;
}, []);
`

All arguments but the first are optional, and the first argument can be
expressed as a string.

The new keywords is not required.

$3

These methods (and their callbacks) behave like the array extra
to which they correspond with exceptions detailed below.

- forEach(str, callback, thisObject) - Unlike the other extras, this
method returns the RegExtras object (to enable chaining).

- some(str, callback, thisObject)

- every(str, callback, thisObject)

- map(str, callback, thisObject)

- filter(str, callback, thisObject)

- reduce(str, cb, prev, thisObj) - Unlike the array extras, allows a
fourth argument to set an alternative value for this within the callback.

- reduceRight(str, cb, prev, thisObj) - Unlike the array extras,
allows a fourth argument to set an alternative value for this within
the callback.

- find(str, cb, thisObj)

- findIndex(str, cb, thisObj)

Also adds the following methods:

- findExec(str, cb, thisObj) - Operates like find() except that it
returns the exec result array (with index and input as well as
numeric properties as returned by RegExp.prototype.exec).

- filterExec(str, cb, thisObj) - Operates like filter() except that
the resulting array will contain the full exec results.

If you are using the Node version (or if, for the browser, you add the
index-generators.js file and you are only supporting modern browsers), one
can use the following generator methods:

- values(str) - Returns an iterator with the array of matches (for each
RegExp.prototype.exec result)

- keys(str) - Returns an iterator with 0-based indexes (from
RegExp.prototype.exec result)

- entries(str) - Returns an iterator with an array containing the
key and the array of matches (for each RegExp.prototype.exec result)

$3

- mixinRegex(regex, newFlags='', newLastIndex=regex.lastIndex) -
Makes a copy of a regular expression.

$3

All callbacks follow the signature:

cb(n1, n2..., i, n0);

...except for the reduce and reduceRight callbacks which follow:

cb(prev, n1, n2..., i, n0);

$3

String and RegExp versions of the above methods are also available.

The RegExp prototype version acts in the same way as RegExtra just
without the need for a separate constructor call.

The String prototype version differs in that instead of the first argument
being a string, it is the regular expression.

Todos

1. Could add Array accessor methods
like slice(), with an additional supplied regular expression to gather
the exec results into an array.

2. Utilize nodeunit browser testing (and add mixinRegex tests)

1. Convert nodeunit tests to ES6 modules running through babel-register?;
streamline as sole set of tests, reconciling test with tests` folder

3. Add generators for prototype versions