Xbasic GuideFunctions
Functions are named reusable Xbasic code blocks. Functions can be called in expressions or by themselves to perform a task. They can optionally take one or more input arguments (also called parameters) and return a value.
Functions are declared as follows:
FUNCTION function_name AS return_type ()
' Xbasic code to execute here
END FUNCTION
The return_type declares the data type of the return value from the function. If a function returns no value, use the void (V) return type. For example:
FUNCTION myFunction AS V () ' Xbasic code to execute here showvar("Function 'myFunction' has been called","myFunction") END FUNCTION
To call the function, type the function name followed by opening and closing parentheses:
myFunction() 'Call myFunction
Passing Data to Functions
Xbasic functions can take one or more arguments. Arguments are defined in the parentheses of the FUNCTION declaration:
FUNCTION myFunction AS V (name AS C, address AS C, age AS N) ' Xbasic code to execute here DIM msg AS C = name + ", age " + age + ", lives at " + address + "." showvar(msg,"myFunction") END FUNCTION
When the function is called, the arguments are passed as a comma-delimited list inside the parentheses. For example:
myFunction("Susan","123 Baker St, Boston, MA", 37)
Arguments can be constant values, as shown above, or variables:
name = "Susan" address = "123 Baker St, Boston, MA" age = 37 myFunction(name,address,age)
Declaring Optional Arguments
Arguments can be assigned default values, making them optional. For example:
FUNCTION myFunction as V (name as C, address as C, age as N, phoneNumber = "") ' Xbasic code to execute here DIM msg AS C = name + ", age " + age + ", lives at " + address + "." if (len(alltrim(phoneNumber)) > 0) then msg = msg + " Phone: " + phoneNumber end if showvar(msg,"myFunction") END FUNCTION
The assignment operator (=) is used instead of the AS keyword when declaring arguments with default values. The default value's type determines the argument's type. For example, phoneNumber is a character type because it is assigned an empty string.
Optional arguments must be declared after all required arguments.
When calling a function, you can omit optional arguments. For example, in the code below the first line omits the phone number argument when calling myFunction while the second line includes phone number:
myFunction("Susan","123 Baker St, Boston, MA", 37) myFunction("Steve","1314 W Elm, Springfield, IL", 44, "123-445-6778")
Returning Values
Data is returned from an Xbasic function by assigning an expression to the function name. For example:
FUNCTION square AS N (value as N) square = value * value END FUNCTION square(12)
Multiple values can be returned from a function by declaring the function's type as P. For example:
FUNCTION getCat AS P () DIM cat AS P cat.pet_name = "Savvy" cat.breed = "Tuxedo" getCat = cat END FUNCTION DIM cat AS P cat = getCat() showvar(cat)
Using the RETURN Keyword
Data can alternatively be returned from a function using the RETURN keyword. The difference between assigning a value to the function name and RETURN is that RETURN immediately exits the function. Assigning an expression to the function name does not terminate the function. For example, copy the code below into the Interactive Window and run it.
FUNCTION squareA AS N (value AS N) DIM result AS N = value * value RETURN result showvar("squareA result = " + result) ' this code is never executed END FUNCTION FUNCTION squareB AS N (value AS N) squareB = value * value showvar("squareB result = " + squareB) ' this code is always executed END FUNCTION aSquare = squareA(10) bSquare = squareB(10)
Note that the showvar() statement in squareA() never executes, but the showvar() statement in squareB() runs, displaying the message shown below.
Returning Data Using Arguments
Data can also be returned using function arguments. If an argument is declared as BYREF, any modifications to the argument by the function changes the variable passed into the function from in the calling script.
FUNCTION squareC AS V (value AS N, BYREF result AS N) result = value * value END FUNCTION DIM num AS N = 10 DIM numSquare AS N = 0 squareC(num, numSquare) showvar("squareC result = " + numSquare)
An argument declared as BYREF is called "passed by reference." All function arguments, except object pointer variables, are passed by value (BYVAL) by default. When an argument is passed by value, a copy of the variable is made and sent to the function. If your variable contains a lot of data, such as the contents of a file, passing the variable by value can require a lot of memory. If a variable is passed by reference, however, the original variable is sent to the function and is not copied. Any modifications to a variable passed by reference changes the variable in the calling script.
Passing arguments by reference is often used by functions and methods in the Xbasic Function Library to return data from the function.
Function Pointers
Functions can be passed as arguments to other functions as function pointers. For example:
FUNCTION sayHello as V (name as C, formatter AS F) msg = "Hello " + name msg = formatter(msg) showvar(msg, "Hello") END FUNCTION sayHello("Jules",UPPER) sayHello("Verne",LOWER)
The sayHello() function takes two arguments: name and formatter. name is a character variable added to the message, msg. formatter is a function pointer used to format the message. formatter can be any function that takes a character variable as an argument and returns a character value. The example demonstrates passing the UPPER() and LOWER() Xbasic functions when calling sayHello(). UPPER() converts a character string to upper case. LOWER() converts a character string to lower case.