range.js

range.js – JavaScript's missing range function

Features:

• The browser and node are both supported.
• Simple: Always returns an array.
• Numeric and decimal ranges.
• Letter ranges.
• Plain syntax range('a', 'z') and Ruby-style range('a..z').
• Reversed ranges.
• Ranges with steps.

Usage

Node

$ npm install range.js

var range = require('range.js');

Browser

Grab lib/strukt.js and include it in your HTML document. If an AMD or CommonJS loader is present it will be used, otherwise range is assigned to window.range.

---

In case you are using component (you should, it's awesome!):

$ component install js-coder/range.js

var range = require('range.js');

---

Syntax

There are two different syntaxes, the plain one and the Ruby style one.

// Plain syntax:
range(from, to, step);

// Ruby style syntax:
range('from..to', step);

For convience, the rest of this documentation will use the plain syntax.

Numeric ranges

range(1, 5); // [1, 2, 3, 4, 5]
range(-2, 2); // [-2, -1, 0, 1, 2]
range(0, 0.5, 0.1); // Approximately, JS floats are not exact: [0.1, 0.2, 0.3, 0.4, 0.5]

Letter ranges

range('a', 'd'); // ['a', 'b', 'c', 'd']
range('A', 'D'); // ['A', 'B', 'C', 'D']
range('y', 'B'); // ['y', 'z', 'A', 'B']
range('Y', 'b'); // ['Y', 'Z', 'a', 'b']

Ranges with steps

range(0, 9, 3); // [0, 3, 6, 9]
range('a', 'e', 2); // ['a', 'c', 'e']

Reversed ranges

range(5, 0); // [5, 4, 3, 2, 1, 0]
range('e', 'a'); ['e', 'd', 'c', 'b', 'a']

Ruby style syntax

range('1..5'); // range(1, 5)
range('a..z'); // range('a', 'z')

// Steps:
range('1..5', 2); // range(1, 5, 2)

// Exclusive ranges:
range('1...5'); // [1, 2, 3, 4]

range.equals(rangeA, rangeB)

Compares ranges by value.

var a = range(1, 5);
var b = range(1, 5);
var c = range('a..z');

range.equals(a, b); // true
range.equals(a, c); // false

range.overlaps(rangeA, rangeB)

range.overlaps(range('a..z'), range('e..f')); // true
range.overlaps(range(1, 10), range(1, 9)); // true
range.overlaps(range(1, 5), range(6, 10)); // false

---

Test suite

The test suite uses the mocha testing framework and the chai assertion library.

Running the tests from the command line:

$ git clone git://github.com/js-coder/range.js.git && cd range.js
$ npm install
$ grunt test

To run the tests in your browser, Clone this repository, and visit ./spec/index.html.

---

Todo

• Add benchmarks
• Improve performance by predefining the length
• Add charCode ranges
• Add range.equals
• Add range.overlaps