Documented Functions

3.3 Calling Documented Functions

C++ has many functions available

• standard functions such as

  sqrt pow string::length ostream::width 
  
  

• programmer-defined functions written for specific applications
• functions that are members of off-the-shelf classes: bankAccount::withdraw

Functions are more easily understood when documented with comments see next slide

Preconditions and Postconditions

Preconditions and postconditions are C++ comments that represents a contract between the implementers of a function and the user (client) of that function.

• Preconditions: What the function requires.
• Postconditions: What the function will do (complete as) if the preconditions are met.

• The preconditions are the circumstances that must be true in order for the function to successfully fulfill the postconditions.

double sqrt(double x)

// pre: x >= 0 

// post: Returns square root of x 

• Note: On most systems now, sqrt(-1.0) returns not a number NaN or infinity -1.#IND

Function Headings

A function heading is the complete declaration of a function without its implementation (body)

The heading is sometimes called the function's signature.

For example, this signature tells us how to call the function (number of parameters and type of parameters), but not how it works:

double sqrt(double x) 

General form of a function heading:

return-type function-name ( parameter-list ) 

• the return-type is any C++ class e.g. double or string
• the function-name is any valid identifier
• the parameter-list is a set of 0 or more parameters

General form for declaring parameters:

class-name  identifier     class-name & identifier

double f(double x)         void init(grid& g)



int max(int j, int k)      int roots(double a,

                           double b, double c,

                           double& r1,  double& r2)

Argument/Parameter Associations

• Example call to f (above) shows that arguments match parameters by position

double f(double x, double y) 

// post: return x-y; 

cout << f(3.0, -5.32); 

• The value of the first argument is copied to the first parameter, the value of the second argument to the second parameter, and so on.
• Like these two assignments:

x = 3.0; 

y = -5.32;

Exercises

Write the output generated by these function calls:

cout << f( 1.0, 1.0) << endl; // _____ 

cout << f( 1.0, 1.5) << endl; // _____ 

cout << f( 3.0, 0.5) << endl; // _____ 

cout << f(-1.0, 1.0) << endl; // _____ 

Write valid for each valid function call or explain why the code is incorrect?

f(1.0)

 f("Bob", "Sue")

f(-0.001, +4.5)

 f(1, 2)

f(1, 2, 3)

f((1, 2)

Given the following function heading :

double larger(double a, double b) 

// post: return the larger of a and b 

What type (class) of value is returned when larger is called _______ ?
What is the function name _______ ?
How many arguments are required to call the function ___________ ?
What class of arguments are required in the function call __________ ?

Given the following function heading :

double foo(double a, double b) 

// pre: a is not equal to b 

// post: Return the lesser of a and b 

write the return value of these function calls: 



foo( 3.0, 6.0) ________ 



foo( 6.0, 3.0) ________ 



foo(-3.0, -6.0) ________ 



foo(-3.0, -3.0) ________ 

Summary

Documented function headings provide the following information:

• The type (or class) of value returned by the function.
• The function name.
• The number of arguments to use in a call.
• The type (class) of arguments required in the function call.
• Pre- and post-conditions tell us what the function will do if the preconditions are met.