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
• Rationale
• 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 want a new feature in this package or you would like us to change some of its functionality, raise an issue on this repo.

• If you tried to use this library but it misbehaves, or you need advice setting it up, and its readme doesn't make sense, just document it and raise an issue on this repo.

• If you would like to add or change some features, just fork it, hack away, and file a pull request. We'll do our best to merge it quickly. Prettier is enabled, so you don't need to worry about the code style.

⬆ back to top

Licence

MIT License (MIT)

Copyright © 2018 Codsen Ltd, Roy Revelt