Ar CustomSort

From the Fallout3 GECK Wiki
Jump to navigation Jump to search
< [[::Category:Functions|Category:Functions]]

A function added by the New Vegas Script Extender.

Description

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.

You can define the sorting method any way you like, but it must be definitive, otherwise an infinite loop (CTD) may result.

Syntax

[help]
(array) Ar_CustomSort Source:array ComparisonUDF:script ReverseSort:bool

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:

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

Usage of Ar_CustomSort in another script:

scn MyCallingScript
    
array_var array1
array_var array2
    
let array1 := Ar_List TrudyRef, SunnyRef, DocMitchellRef, EasyPeteRef, GSJoeCobbRef, GSChetRef

let array2 := ar_CustomSort array1, MyComparisonUDF

Now array2 is a regular array custom sorted, which in our case means in descending order of medicine skill:

    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

If the Ar_CustomSort function was called with the optional ReverseSort boolean, it'll sort the array in reverse order, which in our case means in ascending order of medicine skill (due to implementation of the UDF):

    0    GSJoeCobbRef
    1    EasyPeteRef
    2    SunnyRef
    3    TrudyRef
    4    GSChetRef
    5    DocMitchellRef    

See Also