// --- Example: Functions. Arguments by reference
/*
    Demonstrates that arguments passed by reference
     must be addressable objects, not literal constants. 
     On some systems, the code may still compile (with warnings) 
     and run.  On MSVC++, the attempt to modify a constant
     generates the following syntax error:

     "A reference that is not to 'const' cannot be bound to a non-lvalue."

     The term "lvalue" means "an expression that refers to
     an object (Stroustrup, p. 84)."  What the error means
     is that the expression "5" does not refer to any
     object in memory and therefore cannot be used to 
     provide an argument for the function's reference parameter.
     -----------------------------------------------
*/

#include <iostream.h>
int double_value ( int & i )
{
	cout << "\n  Beginning function \"double_value( int& i )\"";

	cout << "\n i = " << i  ;

        cout << "\n Doubling...\n";
        i += i;
	   
	cout << "\n Now i = " << i  ;
 
        cout << "\n End function \"double_value()\"";
        return i;
}
int main(void) 
{
	cout << "\n ----------------------------\n ";
	cout <<    " Beginning function \"main()\"";
	cout << "\n ---------------------------- ";

	cout << " \n Calling function: double_value( 5 )";
 	int jmain = double_value( 5 );  // THIS CALL IS AN ERROR!
	                                // Never pass a literal constant to a 
					// function expecting a non-constant
					// reference.
	cout << " ----------------------------\n "
	     <<    " Back in function \"main()\"";
	cout << "\n ---------------------------- ";

	cout << "\n returned value (jmain)  = " << jmain;
 
        return 0;
}