fill-range

Fill in a range of numbers or letters, optionally passing an increment or multiplier to use.

Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your :heart: and support.

Install
Usage
About

(TOC generated by verb using markdown-toc)

Install

Install with npm:

$ npm install --save fill-range

Usage

var range = require('fill-range');

range('a', 'e');
//=> ['a', 'b', 'c', 'd', 'e']

Params

range(start, stop, step, options, fn);

start: {String|Number} the number or letter to start with
end: {String|Number} the number or letter to end with
step: {String|Number} optionally pass the step to use. works for letters or numbers.
options: {Object}:
- makeRe: return a regex-compatible string (still returned as an array for consistency)
- step: pass the step on the options as an alternative to passing it as an argument
- silent: true by default, set to false to throw errors for invalid ranges.
fn: {Function} optionally pass a function to modify each character

Examples

range(1, 3)
//=> ['1', '2', '3']

range('1', '3')
//=> ['1', '2', '3']

range('0', '-5')
//=> [ '0', '-1', '-2', '-3', '-4', '-5' ]

range(-9, 9, 3)
//=> [ '-9', '-6', '-3', '0', '3', '6', '9' ])

range('-1', '-10', '-2')
//=> [ '-1', '-3', '-5', '-7', '-9' ]

range('1', '10', '2')
//=> [ '1', '3', '5', '7', '9' ]

range('a', 'e')
//=> ['a', 'b', 'c', 'd', 'e']

range('a', 'e', 2)
//=> ['a', 'c', 'e']

range('A', 'E', 2)
//=> ['A', 'C', 'E']

Invalid ranges

When an invalid range is passed, null is returned.

range('1.1', '2');
//=> null

range('a', '2');
//=> null

range(1, 10, 'foo');
//=> null

If you want errors to be throw, pass silent: false on the options:

Custom function

Optionally pass a custom function as the third or fourth argument:

range('a', 'e', function (val, isNumber, pad, i) {
  if (!isNumber) {
    return String.fromCharCode(val) + i;
  }
  return val;
});
//=> ['a0', 'b1', 'c2', 'd3', 'e4']

Special characters

A special character may be passed as the third arg instead of a step increment. These characters can be pretty useful for brace expansion, creating file paths, test fixtures and similar use case.

range('a', 'z', SPECIAL_CHARACTER_HERE);

Supported characters

+: repeat the given string n times
|: create a regex-ready string, instead of an array
>: join values to single array element
?: randomize the given pattern using [randomatic]

plus

Character: (+)

Repeat the first argument the number of times passed on the second argument.

Examples:

range('a', 3, '+');
//=> ['a', 'a', 'a']

range('abc', 2, '+');
//=> ['abc', 'abc']

pipe and tilde

Characters: (| and ~)

Creates a regex-capable string (either a logical or or a character class) from the expanded arguments.

Examples:

range('a', 'c', '|');
//=> ['(a|b|c)'

range('a', 'c', '~');
//=> ['[a-c]'

range('a', 'z', '|5');
//=> ['(a|f|k|p|u|z)'

Automatic separator correction

To avoid this error:

Range out of order in character class

Fill-range detects invalid sequences and uses the correct syntax. For example:

invalid (regex)

If you pass these:

range('a', 'z', '~5');
// which would result in this
//=> ['[a-f-k-p-u-z]']

range('10', '20', '~');
// which would result in this
//=> ['[10-20]']

valid (regex)

fill-range corrects them to this:

range('a', 'z', '~5');
//=> ['(a|f|k|p|u|z)'

range('10', '20', '~');
//=> ['(10-20)'

angle bracket

Character: (>)

Joins all values in the returned array to a single value.

Examples:

range('a', 'e', '>');
//=> ['abcde']

range('5', '8', '>');
//=> ['5678']

range('2', '20', '2>');
//=> ['2468101214161820']

question mark

Character: (?)

Uses [randomatic] to generate randomized alpha, numeric, or alpha-numeric patterns based on the provided arguments.

Examples:

(actual results would obviously be randomized)

Generate a 5-character, uppercase, alphabetical string:

range('A', 5, '?');
//=> ['NSHAK']

Generate a 5-digit random number:

range('0', 5, '?');
//=> ['36583']

Generate a 10-character alpha-numeric string:

range('A0', 10, '?');
//=> ['5YJD60VQNN']

See the [randomatic] repo for all available options and or to create issues or feature requests related to randomization.

About

<summary>Contributing</summary>

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

<summary>Running Tests</summary>

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:

$ npm install && npm test

<summary>Building docs</summary>

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

$ npm install -g verbose/verb#dev verb-generate-readme && verb

Related projects

You might also be interested in these projects:

braces: Bash-like brace expansion, implemented in JavaScript. Safer than other brace expansion libs, with complete support… more | homepage
expand-range: Fast, bash-like range expansion. Expand a range of numbers or letters, uppercase or lowercase. Used… more | homepage
is-glob: Returns true if the given string looks like a glob pattern or an extglob pattern… more | homepage
micromatch: Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch. | homepage

Contributors

Commits	Contributor
111	jonschlinkert
2	paulmillr
1	edorivai
1	realityking
1	wtgtybhertgeghgtwtg

Author

Jon Schlinkert

License

This file was generated by verb-generate-readme, v0.6.0, on May 08, 2018.

Current Tags

7.1.1 ... latest (6 months ago)
2.2.4 ... patch (7 years ago)

fill-range

Install

Usage

Invalid ranges

Custom function

Special characters

plus

pipe and tilde

angle bracket

question mark

About

Related projects

Contributors

Author

License

Current Tags

33 Versions