# 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
<script src="regextras/dist/index-umd.js"></script>
```

The prototype versions must be required or included separately.

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

```html
<script src="regextras/dist/index-generators-umd.js"></script>
```

## API

### Constructor

`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.

### Instance methods

These methods (and their callbacks) behave like the [array extra](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#Iteration_methods)
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/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)

### Class methods

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

### Callbacks

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);`

### Prototype versions

`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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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