strange

stRange.js
==========
[![NPM version][npm-badge]](https://www.npmjs.com/package/strange)
[![Build status][travis-badge]](https://travis-ci.org/moll/js-strange)

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.

[npm-badge]: https://img.shields.io/npm/v/strange.svg
[travis-badge]: https://travis-ci.org/moll/js-strange.png?branch=master

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

$3

``
npm install strange
`

$3

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

[browserify]: https://github.com/substack/node-browserify


Using
-----
Create a Range object by passing in a beginning and end:
`javascript
var Range = require("strange")
var range = new Range(1, 5)
`

Check if something is a range and use it:
`javascript
var Range = require("strange")
if (range instanceof Range) console.log(range.begin, range.end)
`

$3


You can set a range's bounds by passing the bounds as a two-character string of
parentheses as the 3rd argument:
`javascript
new Range(1, 3, "[)")
`

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

Pair | Meaning
-----|--------
() | open
[] | closed
[) | left-closed, right-open
(] | left-open, right-closed




$3


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

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

To have stRange.js also parse the endpoints, pass a function to Range.parse:
`javascript
Range.parse("[42,69]", Number) // => new Range(42, 69)
`

$3

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][api].

[api]: https://github.com/moll/js-strange/blob/master/doc/API.md

$3

- 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)

$3

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