FUNCTION

Top  Previous  Next

 

The FUNCTION statement introduces a user written.

 

 

Format

 

FUNCTION name{(arg1 {, arg2...}) {VAR.ARGS}}

 

where

 

nameis the name of the function.

 

arg1, etcare the names of the arguments to the function.

 

 

QMBasic programs should commence with a PROGRAM, SUBROUTINE, FUNCTION or CLASS statement. If none of these is present, the compiler behaves as though a PROGRAM statement had been used with name as the name of the source record.

 

A function is a special form of subroutine. It returns a value to the calling program and can be referenced in a QMBasic statement in the same way as the intrinsic functions described in this manual, without the need for an explicit CALL statement. The FUNCTION statement is equivalent to a SUBROUTINE statement with an additional hidden argument at the start which is used to return the result.

 

The number of arguments in calls to the function must be the same as in the FUNCTION statement unless the function is declared with the VAR.ARGS option. When VAR.ARGS is used, any arguments not passed by the caller will be unassigned. The ARG.COUNT() function can be used to determine the actual number of arguments passed, excluding the hidden return argument.

 

Function arguments are normally passed by reference such that changes made to the argument variable inside a subroutine will be visible in the caller's variable referenced by that argument. A function call allows arguments to be passed by value by enclosing them in brackets. The FUNCTION statement also supports this dereferencing syntax. For example

 

FUNCTION CREDIT(P, (Q))

 

The FUNCTION statement must appear before any executable statements. The brackets are optional if there are no arguments. The FUNCTION statement may be split over multiple lines by breaking after a comma.

 

The name used in a FUNCTION statement need not be related to the name of the source record though this eases program maintenance. The name must comply with the QMBasic name format rules.

 

An argument may refer to a whole matrix. In this case the argument variable name must be preceded by the keyword MAT and there must be a DIM statement following the function declaration to indicate whether this is a one or two dimensional matrix. Alternatively, the dimensions may be given after the variable name in the FUNCTION statement. In either case, the actual dimension values are counted by the compiler but otherwise ignored. Use of a dimension value of one emphasises to readers of the program that the value is meaningless. A matrix passed as an argument cannot be redimensioned in the function.

 

Programs that use the function must include a DEFFUN statement to define the function template.

 

 

Example

 

FUNCTION MATMAX(MAT A)

  DIM A(1)

  MAX = A(1)

  N = INMAT(A)

  FOR I = 1 TO N

     IF A(I) > MAX THEN MAX = A(I)

  NEXT I

 

  RETURN MAX

END

 

This function scans a one dimensional matrix and passes back the value of the largest element. The first two lines could alternatively be written as

 

FUNCTION MATMAX(MAT A(1))

 

See also:

DEFFUN