{{fbdoc item="title" value="Returning Values"}}----

{{fbdoc item="section" value="Returning Values"}}
	Refers to the ability of a ##[[KeyPgFunction|Function]]## procedure to have a value when the function finishes such that the value can be used in an expression or assigned to a variable.
	
	The value of a function can be returned in three ways:
		**""-""** ##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_identifier## to the desired return value (but ##Function## keyword or ##function_identifier## does not allow to evaluate the current assigned value). The latter two methods do not cause the function to exit, however.
	
	{{fbdoc item="filename" value="examples/manual/proguide/procs/return-methods.bas"}}%%(freebasic)
'' Using the name of the function to set the return value and continue executing the function:
Function myfunc1() As Integer
   myfunc1 = 1
End Function

'' Using the keyword 'Function' to set the return value and continue executing the function:
Function myfunc2() As Integer
   Function = 2
End Function

'' Using the keyword 'Return' to set the return value and immediately exit the function:
Function myfunc3() As Integer
   Return 3
End Function
%%
	{{fbdoc item="filename" value="examples/manual/proguide/procs/returnval.bas"}}%%(freebasic)
'' This program demonstrates a function returning a value.

Declare Function myFunction () As Integer

Dim a As Integer

'Here we take what myFunction returns and add 10.
a = myFunction() + 10

'knowing that myFunction returns 10, we get 10+10=20 and will print 20.
Print a 

Function myFunction () As Integer
  'Here we tell myFunction to return 10.
  function = 10 
End Function
%%
	##Return## keyword mixed with ##Function=## keyword or ##function_identifier=## or ##Exit Function## keyword in a same function is unsupported when returning objects with constructors.
	
	**Note:**
		When returning by value a UDT instance, ##Return## on the one hand, and ##Function=## or ##function_identifier=## on the other hand, do not treat the instance in the same way (in order to optimize execution time):
			**""-""** When using ##Return##, the only executed ##'Return u'## directly calls the copy-constructor.
			**""-""** When using ##Function=## or ##function_identifier=##, the constructor is always called once at the beginning of the function body, and then each executed ##'Function= u'## or ##'function_identifier= u'## only calls the let-operator.

{{fbdoc item="section" value="Returning References"}}
	Function results can also be returned by reference, rather than by value. The semantics are quite different.
	
	When assigning a ##Byref## function result through a ##Function = variable## or ##Return variable## statement, the function does not copy and return the variable's value. Instead, it returns a reference to that variable. The caller of the function can modify the variable through the reference returned from the function, without having to use pointers manually. This is very much like ##[[KeyPgByref|Byref]]## parameters.
	
	For more information, refer to: ##[[KeyPgByrefFunction|Byref (function results)]]##

{{fbdoc item="section" value="Manually returning pointers as-is from Byref functions"}}
	By specifying the ##Byval## keyword in front of the result variable in the ##Function = variable## or ##Return variable## statements, an address (usually stored in a pointer) can be passed directly as-is, forcing the ##Byref## function result to reference the same memory location which the address pointed to. For example:

	{{fbdoc item="filename" value="examples/manual/proguide/procs/byrefresult-explicit-byval.bas"}}%%(freebasic)
dim shared i as integer = 123

function f( ) byref as integer
	dim pi as integer ptr = @i

	function = byval pi

	'' or, with RETURN it would look like this:
	return byval pi
end function

print i, f( )
%%
{{fbdoc item="see"}}
	- ##[[KeyPgFunction|Function]]##
	- ##[[KeyPgByrefFunction|Byref (function results)]]##

{{fbdoc item="back" value="CatPgProgrammer|Programmer's Guide"}}