Description | Declares the name, arguments, and code that form the body of a function procedure. It now supports declaring an object return type using the AS typename clause. |
Syntax | Function functionname [(argumentlist)] [statementblock] [functionname = expression] [Return [NEW objectconstruction]] [statementblock] [functionname = expression] End Function |
Arguments | • functionname - Name of the function. Function procedure names follow the same naming conventions as other variables and can include a type-declaration character. Functionname cannot be the same as any other globally recognized name in the program. Such names include the names of procedures (in Basic or a dynamic-link library [DLL]), Private variables, and Global constants. • argumentlist - List of variables, representing arguments, that are passed to the function procedure when it is called. Multiple variables are separated by commas. The argument argument list has the following syntax: variable[( )] [,variable[( )]] . . . • variable - Name of the variable representing the argument within argumentlist. For array variables, use the parentheses but omit the number of dimensions. • typename - Used to explicitly declare the object type that the function returns. This clause is only used when the function returns an object type. • statementblock - Any group of statements that are to be executed within the body of the function procedure. • expression - Return value of the function. – A function procedure returns a value by assigning that value to the functionname. Any number of such assignments can be used anywhere within the procedure. – If no value is assigned to functionname, the procedure returns a default value: A numeric function returns 0, a String function returns a zero-length string (""), and a Variant function returns Empty. – When the function returns an object, the return value may also be assigned to a variable within the function and that variable returned using RETURN. When an object variable is returned, it must be initialized (e.g., to an object instance or to NOTHING). • Return [NEW objectconstruction] - The Return statement causes the immediate termination of the function (See Return Statement.) Program execution resumes with the statement after the calling statement. – The Return statement can now optionally be followed by a NEW objectconstruction statement to immediately create and return a new object instance. |
Remarks | All executable code must be in Function procedures. You cannot define a function procedure inside another Function procedure. Function and End Function mark the beginning and end of a function procedure, respectively. You can call a function procedure by using the function name, followed by the argument list in parentheses, in an expression. If the function has no arguments, you still must include the parentheses. Variables used in Function procedures fall into two categories: those that are explicitly declared within the procedure and those that are not. Variables that are explicitly declared in a procedure (using Dim or an equivalent) are always local to the procedure. Other variables used but not explicitly declared in a procedure are also local unless they are explicitly declared at some higher level outside the procedure. A procedure can use a variable that is not explicitly declared in the procedure, but a name conflict can occur if anything you have defined in the Declarations section has the same name. If your procedure refers to an undeclared variable that has the same name as another procedure, a Private-level constant or variable, or an object, Basic assumes that your procedure is referring to that Private-level name. Explicitly declare variables to avoid this kind of conflict. You can use an Option Explicit statement to force explicit declaration of variables. See Option Evaluate Automatic Statement. Caution! Function procedures can be recursive; that is, they can call themselves to perform a given task. However, recursion can lead to stack overflow. In addition, there is a 32 parameter limitation in functions, and if this limitation is exceeded, stack overflow occurs. For more information, see Stack Overflow. |
Example | Example 1: To return a value from a function, assign the value to the function name. For example, in a function named BinarySearch, you could assign the value of the constant False to the name to indicate that the value was not found: Function BinarySearch(...) ... ' Value not found. Return a value of False. If lower > upper Then BinarySearch = False Return End If End Function Example 2: Returning an object from a function is now allowed. The object type being returned must be declared (using the AS typename clause), and the actual object being returned must match that type: PUBLIC FUNCTION MyFunction() AS DJComponent DIM foo AS DJComponent SET foo = NEW DJComponent "XPath Iterator 1.1.1" RETURN foo END FUNCTION DIM bar AS DJComponent SET bar = MyFunction() Note the above could have used the direct ‘return new object’ syntax, however the most common use for such a function would be to create the new object, configure it, and then return it. Note also that if an object variable is being returned, it MUST be initialized: PUBLIC FUNCTION MyFunction(docreate) AS DJComponent DIM foo AS DJComponent IF docreate THEN SET foo = NEW DJComponent "XPath Iterator 1.1.1" END IF RETURN foo END FUNCTION DIM bar AS DJComponent SET bar = MyFunction(FALSE) The above will fail at line 10, because the variable ‘foo’ was never initialized. In the above example, the variable should initially be set to NOTHING: PUBLIC FUNCTION MyFunction(docreate) AS DJComponent DIM foo AS DJComponent SET foo = NOTHING IF docreate THEN SET foo = NEW DJComponent "XPath Iterator 1.1.1" END IF RETURN foo END FUNCTION DIM bar AS DJComponent SET bar = MyFunction(FALSE) |