Skip to content package
string-natural-compare v3.0.1 Compare alphanumeric strings the same way a human would, using a natural order algorithm
node any 0 deps cjs open source
overview readme
license MIT
deps 0
unpacked 9.9 kB
files 4
node any $ npm install string-natural-compare@3.0.1n npmREADME GitHub-flavored package documentation.
downloads Across all versions.
Download trend unavailable.
compatibility Runtime metadata.
keywords Tagged topics.
string natural compare comparison order natcmp strnatcmp sort natsort alphanum alphanumeric
versions Latest published Jan 21, 2020
maintainers Registry package owners.
install size Estimated unpacked size across 1 packages.
9.9 kB
Includes dependencies.
contents String Natural Compare
Compare alphanumeric strings the same way a human would, using a natural order algorithm (originally known as the alphanum algorithm ) where numeric characters are sorted based on their numeric values rather than their ASCII values.
Standard sorting: Natural order sorting:
img1.png img1.png
img10.png img2.png
img12.png img10.png
img2.png img12.png copy
This module exports a function that returns a number indicating whether one string should come before, after, or is the same as another string.
It can be used directly with the native .sort() array method.
Fast and Robust
This module can compare strings containing any size of number and is heavily tested with a custom benchmark suite to make sure that it is as fast as possible.
Installation
npm install string-natural-compare --save
# or
yarn add string-natural-compare copy
Usage
naturalCompare(strA, strB[, options])
strA (string )
strB (string )
options (object ) - Optional options object with the following options:
caseInsensitive (boolean ) - Set to true to compare strings case-insensitively. Default: false.
alphabet (string ) - A string of characters that define a custom character ordering. Default: undefined.
const naturalCompare = require ( 'string-natural-compare' );
// Simple, case-sensitive sorting
const files = [ 'z1.doc' , 'z10.doc' , 'z17.doc' , 'z2.doc' , 'z23.doc' , 'z3.doc' ];
files. sort (naturalCompare);
// -> ['z1.doc', 'z2.doc', 'z3.doc', 'z10.doc', 'z17.doc', 'z23.doc']
// Case-insensitive sorting
const chars = [ 'B' , 'C' , 'a' , 'd' ];
const naturalCompareCI = (a, b) => naturalCompare (a, b, {caseInsensitive: true });
chars. sort (naturalCompareCI);
// -> ['a', 'B', 'C', 'd']
Note: Putting numbers in the custom alphabet can cause undefined behaviour.
// Note:
[ 'a' , 'A' ]. sort (naturalCompareCI); // -> ['a', 'A']
[ 'A' , 'a' ]. sort (naturalCompareCI); // -> ['A', 'a']
// Compare strings containing large numbers
naturalCompare (
'1165874568735487968325787328996865' ,
'265812277985321589735871687040841'
);
// -> 1
// (Other inputs with the same ordering as this example may yield a different number > 0)
// Sorting an array of objects
const hotelRooms = [
{street: '350 5th Ave' , room: 'A-1021' },
{street: '350 5th Ave' , room: 'A-21046-b' }
];
// Sort by street (case-insensitive), then by room (case-sensitive)
hotelRooms. sort ((a, b) => (
naturalCompare (a.street, b.street, {caseInsensitive: true }) ||
naturalCompare (a.room, b.room)
));
// When text transformation is needed or when doing a case-insensitive sort on a
// large array of objects, it is best for performance to pre-compute the
// transformed text and store it on the object. This way, the text will not need
// to be transformed for every comparison while sorting.
const cars = [
{make: 'Audi' , model: 'R8' },
{make: 'Porsche' , model: '911 Turbo S' }
];
// Sort by make, then by model (both case-insensitive)
for ( const car of cars) {
car.sortKey = (car.make + ' ' + car.model). toLowerCase ();
}
cars. sort ((a, b) => naturalCompare (a.sortKey, b.sortKey));
// Using a custom alphabet (Russian alphabet)
const russianOpts = {
alphabet: 'АБВГДЕЁЖЗИЙКЛМНОПРСТУФХЦЧШЩЪЫЬЭЮЯабвгдеёжзийклмнопрстуфхцчшщъыьэюя' ,
};
[ 'Ё' , 'А' , 'б' , 'Б' ]. sort ((a, b) => naturalCompare (a, b, russianOpts));
// -> ['А', 'Б', 'Ё', 'б']
copy