\href{https://travis-ci.org/mziccard/node-timsort}{\texttt{ }} \href{https://www.npmjs.com/package/timsort}{\texttt{ }}

An adaptive and {\bfseries{stable}} sort algorithm based on merging that requires fewer than nlog(n) comparisons when run on partially sorted arrays. The algorithm uses O(n) memory and still runs in O(nlogn) (worst case) on random arrays. ~\newline
 This implementation is based on the original \href{http://svn.python.org/projects/python/trunk/Objects/listsort.txt}{\texttt{ Tim\+Sort}} developed by Tim Peters for Python\textquotesingle{}s lists (code \href{http://svn.python.org/projects/python/trunk/Objects/listobject.c}{\texttt{ here}}). Tim\+Sort has been also adopted in Java starting from version 7.\hypertarget{md_sfcode_node_modules_timsort_README_autotoc_md30451}{}\doxysection{Acknowledgments}\label{md_sfcode_node_modules_timsort_README_autotoc_md30451}

\begin{DoxyItemize}
\item @novacrazy\+: ported the module to ES6/\+ES7 and made it available via bower
\item @kasperisager\+: implemented faster lexicographic comparison of small integers
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_timsort_README_autotoc_md30452}{}\doxysection{Usage}\label{md_sfcode_node_modules_timsort_README_autotoc_md30452}
Install the package with npm\+: 
\begin{DoxyCode}{0}
\DoxyCodeLine{npm install -\/-\/save timsort }

\end{DoxyCode}
 And use it\+: 
\begin{DoxyCode}{0}
\DoxyCodeLine{var TimSort = require('timsort');}
\DoxyCodeLine{}
\DoxyCodeLine{var arr = [...];}
\DoxyCodeLine{TimSort.sort(arr); }

\end{DoxyCode}
 You can also install it with bower\+: 
\begin{DoxyCode}{0}
\DoxyCodeLine{bower install timsort }

\end{DoxyCode}
 As {\ttfamily array.\+sort()} by default the {\ttfamily timsort} module sorts according to lexicographical order. You can also provide your own compare function (to sort any object) as\+: 
\begin{DoxyCode}{0}
\DoxyCodeLine{function numberCompare(a,b) \{}
\DoxyCodeLine{    return a-\/b;}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{var arr = [...];}
\DoxyCodeLine{var TimSort = require('timsort');}
\DoxyCodeLine{TimSort.sort(arr, numberCompare); }

\end{DoxyCode}
 You can also sort only a specific subrange of the array\+: 
\begin{DoxyCode}{0}
\DoxyCodeLine{TimSort.sort(arr, 5, 10);}
\DoxyCodeLine{TimSort.sort(arr, numberCompare, 5, 10); }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_timsort_README_autotoc_md30453}{}\doxysection{Performance}\label{md_sfcode_node_modules_timsort_README_autotoc_md30453}
A benchmark is provided in {\ttfamily benchmark/index.\+js}. It compares the {\ttfamily timsort} module against the default {\ttfamily array.\+sort} method in the numerical sorting of different types of integer array (as described \href{http://svn.python.org/projects/python/trunk/Objects/listsort.txt}{\texttt{ here}})\+:


\begin{DoxyItemize}
\item {\itshape Random array}
\item {\itshape Descending array}
\item {\itshape Ascending array}
\item {\itshape Ascending array with 3 random exchanges}
\item {\itshape Ascending array with 10 random numbers in the end}
\item {\itshape Array of equal elements}
\item {\itshape Random Array with many duplicates}
\item {\itshape Random Array with some duplicates}
\end{DoxyItemize}

For any of the array types the sorting is repeated several times and for different array sizes, average execution time is then printed. I run the benchmark on Node v6.\+3.\+1 (both pre-\/compiled and compiled from source, results are very similar), obtaining the following values\+:

\tabulinesep=1mm
\begin{longtabu}spread 0pt [c]{*{5}{|X[-1]}|}
\hline
\cellcolor{\tableheadbgcolor}\textbf{ }&\cellcolor{\tableheadbgcolor}\textbf{ }&\multicolumn{2}{l|}{\cellcolor{\tableheadbgcolor}\textbf{ Execution Time (ns) }}&\multirow{2}{*}{\cellcolor{\tableheadbgcolor}\textbf{ Speedup  }}\\\cline{1-4}
\endfirsthead
\hline
\endfoot
\hline
\cellcolor{\tableheadbgcolor}\textbf{ }&\cellcolor{\tableheadbgcolor}\textbf{ }&\multicolumn{2}{l|}{\cellcolor{\tableheadbgcolor}\textbf{ Execution Time (ns) }}&&\multirow{2}{*}{\cellcolor{\tableheadbgcolor}\textbf{ Speedup  }}\\\cline{1-5}
\endhead
\cellcolor{\tableheadbgcolor}\textbf{ Array Type }&\cellcolor{\tableheadbgcolor}\textbf{ Length }&\cellcolor{\tableheadbgcolor}\textbf{ Tim\+Sort.\+sort }&\cellcolor{\tableheadbgcolor}\textbf{ array.\+sort  $<$tbody$>$ }\\\cline{1-5}
\multirow{4}{*}{Random}&10&404&1583&3.\+91  \\\cline{2-5}
&100&7147&4442&0.\+62  \\\cline{2-5}
&1000&96395&59979&0.\+62  \\\cline{2-5}
&10000&1341044&6098065&4.\+55  \\\cline{1-5}
\multirow{4}{*}{Descending}&10&180&1881&10.\+41  \\\cline{2-5}
&100&682&19210&28.\+14  \\\cline{2-5}
&1000&3809&185185&48.\+61  \\\cline{2-5}
&10000&35878&5392428&150.\+30  \\\cline{1-5}
\multirow{4}{*}{Ascending}&10&173&816&4.\+69  \\\cline{2-5}
&100&578&18147&31.\+34  \\\cline{2-5}
&1000&2551&331993&130.\+12  \\\cline{2-5}
&10000&22098&5382446&243.\+57  \\\cline{1-5}
\multirow{4}{*}{Ascending + 3 Rand Exc}&10&232&927&3.\+99  \\\cline{2-5}
&100&1059&15792&14.\+90  \\\cline{2-5}
&1000&3525&300708&85.\+29  \\\cline{2-5}
&10000&27455&4781370&174.\+15  \\\cline{1-5}
\multirow{4}{*}{Ascending + 10 Rand End}&10&378&1425&3.\+77  \\\cline{2-5}
&100&1707&23346&13.\+67  \\\cline{2-5}
&1000&5818&334744&57.\+53  \\\cline{2-5}
&10000&38034&4985473&131.\+08  \\\cline{1-5}
\multirow{4}{*}{Equal Elements}&10&164&766&4.\+68  \\\cline{2-5}
&100&520&3188&6.\+12  \\\cline{2-5}
&1000&2340&27971&11.\+95  \\\cline{2-5}
&10000&17011&281672&16.\+56  \\\cline{1-5}
\multirow{4}{*}{Many Repetitions}&10&396&1482&3.\+74  \\\cline{2-5}
&100&7282&25267&3.\+47  \\\cline{2-5}
&1000&105528&420120&3.\+98  \\\cline{2-5}
&10000&1396120&5787399&4.\+15  \\\cline{1-5}
\multirow{4}{*}{Some Repetitions}&10&390&1463&3.\+75  \\\cline{2-5}
&100&6678&20082&3.\+01  \\\cline{2-5}
&1000&104344&374103&3.\+59  \\\cline{2-5}
&10000&1333816&5474000&4.\+10  $<$/tbody$>$ \\\cline{1-5}
\end{longtabu}


{\ttfamily Tim\+Sort.\+sort} {\bfseries{is faster}} than {\ttfamily array.\+sort} on almost of the tested array types. In general, the more ordered the array is the better {\ttfamily Tim\+Sort.\+sort} performs with respect to {\ttfamily array.\+sort} (up to 243 times faster on already sorted arrays). And also, in general, the bigger the array the more we benefit from using the {\ttfamily timsort} module. ~\newline


These data strongly depend on Node.\+js version and the machine on which the benchmark is run. I strongly encourage you to run the benchmark on your own setup with\+: 
\begin{DoxyCode}{0}
\DoxyCodeLine{npm run benchmark }

\end{DoxyCode}
 Please also notice that\+:


\begin{DoxyItemize}
\item This benchmark is far from exhaustive. Several cases are not considered and the results must be taken as partial
\item {\itshape inlining} is surely playing an active role in {\ttfamily timsort} module\textquotesingle{}s good performance
\item A more accurate comparison of the algorithms would require implementing {\ttfamily array.\+sort} in pure javascript and counting element comparisons
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_timsort_README_autotoc_md30454}{}\doxysection{Stability}\label{md_sfcode_node_modules_timsort_README_autotoc_md30454}
Tim\+Sort is {\itshape stable} which means that equal items maintain their relative order after sorting. Stability is a desirable property for a sorting algorithm. Consider the following array of items with an height and a weight. 
\begin{DoxyCode}{0}
\DoxyCodeLine{[ }
\DoxyCodeLine{  \{ height: 100, weight: 80 \},}
\DoxyCodeLine{  \{ height: 90, weight: 90 \},}
\DoxyCodeLine{  \{ height: 70, weight: 95 \},}
\DoxyCodeLine{  \{ height: 100, weight: 100 \},}
\DoxyCodeLine{  \{ height: 80, weight: 110 \},}
\DoxyCodeLine{  \{ height: 110, weight: 115 \},}
\DoxyCodeLine{  \{ height: 100, weight: 120 \},}
\DoxyCodeLine{  \{ height: 70, weight: 125 \},}
\DoxyCodeLine{  \{ height: 70, weight: 130 \},}
\DoxyCodeLine{  \{ height: 100, weight: 135 \},}
\DoxyCodeLine{  \{ height: 75, weight: 140 \},}
\DoxyCodeLine{  \{ height: 70, weight: 140 \} }
\DoxyCodeLine{] }

\end{DoxyCode}
 Items are already sorted by {\ttfamily weight}. Sorting the array according to the item\textquotesingle{}s {\ttfamily height} with the {\ttfamily timsort} module results in the following array\+: 
\begin{DoxyCode}{0}
\DoxyCodeLine{[ }
\DoxyCodeLine{  \{ height: 70, weight: 95 \},}
\DoxyCodeLine{  \{ height: 70, weight: 125 \},}
\DoxyCodeLine{  \{ height: 70, weight: 130 \},}
\DoxyCodeLine{  \{ height: 70, weight: 140 \},}
\DoxyCodeLine{  \{ height: 75, weight: 140 \},}
\DoxyCodeLine{  \{ height: 80, weight: 110 \},}
\DoxyCodeLine{  \{ height: 90, weight: 90 \},}
\DoxyCodeLine{  \{ height: 100, weight: 80 \},}
\DoxyCodeLine{  \{ height: 100, weight: 100 \},}
\DoxyCodeLine{  \{ height: 100, weight: 120 \},}
\DoxyCodeLine{  \{ height: 100, weight: 135 \},}
\DoxyCodeLine{  \{ height: 110, weight: 115 \} }
\DoxyCodeLine{] }

\end{DoxyCode}
 Items with the same {\ttfamily height} are still sorted by {\ttfamily weight} which means they preserved their relative order.

{\ttfamily array.\+sort}, instead, is not guarranteed to be {\itshape stable}. In Node v0.\+12.\+7 sorting the previous array by {\ttfamily height} with {\ttfamily array.\+sort} results in\+: 
\begin{DoxyCode}{0}
\DoxyCodeLine{[ }
\DoxyCodeLine{  \{ height: 70, weight: 140 \},}
\DoxyCodeLine{  \{ height: 70, weight: 95 \},}
\DoxyCodeLine{  \{ height: 70, weight: 125 \},}
\DoxyCodeLine{  \{ height: 70, weight: 130 \},}
\DoxyCodeLine{  \{ height: 75, weight: 140 \},}
\DoxyCodeLine{  \{ height: 80, weight: 110 \},}
\DoxyCodeLine{  \{ height: 90, weight: 90 \},}
\DoxyCodeLine{  \{ height: 100, weight: 100 \},}
\DoxyCodeLine{  \{ height: 100, weight: 80 \},}
\DoxyCodeLine{  \{ height: 100, weight: 135 \},}
\DoxyCodeLine{  \{ height: 100, weight: 120 \},}
\DoxyCodeLine{  \{ height: 110, weight: 115 \} }
\DoxyCodeLine{] }

\end{DoxyCode}
 As you can see the sorting did not preserve {\ttfamily weight} ordering for items with the same {\ttfamily height}. 