Keyword Reference


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]]


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


Variables and functions are case-insensitive, therefore SomeFunc() is the same as SoMEFunC(). and vice versa.

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 that the parameter should be treated as a reference to the original. By default the parameter is copied into a new variable but ByRef links the new variable to the original. 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. However, a literal cannot be passed to a ByRef parameter. ByRef should be used when passing large amounts of data (such as the contents of a file) where copying all the data would impose a significant performance penalty. Another advantage is that passing a parameter ByRef when the function is intended to change the content of the parameter removes any requirement to Return the changed value as the original is directly affected.

Declaring parameters as both ByRef and Const is useful when the large original variable must remain unchanged as AutoIt will return an error if the function attempts to alter it inadvertantly. The order of the keywords is not important, as long as they are both in front of the parameter 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. Note that AutoIt only copies an array parameter if the contents are changed, so it is only in this case that ByRef offers an advantage, although it is recommended that to use it in all cases.

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. Using Return with SetError() allows @error and @extended values to be returned as well as a value.

Note that function declarations cannot appear inside other function declarations.


Global/Local, #include, Const


Example 1

#include <MsgBoxConstants.au3>


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

    Local $iFoo = 2
    Local $iBar = 5
    MsgBox($MB_SYSTEMMODAL, "", "Today is " & today() & @CRLF & "$iFoo equals " & $iFoo)
    swap($iFoo, $iBar)
    MsgBox($MB_SYSTEMMODAL, "", "After swapping $iFoo and $iBar:" & @CRLF & "$iFoo now contains " & $iFoo)
    MsgBox($MB_SYSTEMMODAL, "", "Finally:" & @CRLF & "The larger of 3 and 4 is " & max(3, 4))
EndFunc   ;==>Example

Func swap(ByRef $a, ByRef $b) ;swap the contents of two variables
    Local $t = 0
    $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
        Return $y
EndFunc   ;==>max

Example 2

#include <MsgBoxConstants.au3>


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

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 $sVal = ""
    For $i = 1 To @NumParams
        $sVal &= Eval("v" & $i) & " "
    MsgBox($MB_SYSTEMMODAL, "", "@NumParams = " & @NumParams & @CRLF & @CRLF & $sVal)
EndFunc   ;==>Test_Numparams