A value-returning function is a function that returns a value back to the beginning of the program.

A return is a value that a function returns to the calling script or function when it completes its task. A return value can be any one of the four variable types: handle, integer, object, or string. The type of value your function returns depends largely on the task it performs.

You use the Function Returns edit combo box in the General page of the New Script dialog to tell JAWS the type of value the function returns. You also type the description of the return in the Return description edit box. Adding a description for the return, helps you and anyone else using your function to determine exactly what the value should be used for within the calling script or function.

When you create a new function that returns a string value, the Script Manager places the following function beginning line into your script file:

String Function MyFunction ()

The "string" key word that precedes the "function" key word tells you that the MyFunction function returns a string value to the calling script or user-defined function.

The Return Statement

You use the return statement to send a value back to the calling script or user-defined function. This key word tells JAWS to return the specified value to the calling script or function. You can return the value as a literal value or within a variable. The syntax of a return statement that sends a string value stored in a variable called sText back to the calling script or user-defined function follows:

Return sText

A return statement that returns a string of text, "This is a string", as a literal follows:

Return "this is a string"

When a function returns a value to the calling script or user-defined function, you must store that value in either a local or global variable. You can then use that variable to make decisions on what the calling script or user-defined function should do next. An example of storing a string value returned by a function called MyFunction in a local variable follows:

Example 1: Assigning the Output of a Function to a Variable

Script MyScript ()
Var
String sText
Let sText = MyFunction (); store the return value of MyFunction in sText
If sText != "" Then; the function actually returned a value other than null or nothing
SayFormattedMessage (OT_MESSAGE, sText)
EndIf
EndScript

You can also use the return value of one function as the parameter for another. Using the previous example, the return value from MyFunction could be passed directly to the SayFormattedMessage function without storing it in a local variable first. The only disadvantage to this approach is that the MyFunction function may not retrieve any text. Therefore, the SayFormattedMessage function won't cause JAWS to speak anything. The example reworked to use the return value of MyFunction as the parameter for SayFormattedMessage follows:

Example 2: Using a Function as a Parameter For Another Function

Script MyScript ()
SayFormattedMessage (OT_MESSAGE, MyFunction()); use the return value from MyFunction as the message text for SayFormattedMessage
EndScript

Another example of a user-defined function that returns a value follows:

string function VerbosityLevelToggle(int iRetCurVal)
Var
int Verbosity
if not iRetCurVal then
; update it
VerbosityLevel ()
endIf
let Verbosity = GetVerbosity ()
if Verbosity == 0 then
return cmsg12_L; Beginner
elif Verbosity == 1 then
return cmsg13_L; Intermediate
elif Verbosity == 2 then
return cmsg14_L; Advanced
endIf
EndFunction

You can find the function shown above in the default script file. JAWS performs this function each time you press SPACEBAR on the "User Verbosity" entry in the Adjust JAWS Options dialog. The function begins by determining the value of the iRetCurVal parameter. If the value of the parameter is 0 or false, then JAWS performs the VerbosityLevel function to change the verbosity level from its current value to the next value. For example, if you are using the beginner verbosity level, the VerbosityLevel function changes your verbosity level to intermediate. Next, the GetVerbosity function retrieves the verbosity setting now being used and stores it in the Verbosity local variable. The If statement then determines the value stored in the Verbosity variable and returns the appropriate string of text to indicate the new verbosity level. The actual text is stored in the Common.jsm JAWS message file found in your JAWS settings folder.

What are Functions?

In general, we use (call) functions (aka: modules, methods, procedures, subprocedures, or subprograms) to perform a specific (atomic) task. In algebra, a function is defined as a rule or correspondence between values, called the function's arguments, and the unique value of the function associated with the arguments. For example:

If f(x) = 2x + 5, then f(1) =  7, f(2) =  9, and f(3) = 11

1, 2, and 3 are arguments
7, 9, and 11 are the corresponding values

Bjarne Stroustrup's C++ Glossary

• Functions are building blocks
• Allow complicated programs to be divided into manageable components
• Called modules, methods, procedures, or sub-procedures
• Like miniature programs
• Can be put together to form larger program
• Some advantages of functions:
• Programmer can focus on just the function: develop it, debug it, and test it
• Various developers can work on different functions simultaneously
• Can be used in more than one place in a program--or in different programs

Predefined Functions

Using predefined functions:

• Some predefined C++ mathematical functions:
• pow(x,y)
• sqrt(x)
• floor(x)
• Predefined functions are organized into separate libraries
• C++ Standard Library contains many predefined functions to perform various operations
• I/O functions are in iostream header
• Math functions are in cmath header
• Power Function - pow(x,y):
• Power function pow(x,y) has two parameters
• pow(x,y) returns value of type double
• pow(x,y) calculates x to the power of y: pow(2,3) = 8.0
• x and y called parameters (or arguments) of function pow
• Square Root Function - sqrt(x):
• Square root function sqrt(x) has only one parameter
• sqrt(x) returns value of type double
• sqrt(x) calculates non-negative square root of x, for x >= 0.0: sqrt(2.25) = 1.5
• Floor Function - floor(x):
• Floor function floor(x) has only one parameter
• floor(x) returns value of type double
• floor(x) calculates largest whole number not greater than x: floor(48.79) = 48.0

