Finalize new API, more examples

[DmitryOlshansky]

The core part of pull #1225.
This neatly fixes issue 7260.

Basically everyone (me included) forgets to set the global flag in a regex foreach.
Coupled with the fact that splitter already cracks open regex to set global flag it's painfully obvious that global/local is an attribute of operation but not of the pattern itself.

Hence separate API calls, plus I use the opportunity to simplify the single match case to just get a range of submatches.

Also fixes issue 9579.

[andralex]

We prefer members to start with _. That way incidentally make constructor writing easily because you can use the same name (without underscore) for parameters.

[DmitryOlshansky]

That way incidentally make constructor writing easily

... and everything else uglier. I'm still divided on this matter (as camn be seen in the source code, heh).
Anyway I'll make this struct consistently underscorish.

[andralex]

fix the nits and let's get this in

[DmitryOlshansky]

Done

[DmitryOlshansky]

Perfect.
@AndrejMitrovic I would love to add a line or two about this in the changelog, How should I go about it?
After all this new API that should gradually replace the global flag stuff.

[denis-sh]

@blackwhale, matchFirst and matchAll has equal documentation. Fix please.

[DmitryOlshansky]

@denis-sh Good catch, will do.

[ghost]

@blackwhale

I would love to add a line or two about this in the changelog, How should I go about it?

The procedure is:

1. Wait until the next beta release
2. Use changed.d from the tools repo to generate the changelog listing all the bugs
3. Hand-write any changes which should be more visible than others, especially things like breaking language changes.

So now we're at #1. Once we have a beta I'll begin working on the next changelog and I'll ping you for a description of this changeset.

[ghost]

@blackwhale: If you can you could ping me with the examples of the API so I can put them in the changelog.