====== Functions ======

Functions in XC=BASIC are essentially the same as [[subroutines|Subroutines]], with one important difference: functions //must// return a value. Everything else that is described on the [[subroutines|previous page]] is true for functions and will not be repeated here.

===== Defining the return type =====

A function must always return a type, that is, the type of the value that it returns. You must define the return type in the function definition line using the ''AS'' keyword:

<code xcbasic>
FUNCTION <fn_name> AS <type> (<arg> AS <type>)
  <statements>  
END FUNCTION
</code>
===== Calling a function =====

Functions can not be called using the ''CALL'' keyword, but rather they must be invoked as part of an expression. A function call is treated like an expression and its type is concluded from the function's return type. For example:

<code xcbasic>
FUNCTION test AS LONG ()
  ' -- function body here
END FUNCTION

x = test()
' -- The variable x will be implicitly defined as LONG
' -- because the right hand side is a LONG type
</code>

<adm note>
For the above reason, there are no void functions in XC=BASIC. [[subroutines|Subroutines]] serve as void functions.
</adm>
===== Returning a value =====

There are two ways to return a value from a function:

  * The QBASIC style, by assigning a value to the function name.
  * Using the ''RETURN'' keyword.

Both styles are accepted in XC=BASIC. Here are two examples to demonstrate each:

<code xcbasic>
' -- returning value the QBASIC style
FUNCTION test AS BYTE ()
  test = 42
END FUNCTION
PRINT test() ' will output 42
</code>

<code xcbasic>
' -- returning value using the RETURN keyword
FUNCTION test AS BYTE ()
  RETURN 42
END FUNCTION
PRINT test() ' will output 42
</code>

The above two codes are identical, but the ''RETURN'' keyword comes with a restriction: it immediately exits the function. There can be, however, situations where you want to continue executing the function even after specifying the return value, for example:

  (TODO: provide example)

Note the use of the ''EXIT FUNCTION'' command that is used to early exit the function.

<adm warning>
If the code exits from a function before any return value was specified, an undefined value will be returned.
</adm>