======sortmulti======

<box>
Sort an [[PTPScript:Types:Array|Array]] according to columns.

\\
**Syntax**
  * ''[[PTPScript:Types:Array|Array]] sortmulti( [[PTPScript:Types:Array|Array]] subject, [[PTPScript:Types:Array|Array]] options [, [[PTPScript:Types:Boolean|Boolean]] preserve ] )''
    * ''[[PTPScript:Types:Array|Array]] options ( [[PTPScript:Types:Array|Array]] option [, ... ] )''
      * ''[[PTPScript:Types:Array|Array]] option ( [[PTPScript:Types:Mixed|Mixed]] column [, [[PTPScript:Types:Boolean|Boolean]] reverse [, [[PTPScript:Types:Number|Number]] method ] ] )''

\\
**Parameters**
  * [[PTPScript:Types:Array|Array]] ''subject'' - The Array to sort. This Array should contain sub-Arrays as rows, each of which should contain the columns named for sorting.
  * [[PTPScript:Types:Array|Array]] ''options'' - The sort options. This parameter should consist of an Array of options, where each option is itself an Array containing the option details. The order of the options dictates the sort order.
    * [[PTPScript:Types:Array|Array]] ''option'' - Each sort option should be an Array containing numerically-indexed option details.
      * ''0'': [[PTPScript:Types:Mixed|Mixed]] ''column'' - The name of the column to sort by, where the name is a valid Array key (i.e. a String or an Integer).
      * ''1'': [[PTPScript:Types:Boolean|Boolean]] ''reverse'' - Whether to reverse the sort.
        * **''false''** (default) - ''subject'' will be sorted from lowest to highest.
        * **''true''** - ''subject'' will be sorted from highest to lowest.
      * ''2'': [[PTPScript:Types:Number|Number]] ''method'' - Sort method options.
        * ''0'' (default) - Compare items using standard comparison.
        * ''1'' - Compare items numerically.
        * ''2'' - Compare items as case-sensitive strings.
        * ''3'' - Compare items as case-insensitive strings.
        * ''4'' - Compare items as case-sensitive strings, using [[http://sourcefrog.net/projects/natsort/|natural ordering]].
        * ''5'' - Compare items as case-insensitive strings, using [[http://sourcefrog.net/projects/natsort/|natural ordering]].
        * ''6'' - Compare items as case-sensitive strings, according to locale.
        * ''7'' - Compare items as case-insensitive strings, according to locale.
  * [[PTPScript:Types:Boolean|Boolean]] ''preserve'' - Whether to preserve item keys.
    * **''false''** (default) - Keys will be re-assigned.
    * **''true''** - Keys will be preserved.

\\
**Result**
  * [[PTPScript:Types:Array|Array]] - The sorted Array.
</box>

Returns ''subject'' sorted in order, by column, according to various options. 

<note tip>
Key value, type, and order do not matter - the Array does not have to be numerically indexed.
</note>

<note tip>
The ''sortmulti()'' function uses "safe" sorting, that is, two identical items will retain their original order.
</note>

For more information about comparison methods, see the ''[[PTPScript:Functions:compare|compare()]]'' function.

===Examples===

To demonstrate how to use the ''sortmulti()'' function, let's first set up an Array with some example data:

<code ptpscript>
{ Users = [
    ["Name": "Joe",  "Admin": false],
    ["Name": "Bill", "Admin": true],
    ["Name": "Jim",  "Admin": false],
    ["Name": "Adam", "Admin": false],
    ["Name": "Zak",  "Admin": false],
    ["Name": "Greg", "Admin": true]
  ]
}…
</code>

Now let's create some code to display the contents of the Array:

<code ptpscript>
{ macro Display(Users) }…
{ loop Users as User }…
    { User.Name }
{ endloop }…
{ endmacro }…
</code>

Now we can display the users by running the macro:

<code ptpscript>
{ Display(Users) }
</code>

<output>
    Joe
    Bill
    Jim
    Adam
    Zak
    Greg
</output>

Let's sort the users by name first:

<code ptpscript>
{ SortedUsers = sortmulti(Users, [["Name"]]) }…
{ Display(SortedUsers) }
</code>

<output>
    Adam
    Bill
    Greg
    Jim
    Joe
    Zak
</output>

And now let's sort them so that the admin users are listed first:

<code ptpscript>
{ SortedUsers = sortmulti(Users, [["Admin", true]]) }…
{ Display(SortedUsers) }
</code>

<output>
    Greg
    Bill
    Zak
    Adam
    Jim
    Joe
</output>

Notice that because ''true'' is greater than ''false'', we had to sort in reverse.

Now let's combine both sorts by sorting by Admin and then by Name:

<code ptpscript>
{ SortedUsers = sortmulti(Users, [["Admin", true], ["Name"]]) }…
{ Display(SortedUsers) }
</code>

<output>
    Bill
    Greg
    Adam
    Jim
    Joe
    Zak
</output>

Hopefully that shows how simple, yet powerful, the ''sortmulti()'' function is.