Command
	return

Purpose
	Returns (optionally, a value) from a function.

Aliases
	return, ret, rtn

Syntax
	return [<return_value>]


Options
	None.

Arguments
	<return_value>	A value of the same type as the function type. See the help page
		for fun. If the function is declared as type 'null', this argument should not be
		specified.

		This argument can be specified using either a constant, variable, function call
		(to another function), inline command, or an expression consisting of any of
		these. In all cases, the argument must result in a value of the same type as
		the function type.

Stream Input	
	Ignored.

Stream Output
	None.

Stream Error
	Any errors are written here.

Description
	function...end is a programming construct that allows to separate a certain functionality
	into a separate part of the code. This makes the code more manageable. A function often
	returns a value, and the return command is used for that purpose.

	If, in the flow of execution of a function, the end command is encountered
	before encountering a return command, the default value of of the same type
	as the function type, will be returned. For example, an integer function, that
	has no return command, will return 0.

	There is often a need to write functions that return no value. These functions perform some
	actions, but don't return a value to the caller. The purpose of these functions is just to
	sepearate a functionality. The type of 'null' should be used for these functions.

	Similarly, there are functions that provide output to the user, but return no value to
	the caller. These functions are also declared to be of type 'null'. See the example function
	EvenOdd2 below.
		
Restrictions
	Redirection is not allowed on function, return and end commands. If redirection is specified,
	it will be ignored. However, commands within the function can have their individual redirections.

Valid Examples
	function integer square
	  # This function calculates the square of the number
	  # passed as variable $num.
	  var int num
	  var int sqr
	  set $sqr = $num*$num
	  return $sqr
	  end

	The above function calculates the square of an integer number. Once declared, this function can
	now be called with the following command.

	echo square(num(5))

	The above command will print the square of 5. The function can now be called in this manner
	in any place where an integer value is required (beacause the function's type is integer).

	The return command in the above function can also be written using an expression, as follows.

	return ($num*$num)


	Here is a function that determines if an integer number is an even number or an odd number.

	function string EvenOdd
	    var int num
	    if ( (($num/2)*2) == $num )
	        return "even"
	    else
	        return "odd"
	    endif
	    end

	This function can now be called as

	echo EvenOdd(num(5))

	The above command will print "odd".

	If we want to write the output directly to the user and not return any value to the caller,
	the above function can be written as follows.

	function null EvenOdd2
	    var int num
	    if ( (($num/2)*2) == $num )
	        echo $num " is even"
	    else
	        echo $num " is odd"
	    endif
	    end

	This function can now be called as follows.

	var integer i
	while ($i <= 10)
	do
	    echo EvenOdd2(num($i))
	    set $i = $i + 1
	    done

Invalid Examples

	Consider the following function.

	function string EvenOdd3
	    var int num
	    if ( (($num/2)*2) == $num )
	        return 0
	    else
	        return 1
	    endif
	    end

	When this function is called, an error is produced. This is because, the function's type is
	string, and the return command is returning a value of type integer.

	Now, consider the following function.

	function integer square2
	  var int num
	  var int sqr
	  set $sqr = $num*$num
	  end

	When this function is called, it will return 0. This is beacuse, there is no return command
	in the function. So when the function ends (with the end command), the default value of type
	integer will be returned, which is 0.

See Also
fun
script
exit
break
continue