.config/coc/extensions/node_modules/coc-prettier/node_modules/to-regex-range/README.md

   1 # to-regex-range [![NPM version](https://img.shields.io/npm/v/to-regex-range.svg?style=flat)](https://www.npmjs.com/package/to-regex-range) [![NPM monthly downloads](https://img.shields.io/npm/dm/to-regex-range.svg?style=flat)](https://npmjs.org/package/to-regex-range)  [![NPM total downloads](https://img.shields.io/npm/dt/to-regex-range.svg?style=flat)](https://npmjs.org/package/to-regex-range) [![Linux Build Status](https://img.shields.io/travis/micromatch/to-regex-range.svg?style=flat&label=Travis)](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 ## Install
   6
   7 Install with [npm](https://www.npmjs.com/):
   8
   9 ```sh
  10 $ npm install --save to-regex-range
  11 ```
  12
  13 Install with [yarn](https://yarnpkg.com):
  14
  15 ```sh
  16 $ yarn add to-regex-range
  17 ```
  18
  19 <details>
  20 <summary><strong>What does this do?</strong></summary>
  21
  22 <br>
  23
  24 This libary generates the `source` string to be passed to `new RegExp()` for matching a range of numbers.
  25
  26 **Example**
  27
  28 ```js
  29 var toRegexRange = require('to-regex-range');
  30 var regex = new RegExp(toRegexRange('15', '95'));
  31 ```
  32
  33 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).
  34
  35 <br>
  36
  37 </details>
  38
  39 <details>
  40 <summary><strong>Why use this library?</strong></summary>
  41
  42 <br>
  43
  44 ### Convenience
  45
  46 Creating regular expressions for matching numbers gets deceptively complicated pretty fast.
  47
  48 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:
  49
  50 * regex for matching `1` => `/1/` (easy enough)
  51 * regex for matching `1` through `5` => `/[1-5]/` (not bad...)
  52 * regex for matching `1` or `5` => `/(1|5)/` (still easy...)
  53 * regex for matching `1` through `50` => `/([1-9]|[1-4][0-9]|50)/` (uh-oh...)
  54 * regex for matching `1` through `55` => `/([1-9]|[1-4][0-9]|5[0-5])/` (no prob, I can do this...)
  55 * 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...)
  56 * 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!)
  57
  58 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.
  59
  60 **Learn more**
  61
  62 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.
  63
  64 ### Heavily tested
  65
  66 As of April 27, 2017, 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.
  67
  68 Tests run in ~870ms on my MacBook Pro, 2.5 GHz Intel Core i7.
  69
  70 ### Highly optimized
  71
  72 Generated regular expressions are highly optimized:
  73
  74 * duplicate sequences and character classes are reduced using quantifiers
  75 * smart enough to use `?` conditionals when number(s) or range(s) can be positive or negative
  76 * uses fragment caching to avoid processing the same exact string more than once
  77
  78 <br>
  79
  80 </details>
  81
  82 ## Usage
  83
  84 Add this library to your javascript application with the following line of code
  85
  86 ```js
  87 var toRegexRange = require('to-regex-range');
  88 ```
  89
  90 The main export is a function that takes two integers: the `min` value and `max` value (formatted as strings or numbers).
  91
  92 ```js
  93 var source = toRegexRange('15', '95');
  94 //=> 1[5-9]|[2-8][0-9]|9[0-5]
  95
  96 var re = new RegExp('^' + source + '$');
  97 console.log(re.test('14')); //=> false
  98 console.log(re.test('50')); //=> true
  99 console.log(re.test('94')); //=> true
 100 console.log(re.test('96')); //=> false
 101 ```
 102
 103 ## Options
 104
 105 ### options.capture
 106
 107 **Type**: `boolean`
 108
 109 **Deafault**: `undefined`
 110
 111 Wrap the returned value in parentheses when there is more than one regex condition. Useful when you're dynamically generating ranges.
 112
 113 ```js
 114 console.log(toRegexRange('-10', '10'));
 115 //=> -[1-9]|-?10|[0-9]
 116
 117 console.log(toRegexRange('-10', '10', {capture: true}));
 118 //=> (-[1-9]|-?10|[0-9])
 119 ```
 120
 121 ### options.shorthand
 122
 123 **Type**: `boolean`
 124
 125 **Deafault**: `undefined`
 126
 127 Use the regex shorthand for `[0-9]`:
 128
 129 ```js
 130 console.log(toRegexRange('0', '999999'));
 131 //=> [0-9]|[1-9][0-9]{1,5}
 132
 133 console.log(toRegexRange('0', '999999', {shorthand: true}));
 134 //=> \d|[1-9]\d{1,5}
 135 ```
 136
 137 ### options.relaxZeros
 138
 139 **Type**: `boolean`
 140
 141 **Default**: `true`
 142
 143 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*`.
 144
 145 ```js
 146 console.log(toRegexRange('-001', '100'));
 147 //=> -0*1|0{2}[0-9]|0[1-9][0-9]|100
 148
 149 console.log(toRegexRange('-001', '100', {relaxZeros: false}));
 150 //=> -0{2}1|0{2}[0-9]|0[1-9][0-9]|100
 151 ```
 152
 153 <details>
 154 <summary><strong>Why are zeros relaxed for negative zero-padded ranges by default?</strong></summary>
 155
 156 Consider the following.
 157
 158 ```js
 159 var regex = toRegexRange('-001', '100');
 160 ```
 161
 162 _Note that `-001` and `100` are both three digits long_.
 163
 164 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).
 165
 166 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`.
 167
 168 Thus, we relax zeros by default to provide a more predictable experience for users.
 169
 170 </details>
 171
 172 ## Examples
 173
 174 | **Range** | **Result** | **Compile time** |
 175 | --- | --- | --- |
 176 | `toRegexRange('5, 5')` | `5` | _33μs_ |
 177 | `toRegexRange('5, 6')` | `5\|6` | _53μs_ |
 178 | `toRegexRange('29, 51')` | `29\|[34][0-9]\|5[01]` | _699μs_ |
 179 | `toRegexRange('31, 877')` | `3[1-9]\|[4-9][0-9]\|[1-7][0-9]{2}\|8[0-6][0-9]\|87[0-7]` | _711μs_ |
 180 | `toRegexRange('111, 555')` | `11[1-9]\|1[2-9][0-9]\|[2-4][0-9]{2}\|5[0-4][0-9]\|55[0-5]` | _62μs_ |
 181 | `toRegexRange('-10, 10')` | `-[1-9]\|-?10\|[0-9]` | _74μs_ |
 182 | `toRegexRange('-100, -10')` | `-1[0-9]\|-[2-9][0-9]\|-100` | _49μs_ |
 183 | `toRegexRange('-100, 100')` | `-[1-9]\|-?[1-9][0-9]\|-?100\|[0-9]` | _45μs_ |
 184 | `toRegexRange('001, 100')` | `0{2}[1-9]\|0[1-9][0-9]\|100` | _158μs_ |
 185 | `toRegexRange('0010, 1000')` | `0{2}1[0-9]\|0{2}[2-9][0-9]\|0[1-9][0-9]{2}\|1000` | _61μs_ |
 186 | `toRegexRange('1, 2')` | `1\|2` | _10μs_ |
 187 | `toRegexRange('1, 5')` | `[1-5]` | _24μs_ |
 188 | `toRegexRange('1, 10')` | `[1-9]\|10` | _23μs_ |
 189 | `toRegexRange('1, 100')` | `[1-9]\|[1-9][0-9]\|100` | _30μs_ |
 190 | `toRegexRange('1, 1000')` | `[1-9]\|[1-9][0-9]{1,2}\|1000` | _52μs_ |
 191 | `toRegexRange('1, 10000')` | `[1-9]\|[1-9][0-9]{1,3}\|10000` | _47μs_ |
 192 | `toRegexRange('1, 100000')` | `[1-9]\|[1-9][0-9]{1,4}\|100000` | _44μs_ |
 193 | `toRegexRange('1, 1000000')` | `[1-9]\|[1-9][0-9]{1,5}\|1000000` | _49μs_ |
 194 | `toRegexRange('1, 10000000')` | `[1-9]\|[1-9][0-9]{1,6}\|10000000` | _63μs_ |
 195
 196 ## Heads up!
 197
 198 **Order of arguments**
 199
 200 When the `min` is larger than the `max`, values will be flipped to create a valid range:
 201
 202 ```js
 203 toRegexRange('51', '29');
 204 ```
 205
 206 Is effectively flipped to:
 207
 208 ```js
 209 toRegexRange('29', '51');
 210 //=> 29|[3-4][0-9]|5[0-1]
 211 ```
 212
 213 **Steps / increments**
 214
 215 This library does not support steps (increments). A pr to add support would be welcome.
 216
 217 ## History
 218
 219 ### v2.0.0 - 2017-04-21
 220
 221 **New features**
 222
 223 Adds support for zero-padding!
 224
 225 ### v1.0.0
 226
 227 **Optimizations**
 228
 229 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.
 230
 231 ## Attribution
 232
 233 Inspired by the python library [range-regex](https://github.com/dimka665/range-regex).
 234
 235 ## About
 236
 237 ### Related projects
 238
 239 * [expand-range](https://www.npmjs.com/package/expand-range): Fast, bash-like range expansion. Expand a range of numbers or letters, uppercase or lowercase. See… [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. See the benchmarks. Used by micromatch.")
 240 * [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`")
 241 * [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/jonschlinkert/micromatch "Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch.")
 242 * [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.")
 243 * [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.")
 244
 245 ### Contributing
 246
 247 Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
 248
 249 ### Building docs
 250
 251 _(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.)_
 252
 253 To generate the readme, run the following command:
 254
 255 ```sh
 256 $ npm install -g verbose/verb#dev verb-generate-readme && verb
 257 ```
 258
 259 ### Running tests
 260
 261 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:
 262
 263 ```sh
 264 $ npm install && npm test
 265 ```
 266
 267 ### Author
 268
 269 **Jon Schlinkert**
 270
 271 * [github/jonschlinkert](https://github.com/jonschlinkert)
 272 * [twitter/jonschlinkert](https://twitter.com/jonschlinkert)
 273
 274 ### License
 275
 276 Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert).
 277 Released under the [MIT License](LICENSE).
 278
 279 ***
 280
 281 _This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on April 27, 2017._