fill-range

What is fill-range?

The fill-range npm package is used to generate an array of numbers or strings based on a given range with support for steps, negative ranges, and pattern expansion. It is often used for creating lists of numbers, expanding number and letter sequences, and generating arrays based on patterns.

What are fill-range's main functionalities?

Number Range Generation

Generates an array of numbers from 1 to 5.

[...fillRange(1, 5)]

Letter Range Generation

Generates an array of letters from 'a' to 'e'.

[...fillRange('a', 'e')]

Pattern Expansion

Expands a pattern '1..3' and applies a transformation function to each value, resulting in ['item1', 'item2', 'item3'].

[...fillRange('1..3', { transform: (val) => `item${val}` })]

Step Support

Generates an array of numbers from 1 to 10 with a step of 2, resulting in [1, 3, 5, 7, 9].

[...fillRange(1, 10, { step: 2 })]

Negative Range Support

Generates an array of numbers from -3 to 3.

[...fillRange(-3, 3)]

Other packages similar to fill-range

range-generator

This package provides similar functionality to fill-range by generating an array of numbers within a specified range. It allows for custom steps and can handle both ascending and descending ranges. Compared to fill-range, it focuses specifically on number ranges and does not support pattern expansion or letter ranges.

lodash.range

Part of the Lodash utility library, lodash.range generates an array of numbers progressing from start up to, but not including, end. It supports steps and is a lightweight alternative for number range generation. However, it does not offer the pattern expansion or letter range capabilities that fill-range does.

README

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

Table of Contents

• Install
• Usage
  • Invalid ranges
  • Custom function
• About
  • Related projects
  • Contributing
  • Building docs
  • Running tests
  • Author
  • License

(TOC generated by verb using markdown-toc)

Install

Install with npm:

$ npm install --save fill-range

Usage

Expands numbers and letters, optionally using a step as the last argument. (Numbers may be defined as JavaScript numbers or strings).

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

console.log(fill('a', 'e'));
//=> ['a', 'b', 'c', 'd', 'e']

console.log(fill(0, 25, 5));
//=> [ 0, 5, 10, 15, 20, 25 ]

console.log(fill('a', 'e', {toRegex: true}));
//=> '[a-e]'

console.log(fill('a', 'z', 3, {toRegex: true}));
//=> 'a|d|g|j|m|p|s|v|y'

console.log(fill('1', '100', {toRegex: true}));
//=> '[1-9]|[1-9][0-9]|100'

Create regex-compatible ranges (returns a string, which can be used however you need to create a regex):

console.log(fill('a', 'e', {toRegex: true}));
//=> '[a-e]'

console.log(fill('a', 'z', 3, {toRegex: true}));
//=> 'a|d|g|j|m|p|s|v|y'

console.log(fill('1', '100', {toRegex: true}));
//=> '[1-9]|[1-9][0-9]|100'

Params

fill(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}:
  • toRegex: 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
  • strict: undefined by default, set to true to throw errors on invalid ranges.
• fn: {Function} optionally pass a function to modify each character. This can also be defined as options.transform

Examples

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

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

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

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

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

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

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

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

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

Invalid ranges

When an invalid range is passed, null is returned.

fill('1.1', '2');   // decimals not supported in ranges
//=> null

fill('a', '2');     // unmatched values
//=> null

fill(1, 10, 'foo'); // invalid step
//=> null

If you want errors to be throw, set options.strict to true.

Custom function

Optionally pass a custom function as last argument or on options.transform.

// increase padding by two
var arr = fill('01', '05', function(val, a, b, step, idx, arr, options) {
  return repeat('0', (options.maxLength + 2) - val.length) + val;
});

console.log(arr);
//=> ['0001', '0002', '0003', '0004', '0005']

About

Related projects

• braces: Fastest brace expansion for node.js, with the most complete support for the Bash 4.3 braces… more | homepage
• expand-range: Fast, bash-like range expansion. Expand a range of numbers or letters, uppercase or lowercase. See… more | homepage
• micromatch: Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch. | homepage
• to-regex-range: Returns a regex-compatible range from two numbers, min and max, with 855,412 generated unit tests… more | homepage

Contributing

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

Building docs

(This document was generated by verb-generate-readme (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in .verb.md.)

To generate the readme and API documentation with verb:

$ npm install -g verb verb-generate-readme && verb

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2016, Jon Schlinkert. Released under the MIT license.

---

This file was generated by verb-generate-readme, v0.1.30, on September 15, 2016.