Definiert eine Benutzerfunktion, die Null oder mehr Argumente aufnimmt und optional ein Ergebnis zurückgibt.

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

Parameter

Bemerkungen

Bei Variablen und Funktionen wird die Groß- und Kleinschreibung ignoriert. Dies bedeutet, dass SomeFunc() das gleiche ist wie SoMEFunC() und umgekehrt.

Das Schlüsselwort Const ist optional und zeigt an, dass sich der Wert des Parameters während der Ausführung der Funktion nicht ändert. Es wird automatisch eine neue lokale Variable deklariert, wenn man die Parameter-Variable nicht als Konstante deklariert bzw. weiter gibt.

Das Schlüsselwort ByRef zeigt an, dass der Parameter als Referenz zu dem Originalobjekt behandelt werden soll. Standardmäßig wird der Parameter in eine neue Variable kopiert. Jedoch verknüpft ByRef die neue Variable auf den Originalparameter. Es ist zu beachten, dass nicht nur eine benannte Variable als ByRef Parameter übergeben werden kann; unbenannte temporäre Variablen, wie zum Beispiel Rückgabewerte von Funktionen, können genauso als ByRef Parameter übergeben werden. Literale (z. B: "Peter" oder 123) können jedoch nicht als ByRef-Parameter übergeben werden. ByRef ist zu bevorzugen wenn eine Variable große Mengen an Daten beinhaltet wie zum Beispiel den Inhalt einer Datei. Wird dies nicht getan, so erweist sich das kopieren aller Daten als Bremsklotz. Ein anderer Vorteil des übergebens eines Parameters durch ByRef ist, dass wenn die Funktion beabsichtigt den Inhalt des Parameters zu ändern jegliche Notwendigkeit von Return entällt, da der Wert im Original direkt geändert wird.

Das Deklarieren von Parametern mit der Kombination von ByRef und Const ist nützlich, wenn die große ursprüngliche Variable unverändert bleiben muss, da AutoIt einen Fehler zurückgibt, wenn die Funktion versucht, sie zu ändern. Die Reihenfolge der Schlüsselwörter ist nicht wichtig, solange sie sich vor dem Parameter befinden, den sie ändern.

Komplette Arrays können an Funktionen über- und von ihnen zurückgegeben werden, indem einfach der Arrayname ohne Klammern angegeben wird. Arrays sollten an eine benutzerdefinierte Funktion nur mit dem Schlüsselwort ByRef übergeben werden, da somit das unnötige und langwierige Kopieren der kompletten Daten des Arrays vermieden wird. Es ist zu beachten, dass AutoIt nur einen Array-Parameter kopiert wenn sich der Inhalt ändert. Dies ist nur der Fall wenn ByRef einen Vorteil bringt, obwohl es zu empfehlen ist es in allen Fällen zu verwenden.

Optionale Parameter werden definiert, indem man ihnen einen Standardwert zuweist. Das kann eine globale Variable, ein Makro oder Literal sein.
Optionale Parameter erscheinen immer am Ende der Funktionsdeklaration. Wurde ein Parameter als optional deklariert, müssen alle folgenden Parameter ebenfalls optional sein und Standardwerte erhalten.
Innerhalb der Funktion kann die Anzahl der beim Aufruf angegebenen Parameter über das Makro @NumParams in Erfahrung gebracht werden. (siehe Beispiel 2)

Verwenden Sie das Schlüsselwort Return, um die Funktion zu verlassen. Im Gegensatz zu integrierten Funktionen geben benutzerdefinierte Funktionen 0 zurück, sofern kein anderer Rückgabewert angegeben wird. Wird Return mit SetError() verwendet, können @error- und @extended-Werte sowie ein Wert zurückgegeben werden.

Es ist zu beachten, dass Funktionsdeklarationen nicht innerhalb anderer Funktionsdeklarationen stattfinden dürfen.

Verwandte Funktionen

Const, Global/Local, #include

Beispiel

Beispiel 1

#include <Date.au3>
#include <Math.au3>
#include <MsgBoxConstants.au3>

Example()

Func Example()
    ; Beispielskript mit drei benutzerdefinierten Funktionen
    ; Beachten sie die Nutzung von Variablen, ByRef und Return

    Local $iFoo = 2
    Local $iBar = 5
    MsgBox($MB_SYSTEMMODAL, "", "Heute ist der " & Today() & @CRLF & "$iFoo hat den Wert " & $iFoo)
    Swap($iFoo, $iBar)
    MsgBox($MB_SYSTEMMODAL, "", "Nach dem Tausch von $iFoo und $iBar" & @CRLF & "enthält $iFoo jetzt " & $iFoo)
    MsgBox($MB_SYSTEMMODAL, "", "Zum Schluss" & @CRLF & "Der größere Wert von 3 und 4 ist " & _Max(3, 4))
EndFunc   ;==>Example

Func Swap(ByRef $vVar1, ByRef $vVar2) ; Vertauscht den Inhalt zweier Variablen
    Local $vTemp = $vVar1
    $vVar1 = $vVar2
    $vVar2 = $vTemp
EndFunc   ;==>Swap

Func Today() ; Gibt das aktuelle Datum in der Form Tag.Monat.Jahr zurück.
    Return (@MDAY & "." & @MON & "." & @YEAR)
EndFunc   ;==>Today

Beispiel 2, welches das @NumParams Makro verwendet

#include <MsgBoxConstants.au3>

Example()

Func Example()
    ; Beispielskript, welches das @NumParams Makro verwendet
    Test_Numparams(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14)
EndFunc   ;==>Example

Func Test_Numparams($vVar1 = 0, $vVar2 = 0, $vVar3 = 0, $vVar4 = 0, $vVar5 = 0, $vVar6 = 0, $vVar7 = 0, $vVar8 = 0, $vVar9 = 0, _
        $vVar10 = 0, $vVar11 = 0, $vVar12 = 0, $vVar13 = 0, $vVar14 = 0, $vVar15 = 0, $vVar16 = 0, $vVar17 = 0, $vVar18 = 0, $vVar19 = 0)
    #forceref $vVar1, $vVar2, $vVar3, $vVar4, $vVar5, $vVar6, $vVar7, $vVar8, $vVar9, $vVar10
    #forceref $vVar11, $vVar12, $vVar13, $vVar14, $vVar15, $vVar16, $vVar17, $vVar18, $vVar19
    Local $sVal = ""
    For $i = 1 To @NumParams
        $sVal &= Eval("vVar" & $i) & " "
    Next
    MsgBox($MB_SYSTEMMODAL, "", "@NumParams = " & @NumParams & @CRLF & @CRLF & $sVal)
EndFunc   ;==>Test_Numparams