FUNCTION Statement ---------------------------------------------------------------------------- Action Declares the name, the parameters, and the return type of a FUNCTION procedure. Syntax FUNCTION name -( parameterlist-) - STATIC- - statementblock- - name = expression- - statementblock- - EXIT FUNCTION- - statementblock- END FUNCTION Remarks The following list describes the parts of the FUNCTION statement. ----------------------------------------------------------------------------- Part Description ---------------------------------------------------------------------------- name The name of the function. FUNCTION procedure names follow the same rules as are used for naming BASIC variables and can include a type-declaration character (%, &, !, #, @, or $). Note that the type of the name determines the data type the function returns. For example, to create a function that returns a Part Description ---------------------------------------------------------------------------- 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. parameterlist The list of variables, representing parameters, that will be passed to the function procedure when it is called. Multiple variables are separated by commas. Parameters are passed by reference, so any change to a parameter's value inside the function changes its value in the calling program. STATIC Indicates that the function's local variables are to be saved Part Description ---------------------------------------------------------------------------- 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 procedure in DIM or COMMON statements using the SHARED statement. expression 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, Part Description ---------------------------------------------------------------------------- assigned to the FUNCTION name, the procedure returns a default value. a numeric function returns zero, and a string function returns the null string (""). EXIT FUNCTION Causes an immediate exit from a FUNCTION procedure. Program execution continues where the procedure was invoked. For more information, see the entry for the EXIT statement. The argument parameterlist has the following syntax. variable -()- - AS type- -, variable-()- - AS type--... The following list describes the parts of parameterlist . ----------------------------------------------------------------------------- Argument Description ---------------------------------------------------------------------------- variable A BASIC variable name. Previous versions of BASIC required the number of dimensions in parentheses after an array name. In the current version of BASIC, the number of dimensions is not required. AS type The type of the variable. INTEGER, LONG, SINGLE, DOUBLE, STRING, CURRENCY, or a user-defined type. You cannot use a fixed-length string, or an array of fixed-length strings, as a parameter. However, you can use a simple fixed-length string as an argument in a CALL statement; Argument Description ---------------------------------------------------------------------------- argument in a CALL statement; BASIC converts a simple fixed-length string argument to a variable-length string argument before passing the string to a FUNCTION procedure. 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 procedure, a FUNCTION procedure is used in an expression in the same manner as a BASIC intrinsic function. Like SUB procedures, FUNCTION procedures use local variables. Any variable referred to within the body of the function is local to the FUNCTION procedure unless one of the following conditions is true. - The variable is declared within the function as a shared variable with 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 usually is not used with recursive FUNCTION procedures. Note 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. FUNCTION procedures are recursive -- they can call themselves to perform a given task. See the example for more information. See Also DECLARE (BASIC), DEF FN, STATIC Statement, SUB Example The following example uses a recursive FUNCTION procedure (a procedure that calls itself) to find, and return as an integer, the length of a string. DECLARE FUNCTION StrgLng% (X$). INPUT "Enter a string. "; InString$ PRINT "The string length is"; StrgLng%(InString$) FUNCTION StrgLng% (X$) IF X$ = "" THEN StrLng% = 0 ' The length of a null string is zero. ELSE StrgLng% = 1 + StrgLng%(MID$(X$, 2)) ' Make a recursive call. END IF END FUNCTION