Keyword Reference

Func...Return...EndFunc

Defines a user-defined function that takes zero or more arguments and optionally returns a result.

Func functioname ( [Const] [ByRef] $param1, ..., [Const] [ByRef] $paramN, $optionalpar1 = value, ...)
    ...
    [Return [value]]
EndFunc

Parameters

The parameters are set by you. You later call the function like any other built-in function.

Remarks

The Const keyword is optional and indicates that the value of the parameter will not change during the execution of the function. A variable declared Const can only be passed to a function using a Const parameter.

The ByRef keyword indicates the parameter should be treated as a reference to the original object. The default behavior copies the parameter into a new variable however ByRef links the new variable to the original parameter. ByRef is typically preferred when a function expects large amounts of data, such as a large array, where copying all the data would impose a significant performance penalty. Note that not only a named variable can be passed for a ByRef parameter; unnamed temporary variables, such as function return values, may be passed as ByRef parameters as well. A literal can not be passed to a ByRef parameter.

If using both keywords ByRef and Const with a function parameter, the order of the keywords is not important, so long as they are both in front of the variable they modify.

Entire arrays can be passed to functions (and returned from them) by simply using the array name without any brackets. Arrays should be passed to user-defined functions using the ByRef keyword to avoid the overhead of copying all the data in the array.

Optional parameters are defined by assigning a default value to them. The value may be a global variable, macro or literal value. Optional parameters always appear last in the function definition. All parameters added after the first optional parameter must also be optional. Inside the function, the number of parameters given when the function was called can be retrieved with the @NUMPARAMS macro (see example 2).

Use the Return keyword to exit the function. Unlike built-in functions, user-defined functions return 0 unless another return value is specified.

Note that function declarations cannot appear inside other function declarations.

Related

Dim/Global/Local, #include, Const

Example


Example1()
Example2()

; example1
Func Example1()
    ; Sample script with three user-defined functions
    ; Notice the use of variables, ByRef, and Return

    Local $foo = 2
    Local $bar = 5
    MsgBox(0, "Today is " & today(), "$foo equals " & $foo)
    swap($foo, $bar)
    MsgBox(0, "After swapping $foo and $bar", "$foo now contains " & $foo)
    MsgBox(0, "Finally", "The larger of 3 and 4 is " & max(3, 4))
EndFunc   ;==>Example1

Func swap(ByRef $a, ByRef $b) ;swap the contents of two variables
    Local $t
    $t = $a
    $a = $b
    $b = $t
EndFunc   ;==>swap

Func today() ;Return the current date in mm/dd/yyyy form
    Return (@MON & "/" & @MDAY & "/" & @YEAR)
EndFunc   ;==>today

Func max($x, $y) ;Return the larger of two numbers
    If $x > $y Then
        Return $x
    Else
        Return $y
    EndIf
EndFunc   ;==>max

;End of sample script 1

; example2
Func Example2()
    ; Sample scriptusing @NumParams macro
    Test_Numparams(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14)
EndFunc   ;==>Example2

Func Test_Numparams($v1 = 0, $v2 = 0, $v3 = 0, $v4 = 0, $v5 = 0, $v6 = 0, $v7 = 0, $v8 = 0, $v9 = 0, _
        $v10 = 0, $v11 = 0, $v12 = 0, $v13 = 0, $v14 = 0, $v15 = 0, $v16 = 0, $v17 = 0, $v18 = 0, $v19 = 0)
    #forceref $v1, $v2, $v3, $v4, $v5, $v6, $v7, $v8, $v9, $v10, $v11, $v12, $v13, $v14, $v15, $v16, $v17, $v18, $v19
    Local $val
    For $i = 1 To @NumParams
        $val &= Eval("v" & $i) & " "
    Next
    MsgBox(0, "@NumParams example", "@NumParams =" & @NumParams & @CRLF & @CRLF & $val)
EndFunc   ;==>Test_Numparams

;End of sample script 2