{{fbdoc item="title" value="FUNCTION"}}----
Defines a procedure returning a value

{{fbdoc item="syntax"}}##
	[[[KeyPgPublic Public]]|[[KeyPgPrivate Private]]] **Function** //identifier// [[[KeyPgCdecl CDecl]]|[[KeyPgPascal Pascal]]|[[KeyPgStdcall StdCall]]] [[[KeyPgOverload Overload]]] [[[KeyPgAlias Alias]] //external_identifier//] [([//parameter_list//])] [[[KeyPgAs As]] //return_type//] [[[KeyPgStatic Static]]] [[[KeyPgExport Export]]]
		//statements//
		...
		{ {[[KeyPgReturn Return]] [//return_value//]}|{Function = //return_value//}|{//identifier// = //return_value//} }
		...
	[[KeyPgEndblock End]] Function
##
{{fbdoc item="param"}}
	##//identifier//##: the name of the function
	##//external_identifier//##: externally visible (to the linker) name enclosed in quotes
	##//parameter_list//##: ##//parameter//[, //parameter//[, ...]]##
	##//parameter//##: ##[[[KeyPgByref ByRef]]|[[KeyPgByval ByVal]]] //identifier// [[[KeyPgAs As]] //type//] [= //default_value//]##
		##//identifier//##: the name of the variable referenced in the function.  If the argument is an array then the identifier must be followed by an empty parenthesis. 
		##//type//##: the type of variable
		##//default_value//##: the value of the argument if none is specified in the call
	##//return_type//##: the type of variable returned by the function
	##//statements//##: one or more statements that make up the function body
	##//return_value//##: the value returned from the function

{{fbdoc item="desc"}}
	A function defines a block of code which can be executed with a single statement (a function call), and provide a value back to the caller when finished (a return value). 	There are several reasons to use functions:
	- Reduces redundancy in your program
	- Enables reuse of code in many programs
	- Improves readability of the program
	- Improves maintainability of the program
	- Makes it easy to extend your program

	//Access Rights// : The ##[[KeyPgPublic Public]]## and ##[[KeyPgPrivate Private]]## keywords specify public or private intra module-level access rights, respectively. If neither is given, the function defaults to public access (##[[KeyPgPublic Public]]##).
	
	//Calling Convention// : Calling convention, or the order in which arguments are pushed and popped from the stack during function calls, is specified with the ##[[KeyPgCdecl CDecl]]##, ##[[KeyPgPascal Pascal]]## and ##[[KeyPgStdcall StdCall]]## keywords. If none is given, the function uses the standard convention by default (##[[KeyPgStdcall StdCall]]##).
	
	//Passing Arguments// : Functions may receive one or more variables, or arguments, when called. These arguments are listed as ##//parameters//## in the ##//parameter_list//##. The ##[[KeyPgByref ByRef]]## and ##[[KeyPgByval ByVal]]## keywords specify whether the argument will be passed by reference or by value, respectively. The argument's type is given by "##[[KeyPgAs As]] //type//##" following the ##//parameter//##. If a parameter in the declaration is given a default value, the parameter is optional.  Array parameters are specified by following an identifier with an empty parenthesis.  Note that array parameters are always ##[[KeyPgByref ByRef]]## and the ##[[KeyPgByref ByRef]]## keyword is neither required nor allowed for array parameters.  When calling a function with an array argument the parenthesis must be supplied there too; see the examples.

	//Overloaded Functions// : An overloaded function may share the same name (##//identifier//##) as another with a different signature. The ##[[KeyPgOverload Overload]]## keyword specifies that a function may be overloaded. A function must be defined - or declared - using the ##[[KeyPgOverload Overload]]## keyword prior to any functions that overload them.
	
	//Returning values// : ##//return_type//## specifies the ##[[DataType data type]]## returned by a function upon exit. If no data type is specified, then the function will return the default data type, which will be Integer unless set to another data type using ##[[KeyPgDefsng DefSng]]##, ##[[KeyPgDefdbl DefDbl]]##, ##[[KeyPgDefstr DefStr]]##, etc. Functions can return values using three methods: the ##[[KeyPgReturn Return]]## keyword followed by a value exits the function immediately, and returns that value to the caller. Functions can also return values by assigning the Function keyword or the function's ##//identifier//## to the desired return value. The latter two methods do not cause the function to exit, however. ##[[KeyPgReturn Return]]## keyword mixed with Function= keyword or function's ##//identifier//##= or ##[[KeyPgExit Exit Function]]## keyword in a same function is unsupported when returning objects with constructors. Since functions return values, function calls evaluate to expressions. Thus, function calls can be made wherever an expression is expected, like in [[KeyPgOpAssignment assignments]] or ##[[KeyPgIfthen If]]## statements. Parentheses surrounding the argument list are required on function calls in expressions and even highly recommended if there are no arguments. Functions can also return references by specifying ##[[KeyPgByrefFunction Byref As]] //return_type//##.

	//Local Variable Preservation// : The ##[[KeyPgStatic Static]]## keyword specifies that a function's locally declared variables are preserved between function calls. Upon entering a function defined with ##[[KeyPgStatic Static]]##, local variables have the same value as when the function was last called.

{{fbdoc item="ex"}}

{{fbdoc item="filename" value="examples/manual/procs/func-1.bas"}}%%(freebasic)
'' This program demonstrates the declaration of a function 
'' and returning a value using Return command

Declare Function ReturnTen () as integer

Print ReturnTen () '' ReturnTen returns an integer by default.

Function ReturnTen() as integer
	Return 10
End Function
%%

{{fbdoc item="filename" value="examples/manual/procs/func-2.bas"}}%%(freebasic)
'' This program demonstrates the declaration of a function 
'' and returning a value using assignment to function name

Declare Function ReturnTen () as integer

Print ReturnTen () '' ReturnTen returns an integer by default.

Function ReturnTen() as integer
	ReturnTen = 10
End Function
%%

{{fbdoc item="filename" value="examples/manual/procs/func-3.bas"}}%%(freebasic)
'' This program demonstrates function overloading.

'' The overloaded functions must be FIRST.
Declare Function ReturnTen Overload (a As Single) as integer
Declare Function ReturnTen Overload (a As String) as integer
Declare Function ReturnTen (a as integer) as integer

Print ReturnTen (10.000!) '' ReturnTen will take a single and return an integer
Print ReturnTen (10)      '' ReturnTen will take an integer and return an integer
Print ReturnTen ("10")    '' ReturnTen will take a string and return an integer

Function ReturnTen Overload (a As Single) as integer
	Return Int(a)
End Function

Function ReturnTen Overload (a As String) as integer
	Return Val(a)
End Function

Function ReturnTen (a As Integer) as integer
	Return a
End Function
%%

{{fbdoc item="filename" value="examples/manual/procs/func-4.bas"}}%%(freebasic)
'' The following example demonstrates optional parameters.

Function TestFunc(P As String = "Default") As String
	Return P
End Function

Print TestFunc("Testing:")
Print TestFunc
%%

{{fbdoc item="filename" value="examples/manual/procs/func-5.bas"}}%%(freebasic)
'' This example shows how to declare and call 
'' functions taking array arguments.

Function x(b() As Double) As Integer
  x = UBound(b)-LBound(b)+1
End Function

Dim a(1 To 10) As Double
Print x(a())
Dim c(10 To 20) As Double 
Print x(c())
%%

{{fbdoc item="lang"}}
	- In the //[[CompilerOptlang -lang fb]]// dialect, ##**Byval**## is the default parameter passing convention for all built-in types except ##[[KeyPgString String]]##; String and user-defined ##[[KeyPgType Type]]##s are passed ##[[KeyPgByref Byref]]## by default.
	- In the //[[CompilerOptlang -lang qb]]// and //[[CompilerOptlang -lang fblite]]// dialects, ##**Byref**## is the default parameter passing convention.
	- In the //[[CompilerOptlang -lang qb]]// dialect, the name of the function must be used in an assignment to specify the return value.  Using ##**function** = ...##" to specify the return value may not be used.
	- In the //[[CompilerOptlang -lang qb]]// and //[[CompilerOptlang -lang fblite]]// dialects, ##[[KeyPgReturn Return]]## may only be used to return a value when ##[[KeyPgOptiongosub Option Gosub]]## is off.  In //[[CompilerOptlang -lang qb]]//, this must be done explicitly using the ##[[KeyPgOptionnogosub Option Nogosub]]## statement.

{{fbdoc item="diff"}}
	- Parameters can be optional in ""FreeBASIC"".
	- In QBASIC, the return type could only specified with a suffix, not with ##AS TYPE##, and only allowed functions to return a built-in type.
	- Return value can now be specified by a ##[[KeyPgReturn Return]]## statement.
	- Function ##[[KeyPgOverload Overload]]##ing is supported in ""FreeBASIC"".
	- The return value of functions can be ignored in the calling code.

{{fbdoc item="see"}}
	- ##[[KeyPgSub Sub]]##
	- ##[[KeyPgExit Exit]]##
	- ##[[KeyPgReturn Return]]##
	- ##[[KeyPgDeclare Declare]]##
	- ##[[KeyPgPublic Public]]##
	- ##[[KeyPgPrivate Private]]##

{{fbdoc item="back" value="CatPgProcedures|Procedures"}}
