| [Build]: http://img.shields.io/travis/litejs/natural-compare-lite.png | |
| [Coverage]: http://img.shields.io/coveralls/litejs/natural-compare-lite.png | |
| [1]: https://travis-ci.org/litejs/natural-compare-lite | |
| [2]: https://coveralls.io/r/litejs/natural-compare-lite | |
| [npm package]: https://npmjs.org/package/natural-compare-lite | |
| [GitHub repo]: https://github.com/litejs/natural-compare-lite | |
| @version 1.4.0 | |
| @date 2015-10-26 | |
| @stability 3 - Stable | |
| Natural Compare – [![Build][]][1] [![Coverage][]][2] | |
| =============== | |
| 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". | |
| ```text | |
| 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 | |
| ```html | |
| <script src=min.natural-compare.js></script> | |
| ``` | |
| - In node.js: `npm install natural-compare-lite` | |
| ```javascript | |
| require("natural-compare-lite") | |
| ``` | |
| ### Usage | |
| ```javascript | |
| // 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. | |
| ```javascript | |
| // 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](http://jsperf.com/natural-sort-2/12) | |
| Licence | |
| ------- | |
| Copyright (c) 2012-2015 Lauri Rooden <lauri@rooden.ee> | |
| [The MIT License](http://lauri.rooden.ee/mit-license.txt) | |