fill-range NPM version Build Status

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

Install with npm

  1. npm i fill-range --save

(Table of contents generated by [verb])

Usage

  1. var range = require('fill-range');
  3. range('a', 'e');
  4. //=> ['a', 'b', 'c', 'd', 'e']

Params

  1. 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

  1. range(1, 3)
  2. //=> ['1', '2', '3']
  4. range('1', '3')
  5. //=> ['1', '2', '3']
  7. range('0', '-5')
  8. //=> [ '0', '-1', '-2', '-3', '-4', '-5' ]
  10. range(-9, 9, 3)
  11. //=> [ '-9', '-6', '-3', '0', '3', '6', '9' ])
  13. range('-1', '-10', '-2')
  14. //=> [ '-1', '-3', '-5', '-7', '-9' ]
  16. range('1', '10', '2')
  17. //=> [ '1', '3', '5', '7', '9' ]
  19. range('a', 'e')
  20. //=> ['a', 'b', 'c', 'd', 'e']
  22. range('a', 'e', 2)
  23. //=> ['a', 'c', 'e']
  25. range('A', 'E', 2)
  26. //=> ['A', 'C', 'E']

Invalid ranges

When an invalid range is passed, null is returned. 

  1. range('1.1', '2');
  2. //=> null
  4. range('a', '2');
  5. //=> null
  7. range(1, 10, 'foo');
  8. //=> 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:

  1. range('a', 'e', function (val, isNumber, pad, i) {
  2.   if (!isNumber) {
  3.     return String.fromCharCode(val) + i;
  4.   }
  5.   return val;
  6. });
  7. //=> ['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.

  1. 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:

  1. range('a', 3, '+');
  2. //=> ['a', 'a', 'a']
  4. range('abc', 2, '+');
  5. //=> ['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:

  1. range('a', 'c', '|');
  2. //=> ['(a|b|c)'
  4. range('a', 'c', '~');
  5. //=> ['[a-c]'
  7. range('a', 'z', '|5');
  8. //=> ['(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:

  1. range('a', 'z', '~5');
  2. // which would result in this
  3. //=> ['[a-f-k-p-u-z]']
  5. range('10', '20', '~');
  6. // which would result in this
  7. //=> ['[10-20]']

valid (regex)

fill-range corrects them to this:

  1. range('a', 'z', '~5');
  2. //=> ['(a|f|k|p|u|z)'
  4. range('10', '20', '~');
  5. //=> ['(10-20)'

angle bracket

Character: (>)

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

Examples:

  1. range('a', 'e', '>');
  2. //=> ['abcde']
  4. range('5', '8', '>');
  5. //=> ['5678']
  7. range('2', '20', '2>');
  8. //=> ['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:

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

Generate a 5-digit random number:

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

Generate a 10-character alpha-numeric string:

  1. range('A0', 10, '?');
  2. //=> ['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:

  1. 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

License

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

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