Editing User Defined Function


{{Template:Community_Wiki}} 

==Overview==
User defined functions (UDF) are added by NVSE V4. They must be saved as 'object' type scripts that must use the "Function" block type only. Although 'object' type, they must not be attached to any object and are instead called directly by script name from within other scripts, using the [[Call]] command. 

UDFs may optionally return a single value of any type, using the [[SetFunctionValue]] command within them. They may optionally accept one or more arguments of any type, which are defined within curly braces:
<pre>
scn SomeUDF

int arg1 ; * args are optional
ref arg2
float arg3 ....

Begin Function { arg1, arg2, arg3... }
    ; * do whatever like any other script
End 
</pre>
and called in a similar way to regular functions:
<pre>
scn SomeOtherScript
...
call SomeUDF arg1, arg2, arg3...
</pre>

However, to assign the return to a variable, [[Let]] must be used rather than <b>set .. to ..</b>, and to use in a conditional, [[Eval|if eval]] rather than simply <b>if</b>:
<pre>
let SomeVariable := call SomeOtherUDF arg1

if eval (call SomeSuitableUDF)
    ; the UDF return evaluates to true
endif
</pre>

==Example==
<pre>
scn fnShuffle

; *** This script accepts a list array and returns it in a shuffled order
; ***

; * local vars
array_var aNew
int iKey
int iLast

; * args
array_var aList

Begin Function { aList }

    let aNew := Ar_Construct "array" ; * get a new empty list array

    while (Ar_Size aList) > 0        ; * while input array contains an element
        let iLast := Ar_Size aList   ; * get size of input array
        let iKey := Rand 0, iLast    ; * get random valid key for input array
        Ar_Append aNew, aList[iKey]  ; * append the random choice element to output array
        Ar_Erase aList, iKey         ; * erase that element from input array
    loop

    SetFunctionValue aNew            ; * return the shuffled array
    return

End
</pre>
The above example shows a user defined function that accepts a list array and returns it in a shuffled order. This might be called in another script, like:
<pre>
scn SomeOtherScript

array_var aBeatles

Begin GameMode ; * or some other block type

    let aBeatles := Ar_List JohnREF, PaulREF, GeorgeREF, RingoREF

    let aBeatles := Call fnShuffle aBeatles

    ; * The Beatles array is now in a shuffled order

End
</pre>
==Notes==
*UDFs may be used recursively by saving the script once first without the sub call.
*This article is a simple overview, seek external documentation for further information.

==See Also==
*[[Call]]
*[[SetFunctionValue]]
*[[Eval]]
*[[Let]]
*[[Script Compiler Override]]
==External Links==
*[http://www.loverslab.com/topic/26802-tutorial-nvse4-part-2-user-defined-functions-udfs/ Tutorial on User Defined Functions in NVSE 4]
[[Category:NVSE]]
[[Category:User Defined Functions]]
@@ Line 5: / Line 5: @@
 User defined functions (UDF) are added by NVSE V4. They must be saved as 'object' type scripts that must use the "Function" block type only. Although 'object' type, they must not be attached to any object and are instead called directly by script name from within other scripts, using the [[Call]] command.
-UDFs may optionally return a single value of any type, using the [[SetFunctionValue]] command within them. They may optionally accept up to 15 arguments of any type, which are defined within curly braces:
+UDFs may optionally return a single value of any type, using the [[SetFunctionValue]] command within them. They may optionally accept one or more arguments of any type, which are defined within curly braces:
 <pre>
 scn SomeUDF
@@ Line 33: / Line 33: @@
 </pre>
-==Examples==
+==Example==
-<pre>
-scn GetRandomForm
-; *** This script accepts a form list and returns one random form from it
-; local variables
-int iCount
-int iChoice
-ref RandomForm
-; arguments
-ref rFormList
-Begin Function { rFormList }
-    let iCount := ListGetCount rFormList
-    let iChoice := Rand 0, iCount
-    let RandomForm := ListGetNthForm rFormList, iChoice
-    SetFunctionValue RandomForm
-End
-</pre>
 <pre>
 scn fnShuffle
@@ Line 104: / Line 80: @@
 End
 </pre>
-==Accepting any type arguments (advanced)==
-In some contexts, it is useful to allow arguments of any type for a UDF. Since [[Array Variable|array]] elements can be any type, this can be conveniently achieved using the [[NVSE Expressions]], <b>*</b> ('box') and <b>&</b> ('unbox'), and the [[TypeOf]] / [[GetType]] functions.
-<pre>
-scn MyUDF
-array_var AnyTypeArgument
-Begin Function { AnyTypeArgument }
-    if eval (TypeOf *AnyTypeArgument) == "form"
-        ...
-End
-</pre>
-<pre>
-ref MyRef
-int MyInt
-call MyUDF &MyRef
-call MyUDF &MyInt
-</pre>
 ==Notes==
 *UDFs may be used recursively by saving the script once first without the sub call.
+*This article is a simple overview, seek external documentation for further information.
 ==See Also==