update docs and changelog, run verb

Author: jonschlinkert

.verb.md

@@ -1,94 +1,127 @@
-## Notes
+<details>
+  <summary><strong>What does this do?</strong></summary>
 
-Validated against [1,117,543 generated unit tests](./test/test.js), to provide brute-force verification that the generated regex-ranges are correct.
+<br>
 
-## Usage
+This libary generates the `source` string to be passed to `new RegExp()` for matching a range of numbers. 
+
+**Example**
 
 ```js
 var toRegexRange = require('{%= name %}');
-
-var re = new RegExp(toRegexRange('1', '99'));
-re.test('50');
-//=> true
+var regex = new RegExp(toRegexRange('15', '95'));
 ```
 
-**Examples**
+A string is returned so that you can do whatever you need with it before passing it to `new RegExp()` (like adding `^` or `$` boundaries, defining flags, or combining it another string). 
 
-```js
-console.log(toRegexRange('111', '555'));
-//=> 11[1-9]|1[2-9][0-9]|[2-4][0-9]{2}|5[0-4][0-9]|55[0-5]
+<br>
 
-console.log(toRegexRange('5', '5'));
-//=> 5
+</details>
 
-console.log(toRegexRange('5', '6'));
-//=> [5-6]
+<details>
+  <summary><strong>Why use this library?</strong></summary>
 
-console.log(toRegexRange('51', '229'));
-//=> 5[1-9]|[6-9][0-9]|1[0-9]{2}|2[0-2][0-9]
+<br>
 
-console.log(toRegexRange('29', '51'));
-//=> 29|[3-4][0-9]|5[0-1]
+### Convenience
+
+Creating regular expressions for matching numbers gets deceptively complicated pretty fast. 
+
+For example, let's say you need a validation regex for matching part of a user-id, postal code, social security number, tax id, etc:
+
+- regex for matching `1` => `/1/` (easy enough)
+- regex for matching `1` through `5` => `/[1-5]/` (not bad...)
+- regex for matching `1` or `5` => `/(1|5)/` (still easy...)
+- regex for matching `1` through `50` => `/([1-9]|[1-4][0-9]|50)/` (uh-oh...)
+- regex for matching `1` through `55` => `/([1-9]|[1-4][0-9]|5[0-5])/` (no prob, I can do this...)
+- regex for matching `1` through `555` => `/([1-9]|[1-9][0-9]|[1-4][0-9]{2}|5[0-4][0-9]|55[0-5])/` (maybe not...)
+- regex for matching `0001` through `5555` => `/(0{3}[1-9]|0{2}[1-9][0-9]|0[1-9][0-9]{2}|[1-4][0-9]{3}|5[0-4][0-9]{2}|55[0-4][0-9]|555[0-5])/` (okay, I get the point!)
+
+The numbers are contrived, but they're also really basic. In the real world you might need to generate a regex on-the-fly for validation. 
+
+**Learn more**
+
+If you're interested in learning more about [character classes](http://www.regular-expressions.info/charclass.html) and other regex features, I personally have always found [regular-expressions.info](http://www.regular-expressions.info/charclass.html) to be pretty useful.
+
+
+### Heavily tested
+
+As of {%= date() %}, this library runs [2,783,483 test assertions](./test/test.js) against generated regex-ranges to provide brute-force verification that results are indeed correct. 
+
+Tests run in ~870ms on my MacBook Pro, 2.5 GHz Intel Core i7.
+
+### Highly optimized
+
+Generated regular expressions are highly optimized:
+- duplicate sequences and character classes are reduced using quantifiers
+- smart enough to use `?` conditionals when number(s) or range(s) can be positive or negative
+- uses fragment caching to avoid processing the same exact string more than once 
+
+<br>
+
+</details>
+
+## Usage
+
+Add this library to your javascript application with the following line of code
 
-console.log(toRegexRange('1', '100000'));
-//=> [1-9]|[1-9][0-9]{1,4}|100000
+```js
+var toRegexRange = require('{%= name %}');
 ```
 
-When the `min` is larger than the `max`, values will be flipped to create a valid range:
+The main export is a function that takes two integers: the `min` value and `max` value (formatted as strings or numbers).
 
 ```js
