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

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

    1.4.0 • Public • Published
    @version    1.4.0
    @date       2015-10-26
    @stability  3 - Stable
    

    Natural Compare – Build Coverage

    Compare strings containing a mix of letters and numbers in the way a human being would in sort order. This is described as a "natural ordering".

    Standard sorting:   Natural order sorting:
        img1.png            img1.png
        img10.png           img2.png
        img12.png           img10.png
        img2.png            img12.png

    String.naturalCompare returns a number indicating whether a reference string comes before or after or is the same as the given string in sort order. Use it with builtin sort() function.

    Installation

    • In browser
    <script src=min.natural-compare.js></script>
    • In node.js: npm install natural-compare-lite
    require("natural-compare-lite")

    Usage

    // Simple case sensitive example
    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"]
     
    // Use wrapper function for case insensitivity
    a.sort(function(a, b){
      return String.naturalCompare(a.toLowerCase(), b.toLowerCase());
    })
     
    // 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 (eg toLowerCase()),
    // it is best for performance to keep
    // transformed key in that object.
    // There are no need to do text transformation
    // on each comparision when sorting.
    var a = [ {"make":"Audi", "model":"A6"}
            , {"make":"Kia",  "model":"Rio"} ];
     
    // sort by make, then by model
    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);
    })
    • Works well with dates in ISO format eg "Rev 2012-07-26.doc".

    Custom alphabet

    It is possible to configure a custom alphabet to achieve a desired order.

    // 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)
    // ["А", "Б", "Ё"]

    External links

    • [GitHub repo][https://github.com/litejs/natural-compare-lite]
    • jsperf test

    Licence

    Copyright (c) 2012-2015 Lauri Rooden <lauri@rooden.ee>
    The MIT License

    Install

    npm i natural-compare

    DownloadsWeekly Downloads

    15,250,678

    Version

    1.4.0

    License

    MIT

    Last publish

    Collaborators

    • avatar