https://github.com/radekmie/ranges-set

Set operations on human-friendly ranges.
https://github.com/radekmie/ranges-set

friendly hacktoberfest human range set util

Last synced: 1 day ago
JSON representation

Set operations on human-friendly ranges.

• Host: GitHub
• URL: https://github.com/radekmie/ranges-set
• Owner: radekmie
• License: mit
• Created: 2021-01-28T23:41:11.000Z (over 3 years ago)
• Default Branch: master
• Last Pushed: 2024-04-13T12:02:09.000Z (6 months ago)
• Last Synced: 2024-09-16T17:13:21.871Z (17 days ago)
• Topics: friendly, hacktoberfest, human, range, set, util
• Language: TypeScript
• Homepage: https://npmjs.com/package/ranges-set
• Size: 1.82 MB
• Stars: 9
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE

Awesome Lists containing this project

README

        
# 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

```ts

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

```ts

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.

```ts

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;

```