Function...End Function statement - MapBasic - 2023

Purpose

Defines a custom function.

Restrictions

You cannot issue a Function...End Function statement through the MapBasic window.

Syntax

Function name ( [ [ ByVal ] parameter As datatype ] 
	 [ , [ ByVal ] parameter As datatype... ] ) As return_type 
	statement_list 
End Function

name is the function name.

parameter is the name of a parameter to the function.

datatype is a variable type, such as integer; arrays and custom Types are allowed.

return_type is a standard scalar variable type; arrays and custom Types are not allowed.

statement_list is the list of statements that the function will execute.

Description

The Function...End Function statement creates a custom, user-defined function. User-defined functions may be called in the same fashion that standard MapInfo Pro functions are called.

Each Function...End Function definition must be preceded by a Declare Function statement.

A user-defined function is similar to a Sub procedure; but a function returns a value. Functions are more flexible, in that any number of function calls may appear within one expression. For example, the following statement performs an assignment incorporating two calls to the Proper$() function:

 fullname = Proper$(firstname) + " " + Proper$(lastname)

Within a Function...End Function definition, the function name parameter acts as a variable. The value assigned to the name "variable" will be the value that is returned when the function is called. If no value is assigned to name, the function will always return a value of zero (if the function has a numeric data type), FALSE (if the function has a logical data type), or a null string (if the function has a string data type).

Restrictions on Parameter Passing

A function call can return only one "scalar" value at a time. In other words, a single function call cannot return an entire array's worth of values, nor can a single function call return a set of values to fill in a custom data Type variable. By default, every parameter to a user-defined function is a by-reference parameter. This means that the function's caller must specify the name of a variable as the parameter. If the function modifies the value of a by-reference parameter, the modified value will be reflected in the caller's variable.

Any or all of a function's parameters may be specified as by-value if the optional ByVal keyword precedes the parameter name in the Function...End Function definition. When a parameter is declared by-value, the function's caller can specify an expression for that parameter, rather than having to specify the name of a single variable. However, if a function modifies the value of a by-value parameter, there is no way for the function's caller to access the new value. You cannot pass arrays, custom Type variables, or Alias variables as ByVal parameters to custom functions. However, you can pass any of those data types as by-reference parameters. If your custom function takes no parameters, your Function...End Function statement can either include an empty pair of parentheses, or omit the parentheses entirely. However, every function call must include a pair of parentheses, regardless of whether the function takes parameters. For example, if you wish to define a custom function called Foo, your Function...End Function statement could either look like this:

Function Foo()
	' ... statement list goes here ...
End Function

or like this:

Function Foo
	' ... statement list goes here ...
End Function

but all calls to the function would need to include the parentheses, in this fashion:

var_name = Foo()

Availability of Custom Functions

The user may not incorporate calls to user-defined functions when filling in standard MapInfo Pro dialog boxes. A custom function may only be called from within a compiled MapBasic application. Thus, a user may not specify a user-defined function within the SQL Select dialog box; however, a compiled MapBasic program may issue a Select statement which does incorporate calls to user-defined functions.

A custom function definition is only available from within the application that defines the function. If you write a custom function which you wish to include in each of several MapBasic applications, you must copy the Function...End Function definition to each of the program files.

Function Names

The Function...End Function statement's name parameter can match the name of a standard MapBasic function, such as Abs or Chr$. Such a custom function will replace the standard MapBasic function by the same name (within the confines of that MapBasic application). If a program defines a custom function named Abs, any subsequent calls to the Abs function will execute the custom function instead of MapBasic's standard Abs() function.

When a MapBasic application redefines a standard function in this fashion, other applications are not affected. Thus, if you are writing several separate applications, and you want each of your applications to use your own, customized version of the Distance() function, each of your applications must include the appropriate Function...End Function statement.

When a MapBasic application redefines a standard function, the re-definition applies throughout the entire application. In every procedure of that program, all calls to the redefined function will use the custom function, rather than the original.

Example

The following example defines a custom function, CubeRoot, which returns the cube root of a number (the number raised to the one-third power). Because the call to CubeRoot appears earlier in the program than the CubeRoot Function...End Function definition, this example uses the Declare Function statement to pre-define the CubeRoot function parameter list.

Declare Function CubeRoot(ByVal x As Float) As Float
Declare Sub Main 

Sub Main 
	Dim f_result As Float
	f_result = CubeRoot(23)
	Note Str$(f_result)
End Sub 

Function CubeRoot(ByVal x As Float) As Float
	CubeRoot = x ^ 0.33333333333
End Function

See Also:

Declare Function statement, Declare Sub statement, Sub...End Sub statement