FUNCTION

From QB64 Wiki

Jump to: navigation, search

A FUNCTION block statement is used when creating a function procedure to return a calculated value to a program.


Syntax:

FUNCTION name[type-suffix] [(parameters)]
.
.
.
END FUNCTION


  • The function type can be any variable type that it will return to the program and is represented by the type suffix. Cannot use AS!
  • Functions hold ONE return value in the function's name which is a variable type. Other values can be passed through parameter(s).
  • If there are no parameters passed or they are SHARED the parameters and parenthesis are not required.
  • The IDE may require that an intermediate variable be used when calculations define the function's value more than once! In those cases, make the Function's name equal to the intermediate variable's value at the end of the Function.
  • Variable names within the procedure do not have to match the names used in the reference parameters, just the value types.
  • A Function needs to return the value to something such as a variable or as a argument for a sub, function or statement.
  • All dynamic variable values return to 0 or null strings when the procedure is exited except when a variable or the entire function is STATIC. This can save program memory as all dynamic memory used in a FUNCTION is released on procedure exit.
  • FUNCTION procedure code can use GOSUB and GOTO line numbers or labels inside of the procedure when necessary.
  • For early function exits use EXIT FUNCTION before END FUNCTION and GOSUB procedures using RETURN.
  • Once a FUNCTION is created and used, the Qbasic IDE will DECLARE it when the file is saved. QB64 doesn't need them!
  • Functions are often referred to in program calculations, not called like SUB procedures. CALL cannot be used!
  • The IDE can create the FUNCTION and END FUNCTION lines for you. Use the Make FUNCTION option in the Edit Menu. A box will come up for you to enter a name for the FUNCTION. Enter all code between the FUNCTION and END FUNCTION lines.
  • QB64 ignores all procedural DECLARE statements! Define all parameter TYPEs in the FUNCTION procedure.
  • Qbasic's IDE may place a DEFINT, DEFSNG, DEFLNG, DEFDBL or DEFSTR statement before the FUNCTION line if it is used in the main module. It may even be the wrong variable type needed. It can be changed or removed when necessary.
  • Images are not deallocated when the SUB or FUNCTION they are created in ends. Free them with _FREEIMAGE.
  • WARNING! Do not place DATA fields after SUB or FUNCTION procedures! QB64 will FAIL to compile properly!
Qbasic allowed programmers to add DATA fields anywhere because the IDE separated the main code from other procedures.


Example: Returns a LONG array byte size required for a certain sized screen pixel area.

DEFINT A-Z INPUT "Enter a screen mode: ", mode% INPUT "Enter image width: ", wide& INPUT "Enter image depth: ", deep& IntegerArray& = ImageBufferSize&(wide&, deep&, mode%) \ 2 ' returns size of an INTEGER array. PRINT IntegerArray& END DEFINT A-Z FUNCTION ImageBufferSize& (Wide&, Deep&, mode%) SELECT CASE ScreenMode% CASE 1: BPPlane = 2: Planes = 1 CASE 2, 3, 4, 11: BPPlane = 1: Planes = 1 CASE 7, 8, 9, 12: BPPlane = 1: Planes = 4 CASE 10: BPPlane = 1: Planes = 2 CASE 13: BPPlane = 8: Planes = 1 CASE ELSE: BPPlane = 0 END SELECT ImageBufferSize& = 4 + INT((Wide& * BPPlane + 7) / 8) * (Deep& * Planes) END FUNCTION

Explanation: Function calculates the array byte size required when you GET an area of the SCREEN mode used in graphics. Each mode will require a different sized array. Since graphics uses INTEGER arrays, 2 byte elements, the size returned is divided by 2 in the IntegerArray& calculation function reference. Function returns only 4 for SCREEN 0 which is an illegal text only mode.


See also:

  • SUB, SCREEN (statement)
  • DEF FN
  • EXIT (statement), END
  • _EXIT (function)



Navigation:
Go to Keyword Reference - Alphabetical
Go to Keyword Reference - By usage
Go to Main WIKI Page
Personal tools
Toolbox