Futurebasic/Language/Reference/local fn

LOCAL FN

Syntax

[CLEAR] LOCAL FN functionName [(arg1 [,arg2 ...])]    [statementBlock] END FN [= expr]

Description

This statement marks the beginning of an FB local function. The end of the local function is marked by the END FN statement. A local function is a named collection of statements which can be accessed and executed as a unit by referring to the function's name (see the FN <userFunction> statement). All variables and arrays referenced in a local function (except those explicitly declared as "global") are local to the function, which means they do not have any influence outside of the function; any identically-named variables which appear outside of the function are actually different variables, and occupy a different place in memory, than the function's local variables. (An exception to this rule occurs when an array is listed as one of the function's formal parameters; see more about this below.) When your program "calls" (executes) a local function, you can pass data into the function by means of its parameter list (also called its argument list), and you can receive a value back from the function by means of its return value. Local functions allow you to encapsulate complex programming tasks; they're a fundamental and extremely powerful programming construct.

In addition to marking the beginning of the function, the LOCAL FN statement also declares the function's name, the data type of its return value (if any), and the number and types of its input parameters (if any). A local function can be placed anywhere in the program, except inside another local function; you should also not place a local function inside a "block" structure such as LONG IF...END IF, etc. The statements in statementBlock can contain anything except the following:

• A LOCAL statement;
• An ENTERPROC...EXITPROC block;
• Another local function.

Adding the CLEAR keyword causes all of the function's local variables and arrays (except the parameter variables arg1, arg2 etc.) to be initialized to zeros, null strings or empty records, each time the function is called. Otherwise, the local variables and arrays will have unpredictable initial values. (You can accomplish the same effect by using the LOCAL statement with the CLEAR keyword; see the LOCAL statement for more information.)

The functionName must be unique; that is, it must be different from the name used in any other LOCAL FN, ENTERPROC FN, LONG FN, DEF FN USING or DEF FN <expr> statement anywhere else in the program. If the function is to return a value, then you should specify the data type of the return value by including an appropriate type-identifier suffix at the end of functionName. For example, a local function which is to return a string value might be declared as follows:

  LOCAL FN FullName$(idNum&)

The default data type of a function's return value is "long integer"; if the function is to return a long integer value, you can either include the "&" type-identifier suffix or omit it. No type-identifier suffix should be appended to functionName if the function does not return a value.

In order to execute the statements in statementBlock, your program must "call" the function using the FN <userFunction> statement. The FN <userFunction> statement can appear anywhere in your program, as long as the function it calls is either defined (using the LOCAL FN statement) or prototyped (using the DEF FN <prototype> statement) somewhere above the FN <userFunction> statement. This restriction is required in order to allow your program to compile; however, the actual order of execution of your program's statements is not affected by where you place your LOCAL FN's.

Function Parameters Each of the parameters arg1, arg2 etc. can have any of the following forms:

The parameters in the LOCAL FN statement are called the function's "formal arguments." They must not be global variables. You should not declare the formal argument variables in a DIM statement; they are implicitly declared by the LOCAL FN statement.

When your program calls the function, the arguments passed to it in the FN <userFunction> statement are called the "actual arguments." They must match the function's formal arguments in number, and they must be of "compatible types" (see FN <userFunction> for more information). Each time the function is called, values are assigned to its formal arguments as follows:

• If the formal argument is a simpleVar, the value of the actual argument is copied into simpleVar.
• If the formal argument is of the form ptrVar AS POINTER [TO someType], then the actual argument should be either a record variable or a long-integer expression. In the first case, the record's address is copied into ptrVar; in the second case, the long integer's value is copied into ptrVar.
• If the formal argument is of the form @longVar&, or @ptrVar AS POINTER [TO someType], then the actual argument must either be a variable (possibly a record variable), or a long integer expression preceded by "=". In the first case, the variable's address is copied into longVar& or ptrVar. In the second case, the value of the long integer expression is copied into longVar& or ptrVar.
• If the formal argument is array(dim1 [,dim2 ...]), then the actual argument must be the base element of an array of the same type, which has the same number of dimensions. The base element is the element in which all subscripts are set to zero. The entire array is then accessible to the local function, and (important!) any changes made to the array's elements within the function will persist after the function exits.

If the local function has no parameters, you should omit the parentheses after functionName

.

Passing an Array of Unknown Size Sometimes it's useful to write a local function which operates on an array passed in its parameter list, without knowing in advance the size of the passed array. For example, suppose you wish to write a function which sorts the elements of a long integer array, and you want it to work regardless of the declared size of the passed array.

When you declare an array as a formal parameter, FB ignores the value of the array's first declared dimension in the LOCAL FN statement. For example, suppose we have a function defined like this:

LOCAL FN SetElements(anArray&(1,7), max&)   'Set each element to 1492 in the array:   FOR i& = 0 TO max&     FOR j = 0 TO 7       anArray&(i&,j) = 1492     NEXT   NEXT END FN

When we pass a long integer array to FN SetElements, the passed array can have any size as its first declared dimension, as long as it has a second dimension declared as 7. For example:

DIM arrayOne&(1250,7), arrayTwo&(465,7) FN SetElements(arrayOne&(0,0), 1250) FN SetElements(arrayTwo&(0,0), 465)

Within the function, we can safely manipulate elements in the array as long as the subscripts we use don't exceed the declared dimensions of the actual array that was passed. Thus, in FN SetElements, we can set the first subscript in anArray& to values much greater than 1, even though anArray& was "declared" with dimensions (1,7).

Note: you do not have equal freedom with the second, third, etc. dimensions of the parameter array. If the array is multi-dimensional, the second and subsequent dimensions must be declared with the same values in both the "formal" array parameter (in the LOCAL FN statement) and the external DIM statement that declares the actual passed array.

Returning a Value If you specify an expr in the END FN statement, the function will "return" the value of expr. This can be any expression which is compatible with the type-identifier suffix (if any) that appears in functionName. When your function "returns" a value, it means that you can reference the function (using FN <userFunction>) as part of a string or numeric expression, and the function's return value will be substituted in the expression. For example:

   maxPuppets = 6 * FN storeCount%(x)

Here, if FN storeCount%(x) returns a value of 7, then the value 42 will be assigned to maxPuppets.

The Lifespan of Local Variables The memory space for a function's local variables is reserved when the function is called. This memory is released after the END FN statement is executed. Therefore, you should never make reference to a local variable's address after the function has finished executing; in particular, you should never pass a local variable's address back to the routine that called the function. For example:

'DON'T DO THIS! LOCAL FN myFunction&(x,y,z)   DIM r#   r# = SQR(x*x + y*y + z*z) END FN = @r#

   rAddr& = FN myFunction&(x,y,z)

After the preceding is executed, rAddr& points to an area of memory (the old address of r#) which is no longer reserved, and which should not be used.

On the other hand, it is permissible to pass a local variable's address into another local function. This works because the first local function has not yet finished executing when it calls the second local function. Therefore, the memory space holding the first function's local variables is still reserved intact while the second function executes.

'THIS IS OKAY: LOCAL FN FirstFn   DIM 255 myString$   'Pass address of local var into another FN:   FN SecondFN(@myString$) END FN   : LOCAL FN SecondFn(strAddr&)   BLOCKMOVE @gString$, strAddr&, LEN(gString$)+1 END FN

Recursive functions You can have several functions executing simultaneously, in the sense that one function can call a second function, which can call a third, and so on. If you design your function calls in such a way that a function can call a function that is already executing, then you have a "recursive function." The most obvious (but not the only) example of a recursive function is any function which calls itself. When that happens, we say that two (or more) "instances" of the function are executing simultaneously.

In FB, every currently executing "instance" of a local function maintains its own private set of local variables, and they don't interfere with the local variables of any other executing instance of that function. Calling a function recursively is very much like calling a "different" function which just happens to contain exactly the same program lines.

Although recursive functions may at first seem like a bizarre concept, they are perfectly acceptable, and often very useful. For example, here is a short program which prints all the permutations of the characters contained in a given input string; note that FNpermute_r calls itself. It would be very difficult to write such a program without using recursive functions.

'Function prototypes: DEF FN Permute(aString$) DEF FN permute_r(prefix$, suffix$)

INPUT "Enter a word: "; theWord$ FN Permute(theWord$) END

LOCAL FN Permute(aString$)    'Prints all permutations of the letters in aString$    FN permute_r("", aString$) END FN

LOCAL FN permute_r(prefix$, suffix$)   'Prints all permutations of prefix$+suffix$   'that start with prefix$   LONG IF suffix$ = ""     PRINT prefix$   XELSE     FOR i = 1 to LEN(suffix$)       'Move the i-th letter of suffix$ over to newprefix$:       newprefix$ = prefix$ + MID$(suffix$, i, 1)       newsuffix$ = LEFT$(suffix$,i-1) + MID$(suffix$,i+1)       'Now print all permutations that       'start with newprefix$       FN permute_r(newprefix$, newsuffix$)     NEXT   END IF END FN

Returning Multiple Values The END FN statement can return only a single numeric or string expression. But many times, it's useful to have a local function which can return more than one value. The way to accomplish this is through the function's parameter list. If you give the function access to the address of some external variable or array, then the function can alter the contents at that address, effectively modifying the value of that variable or array.

There are three ways to pass an address to your function:

• If you pass an entire array (using the array(dim1 [,dim2 ...]) syntax in the formal parameter list), then your function implicitly has access to the address of the passed array. Any changes you make to the array's elements inside your function are actually made to the external array, so the changes persist after the function exits.
• If you use the @var syntax in the function's formal parameter list, and specify a variable when you call the function, then the variable's address is copied into var. Your function can then modify the contents at that address.
• You can explicitly pass any address into a long integer or POINTER formal parameter.

Example: CD Example: LOCALFN.BAS

See Also

FN <userFunction>; LOCAL; @FN; DEF FN <prototype>