FUNCTION

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.

 

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 it is recommended that they are the same as this eases program maintenance. The name must comply with the QMBasic name format rules.

 

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.

 

 

Variable Length Argument Lists and Default Values

 

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. The ARG.PRESENT() function can be used to test for the presence of an optional argument by name.

FUNCTION CREDIT.RATING(CLIENT, CLASS, CODE) VAR.ARGS

In this example, if the calling program supplies only one argument, the CLASS and CODE variables will be unassigned. If the calling program provides two arguments, the CODE variable will  be unassigned.

 

 

When using VAR.ARGS, default values may be provided for any arguments by following the argument name with an = sign and the required numeric or string value or the @FALSE or @TRUE constants. For example,

FUNCTION CREDIT.RATING(CLIENT, CLASS = 1, CODE = "Standard") VAR.ARGS

In this example, if the calling program supplies only one argument, the CLASS variable will default to 1 and the CODE variable will default to "Standard". If the calling program provides two arguments, the default value for CLASS is ignored and the CODE variable defaults to "Standard".

 

Default argument values can also be provided when the DEFAULT.UNASS.ARGS option of the $MODE compiler directive is enabled. In this case, the default value will be applied if the argument variable passed from the calling program is unassigned.

 

 

Pass By Reference

 

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

 

If dereferencing is used with the default argument syntax described above, the default value is placed inside the parenthesis. For example,

FUNCTION INVOICE(P, (Q = 7)) VAR.ARGS

 

 

Matrix Arguments

 

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 default style (not Pick style) matrix passed as an argument can be re-dimensioned in the subroutine by use of the REDIMENSION (or REDIM) statement. Used in any other context, this statement is identical to use of DIM.

 

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