Syntax

Declares a named block of code that takes parameters and can give back a value. It runs to its end in one go, inside the current frame.

FUNCTION <name>([<parameter>, …]) [AS <type>]
  EXITFUNCTION [<value>]
  RETURN [<value>]
ENDFUNCTION [<value>]
Procedure <name>([<parameter>, …]) [AS <type>]
  ProcedureReturn [<value>]
EndProcedure
<parameter> = [OPTIONAL] <param> [AS <type>] [= <default>]
<parameter> = PARAMARRAY <param> [AS <type>]
<parameter> = <param> [AS <type>]...

Also written : ENDFUNCTION, EXITFUNCTION, Procedure, EndProcedure, ProcedureReturn, OPTIONAL, PARAMARRAY

Parts

<name>The function name. Case does not matter. A sigil ($, #, %, &) may end it, as a label only.
<parameter>One parameter, in one of the three forms below. Separate them with commas. The list may be empty.
<type>A numeric type, string, HANDLE, a TYPE you declared, or an array of them (integer[], up to six []). On the function, it converts every returned value.
<value>The value given back. Optional: without it, the function returns nothing, or the default of its AS type.
<param>The parameter name, local to the function.
<default>The value used when the caller leaves the argument out. It is computed at each call and may use an earlier parameter.

Returns

The value after ENDFUNCTION, EXITFUNCTION or RETURN, converted to the AS type if there is one. With no value: nothing (undefined when printed), or the default of the AS type (0, "", an empty record).

Good to know

  • ENDFUNCTION and EXITFUNCTION are one word. END FUNCTION is refused ("FUNCTION requires ENDFUNCTION"). EXIT FUNCTION in two words is not refused, but the program cannot run.
  • A call always carries parentheses, even with no argument: showTitle(). A bare showTitle compiles as a variable and fails only when the program runs.
  • Declare functions at the top level of a file, never inside an IF, a loop or another function. You may call a function above the line that declares it. A user function wins over a catalogue command of the same name.
  • A sigil on the name is not a conversion: whole%(9.8) with no AS returns 9.8. title$("x") and title("x") call the same function. To convert, write AS integer or AS string.
  • OPTIONAL without a default gives the default of the parameter type. A sigil does not type it: OPTIONAL name$ receives 0, not ""; write OPTIONAL name AS string. A required parameter cannot follow an optional one, and f(1, , 5) does not skip the middle argument: 5 lands in the second parameter.
  • A variadic parameter (PARAMARRAY values or values...) is the last one, has no default and cannot be REF. With a type, write values AS float...; values... AS float is refused. Its .length is the last index: three values give 2, none gives -1.
  • An untyped parameter shares a record or an array with the caller. A typed parameter gets a copy. To change the caller variable on purpose, use REF.
  • Several functions may share a name if their argument counts do not overlap. The compiler picks one by count only, never by type. Overlapping ranges give "Ambiguous BASIC overload".
  • Nothing that waits is allowed inside a function: END, Wait(), Sleep(), AWAITTASK, AWAITALL and AWAITANY are refused. Sync(), Swap() and YieldTask() are accepted, but in a program with DO … LOOP the program cannot start. Wait in the main loop, a GOSUB subroutine or a task.
  • In a program with DO … LOOP, a function does not see plain variables set above DO. Declare shared values with GLOBAL, and turn on OPTION EXPLICIT.
  • PureBasic: Procedure, ProcedureReturn and EndProcedure are aliases of FUNCTION, EXITFUNCTION and ENDFUNCTION. The typed form Procedure.s Name() is refused: write Procedure Name() AS string. Visual Basic has Sub; here a FUNCTION that returns nothing plays that role.

Example

FUNCTION Greet(name AS string = "stranger", OPTIONAL mark AS string) AS stringENDFUNCTION "Hello " + name + markFUNCTION Total(PARAMARRAY values AS integer) AS integer  LOCAL sum AS integer = 0  FOR i = 0 TO values.length    sum = sum + values[i]  NEXT iENDFUNCTION sumFUNCTION Sign(n)  IF n < 0 THEN EXITFUNCTION -1ENDFUNCTION 1Console(Greet())                 ' Hello strangerConsole(Greet("Ada", "!"))       ' Hello Ada!Console(Str(Total(2, 4, 9)))     ' 15Console(Str(Sign(-5)))           ' -1
In the manual : Functions

See also