string-natural-compare

What is string-natural-compare?

The string-natural-compare npm package provides a way to compare strings in a human-friendly manner, often referred to as 'natural order' comparison. This is particularly useful for sorting lists of strings that include numbers, where you want the numbers to be sorted in numerical order rather than lexicographical order.

What are string-natural-compare's main functionalities?

Basic Natural Comparison

This feature allows you to compare two strings in a natural order. In this example, 'file10' is compared to 'file2', and the result is 1, indicating that 'file10' comes after 'file2' in natural order.

const naturalCompare = require('string-natural-compare');

const result = naturalCompare('file10', 'file2');
console.log(result); // Output: 1

Sorting an Array

This feature allows you to sort an array of strings in natural order. In this example, the array ['file10', 'file2', 'file1'] is sorted to ['file1', 'file2', 'file10'].

const naturalCompare = require('string-natural-compare');

const files = ['file10', 'file2', 'file1'];
files.sort(naturalCompare);
console.log(files); // Output: ['file1', 'file2', 'file10']

Case-Insensitive Comparison

This feature allows you to perform a case-insensitive natural comparison. In this example, 'File10' is compared to 'file2' with case insensitivity, and the result is 1, indicating that 'File10' comes after 'file2' in natural order.

const naturalCompare = require('string-natural-compare');

const result = naturalCompare('File10', 'file2', { caseInsensitive: true });
console.log(result); // Output: 1

Other packages similar to string-natural-compare

natural-compare-lite

The natural-compare-lite package provides similar functionality for natural order string comparison but is designed to be a lighter and faster alternative. It lacks some of the additional options available in string-natural-compare, such as case insensitivity.

alphanum-sort

The alphanum-sort package offers alphanumeric sorting of arrays, which is similar to natural order comparison. It is optimized for performance and can handle large arrays efficiently. However, it does not provide as many customization options as string-natural-compare.

README

Natural Compare

Compare alphanumeric strings the same way a human would, using a natural order algorithm

Installation

Node.js:

npm install string-natural-compare --save

Then in your JS:

require('string-natural-compare');

Bower:

Get the package:

bower install string-natural-compare

Include the script in your HTML (drop the ".min" to use the development version):

<script src="/bower_components/string-natural-compare/dist/natural-compare.min.js"></script>

Plain HTML:

Download the script and include it in your page:

<script src="natural-compare.min.js"></script>

Usage

Natural Compare makes two functions available on the global String object:

• String.naturalCompare (case-sensitive)
• String.naturalCaseCompare (case-insensitive)

Examples:

// Simple case-sensitive sorting
var a = ['z1.doc', 'z10.doc', 'z17.doc', 'z2.doc', 'z23.doc', 'z3.doc'];
a.sort(String.naturalCompare);
// -> ['z1.doc', 'z2.doc', 'z3.doc', 'z10.doc', 'z17.doc', 'z23.doc']


// Simple case-insensitive sorting
var a = ['B', 'C', 'a', 'd'];
a.sort(String.naturalCaseCompare);
// -> ['a', 'B', 'C', 'd']


// Compare very large numbers as strings (or strings containing long, numeric substrings)
String.naturalCompare(
  '1165874568735487968325787328996865',
  '1165874568735487968325787328996864'
);
// -> 1


// In most cases we want to sort an array of objects
var a = [
  {street: '350 5th Ave', room: 'A-1021'},
  {street: '350 5th Ave', room: 'A-21046-b'}
];

// Sort by street, then by room
a.sort(function(a, b) {
  return String.naturalCompare(a.street, b.street) || String.naturalCompare(a.room, b.room);
});


// When text transformation is needed or when doing a case-insensitive sort on a
// large array, it is best for performance to pre-compute the transformed text
// and store it in that object. This way, the text transformation will not be
// needed for every comparison when sorting.
var a = [
  {make: 'Audi', model: 'R8'},
  {make: 'Porsche', model: '911 Turbo S'}
];

// Sort by make, then by model
a = a.map(function(car) {
  car.sort_key = (car.make + ' ' + car.model).toLowerCase();
});
a.sort(function(a, b) {
  return String.naturalCompare(a.sort_key, b.sort_key);
});

Custom Alphabet

It is possible to configure a custom alphabet to achieve a desired character ordering.

// Estonian alphabet
String.alphabet = 'ABDEFGHIJKLMNOPRSŠZŽTUVÕÄÖÜXYabdefghijklmnoprsšzžtuvõäöüxy';
['t', 'z', 'x', 'õ'].sort(String.naturalCompare);
// -> ['z', 't', 'õ', 'x']

// Russian alphabet
String.alphabet = 'АБВГДЕЁЖЗИЙКЛМНОПРСТУФХЦЧШЩЪЫЬЭЮЯабвгдеёжзийклмнопрстуфхцчшщъыьэюя';
['Ё', 'А', 'Б'].sort(String.naturalCompare);
// -> ['А', 'Б', 'Ё']

Note: Putting numbers in the custom alphabet can cause undefined behaviour.