Futurebasic/Language/Reference/local fn

Description
This statement marks the beginning of an FB local function. The end of the local function is marked by the  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  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  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, etc. The statements in   can contain anything except the following:

 A  statement;

An  block;

Another local function.



Adding the  keyword causes all of the function's local variables and arrays (except the parameter variables ,   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 statement with the  keyword; see the  statement for more information.)

The  must be unique; that is, it must be different from the name used in any other ,  ,  ,   or  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. For example, a local function which is to return a string value might be declared as follows:

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  if the function does not return a value.

In order to execute the statements in, your program must "call" the function using the  statement. The statement can appear anywhere in your program, as long as the function it calls is either defined (using the   statement) or prototyped (using the   statement) somewhere above the   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 's.

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

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

When your program calls the function, the arguments passed to it in the  statement are called the "actual arguments." They must match the function's formal arguments in number, and they must be of "compatible types" (see  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, 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.

If the formal argument is of the form, or  , 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  or. In the second case, the value of the long integer expression is copied into  or.

If the formal argument is, 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

.

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  statement. For example, suppose we have a function defined like this:

When we pass a long integer array to, 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:

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, we can set the first subscript in   to values much greater than 1, even though  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  statement) and the external   statement that declares the actual passed array.

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

Here, if  returns a value of 7, then the value 42 will be assigned to.

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  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:

After the preceding is executed,  points to an area of memory (the old address of  ) 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.

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 calls itself. It would be very difficult to write such a program without using recursive functions.

Returning Multiple Values The  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 ) 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  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  formal parameter.



Example: