stRange.js

stRange.js is a range object for JavaScript. Use it to have a single value type with two endpoints and their boundaries. Also implements an interval tree for quick lookups. Stringifies itself in the style of [begin,end) and allows you to parse a string back. Also useful with PostgreSQL.

Installing

stRange.js follows semantic versioning, so feel free to depend on its major version with something like >= 1.0.0 < 2 (a.k.a ^1.0.0).

Installing on Node.js

npm install strange

Installing for the browser

stRange.js doesn't yet have a build ready for the browser, but you might be able to use Browserify to have it run there till then.

Using

Create a Range object by passing in a beginning and end:

var Range = require("strange")
var range = new Range(1, 5)

Check if something is a range and use it:

var Range = require("strange")
if (range instanceof Range) console.log(range.begin, range.end)

Bounds

You can set a range's bounds by passing the bounds as a two-character string of parentheses as the 3rd argument:

new Range(1, 3, "[)")

Bounds signify whether the range includes or excludes that particular endpoint. The range above therefore includes numbers >= 1 < 3.

Parsing

To parse a range stringified by Range.prototype.toString, pass it to Range.parse:

Range.parse("[a,z)") // => new Range("a", "z", "[)")

To have stRange.js also parse the endpoints, pass a function to Range.parse:

Range.parse("[42,69]", Number) // => new Range(42, 69)

Using with PostgreSQL

The string format used by stRange.js matches PostgreSQL's range type format. You can therefore use stRange.js to parse and stringify ranges for your database.

API

For extended documentation on all functions, please see the stRange.js API Documentation.

Range

• begin
• bounds
• end
• .prototype.compareBegin(begin)
• .prototype.compareEnd(end)
• .prototype.contains(value)
• .prototype.intersects(other)
• .prototype.isBounded()
• .prototype.isEmpty()
• .prototype.isFinite()
• .prototype.isInfinite()
• .prototype.isUnbounded()
• .prototype.toJSON()
• .prototype.toString()
• .prototype.valueOf()
• .compareBeginToBegin(a, b)
• .compareBeginToEnd(a, b)
• .compareEndToEnd(a, b)
• .parse(range, [parseEndpoint])
• .union(union, a, b)

RangeTree

• .prototype.search(valueOrRange)
• .from(ranges)

License

stRange.js is released under a Lesser GNU Affero General Public License, which in summary means:

• You can use this program for no cost.
• You can use this program for both personal and commercial reasons.
• You do not have to share your own program's code which uses this program.
• You have to share modifications (e.g bug-fixes) you've made to this program.

For more convoluted language, see the LICENSE file.

About

Andri Möll typed this and the code.
Monday Calendar supported the engineering work.

If you find stRange.js needs improving, please don't hesitate to type to me now at andri@dot.ee or create an issue online.

1.7.2 (Feb 22, 2017)

• Fixes RangeTree given a range that ended farther than ranges beginning after it.
  This occurring was dependent on how the binary tree laid itself out.
  Thanks, Ross Allen, for reporting this!

1.7.1 (Jan 15, 2017)

• Fixes searching RangeTree with an empty range in it. Empty ranges are now ignored.

1.7.0 (Aug 5, 2016)

• Throws RangeError if the given bounds are not valid (not of the following: [], (), [), (]).
  Thanks, Nikhil Benesch, for the hint!

1.6.0 (Aug 5, 2016)

• Adds Range.compareBeginToEnd
• Adds support for calling RangeTree.prototype.search with range to find ranges that intersect.

1.5.0 (Jul 12, 2016)

• Adds Range.prototype.valueOf to get a more primitive representation of a range.
  Useful with Egal.js or other libraries that compare value objects by their valueOf output.

1.4.0 (Jul 8, 2016)

• Makes Range.prototype a valid empty Range.
  Allows you to use it as an empty range:

  var EMPTY_RANGE = Range.prototype
  EMPTY_RANGE.isEmpty() // => true
  EMPTY_RANGE.contains(new Range(0, 1)) // => false

1.3.0 (Jul 17, 2015)

• Adds Range.compareBeginToBegin.
• Adds Range.compareEndToEnd.
• Adds Range.union.
• Adds Range.prototype.compareBegin.

• Adds Range.prototype.compareEnd.

• Sets numeric unbounded endpoints to -Infinity/Infinity if you pass Number to Range.parse as the parse function.

  Range.parse("[15,]", Number) // => new Range(15, Infinity)
  Range.parse("(,3.14]", Number) // => new Range(-Infinity, 3.14, "(]")

• Fixes Range.prototype.intersects to handle exclusive unbounded ranges properly.

• Adds RangeTree for creating an interval tree (augmented binary search tree) for searching ranges that intersect with a given value.

1.2.0 (Jul 4, 2015)

• Adds Range.prototype.isBounded.
• Adds Range.prototype.isUnbounded.
• Adds Range.prototype.isFinite.
• Adds Range.prototype.isInfinite.

1.1.0 (Jun 29, 2015)

• Adds Range.prototype.isEmpty.
• Adds Range.prototype.intersects.
• Adds Range.prototype.contains.

1.0.0 (May 11, 2015)

• Adds support for setting range bounds with new Range(1, 3, "[)") to set a left-closed, right-open range.
• Adds Range.prototype.toString to stringify a range.
• Adds Range.prototype.toJSON as an alias to Range.prototype.toString.
• Adds Range.parse to parse the stringified range.

0.1.337 (Oct 9, 2013)

• First release. Its future is an infinite exclusive range.