string-sort

string-sort
===========
Simple library to sort an array based on string character priority.

This module performs a Schwartzian Transform on strings to return a 'transformed' version, sorts by that then resolves back to the original value. The upshot of this is that you can change the default string comparator behaviour so you can bias what characters are worth in the sort order. This is especially useful when wanting to sort by numbers above alpha characters or reorder the behaviour of punctuation.

``javascript
var ss = require('string-sort');

// For whatever reason we hate the letter 'c', send it to the bottom of the sort order
ss.sort(['a', 'b', 'c', 'd', 'e', 'f'], {charOrder: 'abdef'});
// => ['a', 'b', 'd', 'e', 'f', 'c']

// Sort so that numbers sort before alpha characters
ss.sort(['a', 'b', 'c', '1', '5', '9'], {charOrder: '0123456789abcdefghijklmnopqrstuvwxyz'});
// => ['1', '5', '9', 'a', 'b', 'c]
`


API
===

stringSort.sort(array, [options])
---------------------------------
Sort and return an array with the supplied options.
This function really just wraps Array.sort(), calculating the transform table beforehand.


stringSort.sortBy(collection, key, [options])
---------------------------------------------
Similar to sort() but works on a collection (an array of objects) using the specified key as the sorter.


stringSort.transformTable(charOrder)
------------------------------------
Return a string transformation table.
This is mainly used internally by transform() and untransform().


stringSort.transform(str, [options])
------------------------------------
Return the translated, sort compatible version of an input string.
This function is very slow as it needs to parse the options structure and reconstruct the table each time. Use sort() for larger arrays.


stringSort.untransform(str, [options])
------------------------------------
Return the untranslated, version of a translated string.
This function is very slow as it needs to parse the options structure and reconstruct the table each time. Use sort() for larger arrays.


stringSort.defaults
-------------------
An object of the default options to use if unspecified.


Options
=======
The following are the default options used by the functions.

| Option | Type | Default | Description |
|------------------|------------|--------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| charOrder | string | abcdefghijklmnopqrstuvwxyz0123456789:/-_ | The ascending character values when comparing strings. Anything not in this string will get its value via fallback |
| fallback(char) | function | c => 999 | Function that is expected to return the fallback values if the char does not exist in charOrder` |