-toRegexRange('51', '29');
-//=> 29|[3-4][0-9]|5[0-1]
+var source = toRegexRange('15', '95');
+//=> 1[5-9]|[2-8][0-9]|9[0-5]
+
+var re = new RegExp('^' + source + '$');
+console.log(re.test('14')); //=> false
+console.log(re.test('50')); //=> true
+console.log(re.test('94')); //=> true
+console.log(re.test('96')); //=> false
 ```
 
-**Heads up!**
+## Examples
 
-This library does not support steps (increments) or zero-padding. 
+{%= rangeExamples() %}
 
-## History
+## Heads up!
+
+**Order of arguments**
+
+When the `min` is larger than the `max`, values will be flipped to create a valid range:
+
+```js
+toRegexRange('51', '29');
+```
 
-### v1.0
+Is effectively flipped to:
 
-More optimizations! As of v1.0, repeating ranges are now grouped using quantifiers. Processing time is roughly the same, but the generated regex is much smaller, which should result in faster matching.
+```js
+toRegexRange('29', '51');
+//=> 29|[3-4][0-9]|5[0-1]
+```
 
-**Key**
+**Steps / increments**
 
-_(for the before/after comparison tables)_
+This library does not support steps (increments). A pr to add support would be welcome.
 
-- `range`: the generated range, e.g. `toRegexRange(1, 10000000)`
-- `stats`: size of the generated string, and processing time
-- `result`: generated string
 
-#### Before
+## History
+
+### v2.0.0 - 2017-04-21
 
-Patterns generated before v1.0 changes:
+**New features**
 
-**Range**     | **Stats**           | **Result**
----           | ---                 | ---
-`1..10000000` | `99 B` (11ms 666μs) | `([1-9]|[1-9][0-9]|[1-9][0-9]{2}|[1-9][0-9]{3}|[1-9][0-9]{4}|[1-9][0-9]{5}|[1-9][0-9]{6}|10000000)`
-`1..1000000`  | `84 B` (2ms 96μs)   | `([1-9]|[1-9][0-9]|[1-9][0-9]{2}|[1-9][0-9]{3}|[1-9][0-9]{4}|[1-9][0-9]{5}|1000000)`
-`1..100000`   | `69 B` (1ms 674μs)  | `([1-9]|[1-9][0-9]|[1-9][0-9]{2}|[1-9][0-9]{3}|[1-9][0-9]{4}|100000)`
-`1..10000`    | `54 B` (2ms 40μs)   | `([1-9]|[1-9][0-9]|[1-9][0-9]{2}|[1-9][0-9]{3}|10000)`
-`1..1000`     | `39 B` (1ms 263μs)  | `([1-9]|[1-9][0-9]|[1-9][0-9]{2}|1000)`
-`1..100`      | `24 B` (1ms 905μs)  | `([1-9]|[1-9][0-9]|100)`
-`1..10`       | `12 B` (383μs)      | `([1-9]|10)`
-`1..3`        | `9 B` (260μs)       | `([1-3])`
+Adds support for zero-padding!
 
-#### After 
+### v1.0.0
 
-With v1.0 optimizations.
+**Optimizations**
 
-**Range**     | **Stats**           | **Result**
----           | ---                 | ---
-`1..10000000` | `34 B` (11ms 702μs) | `([1-9]|[1-9][0-9]{1,6}|10000000)`
-`1..1000000`  | `33 B` (1ms 274μs)  | `([1-9]|[1-9][0-9]{1,5}|1000000)`
-`1..100000`   | `32 B` (726μs)      | `([1-9]|[1-9][0-9]{1,4}|100000)`
-`1..10000`    | `31 B` (2ms 432μs)  | `([1-9]|[1-9][0-9]{1,3}|10000)`
-`1..1000`     | `30 B` (507μs)      | `([1-9]|[1-9][0-9]{1,2}|1000)`
-`1..100`      | `24 B` (267μs)      | `([1-9]|[1-9][0-9]|100)`
-`1..10`       | `12 B` (240μs)      | `([1-9]|10)`
-`1..3`        | `9 B` (665μs)       | `([1-3])`
+Repeating ranges are now grouped using quantifiers. rocessing time is roughly the same, but the generated regex is much smaller, which should result in faster matching.
 
 ## Attribution
 
-Inspired by the python lib [range-regex](https://github.com/dimka665/range-regex).
+Inspired by the python library [range-regex](https://github.com/dimka665/range-regex).