Q(uick)BASIC Statement: FUNCTION

A parameterlist has the following syntax:

• variable[( )][AS type][,variable[()][AS type]]

A variable is any valid BASIC variable. The optional type can be either INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined type.

Earlier versions of BASIC required the number of dimensions in parentheses after an array name. The number of dimensions is no longer required. Only the parentheses are required to indicate the parameter is an array. For example, the following statement indicates that both Keywords$ and KeywordTypes are arrays:

• FUNCTION ParseLine(Keywords$(),KeywordTypes())

A FUNCTION procedure is like a SUB procedure: it can accept parameters, perform a series of statements, and change the values of its parameters. Unlike a SUB, a FUNCTION is used in an expression in the same manner as a BASIC intrinsic function.

Like SUB procedures, FUNCTION procedures use local variables. Any variable not in the parameter list is local to the FUNCTION unless it is declared as a shared variable in a SHARED statement, or unless the variable appears in a DIM or COMMON statement with the SHARED attribute.

To return a value from a function, assign the value to the function name. For example, in a function named BinarySearch, you might assign the value of the constant FALSE to the name to indicate the value was not found:

• FUNCTION BinarySearch(…)
• CONST FALSE=0
• ⋮
• ' Value not found. Return a value of FALSE.
• IF Lower>Upper THEN
• BinarySearch=FALSE
• EXIT FUNCTION
• END IF
• ⋮
• END FUNCTION

Using the STATIC keyword slightly increases execution speed. STATIC is not usually used with recursive FUNCTION procedures.

The EXIT FUNCTION statement provides an alternative exit from a FUNCTION. See the EXIT statement.

Because BASIC may rearrange arithmetic expressions to attain greater efficiency, avoid using FUNCTION procedures that change program variables in arithmetic expressions. Also avoid using FUNCTION procedures that perform I/O in I/O statements.

QuickBASIC FUNCTION procedures are recursive - they can call themselves to perform a given task. See the second example below.

• The type of name determines the type of value the function returns. For example, to create a function that returns a string, you would include a dollar sign in the name or give it a name defined as a string name by a DEFSTR statement. FUNCTION procedure names follow the rules for naming BASIC variables.
• Names in the parameterlist are separated by commas. The syntax of parameterlist is:

• [BYVAL] variable[( )] [AS type] [,[BYVAL] variable[()] [AS type]]…

• STATIC indicates that the function's local variables are to be saved between calls. Without STATIC, the local variables are allocated each time the function is invoked, and the variables' values are lost when the function returns to the calling program. The STATIC attribute does not affect variables that are used in a FUNCTION procedure but declared outside the FUNCTION procedure in DIM or COMMON statements using the SHARED statement.
• The expression is the return value of the function. A FUNCTION procedure returns a value by assigning a value to the function name. If no value is assigned to the FUNCTION name, the FUNCTION procedure returns a default value: a numeric function returns 0, and a string function returns the null string ("").
• EXIT FUNCTION immediately exits a FUNCTION procedure. Program execution continues where the function was invoked. EXIT FUNCTION can be used only in a FUNCTION procedure. For more information, see the ⮜ EXIT ⮞.

Usage Notes

• If a parameter is passed by reference, any change to the parameter's value inside the procedure changes its value in the calling program.
• If a parameter is passed by value, any changes to the parameter's value inside the procedure is local to that procedure and does not affect its value in the calling program.
• Earlier versions of BASIC required the number of dimensions in parentheses after an array name. The number of dimensions is no longer required. Only the parentheses are required to indicate the parameter is an array. For example, the following statement indicates that both Keywords$ and KeywordTypes are arrays:

• FUNCTION ParseLine (Keywords$(), KeywordTypes())

• Earlier versions of BASIC did not allow you to pass arrays containing fixed-length strings as parameters. BASIC now supports this.
• A FUNCTION procedure is like a SUB procedure: it can be defined with parameters, perform a series of statements, and change the values of its parameters. A FUNCTION procedure is always used in an expression in the same manner as a BASIC intrinsic function.
• Like SUB procedures, FUNCTION procedures can use local variables. Any variable referred to within the body of the function is local to the FUNCTION unless one of the following conditions is true:
  • The variable is declared within the function as a shared variable in a SHARED statement
  • The variable appears in a DIM or COMMON statement with the SHARED attribute at the module level
• To return a value from a function, assign the value to the function name. For example, in a function named BinarySearch, you might assign the value of the constant FALSE to the name to indicate the value was not found:

• FUNCTION BinarySearch(…)
• CONST FALSE=0
• ⋮
• ' Value not found. Return a value of FALSE.
• IF Lower>Upper THEN
• BinarySearch=FALSE
• EXIT FUNCTION
• END IF
• ⋮
• END FUNCTION

• Using the STATIC attribute increases execution speed slightly. STATIC is usually not used with recursive FUNCTION procedures.
• Because BASIC may rearrange arithmetic expressions to attain greater efficiency, avoid using FUNCTION procedures that change program variables in arithmetic expressions. Also, avoid using FUNCTION procedures that perform I/O.
• FUNCTION procedures can be recursive--they can call themselves to perform a given task. See the example for more information.

Important

• Avoid using I/O statements in a FUNCTION procedure called from an I/O statement; they can cause unpredictable results. Also, because BASIC may rearrange arithmetic expressions to attain greater efficiency, avoid using FUNCTION procedures that change program variables in arithmetic expressions.