# Defining a Function

Jump to navigation
Jump to search

**Navigation: PGMs ➔ Functions**

Functions | Subroutines | Classes | |||||
---|---|---|---|---|---|---|---|

Defining a Function | Predefined Functions | Tag Functions | Mathematical Functions | String Functions | Defining a Subroutine | Trigger Subroutines | Defining a Class |

## Introduction

A function is a set of common tasks that can be defined once and called multiple times from within a PGM.

- A function is very similar to a subroutine. In many instances, either could be used.
- A subroutine can be used instead of a function if a value does not need to be returned.
- If a value does need to be returned then a function will need to be used.

## Syntax

```
Function functName (argument list)
...statements...
Return value
EndFunct
```

```
StrFunction functName (argument list)
...statements...
Return string value
EndFunct
```

**functName** : is an unique name of the function, used to refer to the function.

**argument list** : optional list of parameters in the following format : (*datatype* parameterName, *datatype* parameterName...etc)

- The
**function**declaration must begin with the*Function*or*StrFunction*keyword and end with the*EndFunct*keyword. - Use
**StrFunction**if the function is going to return a string and**Function**if the function is going to return a numerical value. - A function may call itself (ie recursive functions are allowed). However, a true stack of the function variables is not used.
- Every possible execution path must use
*Return*to ensure that the function is exited correctly. - The
*parameter list*cannot include instance of classes or variables passed by reference. - Empty parentheses must be inserted, if no parameters are required by the function.
- Local variables can be declared within the function, and their scope is limited to the function. However when a function calls itself recursively a local stack is not used.
- Function definitions cannot be nested (ie functions cannot be defined within functions).

## Examples and Use

**Function Examples**

Number | Defining the Function | Calling the Function |
---|---|---|

Example 1 |
```
Function HoursToMinutes(Real timeInHours)
Return timeInHours*60
EndFunct
``` |
```
Real TimeInMinute@
TimeInMinute = HoursToMinutes(3)
``` |

Example 2 |
```
Array c5
;this function initialises the array
function SetupArray()
if (c5.Load("array.csv")) ;attempt to load the array from a file
LogNote("loaded array")
c5.SetLen(Max(c5.GetLen(),3)) ;ensure the array has at least three elements
return 0 ;exit function
endif
c5.SetLen(6) ;set the length of the array
c5.SetAll(1) ;set all the elements of the array to 1
return 0
endfunct
``` |
```
Sub InitialiseSolution()
SetupArray() ;array gets setup when run is pressed or PGM is reloaded
EndSub
``` |

Example 3 |
```
;this function places a random number in each element of the array
function RndLoop(byte Cnt)
while (Cnt>0)
Cnt = Cnt - 1
c5.SetAt(Cnt, random(10) - 5) ;set the specified element in the array
endwhile
return 0
endfunct
``` |
```
if (Random(100)<10)
RndLoop(c5.GetLen()) ;a ten percent chance that the function will be called
else
c5.SetAt(0, c5.GetAt(1) * c5.GetAt(2)) ;set c5[0] = c5[1]*c5[2]
endif
``` |

Example 4 |
```
StrFunction MakeTag(Str Prefix, long No)
return Concatenate(Prefix, "_", IntStr(No, 0))
endfunct
``` |
```
Str s1*
s1 = MakeTag("P", 3)
``` |

**Examples**: Mathematical Function Examples, String Function Examples, Example PGM Files