User-Defined Functions

Using User-Defined functions:

• Two types:
1. Void functions (nonvalue-returning): no return type, do not return a value
2. Value-returning functions: have a data type, return only one value to caller
• When utilizing functions:
• Include correct header file
• Know function name
• Know number of parameters, if any
• Know data type of parameters
• Know data type of value computed by function
• Value-returning function used 3 ways:
1. Assignment statement
2. Output statement
3. Argument (actual parameter) in another function call
• Creating functions:

Mnemonic: "ProDeCall":
1. Prototype
2. Definition
3. Call

1. Header (or heading) includes:
1. Function name
2. Number of parameters (if any)
3. Data type of each parameter
4. Type of function (data type or void)
2. Body includes:
1. Code to accomplish task
2. ***Any variables (if any) declared in body of function are local to function

• Formal parameter (or parameter): variable declared in heading
• Actual parameter (or argument): expressions, variables, or constant values listed in function call

//Value-returning function definition syntax: including header and body
functionType functionName(formal parameter list) //function header
{
   //function body
   statements...

   //value-returning function return statement
   return expression;
}

• Formal parameter list can be empty: parentheses still required

• Function prototype: function heading without body of function
• While you don't HAVE to prototype, you SHOULD!
• Why? Reduce program errors!
1. Compiler correctly handles function return value
2. Compiler checks you used correct number of function arguments
3. Compiler checks you used correct type of arguments, if not, automatically type casts (numeric data types only)
4. NOTE: Some compilers do these automatically, BUT it's best to be safe--prototype your functions!
• Easiest way to prototype?
  Copy function header and add a semi-colon (;)--however, don't need parameter names, only data types
• If prototypes not used, then function must be defined before it is called, that is above main()--not good to do with large programs

//function prototype syntax: only data types (not names) of parameters must be specified
functionType functionName(formal parameter list);

• Name with actual parameters (if any) in parentheses
• In call statement, specify only arguments (actual parameters), not data types
• One-to-one correspondence between actual and formal parameters

Mnemonic: "TON" - (must agree in Type, Order, and Number)
• Value-returning function called in an expression (only 3 ways):
1. Assignment statement
2. Output statement
3. Argument (actual parameter) in another function call
• Function call results in execution of body of called function

//function call syntax:
x = functionName(actual parameter list); //Assignment, Output, Argument in another function call

• Call to value-returning function with empty formal parameter list:

x = functionName(); //Assignment, Output, Argument in another function call

• After value-returning function is invoked, function returns value via return statement

//return statement syntax:
return expression;

• When return statement executes:
1. Function terminates
2. Control goes back to caller
• ***When return statement executes in function main(), program terminates

Flow of Execution

Program Execution:

• Begins with first statement in function main()
• Additional functions invoked when called
• Function prototypes appear before function definitions--that is, before function main()
• Compiler translates prototypes first
• Function call invocation:
1. Transfer of control to first statement in body of called function
2. After function body executed: control passed back to point immediately following function call
3. Value-returning function returns value
4. After function execution: value that function returns replaces function call statement

/*
This program illustrates value-returning functions 
  and compares two, then three numbers.
written by Mark K. Jowett, Ph.D.
6:03 PM 9/11/2004
*/

#include<iostream>
//using namespace std;

//function prototypes
double testTwo(double x, double y);
double testThree(double x, double y, double z);

int main() 
{
  double num1, num2;

  //value-returning function used in output
  std::cout << "The larger of 5 and 10 is "
	    << testTwo(5, 10) << std::endl; //function call

  std::cout << "Enter one number: ";
  std::cin >> num1;

  std::cout << "Enter another number: ";
  std::cin >> num2;
  std::cout << std::endl;

  //value-returning function used in output
  std::cout << "The larger of " << num1 << " and "
	    << num2 << " is " << testTwo(num1, num2) << std::endl; //function call

  //value-returning function used in output
  std::cout << "The largest of 10, 15, and 20 is "
	    << testThree(10, 15, 20) << std::endl; //function call

  std::cout << "Press Enter key to exit...";
  std::cin.get(); std::cin.get(); // make DOS window stay open

  return 0;
}

//function definition
double testTwo(double x, double y)
{
  if (x >= y)
    return x;
  else 
    return y;
}

//function definition
double testThree (double x, double y, double z)
{
//value-returning function used as argument in another function call
  return testTwo(x, testTwo(y, z));
}


Displays:
The larger of 5 and 10 is 10
Enter one number: 2
Enter another number: 3

The larger of 2 and 3 is 3
The largest of 10, 15, and 20 is 20
Press Enter key to exit...

What is the first line in a function called?

Does the function header marks the beginning of the function definition?

What does the following statement mean num1 num2 Get_num ()?

When a function is called by its name during the execution of a program then it is?