ranges-set

ranges-set

Set operations on human-friendly ranges.

Features

• Easy for the users to understand and developers to use
• Fast even for huge ranges
• Small bundle footprint (less than 1Kb gzipped)

Motivation

A naive implementation of this package would always expand the sets first and then operate on arrays or native Set objects. While this approach works, one can hang your app with a simple input of 1-1000000000.

That is why ranges-set operates on actual ranges, resulting in performance scalable with the number of ranges (i.e., the number of commas). Caution: it is not the case for expand, as it has to return all elements!

Usage

import { difference, equal, expand, intersection, normalize, subset, union } from 'ranges-set';

difference('1-4', '2-3'); // '1,4'
equal('1-3', '1-2'); // false
expand('1-3,5-7'); // ['1', '2', '3', '5', '6', '7']
intersection('1-10', '5-10'); // '5-10'
normalize('1,2,3,5,6-8'); // '1-3,5-8'
subset('1-3', '1-2'); // true
union('1-60,40-100'); // '1-100'

API

function difference(textA: string, textB: string): string;
function equal(textA: string, textB: string): boolean;
function expand(text: string): string[];
function intersection(textA: string, textB: string): string;
function normalize(text: string): string;
function subset(textA: string, textB: string): boolean;
function union(textA: string, textB: string): string;

On top of that, all internal functions are exported with a prefix (_). It allows you to achieve the best performance, as you can operate on the internal representation of the parsed objects instead of strings.

function _compare(reprA: Repr, reprB: Repr): number;
function _createLiteral(text: string): Repr;
function _createRange(min: number, max: number): Repr;
function _differenceReprs(reprsA: Repr[], reprsB: Repr[]): Repr[];
function _equalReprs(reprsA: Repr[], reprsB: Repr[]): boolean;
function _expandReprs(reprs: Repr[]): string[];
function _intersectionRepr(reprA: Repr, reprB: Repr): Repr | null;
function _intersectionReprs(reprsA: Repr[], reprsB: Repr[]): Repr[];
function _parse(text: string): Repr[];
function _parseOne(text: string): Repr;
function _serialize(reprs: Repr[]): string;
function _serializeOne(repr: Repr): string;
function _subsetReprs(reprsA: Repr[], reprsB: Repr[]): boolean;
function _unionRepr(reprA: Repr, reprB: Repr): boolean;
function _unionReprs(reprs: Repr[], repr: Repr): void;
function _unionReprsAt(reprs: Repr[], repr: Repr, index: number): boolean;