QB64-PE/internal/help/FUNCTION.txt

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


{{PageSyntax}}
:: '''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. '''Currently cannot use FUNCTION name [[AS]] type!'''  
* 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|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|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'' [[TYPE]]s 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 1:'' A simple function that returns the current path. Place [[FUNCTION]] or [[SUB]] procedures after the program [[END]].
{{CodeStart}} '' ''
{{Cl|PRINT}} "Current path = "; PATH$
{{Cl|END}}

{{Cl|FUNCTION}} PATH$
f% = {{Cl|FREEFILE}}
file$ = "D0Spath.inf" 'file name uses a zero to prevent an overwrite of existing file name
{{Cl|SHELL}} {{Cl|_HIDE}} "CD > " + file$ 'send screen information to a created text file
{{Cl|OPEN}} file$ {{Cl|FOR (file statement)|FOR}} {{Cl|INPUT (file mode)|INPUT}} {{Cl|AS}} #f% 'file should exist with one line of text
{{Cl|LINE INPUT (file statement)|LINE INPUT}} #f%, PATH$ 'read file path text to function name
{{Cl|CLOSE}} #f%
{{Cl|KILL}} file$
{{Cl|END FUNCTION}} '' ''
{{CodeEnd}}


''Example 2:'' Returns a [[LONG]] array byte size required for a certain sized graphics screen pixel area [[GET (graphics statement)|GET]].
{{CodeStart}} '' ''
{{Cl|INPUT}} "Enter a screen mode: ", mode%
{{Cl|INPUT}} "Enter image width: ", wide&
{{Cl|INPUT}} "Enter image depth: ", deep&
IntegerArray& = ImageBufferSize&(wide&, deep&, mode%) \ 2 ' returns size of an {{Cl|INTEGER}} array.
{{Cl|PRINT}} IntegerArray&
{{Cl|END}}

{{Cl|DEFINT}} A-Z
{{Cl|FUNCTION}} ImageBufferSize& (Wide&, Deep&, ScreenMode%)
{{Cl|SELECT CASE}} ScreenMode%
  {{Cl|CASE}} 1: BPPlane = 2: Planes = 1
  {{Cl|CASE}} 2, 3, 4, 11: BPPlane = 1: Planes = 1
  {{Cl|CASE}} 7, 8, 9, 12: BPPlane = 1: Planes = 4
  {{Cl|CASE}} 10: BPPlane = 1: Planes = 2
  {{Cl|CASE}} 13: BPPlane = 8: Planes = 1
  {{Cl|CASE ELSE}}: BPPlane = 0
{{Cl|END SELECT}}
ImageBufferSize& = 4 + {{Cl|INT}}((Wide& * BPPlane + 7) / 8) * (Deep& * Planes) 'return the value to function name.
{{Cl|END FUNCTION}} '' ''
{{CodeEnd}}
:''Explanation:'' Function calculates the array byte size required when you [[GET (graphics statement)|GET]] an area of a graphics [[SCREEN]]. Each mode may 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 a text only mode.


''See also:'' 
* [[SUB]], [[SCREEN (statement)]] 
* [[DEF FN]]
* [[EXIT]] (statement), [[END]]
* [[_EXIT (function)]]


{{PageNavigation}}