| [6a3a178] | 1 | # to-regex-range [](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=W8YFZ425KND68) [](https://www.npmjs.com/package/to-regex-range) [](https://npmjs.org/package/to-regex-range) [](https://npmjs.org/package/to-regex-range) [](https://travis-ci.org/micromatch/to-regex-range)
|
|---|
| 2 |
|
|---|
| 3 | > Pass two numbers, get a regex-compatible source string for matching ranges. Validated against more than 2.78 million test assertions.
|
|---|
| 4 |
|
|---|
| 5 | Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.
|
|---|
| 6 |
|
|---|
| 7 | ## Install
|
|---|
| 8 |
|
|---|
| 9 | Install with [npm](https://www.npmjs.com/):
|
|---|
| 10 |
|
|---|
| 11 | ```sh
|
|---|
| 12 | $ npm install --save to-regex-range
|
|---|
| 13 | ```
|
|---|
| 14 |
|
|---|
| 15 | <details>
|
|---|
| 16 | <summary><strong>What does this do?</strong></summary>
|
|---|
| 17 |
|
|---|
| 18 | <br>
|
|---|
| 19 |
|
|---|
| 20 | This libary generates the `source` string to be passed to `new RegExp()` for matching a range of numbers.
|
|---|
| 21 |
|
|---|
| 22 | **Example**
|
|---|
| 23 |
|
|---|
| 24 | ```js
|
|---|
| 25 | const toRegexRange = require('to-regex-range');
|
|---|
| 26 | const regex = new RegExp(toRegexRange('15', '95'));
|
|---|
| 27 | ```
|
|---|
| 28 |
|
|---|
| 29 | 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).
|
|---|
| 30 |
|
|---|
| 31 | <br>
|
|---|
| 32 |
|
|---|
| 33 | </details>
|
|---|
| 34 |
|
|---|
| 35 | <details>
|
|---|
| 36 | <summary><strong>Why use this library?</strong></summary>
|
|---|
| 37 |
|
|---|
| 38 | <br>
|
|---|
| 39 |
|
|---|
| 40 | ### Convenience
|
|---|
| 41 |
|
|---|
| 42 | Creating regular expressions for matching numbers gets deceptively complicated pretty fast.
|
|---|
| 43 |
|
|---|
| 44 | 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:
|
|---|
| 45 |
|
|---|
| 46 | * regex for matching `1` => `/1/` (easy enough)
|
|---|
| 47 | * regex for matching `1` through `5` => `/[1-5]/` (not bad...)
|
|---|
| 48 | * regex for matching `1` or `5` => `/(1|5)/` (still easy...)
|
|---|
| 49 | * regex for matching `1` through `50` => `/([1-9]|[1-4][0-9]|50)/` (uh-oh...)
|
|---|
| 50 | * regex for matching `1` through `55` => `/([1-9]|[1-4][0-9]|5[0-5])/` (no prob, I can do this...)
|
|---|
| 51 | * 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...)
|
|---|
| 52 | * 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!)
|
|---|
| 53 |
|
|---|
| 54 | 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.
|
|---|
| 55 |
|
|---|
| 56 | **Learn more**
|
|---|
| 57 |
|
|---|
| 58 | 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.
|
|---|
| 59 |
|
|---|
| 60 | ### Heavily tested
|
|---|
| 61 |
|
|---|
| 62 | As of April 07, 2019, this library runs [>1m test assertions](./test/test.js) against generated regex-ranges to provide brute-force verification that results are correct.
|
|---|
| 63 |
|
|---|
| 64 | Tests run in ~280ms on my MacBook Pro, 2.5 GHz Intel Core i7.
|
|---|
| 65 |
|
|---|
| 66 | ### Optimized
|
|---|
| 67 |
|
|---|
| 68 | Generated regular expressions are optimized:
|
|---|
| 69 |
|
|---|
| 70 | * duplicate sequences and character classes are reduced using quantifiers
|
|---|
| 71 | * smart enough to use `?` conditionals when number(s) or range(s) can be positive or negative
|
|---|
| 72 | * uses fragment caching to avoid processing the same exact string more than once
|
|---|
| 73 |
|
|---|
| 74 | <br>
|
|---|
| 75 |
|
|---|
| 76 | </details>
|
|---|
| 77 |
|
|---|
| 78 | ## Usage
|
|---|
| 79 |
|
|---|
| 80 | Add this library to your javascript application with the following line of code
|
|---|
| 81 |
|
|---|
| 82 | ```js
|
|---|
| 83 | const toRegexRange = require('to-regex-range');
|
|---|
| 84 | ```
|
|---|
| 85 |
|
|---|
| 86 | The main export is a function that takes two integers: the `min` value and `max` value (formatted as strings or numbers).
|
|---|
| 87 |
|
|---|
| 88 | ```js
|
|---|
| 89 | const source = toRegexRange('15', '95');
|
|---|
| 90 | //=> 1[5-9]|[2-8][0-9]|9[0-5]
|
|---|
| 91 |
|
|---|
| 92 | const regex = new RegExp(`^${source}$`);
|
|---|
| 93 | console.log(regex.test('14')); //=> false
|
|---|
| 94 | console.log(regex.test('50')); //=> true
|
|---|
| 95 | console.log(regex.test('94')); //=> true
|
|---|
| 96 | console.log(regex.test('96')); //=> false
|
|---|
| 97 | ```
|
|---|
| 98 |
|
|---|
| 99 | ## Options
|
|---|
| 100 |
|
|---|
| 101 | ### options.capture
|
|---|
| 102 |
|
|---|
| 103 | **Type**: `boolean`
|
|---|
| 104 |
|
|---|
| 105 | **Deafault**: `undefined`
|
|---|
| 106 |
|
|---|
| 107 | Wrap the returned value in parentheses when there is more than one regex condition. Useful when you're dynamically generating ranges.
|
|---|
| 108 |
|
|---|
| 109 | ```js
|
|---|
| 110 | console.log(toRegexRange('-10', '10'));
|
|---|
| 111 | //=> -[1-9]|-?10|[0-9]
|
|---|
| 112 |
|
|---|
| 113 | console.log(toRegexRange('-10', '10', { capture: true }));
|
|---|
| 114 | //=> (-[1-9]|-?10|[0-9])
|
|---|
| 115 | ```
|
|---|
| 116 |
|
|---|
| 117 | ### options.shorthand
|
|---|
| 118 |
|
|---|
| 119 | **Type**: `boolean`
|
|---|
| 120 |
|
|---|
| 121 | **Deafault**: `undefined`
|
|---|
| 122 |
|
|---|
| 123 | Use the regex shorthand for `[0-9]`:
|
|---|
| 124 |
|
|---|
| 125 | ```js
|
|---|
| 126 | console.log(toRegexRange('0', '999999'));
|
|---|
| 127 | //=> [0-9]|[1-9][0-9]{1,5}
|
|---|
| 128 |
|
|---|
| 129 | console.log(toRegexRange('0', '999999', { shorthand: true }));
|
|---|
| 130 | //=> \d|[1-9]\d{1,5}
|
|---|
| 131 | ```
|
|---|
| 132 |
|
|---|
| 133 | ### options.relaxZeros
|
|---|
| 134 |
|
|---|
| 135 | **Type**: `boolean`
|
|---|
| 136 |
|
|---|
| 137 | **Default**: `true`
|
|---|
| 138 |
|
|---|
| 139 | This option relaxes matching for leading zeros when when ranges are zero-padded.
|
|---|
| 140 |
|
|---|
| 141 | ```js
|
|---|
| 142 | const source = toRegexRange('-0010', '0010');
|
|---|
| 143 | const regex = new RegExp(`^${source}$`);
|
|---|
| 144 | console.log(regex.test('-10')); //=> true
|
|---|
| 145 | console.log(regex.test('-010')); //=> true
|
|---|
| 146 | console.log(regex.test('-0010')); //=> true
|
|---|
| 147 | console.log(regex.test('10')); //=> true
|
|---|
| 148 | console.log(regex.test('010')); //=> true
|
|---|
| 149 | console.log(regex.test('0010')); //=> true
|
|---|
| 150 | ```
|
|---|
| 151 |
|
|---|
| 152 | When `relaxZeros` is false, matching is strict:
|
|---|
| 153 |
|
|---|
| 154 | ```js
|
|---|
| 155 | const source = toRegexRange('-0010', '0010', { relaxZeros: false });
|
|---|
| 156 | const regex = new RegExp(`^${source}$`);
|
|---|
| 157 | console.log(regex.test('-10')); //=> false
|
|---|
| 158 | console.log(regex.test('-010')); //=> false
|
|---|
| 159 | console.log(regex.test('-0010')); //=> true
|
|---|
| 160 | console.log(regex.test('10')); //=> false
|
|---|
| 161 | console.log(regex.test('010')); //=> false
|
|---|
| 162 | console.log(regex.test('0010')); //=> true
|
|---|
| 163 | ```
|
|---|
| 164 |
|
|---|
| 165 | ## Examples
|
|---|
| 166 |
|
|---|
| 167 | | **Range** | **Result** | **Compile time** |
|
|---|
| 168 | | --- | --- | --- |
|
|---|
| 169 | | `toRegexRange(-10, 10)` | `-[1-9]\|-?10\|[0-9]` | _132μs_ |
|
|---|
| 170 | | `toRegexRange(-100, -10)` | `-1[0-9]\|-[2-9][0-9]\|-100` | _50μs_ |
|
|---|
| 171 | | `toRegexRange(-100, 100)` | `-[1-9]\|-?[1-9][0-9]\|-?100\|[0-9]` | _42μs_ |
|
|---|
| 172 | | `toRegexRange(001, 100)` | `0{0,2}[1-9]\|0?[1-9][0-9]\|100` | _109μs_ |
|
|---|
| 173 | | `toRegexRange(001, 555)` | `0{0,2}[1-9]\|0?[1-9][0-9]\|[1-4][0-9]{2}\|5[0-4][0-9]\|55[0-5]` | _51μs_ |
|
|---|
| 174 | | `toRegexRange(0010, 1000)` | `0{0,2}1[0-9]\|0{0,2}[2-9][0-9]\|0?[1-9][0-9]{2}\|1000` | _31μs_ |
|
|---|
| 175 | | `toRegexRange(1, 50)` | `[1-9]\|[1-4][0-9]\|50` | _24μs_ |
|
|---|
| 176 | | `toRegexRange(1, 55)` | `[1-9]\|[1-4][0-9]\|5[0-5]` | _23μs_ |
|
|---|
| 177 | | `toRegexRange(1, 555)` | `[1-9]\|[1-9][0-9]\|[1-4][0-9]{2}\|5[0-4][0-9]\|55[0-5]` | _30μs_ |
|
|---|
| 178 | | `toRegexRange(1, 5555)` | `[1-9]\|[1-9][0-9]{1,2}\|[1-4][0-9]{3}\|5[0-4][0-9]{2}\|55[0-4][0-9]\|555[0-5]` | _43μs_ |
|
|---|
| 179 | | `toRegexRange(111, 555)` | `11[1-9]\|1[2-9][0-9]\|[2-4][0-9]{2}\|5[0-4][0-9]\|55[0-5]` | _38μs_ |
|
|---|
| 180 | | `toRegexRange(29, 51)` | `29\|[34][0-9]\|5[01]` | _24μs_ |
|
|---|
| 181 | | `toRegexRange(31, 877)` | `3[1-9]\|[4-9][0-9]\|[1-7][0-9]{2}\|8[0-6][0-9]\|87[0-7]` | _32μs_ |
|
|---|
| 182 | | `toRegexRange(5, 5)` | `5` | _8μs_ |
|
|---|
| 183 | | `toRegexRange(5, 6)` | `5\|6` | _11μs_ |
|
|---|
| 184 | | `toRegexRange(1, 2)` | `1\|2` | _6μs_ |
|
|---|
| 185 | | `toRegexRange(1, 5)` | `[1-5]` | _15μs_ |
|
|---|
| 186 | | `toRegexRange(1, 10)` | `[1-9]\|10` | _22μs_ |
|
|---|
| 187 | | `toRegexRange(1, 100)` | `[1-9]\|[1-9][0-9]\|100` | _25μs_ |
|
|---|
| 188 | | `toRegexRange(1, 1000)` | `[1-9]\|[1-9][0-9]{1,2}\|1000` | _31μs_ |
|
|---|
| 189 | | `toRegexRange(1, 10000)` | `[1-9]\|[1-9][0-9]{1,3}\|10000` | _34μs_ |
|
|---|
| 190 | | `toRegexRange(1, 100000)` | `[1-9]\|[1-9][0-9]{1,4}\|100000` | _36μs_ |
|
|---|
| 191 | | `toRegexRange(1, 1000000)` | `[1-9]\|[1-9][0-9]{1,5}\|1000000` | _42μs_ |
|
|---|
| 192 | | `toRegexRange(1, 10000000)` | `[1-9]\|[1-9][0-9]{1,6}\|10000000` | _42μs_ |
|
|---|
| 193 |
|
|---|
| 194 | ## Heads up!
|
|---|
| 195 |
|
|---|
| 196 | **Order of arguments**
|
|---|
| 197 |
|
|---|
| 198 | When the `min` is larger than the `max`, values will be flipped to create a valid range:
|
|---|
| 199 |
|
|---|
| 200 | ```js
|
|---|
| 201 | toRegexRange('51', '29');
|
|---|
| 202 | ```
|
|---|
| 203 |
|
|---|
| 204 | Is effectively flipped to:
|
|---|
| 205 |
|
|---|
| 206 | ```js
|
|---|
| 207 | toRegexRange('29', '51');
|
|---|
| 208 | //=> 29|[3-4][0-9]|5[0-1]
|
|---|
| 209 | ```
|
|---|
| 210 |
|
|---|
| 211 | **Steps / increments**
|
|---|
| 212 |
|
|---|
| 213 | This library does not support steps (increments). A pr to add support would be welcome.
|
|---|
| 214 |
|
|---|
| 215 | ## History
|
|---|
| 216 |
|
|---|
| 217 | ### v2.0.0 - 2017-04-21
|
|---|
| 218 |
|
|---|
| 219 | **New features**
|
|---|
| 220 |
|
|---|
| 221 | Adds support for zero-padding!
|
|---|
| 222 |
|
|---|
| 223 | ### v1.0.0
|
|---|
| 224 |
|
|---|
| 225 | **Optimizations**
|
|---|
| 226 |
|
|---|
| 227 | 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.
|
|---|
| 228 |
|
|---|
| 229 | ## Attribution
|
|---|
| 230 |
|
|---|
| 231 | Inspired by the python library [range-regex](https://github.com/dimka665/range-regex).
|
|---|
| 232 |
|
|---|
| 233 | ## About
|
|---|
| 234 |
|
|---|
| 235 | <details>
|
|---|
| 236 | <summary><strong>Contributing</strong></summary>
|
|---|
| 237 |
|
|---|
| 238 | Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
|
|---|
| 239 |
|
|---|
| 240 | </details>
|
|---|
| 241 |
|
|---|
| 242 | <details>
|
|---|
| 243 | <summary><strong>Running Tests</strong></summary>
|
|---|
| 244 |
|
|---|
| 245 | Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
|
|---|
| 246 |
|
|---|
| 247 | ```sh
|
|---|
| 248 | $ npm install && npm test
|
|---|
| 249 | ```
|
|---|
| 250 |
|
|---|
| 251 | </details>
|
|---|
| 252 |
|
|---|
| 253 | <details>
|
|---|
| 254 | <summary><strong>Building docs</strong></summary>
|
|---|
| 255 |
|
|---|
| 256 | _(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_
|
|---|
| 257 |
|
|---|
| 258 | To generate the readme, run the following command:
|
|---|
| 259 |
|
|---|
| 260 | ```sh
|
|---|
| 261 | $ npm install -g verbose/verb#dev verb-generate-readme && verb
|
|---|
| 262 | ```
|
|---|
| 263 |
|
|---|
| 264 | </details>
|
|---|
| 265 |
|
|---|
| 266 | ### Related projects
|
|---|
| 267 |
|
|---|
| 268 | You might also be interested in these projects:
|
|---|
| 269 |
|
|---|
| 270 | * [expand-range](https://www.npmjs.com/package/expand-range): Fast, bash-like range expansion. Expand a range of numbers or letters, uppercase or lowercase. Used… [more](https://github.com/jonschlinkert/expand-range) | [homepage](https://github.com/jonschlinkert/expand-range "Fast, bash-like range expansion. Expand a range of numbers or letters, uppercase or lowercase. Used by micromatch.")
|
|---|
| 271 | * [fill-range](https://www.npmjs.com/package/fill-range): Fill in a range of numbers or letters, optionally passing an increment or `step` to… [more](https://github.com/jonschlinkert/fill-range) | [homepage](https://github.com/jonschlinkert/fill-range "Fill in a range of numbers or letters, optionally passing an increment or `step` to use, or create a regex-compatible range with `options.toRegex`")
|
|---|
| 272 | * [micromatch](https://www.npmjs.com/package/micromatch): Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch. | [homepage](https://github.com/micromatch/micromatch "Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch.")
|
|---|
| 273 | * [repeat-element](https://www.npmjs.com/package/repeat-element): Create an array by repeating the given value n times. | [homepage](https://github.com/jonschlinkert/repeat-element "Create an array by repeating the given value n times.")
|
|---|
| 274 | * [repeat-string](https://www.npmjs.com/package/repeat-string): Repeat the given string n times. Fastest implementation for repeating a string. | [homepage](https://github.com/jonschlinkert/repeat-string "Repeat the given string n times. Fastest implementation for repeating a string.")
|
|---|
| 275 |
|
|---|
| 276 | ### Contributors
|
|---|
| 277 |
|
|---|
| 278 | | **Commits** | **Contributor** |
|
|---|
| 279 | | --- | --- |
|
|---|
| 280 | | 63 | [jonschlinkert](https://github.com/jonschlinkert) |
|
|---|
| 281 | | 3 | [doowb](https://github.com/doowb) |
|
|---|
| 282 | | 2 | [realityking](https://github.com/realityking) |
|
|---|
| 283 |
|
|---|
| 284 | ### Author
|
|---|
| 285 |
|
|---|
| 286 | **Jon Schlinkert**
|
|---|
| 287 |
|
|---|
| 288 | * [GitHub Profile](https://github.com/jonschlinkert)
|
|---|
| 289 | * [Twitter Profile](https://twitter.com/jonschlinkert)
|
|---|
| 290 | * [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)
|
|---|
| 291 |
|
|---|
| 292 | Please consider supporting me on Patreon, or [start your own Patreon page](https://patreon.com/invite/bxpbvm)!
|
|---|
| 293 |
|
|---|
| 294 | <a href="https://www.patreon.com/jonschlinkert">
|
|---|
| 295 | <img src="https://c5.patreon.com/external/logo/become_a_patron_button@2x.png" height="50">
|
|---|
| 296 | </a>
|
|---|
| 297 |
|
|---|
| 298 | ### License
|
|---|
| 299 |
|
|---|
| 300 | Copyright © 2019, [Jon Schlinkert](https://github.com/jonschlinkert).
|
|---|
| 301 | Released under the [MIT License](LICENSE).
|
|---|
| 302 |
|
|---|
| 303 | ***
|
|---|
| 304 |
|
|---|
| 305 | _This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on April 07, 2019._ |
|---|
