Returning Values

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.

	'' 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

	'' 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.

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)

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:

	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( )

See also
	* KeyPgFunctionFunction
	* KeyPgByrefFunctionByref (Function Results)

