1 | # fill-range [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=W8YFZ425KND68) [![NPM version](https://img.shields.io/npm/v/fill-range.svg?style=flat)](https://www.npmjs.com/package/fill-range) [![NPM monthly downloads](https://img.shields.io/npm/dm/fill-range.svg?style=flat)](https://npmjs.org/package/fill-range) [![NPM total downloads](https://img.shields.io/npm/dt/fill-range.svg?style=flat)](https://npmjs.org/package/fill-range) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/fill-range.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/fill-range)
|
2 |
|
3 | > 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`
|
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 fill-range
|
13 | ```
|
14 |
|
15 | ## Usage
|
16 |
|
17 | Expands numbers and letters, optionally using a `step` as the last argument. _(Numbers may be defined as JavaScript numbers or strings)_.
|
18 |
|
19 | ```js
|
20 | const fill = require('fill-range');
|
21 | // fill(from, to[, step, options]);
|
22 |
|
23 | console.log(fill('1', '10')); //=> ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10']
|
24 | console.log(fill('1', '10', { toRegex: true })); //=> [1-9]|10
|
25 | ```
|
26 |
|
27 | **Params**
|
28 |
|
29 | * `from`: **{String|Number}** the number or letter to start with
|
30 | * `to`: **{String|Number}** the number or letter to end with
|
31 | * `step`: **{String|Number|Object|Function}** Optionally pass a [step](#optionsstep) to use.
|
32 | * `options`: **{Object|Function}**: See all available [options](#options)
|
33 |
|
34 | ## Examples
|
35 |
|
36 | By default, an array of values is returned.
|
37 |
|
38 | **Alphabetical ranges**
|
39 |
|
40 | ```js
|
41 | console.log(fill('a', 'e')); //=> ['a', 'b', 'c', 'd', 'e']
|
42 | console.log(fill('A', 'E')); //=> [ 'A', 'B', 'C', 'D', 'E' ]
|
43 | ```
|
44 |
|
45 | **Numerical ranges**
|
46 |
|
47 | Numbers can be defined as actual numbers or strings.
|
48 |
|
49 | ```js
|
50 | console.log(fill(1, 5)); //=> [ 1, 2, 3, 4, 5 ]
|
51 | console.log(fill('1', '5')); //=> [ 1, 2, 3, 4, 5 ]
|
52 | ```
|
53 |
|
54 | **Negative ranges**
|
55 |
|
56 | Numbers can be defined as actual numbers or strings.
|
57 |
|
58 | ```js
|
59 | console.log(fill('-5', '-1')); //=> [ '-5', '-4', '-3', '-2', '-1' ]
|
60 | console.log(fill('-5', '5')); //=> [ '-5', '-4', '-3', '-2', '-1', '0', '1', '2', '3', '4', '5' ]
|
61 | ```
|
62 |
|
63 | **Steps (increments)**
|
64 |
|
65 | ```js
|
66 | // numerical ranges with increments
|
67 | console.log(fill('0', '25', 4)); //=> [ '0', '4', '8', '12', '16', '20', '24' ]
|
68 | console.log(fill('0', '25', 5)); //=> [ '0', '5', '10', '15', '20', '25' ]
|
69 | console.log(fill('0', '25', 6)); //=> [ '0', '6', '12', '18', '24' ]
|
70 |
|
71 | // alphabetical ranges with increments
|
72 | console.log(fill('a', 'z', 4)); //=> [ 'a', 'e', 'i', 'm', 'q', 'u', 'y' ]
|
73 | console.log(fill('a', 'z', 5)); //=> [ 'a', 'f', 'k', 'p', 'u', 'z' ]
|
74 | console.log(fill('a', 'z', 6)); //=> [ 'a', 'g', 'm', 's', 'y' ]
|
75 | ```
|
76 |
|
77 | ## Options
|
78 |
|
79 | ### options.step
|
80 |
|
81 | **Type**: `number` (formatted as a string or number)
|
82 |
|
83 | **Default**: `undefined`
|
84 |
|
85 | **Description**: The increment to use for the range. Can be used with letters or numbers.
|
86 |
|
87 | **Example(s)**
|
88 |
|
89 | ```js
|
90 | // numbers
|
91 | console.log(fill('1', '10', 2)); //=> [ '1', '3', '5', '7', '9' ]
|
92 | console.log(fill('1', '10', 3)); //=> [ '1', '4', '7', '10' ]
|
93 | console.log(fill('1', '10', 4)); //=> [ '1', '5', '9' ]
|
94 |
|
95 | // letters
|
96 | console.log(fill('a', 'z', 5)); //=> [ 'a', 'f', 'k', 'p', 'u', 'z' ]
|
97 | console.log(fill('a', 'z', 7)); //=> [ 'a', 'h', 'o', 'v' ]
|
98 | console.log(fill('a', 'z', 9)); //=> [ 'a', 'j', 's' ]
|
99 | ```
|
100 |
|
101 | ### options.strictRanges
|
102 |
|
103 | **Type**: `boolean`
|
104 |
|
105 | **Default**: `false`
|
106 |
|
107 | **Description**: By default, `null` is returned when an invalid range is passed. Enable this option to throw a `RangeError` on invalid ranges.
|
108 |
|
109 | **Example(s)**
|
110 |
|
111 | The following are all invalid:
|
112 |
|
113 | ```js
|
114 | fill('1.1', '2'); // decimals not supported in ranges
|
115 | fill('a', '2'); // incompatible range values
|
116 | fill(1, 10, 'foo'); // invalid "step" argument
|
117 | ```
|
118 |
|
119 | ### options.stringify
|
120 |
|
121 | **Type**: `boolean`
|
122 |
|
123 | **Default**: `undefined`
|
124 |
|
125 | **Description**: Cast all returned values to strings. By default, integers are returned as numbers.
|
126 |
|
127 | **Example(s)**
|
128 |
|
129 | ```js
|
130 | console.log(fill(1, 5)); //=> [ 1, 2, 3, 4, 5 ]
|
131 | console.log(fill(1, 5, { stringify: true })); //=> [ '1', '2', '3', '4', '5' ]
|
132 | ```
|
133 |
|
134 | ### options.toRegex
|
135 |
|
136 | **Type**: `boolean`
|
137 |
|
138 | **Default**: `undefined`
|
139 |
|
140 | **Description**: Create a regex-compatible source string, instead of expanding values to an array.
|
141 |
|
142 | **Example(s)**
|
143 |
|
144 | ```js
|
145 | // alphabetical range
|
146 | console.log(fill('a', 'e', { toRegex: true })); //=> '[a-e]'
|
147 | // alphabetical with step
|
148 | console.log(fill('a', 'z', 3, { toRegex: true })); //=> 'a|d|g|j|m|p|s|v|y'
|
149 | // numerical range
|
150 | console.log(fill('1', '100', { toRegex: true })); //=> '[1-9]|[1-9][0-9]|100'
|
151 | // numerical range with zero padding
|
152 | console.log(fill('000001', '100000', { toRegex: true }));
|
153 | //=> '0{5}[1-9]|0{4}[1-9][0-9]|0{3}[1-9][0-9]{2}|0{2}[1-9][0-9]{3}|0[1-9][0-9]{4}|100000'
|
154 | ```
|
155 |
|
156 | ### options.transform
|
157 |
|
158 | **Type**: `function`
|
159 |
|
160 | **Default**: `undefined`
|
161 |
|
162 | **Description**: Customize each value in the returned array (or [string](#optionstoRegex)). _(you can also pass this function as the last argument to `fill()`)_.
|
163 |
|
164 | **Example(s)**
|
165 |
|
166 | ```js
|
167 | // add zero padding
|
168 | console.log(fill(1, 5, value => String(value).padStart(4, '0')));
|
169 | //=> ['0001', '0002', '0003', '0004', '0005']
|
170 | ```
|
171 |
|
172 | ## About
|
173 |
|
174 | <details>
|
175 | <summary><strong>Contributing</strong></summary>
|
176 |
|
177 | Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
|
178 |
|
179 | </details>
|
180 |
|
181 | <details>
|
182 | <summary><strong>Running Tests</strong></summary>
|
183 |
|
184 | 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:
|
185 |
|
186 | ```sh
|
187 | $ npm install && npm test
|
188 | ```
|
189 |
|
190 | </details>
|
191 |
|
192 | <details>
|
193 | <summary><strong>Building docs</strong></summary>
|
194 |
|
195 | _(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.)_
|
196 |
|
197 | To generate the readme, run the following command:
|
198 |
|
199 | ```sh
|
200 | $ npm install -g verbose/verb#dev verb-generate-readme && verb
|
201 | ```
|
202 |
|
203 | </details>
|
204 |
|
205 | ### Contributors
|
206 |
|
207 | | **Commits** | **Contributor** |
|
208 | | --- | --- |
|
209 | | 116 | [jonschlinkert](https://github.com/jonschlinkert) |
|
210 | | 4 | [paulmillr](https://github.com/paulmillr) |
|
211 | | 2 | [realityking](https://github.com/realityking) |
|
212 | | 2 | [bluelovers](https://github.com/bluelovers) |
|
213 | | 1 | [edorivai](https://github.com/edorivai) |
|
214 | | 1 | [wtgtybhertgeghgtwtg](https://github.com/wtgtybhertgeghgtwtg) |
|
215 |
|
216 | ### Author
|
217 |
|
218 | **Jon Schlinkert**
|
219 |
|
220 | * [GitHub Profile](https://github.com/jonschlinkert)
|
221 | * [Twitter Profile](https://twitter.com/jonschlinkert)
|
222 | * [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)
|
223 |
|
224 | Please consider supporting me on Patreon, or [start your own Patreon page](https://patreon.com/invite/bxpbvm)!
|
225 |
|
226 | <a href="https://www.patreon.com/jonschlinkert">
|
227 | <img src="https://c5.patreon.com/external/logo/become_a_patron_button@2x.png" height="50">
|
228 | </a>
|
229 |
|
230 | ### License
|
231 |
|
232 | Copyright © 2019, [Jon Schlinkert](https://github.com/jonschlinkert).
|
233 | Released under the [MIT License](LICENSE).
|
234 |
|
235 | ***
|
236 |
|
237 | _This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on April 08, 2019._ |
\ | No newline at end of file |