Add consecutive_groups()

[bbayles]

This PR adds consecutive_groups(), a tool for finding consecutive blocks of items in an iterable. This is an extension of the example in the old itertools docs.

---

I've always admired the trick offered in the example, which is excerpted here:

>>> data = [ 1,  4,5,6, 10, 15,16,17,18, 22, 25,26,27,28]
>>> for k, g in groupby(enumerate(data), lambda (i,x):i-x):
...     print map(operator.itemgetter(1), g)
... 
[1]
[4, 5, 6]
[10]
[15, 16, 17, 18]
[22]
[25, 26, 27, 28]

This works because enumerate counts up by 1 for each item in the iterable (0, 1, 2, 3...), so if we have a run of numbers (20, 21, 22, 23), we'll wind up with a constant difference between the index and each item in the run (20 - 0 = 20, 21 - 1 = 20, 22 - 2 = 20, ...). This we use for grouping.

---

The example shows how to work with iterables of numbers, but the same method can be applied to any sequence with a clear ordering. I've used this for finding consecutive IP addresses, for example.

>>> from socket import inet_aton
... from struct import unpack
... 
... from more_itertools import consecutive_groups
... 
... iterable = ['192.0.2.0', '192.0.2.2', '192.0.2.3', '192.0.2.5']
... ordering = lambda x: unpack(b'!I', inet_aton(x))[0]
... 
... for group in consecutive_groups(iterable, ordering):
...     print(list(group))
['192.0.2.0']
['192.0.2.2', '192.0.2.3']
['192.0.2.5']

The tests show another example where there's not an obvious numerical representation, but all we need is a ranking method.

[pylang]

Absolutely. This unsung recipe is so clever. I'm glad you found a general name for it.

For reference, here are other use cases in the wild:

• Identify groups of continuous numbers in a list
• converting a list of integers into range in python
• Find indexes of repeated elements in an array (Python, NumPy)