fill-range

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

Install with npm

npm i fill-range --save

• Usage
  • Invalid ranges
  • Custom function
  • Special characters
  • plus
  • pipe and tilde
  • angle bracket
  • question mark
• Other useful libs
• Running tests
• Contributing
• Author
• License

(Table of contents generated by [verb])

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.

Other useful libs

• micromatch: Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch. Just use micromatch.isMatch() instead of minimatch(), or use micromatch() instead of multimatch().
• expand-range: Fast, bash-like range expansion. Expand a range of numbers or letters, uppercase or lowercase. See the benchmarks. Used by micromatch.
• braces: Fastest brace expansion for node.js, with the most complete support for the Bash 4.3 braces specification.
• is-glob: Returns true if the given string looks like a glob pattern.

Running tests

Install dev dependencies:

npm i -d && npm test

Contributing

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

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright (c) 2014-2015 Jon Schlinkert
Released under the MIT license

---

This file was generated by verb-cli on April 07, 2015.