Notoriously Pedantic Magistrate
    Wondering what’s next for npm?Check out our public roadmap! »

    string-natural-compare
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/string-natural-compare package

    3.0.1 • Public • Published

    String Natural Compare

    NPM Version Build Status Coverage Status Dependencies Status

    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
    

    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

    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:
    ['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));
    // -> ['А', 'Б', 'Ё', 'б']

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

    Install

    npm i string-natural-compare

    DownloadsWeekly Downloads

    1,531,652

    Version

    3.0.1

    License

    MIT

    Unpacked Size

    10.1 kB

    Total Files

    4

    Last publish

    Collaborators

    • avatar