Function
From Xojo Documentation
Declares the name, parameters, returned value, and code that form the body of a function (method that returns a value).
Usage
For use in XojoScript code:
Function name ([parameterList]) As type
[local variable declarations]
[statements]
[ Return ... ]
[statements]
[exception handlers]
[ Finally ]
End [Function]
| Part | Description |
|---|---|
| name | Required. The name of the function (method); follows standard variable naming conventions. |
| parameterList | Optional list of values representing parameters that are passed to the function when it is called. Multiple parameters are separated by commas. You can optionally assign default values to parameters. The default value can be a literal, a constant, or an enum. |
| type | The data type of the value returned by the function. |
Notes
The Function statement is used to define a method that can be used on the right side of an expression just like the built-in functions such as Abs, Len, etc. All executable code must be in a Sub or Function statement. A Function differs from a Sub in that a Function can be used on the right side of an expression and a Sub cannot. A function cannot be defined inside another Sub or function. A function executes each line of code from the top down. Once the last line of code is executed, control returns to the line that called the function.
You call a function by using its name followed by its parameters in parentheses.
When you declare parameters, you declare the name of each parameter and its data type in the form:
If you declare more than one parameter, separate each declaration with a comma. You can optionally set a default value for the parameter using the syntax:
For example, if you want to declare the parameter "startValue" as an Integer and give it value of 1, you would write
You can provide default values for more than one parameter. For example, the following is valid:
When you pass a default value, you can use either a literal (as shown here), a constant, or an enum. If you don't provide a default value, the parameter takes the default value for the data type, e.g., 0 for numbers, an empty string ("") for Strings, and Nil for objects.
A constant is used as a default value using the same syntax. For example, suppose you define a global constant in a module, InitialValue. You can use it as a default value for a parameter like this:
Similarly, you can use an enum as a default value. Suppose you have created an enum in a module called SecurityLevel, with values None, Minimum, Maximum, and Forced. You can then assign the default value of a parameter using one of the enum values:
All variables used in a function must be declared before they are used in a statement. Variables and parameters used in a function are local. Properties can be accessed from within any Sub or function. Local variables are variables that are created each time the function is run and destroyed when the function finishes. Consequently, they can only be accessed by the statements within the function. They are created by using the Var statement from within a Sub or function. A Var statement can be placed anywhere within the function.
The Return statement can be used to immediately return control to the statement that called the function and to pass back a value to the left side of the statement. If the Return statement is not called, the default value of the data type returned by the function is returned (Nil for objects).
Exception handlers are statements that handle errors. See the RuntimeException class and the Try and Exception statements for more information.
If your method does not need to return a value, you declare it as a Sub. A Sub is a method that does not return a value. See the Sub statement for more information.
The variable that is returned by a function can be a “regular” single-element variable or an array. When you want to return one value, simply enter the data type of that variable in the Return Type field. To declare the variable as an array, place empty parentheses after the data type. For example, if you want to return an array of integers instead of only one integer, write "Integer()" instead of "Integer" as the function’s Return Type field.
If you need to return several values but not in the form of an array, you can use the ByRef keyword when you define the routine’s parameters. Using ByRef, you can return the results into the parameters.
A Function method can call itself, resulting in recursion. Too much recursion can lead to stack overflow errors.
Sometimes a function needs to do some cleanup work whether it is finishing normally or aborting early because of an exception. The optional Finally block at the end of the function serves this purpose. Code in this block will be executed even if an exception has occured, whether the exception was handled or not.
Constants
The built-in metaconstant CurrentMethodName is available in all methods and events. It automatically contains the fully qualified name of the method or event. It is the same as if the user had declared the constant manually:
For example, if you create a method, MyNewMethod, belonging to Window1 that has the code:
A call to this method will display the name "Window1.MyNewMethod".
Sample Code
This example is a function that calculates area based on the length and height passed.
Var theArea As Double
theArea = length * height
Return theArea
End Function
This example shows the Area function above written in a simpler form (without the extra local variable).
This example shows the Area function above being called and its returned value assigned to variable.
See Also
Break, Catch, Exit, Finally, Raise, Return, Sub statements; RuntimeException class; CurrentMethodName constant.