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.