FUNCTION: Difference between revisions

From QB64 Phoenix Edition Wiki
Jump to navigation Jump to search
(Created page with "A FUNCTION block statement is used to create a function procedure to return a calculated value to a program. {{PageSyntax}} : '''FUNCTION procedureName'''[type-suffix] [(''parameters'')] :: ''{code}'' :: 'variable definitions and procedure statements :: ⋮ :: procedureName = returnValue : '''END FUNCTION''' {{PageDescription}} * The function type can be any variable type that it will return to the program and is represented by the type suffix. * Functions hold o...")
 
No edit summary
 
(5 intermediate revisions by the same user not shown)
Line 17: Line 17:
* If there are no parameters passed or they are [[SHARED]] the ''parameters'' and parenthesis are not required.
* If there are no parameters passed or they are [[SHARED]] the ''parameters'' and parenthesis are not required.
* Variable names within the procedure do not have to match the names used in the reference parameters, just the value types.
* Variable names within the procedure do not have to match the names used in the reference parameters, just the value types.
* To pass parameter variables [[BYVAL|by value]] to protect the value in a call, parenthesis can be placed around each variable name also.
* To pass [[arrays]] to a sub-procedure use empty brackets after the name or indicate the index in the call.
* 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.
* 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.  
* 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]].
* For early function exits use [[EXIT]] [[FUNCTION]] before [[END FUNCTION]] and [[GOSUB]] procedures using [[RETURN]].
* '''QB64 ignores all procedural DECLARE statements.''' Define all ''parameter'' [[Data types|types]] in the FUNCTION procedure.
* '''QB64 ignores all procedural DECLARE statements.''' Define all ''parameter'' [[Data types|types]] in the FUNCTION procedure.
Line 24: Line 26:
* The IDE can create the FUNCTION and END FUNCTION lines for you. Use the ''New 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.
* The IDE can create the FUNCTION and END FUNCTION lines for you. Use the ''New 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.


 
=== QBasic/QuickBASIC ===
==QBasic/QuickBASIC==
* Once a FUNCTION was created and used, the QBasic IDE would DECLARE it when the file was saved. '''QB64 doesn't need these declarations.'''
* Once a FUNCTION was created and used, the QBasic IDE would DECLARE it when the file was saved. '''QB64 doesn't need these declarations.'''
* QBasic's IDE could 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.
* QBasic's IDE could 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.
Line 33: Line 34:
{{PageExamples}}
{{PageExamples}}
''Example 1:'' A simple function that returns the current path. Place [[FUNCTION]] or [[SUB]] procedures after the program [[END]].
''Example 1:'' A simple function that returns the current path. Place [[FUNCTION]] or [[SUB]] procedures after the program [[END]].
{{CodeStart}} '' ''
{{CodeStart}}
{{Cl|PRINT}} "Current path = "; PATH$
{{Cl|PRINT}} "Current path = "; PATH$
{{Cl|END}}
{{Cl|END}}
Line 45: Line 46:
     {{Cl|CLOSE}} #f%
     {{Cl|CLOSE}} #f%
     {{Cl|KILL}} file$
     {{Cl|KILL}} file$
{{Cl|END FUNCTION}} '' ''
{{Cl|END FUNCTION}}
{{CodeEnd}}
{{CodeEnd}}




''Example 2:'' Returns a [[LONG]] array byte size required for a certain sized graphics screen pixel area [[GET (graphics statement)|GET]].
''Example 2:'' Returns a [[LONG]] array byte size required for a certain sized graphics screen pixel area [[GET (graphics statement)|GET]].
{{CodeStart}} '' ''
{{CodeStart}}
{{Cl|INPUT}} "Enter a screen mode: ", mode%
{{Cl|INPUT}} "Enter a screen mode: ", mode%
{{Cl|INPUT}} "Enter image width: ", wide&
{{Cl|INPUT}} "Enter image width: ", wide&
Line 69: Line 70:
     {{Cl|END SELECT}}
     {{Cl|END SELECT}}
     ImageBufferSize& = 4 + {{Cl|INT}}((Wide& * BPPlane + 7) / 8) * (Deep& * Planes) 'return the value to function name.
     ImageBufferSize& = 4 + {{Cl|INT}}((Wide& * BPPlane + 7) / 8) * (Deep& * Planes) 'return the value to function name.
{{Cl|END FUNCTION}} '' ''
{{Cl|END FUNCTION}}
{{CodeEnd}}
{{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.
:''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.
Line 75: Line 76:


{{PageSeeAlso}}
{{PageSeeAlso}}
* [[SUB]], [[SCREEN (statement)]]  
* [[SUB]], [[SCREEN]]
* [[EXIT]] (statement), [[END]]
* [[EXIT]] (statement), [[END]]
* [[_EXIT (function)]]
* [[_EXIT (function)]]

Latest revision as of 00:32, 28 January 2023

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


Syntax

FUNCTION procedureName[type-suffix] [(parameters)]
{code}
'variable definitions and procedure statements
⋮
procedureName = returnValue
END FUNCTION


Description

  • The function type can be any variable type that it will return to the program and is represented by the type suffix.
  • Functions hold one return value in the function's name which is a variable type. Other values can be passed through parameters.
  • Functions are often referred to in program calculations, not called like SUB procedures. CALL cannot be used with functions.
  • If there are no parameters passed or they are SHARED the parameters and parenthesis are not required.
  • Variable names within the procedure do not have to match the names used in the reference parameters, just the value types.
  • To pass parameter variables by value to protect the value in a call, parenthesis can be placed around each variable name also.
  • To pass arrays to a sub-procedure use empty brackets after the name or indicate the index in the call.
  • 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.
  • QB64 ignores all procedural DECLARE statements. Define all parameter types in the FUNCTION procedure.
  • Images are not deallocated when the SUB or FUNCTION they are created in ends. Free them with _FREEIMAGE.
  • The IDE can create the FUNCTION and END FUNCTION lines for you. Use the New 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.

QBasic/QuickBASIC

  • Once a FUNCTION was created and used, the QBasic IDE would DECLARE it when the file was saved. QB64 doesn't need these declarations.
  • QBasic's IDE could 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.
  • QBasic allowed programmers to add DATA fields anywhere because the IDE separated the main code from other procedures.


Examples

Example 1: A simple function that returns the current path. Place FUNCTION or SUB procedures after the program END. 

PRINT "Current path = "; PATH$
END

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


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

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&, ScreenMode%)
    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) 'return the value to function name.
END FUNCTION
Explanation: Function calculates the array byte size required when you 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


Navigation:
Main Page with Articles and Tutorials
Keyword Reference - Alphabetical
Keyword Reference - By usage
Report a broken link
Retrieved from "https://qb64phoenix.com/qb64wiki/index.php?title=FUNCTION&oldid=6773"