Segment-sort NPM

Segment Sort

Downloads

Create string sort algorithm from segment config.

Usage

npm i segment-sort

import segmentSorter from 'segment-sort';

// Case sensitive, upper < lower < _
const comparator1 = segmentSorter(['AZ', 'az', '_']);
['a', 'b', 'A', 'B', '_'].sort(comparator1); // ['A', 'B', a', 'b', '_']

// Case insensitive, lower < upper < _
const comparator2 = segmentSorter(['aA', '_']);
['a', 'b', 'A', 'B', '_'].sort(comparator2); // ['a', 'A', 'b', 'B', '_']

For more info, please check the APIs.

APIs Documentation

Type Aliases

Comparator

Ƭ Comparator: (a: string | undefined, b: string | undefined) => number

Type declaration

▸ (a, b): number

Type of a function to compare two strings.

Parameters

Name	Type
`a`	`string` \| `undefined`
`b`	`string` \| `undefined`

Returns

number

0 if a === b; or negative if a < b; or positive if a > b

Defined in

index.ts:13

CompareRule

Ƭ CompareRule: SegSymbol[]

String comparison rule.

Defined in

types.ts:16

SegSymbol

Ƭ SegSymbol: "az" | "AZ" | "aA" | "aZ" | "Aa" | "Az" | "_"

Symbols for char segments:

az - Lower case letters, i.e. a-z.
AZ - Upper case letters, i.e. A-Z.
aA or aZ - Both case letters and lower case first, i.e. a-zA-Z and 'a' < 'A' < 'b' < 'B' < ...
Aa or Az - Both case letters and upper case first, i.e. a-zA-Z and 'A' < 'a' < 'B' < 'b' < ...
- Chars with ASCII from 91 to 96, i.e. [, \, ], ^, `, ``` `(backtick).

Defined in

types.ts:11

Functions

default

▸ default(rule): undefined | Comparator

Generate a string comparison function based on the given rule.

Parameters

Name	Type	Description
`rule`	`CompareRule`	Comparison rule

Returns

undefined | Comparator

A string comparison function; or undefined if rule is invalid

Defined in

index.ts:22

Algorithm

The key of segment-sort is to define a CompareRule so it creates a custom string sort algorithm for you.

Compare Rule

A CompareRule is an array of segments.

Segment

A segment is a collection of characters with a sorting rule. Currently, there are 5 predefined segments:

"az": Lower-case letters ([a-z]) sorted alphabetically.
"AZ": Upper-case letters([A-Z]) sorted alphabetically.
"aA" or "aZ": Both case letters ([a-zA-Z]) sorted case-insensitively and lower case first in case of a tie ('a' < 'A' < 'b' < 'B' < ...).
"Aa" or "Az": Both case letters ([a-zA-Z]) sorted case-insensitively and upper case first in case of a tie ('A' < 'a' < 'B' < 'b' < ...).
"_" - Chars of ASCII from 91 to 96, i.e. [, \, ], ^, _, `(backtick), sorted alphabetically.

Case Sensitivity

The segments used in CompareRule implicitly decide whether to compare strings case-sensitively or -insensitively:

"az" or "AZ": Compare strings case-sensitively;
"aA", "Aa", "aZ" or "Az": Compare strings case-insensitively;

Some Examples

`["_", "aA"]` or `["_", "aZ"]`

Strings are compared case-insensitively, and lower case goes first in case of a tie.
[, \, ], ^, _, `(backtick) are in front of letters ([a-zA-Z]).

A sorted example is ['_', 'a', 'A', 'b', 'B'].

`["Aa", "_"]` or `["Az", "_"]`

Strings are compared case-insensitively, and upper case goes first in case of a tie.
[, \, ], ^, _, `(backtick) are after letters ([a-zA-Z]).

This is widely used, e.g. as the default option ("case-insensitive") in TSLint Rule: ordered-imports. A sorted example is ['A', 'a', 'B', 'b', '_'].

`["az", "_", "AZ"]`

Strings are compared case-sensitively, and lower-case letters ([a-z]) are in front of upper-case letters ([A-Z]).
[, \, ], ^, _, `(backtick) are behind lower-case letters and before upper-case letters.

This corresponds to "lowercase-first" in TSLint Rule: ordered-imports. A sorted example is ['a', 'b', '_', 'A', 'B'].

`["AZ", "_", "az"]`

Strings are compared case-sensitively, and upper-case letters ([A-Z]) are in front of lower-case letters ([a-z]).
[, \, ], ^, _, `(backtick) are behind upper-case letters and before lower-case letters.

This corresponds to "lowercase-last" in TSLint Rule: ordered-imports.

A sorted example is ['A', 'B', '_', 'a', 'b'].

Incomplete Rules

The algorithm in this package is smart enough to complete CompareRule by appending missing segments in the end.

For example, ["az", "_"] will be padded with "AZ", and equals to ["az", "_", "AZ"].

But it will give up if there is uncertainty. For example, ["az"] can't be completed as the order between "_" and "AZ" is unknown, hence undefined is returned.

Here are some incomplete but meaningful rules: