Keyword

# Function

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Description

Declares the name, parameters, returned value, and code that form the body of a <span class="title-ref">Function</span> (method that returns a value).

## Usage

For use in `XojoScript</api/language/xojo_script/xojoscript>` code:

``` xojo
Function name ([ parameterList ]) As type
  [ local variable declarations ]
  [ statements ]
  [ Return ... ]
  [ statements ]
  [ exception handlers ]
  [ Finally ]
    [ statements ]
 End [ Function ]
```

| Part          | Description                                                                                                                                                                                                                                                                                                                                              |
|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| name          | Required. The name of the <span class="title-ref">function</span> (method); follows standard variable naming conventions.                                                                                                                                                                                                                                |
| parameterList | Optional list of values representing parameters that are passed to the <span class="title-ref">function</span> 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</api/language/const>`, or an `enum</api/data_types/enumeration>`. |
| type          | The data type of the value returned by the <span class="title-ref">function</span>.                                                                                                                                                                                                                                                                      |

## Notes

The <span class="title-ref">Function</span> 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</api/math/abs>`, `String.Length<string.length>`, etc. All executable code must be in a `Sub</api/language/sub>` or <span class="title-ref">Function</span> statement. A <span class="title-ref">Function</span> differs from a `Sub</api/language/sub>` in that a <span class="title-ref">Function</span> can be used on the right side of an expression and a `Sub</api/language/sub>` cannot. A <span class="title-ref">Function</span> cannot be defined inside another `Sub</api/language/sub>` or <span class="title-ref">Function</span>. A <span class="title-ref">Function</span> 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 <span class="title-ref">Function</span>.

You call a <span class="title-ref">Function</span> 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:

``` xojo
ParameterName As DataType
```

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:

``` xojo
ParameterName As DataType = DefaultValue
```

For example, if you want to declare the parameter "startValue" as an Integer and give it value of 1, you would write

``` xojo
startValue As Integer = 1
```

You can provide default values for more than one parameter. For example, the following is valid:

``` xojo
a As Integer = 10, b As Integer = 20
```

When you pass a default value, you can use either a literal (as shown here), a `constant</api/language/const>`, or an `enum</api/data_types/enumeration>`. 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:

``` xojo
a As Integer = InitialValue
```

Similarly, you can use an `enum</api/data_types/enumeration>` as a default value. Suppose you have created an `enum</api/data_types/enumeration>` 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:

``` xojo
a As Integer = SecurityLevel.Forced
```

All variables used in a <span class="title-ref">Function</span> must be declared before they are used in a statement. Variables and parameters used in a <span class="title-ref">Function</span> are local. Properties can be accessed from within any `Sub</api/language/sub>` or <span class="title-ref">Function</span>. Local variables are variables that are created each time the <span class="title-ref">Function</span> is run and destroyed when the <span class="title-ref">Function</span> finishes. Consequently, they can only be accessed by the statements within the <span class="title-ref">Function</span>. They are created by using the `Var</api/language/var>` statement from within a `Sub</api/language/sub>` or <span class="title-ref">Function</span>. A `Var</api/language/var>` statement can be placed anywhere within the <span class="title-ref">Function</span>.

The `Return</api/language/return>` statement can be used to immediately return control to the statement that called the <span class="title-ref">Function</span> and to pass back a value to the left side of the statement. If the `Return</api/language/return>` statement is not called, the default value of the data type returned by the <span class="title-ref">Function</span> is returned (Nil for objects).

Exception handlers are statements that handle errors. See the `RuntimeException</api/exceptions/runtimeexception>`\<nowiki/\>class and the `Try</api/language/try>` and `Exception</api/exceptions/exception>` statements for more information.

If your method does not need to return a value, you declare it as a `Sub</api/language/sub>`. A `Sub</api/language/sub>` is a method that does not return a value. See the `Sub</api/language/sub>` statement for more information.

The variable that is returned by a <span class="title-ref">Function</span> can be a “regular” single-element variable or an array. When you want to return one value, 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 <span class="title-ref">Function</span>'s Return Type field.

If you need to return several values but not in the form of an array, you can use the `ByRef</api/language/byref>` keyword when you define the routine's parameters. Using `ByRef</api/language/byref>`, you can return the results into the parameters.

A <span class="title-ref">Function</span> method can call itself, resulting in recursion. Too much recursion can lead to stack overflow errors.

Sometimes a <span class="title-ref">Function</span> needs to do some cleanup work whether it is finishing normally or aborting early because of an exception. The optional `Finally</api/language/finally>` block at the end of the <span class="title-ref">Function</span> 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</api/language/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:

``` xojo
Const CurrentMethodName = "methodname"
```

For example, if you create a method, MyNewMethod, belonging to Window1 that has the code:

``` xojo
MessageBox(CurrentMethodName)
```

A call to this method will display the name "Window1.MyNewMethod".

## Sample code

This example is a <span class="title-ref">Function</span> that calculates area based on the length and height passed.

``` xojo
Function Area(length As Double, height As Double) As Double
  Var theArea As Double
  theArea = length * height
  Return theArea
End Function
```

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

This example shows the Area <span class="title-ref">Function</span> above written in a simpler form (without the extra local variable).

``` xojo
Function Area(length As Double, height As Double) As Double
  Return length * height
End Function
```

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

This example shows the Area <span class="title-ref">Function</span> above being called and its returned value assigned to variable.

``` xojo
Var a As Double
a = Area(10, 10) ' returns 100
```

## Compatibility

|                       |     |
|-----------------------|-----|
| **Project Types**     | All |
| **Operating Systems** | All |

<div class="seealso">

`Break</api/language/break>`, `Catch</api/language/catch>`, `Exit</api/language/loops/exit>`, `Finally</api/language/finally>`, `Raise</api/language/raise>`, `Return</api/language/return>`, `Sub</api/language/sub>` statements; `RuntimeException</api/exceptions/runtimeexception>` class; `CurrentMethodName</api/language/currentmethodname>` constant.

</div>