ranges-sort

Sort natural number index ranges [ [5, 6], [1, 3] ] => [ [1, 3], [5, 6] ]

Install

npm i ranges-sort

// consume as CommonJS require:
const rangesSort = require("ranges-sort");
// or as a native ES module:
import rangesSort from "ranges-sort";

Here's what you'll get:

⬆ back to top

Table of Contents

• Install
• What it does
• API
• Contributing
• Licence

What it does

Background: strings in JavaScript consist of characters. For example, abc is a string. Each character has an index number and the numbering starts from zero. For example, in "abc", "a" has index 0, "b" has index 1 and so on.

We use arrays to mark what to delete from a string, from example, deletion from index 0 to index 5 would be [0, 5]. If we added a third element, that would mean we want to insert it, replacing the given index range. For example, if a string is abc and we want to delete "b", that would be range [1, 2]. If we wanted to replace "b" with "x", that would be range [1, 2, "x"].

Now, if you have an array of such ranges (that's an array of arrays), this library can sort them. For example:

[ [5, 6], [1, 3] ] => [ [1, 3], [5, 6] ]
[ [5, 6], [5, 3], [5, 0] ] => [ [5, 0], [5, 3], [5, 6] ]
[] => []

[[1, 2], []] => // throws, because there's at least one empty range
[['a']] => // throws, because range is not a range but a string
[[1], [2]] => // throws, because one index is not a range

// 3rd argument and onwards are ignored:
[[3, 4, 'aaa', 'bbb'], [1, 2, 'zzz']] => [[1, 2, 'zzz'], [3, 4, 'aaa', 'bbb']]

This is a specialised library to sort these types of arrays, not any type of arrays. We expect first two elements in each array to be a natural number and there can be optional third argument (of any type).

The purpose of string index ranges is to avoid changing a string many times but instead, track the changes (ranges of indexes), compiling them in an array, and later perform all changes in one go. This guarantees the original characters in the string retain the original positions throughout the whole operation. It's easier and faster to process strings this way.

The purpose of range sorting is to make life easier for other range-processing libraries.

⬆ back to top

API

rangesSort(arr[, opts]) — in other words, this library gives you a function and you must feed an array into its first argument and also if you wish, you can feed a second argument, the Optional Options Object (bracket in [, opts] means "optional").

For example,

[ [5, 9], [5, 3] ] => [ [5, 3], [5, 9] ]

This library does not mutate the inputs. In theory, a function in JavaScript could mutate its arguments, but only if they are on an "object" primitive type (an array or a plain object, for example).

⬆ back to top

Options object

Output: Sorted input array. First, we sort by the first argument of each child range array, then by second.

Here is whole Optional Options Object in one place, with all defaults, in case you want to copy it:

{
  strictlyTwoElementsInRangeArrays: false,
  progressFn: null
}

⬆ back to top

Contributing

• If you see an error, raise an issue.
• If you want a new feature but can't code it up yourself, also raise an issue. Let's discuss it.
• If you tried to use this package, but something didn't work out, also raise an issue. We'll try to help.
• If you want to contribute some code, fork the monorepo via BitBucket, then write code, then file a pull request via BitBucket. We'll merge it in and release.

In monorepo, npm libraries are located in packages/ folder. Inside, the source code is located either in src/ folder (normal npm library) or in the root, cli.js (if it's a command line application).

The npm script "dev", the "dev": "rollup -c --dev --silent" builds the development version retaining all console.logs with row numbers. It's handy to have js-row-num-cli installed globally so you can automatically update the row numbers on all console.logs.

⬆ back to top

Licence

MIT License

Copyright (c) 2015-2019 Roy Revelt and other contributors