Skip to content

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
jonschlinkert committed Apr 7, 2019
1 parent baf1457 commit 9045d5f
Show file tree
Hide file tree
Showing 4 changed files with 132 additions and 180 deletions.
4 changes: 0 additions & 4 deletions .travis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,3 @@ node_js:
- '10'
- '9'
- '8'
- '7'
- '6'
- '5'
- '4'
62 changes: 32 additions & 30 deletions .verb.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,13 +46,14 @@ If you're interested in learning more about [character classes](http://www.regul

### 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.
As of {%= date() %}, this library runs [>1m test assertions](./test/test.js) against generated regex-ranges to provide brute-force verification that results are correct.

Tests run in ~580ms on my MacBook Pro, 2.5 GHz Intel Core i7.
Tests run in ~280ms on my MacBook Pro, 2.5 GHz Intel Core i7.

### Highly optimized
### Optimized

Generated regular expressions are 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
Expand All @@ -75,11 +76,11 @@ The main export is a function that takes two integers: the `min` value and `max`
const source = toRegexRange('15', '95');
//=> 1[5-9]|[2-8][0-9]|9[0-5]

const 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
const regex = new RegExp(`^${source}$`);
console.log(regex.test('14')); //=> false
console.log(regex.test('50')); //=> true
console.log(regex.test('94')); //=> true
console.log(regex.test('96')); //=> false
```

## Options
Expand Down Expand Up @@ -122,35 +123,32 @@ console.log(toRegexRange('0', '999999', { shorthand: true }));

**Default**: `true`

This option only applies to **negative zero-padded ranges**. By default, when a negative zero-padded range is defined, the number of leading zeros is relaxed using `-0*`.
This option relaxes matching for leading zeros when when ranges are zero-padded.

```js
console.log(toRegexRange('-001', '100'));
//=> -0*1|0{2}[0-9]|0[1-9][0-9]|100

console.log(toRegexRange('-001', '100', {relaxZeros: false}));
//=> -0{2}1|0{2}[0-9]|0[1-9][0-9]|100
const source = toRegexRange('-0010', '0010');
const regex = new RegExp(`^${source}$`);
console.log(regex.test('-10')); //=> true
console.log(regex.test('-010')); //=> true
console.log(regex.test('-0010')); //=> true
console.log(regex.test('10')); //=> true
console.log(regex.test('010')); //=> true
console.log(regex.test('0010')); //=> true
```

<details>
<summary><strong>Why are zeros relaxed for negative zero-padded ranges by default?</strong></summary>

Consider the following.
When `relaxZeros` is false, matching is strict:

```js
const regex = toRegexRange('-001', '100');
const source = toRegexRange('-0010', '0010', { relaxZeros: false });
const regex = new RegExp(`^${source}$`);
console.log(regex.test('-10')); //=> false
console.log(regex.test('-010')); //=> false
console.log(regex.test('-0010')); //=> true
console.log(regex.test('10')); //=> false
console.log(regex.test('010')); //=> false
console.log(regex.test('0010')); //=> true
```

_Note that `-001` and `100` are both three digits long_.

In most zero-padding implementations, only a single leading zero is enough to indicate that zero-padding should be applied. Thus, the leading zeros would be "corrected" on the negative range in the example to `-01`, instead of `-001`, to make total length of each string no greater than the length of the largest number in the range (in other words, `-001` is 4 digits, but `100` is only three digits).

If zeros were not relaxed by default, you might expect the resulting regex of the above pattern to match `-001` - given that it's defined that way in the arguments - _but it wouldn't_. It would, however, match `-01`. This gets even more ambiguous with large ranges, like `-01` to `1000000`.

Thus, we relax zeros by default to provide a more predictable experience for users.

</details>

## Examples

{%= examples() %}
Expand Down Expand Up @@ -179,6 +177,10 @@ This library does not support steps (increments). A pr to add support would be w

## History

### v5.0.0 - 2019-04-07

Optimizations. Updated code to use newer ES features.

### v2.0.0 - 2017-04-21

**New features**
Expand Down

0 comments on commit 9045d5f

Please sign in to comment.