Editing Ar CustomSort

{{Function
 |origin = NVSE
 |summary = Sorts the elements of an array based on the return of a specified [[User Defined Function]], which you must have previously created. 

Ar_CustomSort will repeatedly take 2 elements from the array to sort, and pass them to the UDF as parameters in the form of two single element arrays. Your UDF  determines how the values of the 2 array var parameters should be sorted in relation to each other.
This is useful if you wish to sort forms according to anything other than their name/formID (eg weight, size, skills etc), or sub-arrays. You let the function know that one element should be considered 'earlier than' or 'less than' in the resulting array's order by letting the UDF return 'true', ie: [[SetFunctionValue]]. 

 |name = Ar_CustomSort
 |returnType = array
 |arguments = 
  {{FunctionArgument
   |Name = Source
   |Type = array}}{{FunctionArgument
   |Name = ComparisonUDF
   |Type = script}}{{FunctionArgument
   |Name = <i>SortDescending</i>
   |Type = <i>bool</i>}}}}
==Example==
I want to sort a bunch of Goodsprings residents according to their medicine skill, with those with higher skill earlier in the array, ie 'less than'.

The comparison UDF: 
<pre>
scn MyComparisonUDF
    
array_var a        ; parameters
array_var b

ref rA            ; local ref vars
ref rB

Begin Function {a, b}
    let rA := a[0]
    let rB := b[0]
    if rA.GetAV Medicine > rB.GetAV Medicine
        SetFunctionValue 1    
        ; * SetFunctionValue non-zero (true) marks the comparison as returning:
        ; * element value a < element value b
    endif
End
</pre>

Usage of Ar_CustomSort in another script:
<pre>
scn MyCallingScript
    
array_var array1
array_var array2
    
let array1 := Ar_List TrudyRef, SunnyRef, DocMitchellRef, EasyPeteRef, GSJoeCobbRef, GSChetRef

let array2 := ar_CustomSort array1, MyComparisonUDF
</pre>

Now array2 is a regular array custom sorted, which in our case means in descending order of medicine skill:
<pre>
    0    DocMitchellRef    ; Doc has 33 medicine
    1    GSChetRef         ; Chet has 15
    2    TrudyRef          ; These three all have 12
    3    SunnyRef
    4    EasyPeteRef
    5    GSJoeCobbRef      ; Joe Cobb has 10
</pre>

If the Ar_CustomSort function was called with the optional descendingbool, it'll sort the array in reverse order, which in our case means in <i>ascending</i> order (since its based on UDF) of medicine skill:
<pre>
    0    GSJoeCobbRef
    1    EasyPeteRef
    2    SunnyRef
    3    TrudyRef
    4    GSChetRef
    5    DocMitchellRef    
</pre>
==See Also==
*[[Array Variable]]
*[[User Defined Function]]
*[[Ar_SortAlpha]]
*[[Ar_Sort]]
*[[Tutorial: Array Variables 1]]
[[Category:Functions_(NVSE)]]
[[Category:Array Variables]]