FUNCTION: Difference between revisions

From QB64 Phoenix Edition Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(4 intermediate revisions by the same user not shown)
Line 20: Line 20:
* To pass [[arrays]] to a sub-procedure use empty brackets after the name or indicate the index in the call.
* 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 26: 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 35: 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 47: 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 71: 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 77: 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"