Lab 3a: Functions & Libraries

course.wilkes.edu/CS125Labs
Welcome to the site for CS 125 labs!

Lab 3a: Functions & Libraries

Introduction

As you likely found out the last time you purchased your last textbook, books can be quite expensive. One way that this expense can be reduced is the idea of sharing: If you are unable to afford the full price for a book, and can find another person with the same problem, then you might purchase the book together, and share it. By having one person use the book and then another person re-use the book, the individual cost of using the book is cut in half.

A library is a generalization on this idea of sharing. If a community of people pool their resources, then they can buy and share a centralized collection of books. By cooperating this way, each person has access to a greater set of books than he or she could afford individually.

The ideas of sharing, libraries and re-use are very important in C++, and we have already (unwittingly) used them extensively. For example, in the previous lab exercises, we wrote

   #include <iostream>

Recall that the effect of this directive is to insert the contents of the file iostream (in which cin, cout, << and >> are declared) into our source program. Recall also that each of the programs we have written has re-used this same set of declarations. The file iostream is thus similar to a library of books, in that it contains a set of declarations that can be shared and re-used by any program that needs them. In fact, iostream is a part of the iostream library -- a software library of I/O related functions.

Software libraries are particularly useful and important, because with carefuly planning, they can reduce the cost of programming. For example, in a previous lab exercise, we used the sqrt() function from the C++ math library, and so avoided the extra "cost" of having to write our own square root function. Libraries thus provide a place where groups of related functions can be stored, so that we (or even other programmers) can access them and thus avoid "re-inventing the wheel."

While C++ provides a number of ready-made libraries for us, C++ also permits programmers to create their own libraries, which are technically called library modules, or just modules. (We will use the terms library and module interchangeably.) Creating a library is the subject of today's exercise.

Review

Let us briefly review what we know about function libraries. We have seen that C++ provides a variety of function libraries, including cmath that provides various mathematical functions, and cctype that provides character-processing functions.

To use a library function, a program must use the #include directive to include the library's header file:

   #include <cmath>

which inserts declarations of the library's functions into the program.

To call a function, you must give its name and a pair of parentheses containing any arguments the function needs to do its job:

   result = pow(x, y);

When control reaches such a function call, the arguments x and y are evaluated and passed to the function, which performs its task and (if appropriate) returns a value back to its caller (in this case x^y).

Planning a Library

To keep our presentation simple, we will construct our library in our working directory for this exercise (e.g., ~/cs125/labs/3a), so begin by creating that directory and then change directory so that it is the working directory.

The library we will create today will provide us with a set of functions to convert English-system measurements into their metric-system counterparts. We will call our library metric.

The first thing that we must decide is what measurement conversions we wish our library to provide. For example, the following are just a few of the useful conversions:

English Unit Metric Unit Conversion Formula

Inches Centimeters 1 inch = 2.54 cm

Feet Centimeters 1 foot = 30.48 cm

Feet Meters 1 foot = 0.3048 m

Yards Meters 1 yard = 0.9144 m

Miles Kilometers 1 mile = 1.609344 km

Ounces Grams 1 ounce = 28.349523 g

Pounds Kilograms 1 pound = 0.453592 kg

Tons Kilograms 1 ton = 907.18474 kg

Pints Liters 1 pint = 0.473163 l

Quarts Liters 1 quart = 0.946326 l

Gallons Liters 1 gallon = 3.785306 l

Our exercise today is to write a subprogram (more precisely, a function) to convert feet into meters. By storing this function in library metric, it can be shared by any and all programs that need to convert feet into meters, allowing them to avoid "redefining the wheel."

Library Structure

A library consists three separate files:

the library's header file in which you declare each name that is to be accessible outside the library;
the library's implementation file in which you define each name declared in the header file; and
the library's documentation file in which you can write comments about how to use the library.

The documentation file is not strictly necessary, any more than are comments within a program; however it is good style to always provide such a file, and store within it all of the information needed to use the library. Our custom is to place function specifications in this file.

The header file is necessary, and its role is to provide an interface to the library, by providing just enough information for a program to use the functions it provides, without specifying their details. The part of the function that is provided in the header file is called its declaration or prototype. We will use the term prototype throughout this manual.

By contrast, the role of the implementation file is to provide complete definitions of the library's functions. An implementation file thus contains a series of function definitions.

Why this separation? The reason has to do with program maintenance. If we are writing a library, then we expect that a number of programs will make use of it. It is often the case that even a well-designed library may need to be updated (i.e., maintained), if a better way is discovered to perform one of its functions. If we have designed our functions carefully, then updating a library function should simply involve altering its definition (in the implementation file), not its prototype (in the header file).

Now suppose that a program could access and make use of the definition details of a library function. If it did, then updating the function will likely change those details, and if the program were written in such a way as to be dependent on those details, then it would have to be updated, too. That is what we want to avoid at all costs -- we should never have to modify a program as a result of updating a library function.

By separating a library into two files, we can place the prototypes in one file and make it visible to a program (via the #include directive), while keeping the definitions "hidden" from the program in the implementation file. This makes it impossible to write a program that is dependent on the definition details of a function.

Header File Structure

Begin by making sure that your working directory is labs/3a. Then save copies of Makefile,metric.h,metric.cpp, metric.doc,and driver.cpp to your working directory.

Using your text editor, edit metric.h (the name of the library's header file usually ends in .h) and personalize its opening documentation. A simplified general pattern for a library header file is as follows:

   OpeningDocumentation
   PrototypeList

where OpeningDocumentation is a comment describing the purpose of the library, who wrote it, when it was last updated, and so on; and PrototypeList is any sequence of valid C++ declarations.

Function Design

As we have seen, software that is carefully designed is better than software that is poorly designed. The same holds true for functions, so let's spend a few moments using object-centered design to design our function.

Behavior

   Our function should receive from its caller the number of feet
   to be converted, and should check that this value is positive.
   It should convert that quantity to meters by multiplying it by
   0.3048, and return the resulting value to the caller.

Note that where a program typically inputs values from the keyboard, a function typically receives values from whoever called the function. Similarly, where a program typically outputs values to the screen, a function typically returns a value to whoever called the function

Note also that we want to try and anticipate what could go wrong. Since the function will only produce a correct result if the value it receives is not negative, we say that this function has a precondition, a condition that must be true in order for the function to execute correctly.

Objects

The objects of a function are similar to those of a program, except that in addition to describing the type and kind of each object, we also want to describe its movement: does it move into the function from outside, does it move from the function out to the outside, or is it purely local to the function?

Description Type Kind Movement Name

the number of feet double varying in feet

the conversion factor double constant local 0.3048

the corresponding number of meters double varying out meters

This information provides us with what we need to specify the problem our function solves:

   Specification:
      receive: feet, the (double) number of feet to be converted.
      precondition: feet is not negative.
      return: meters, the (double) equivalent of feet in meters.

Note that we include the function's precondition as part of its specification.

This specification in turn provides us with what we need to write a function prototype. The simplified pattern for a function prototype is

   ReturnType FunctionName ( ParameterDecList ) ;

where

ReturnType is the type of value the function returns,
FunctionName is the name of the function, and
ParameterDecList is a list of declarations of parameters -- objects that will store values that are passed to the function when it is called.

That is, a parameter must be declared for each value that a function receives from its caller.

A precise function specification tell us how to build the function's prototype. To illustrate:

The specification tells us that FeetToMeters() must return a real value to its caller, and so its ReturnType should be double.
The specification also tells us that FeetToMeters() must receive one real value from its caller (the number of feet to be converted), so FeetToMeters() should have one double parameter, which we will call feet.

We can thus complete our header file with this prototype of function FeetToMeters():

   double FeetToMeters(double feet);

After you have added this line to metric.h, copy-and-paste it into metric.doc, below its specification.

Since parameters are like variables, their names usually begin with a lowercase letter, with every word after the first capitalized. By contrast, each word in a function's name is capitalized.

As this illustrates, the stages of software design are fluid, not firm. We can build a function's prototype (a part of coding) during our design stage, as soon as we have enough information. (And the specification provides all of the necessary information to write the prototype.)

Operations

Continuing with our design, our list of needed operations is quite short:

Description Predefined? Name Library?

get a value from the caller yes parameter mechanism built-in

check that the value is not negative yes value >= 0 built-in

halt the program if the value is not negative yes assert() cassert

multiple two real values yes * built-in

return a value to the caller yes return built-in

As we shall see, the C++ parameter mechanism permits a function to automatically receive a value from its caller, and the C++ return statement permits a function to return a value to its caller.

To test our precondition and halt the program if it fails, we can use the assert() mechanism and a boolean expression that returns true if and only if feet is not negative.

Algorithm

We can then organize these operations and objects into the following algorithm:

   1. Receive feet from the caller.
   2. Halt the program if feet is negative.
   3. Compute meters = feet * 0.3048.
   4. Return meters.

Given an algorithm, we are ready to define FeetToMeters() in our implementation file.

Implementation File Structure

As stated previously, the definitions of library functions are stored in the library's implementation file, so using your text editor, open the file metric.cpp. (Implementation file names end in the .cpp suffix.

The general pattern for an implementation file is as follows:

OpeningDocumentation

#include "HeaderFileName"

DefinitionList

Take a moment to personalize the opening documentation, and add a #include directive that inserts the header file of our metric library. (Note that quotes, not <>, surround the file name. This tells the compiler to search the working directory for the file, instead of the special system include directory.)

Defining A Function (Coding)

The general pattern for a function definition is

   ReturnType FunctionName ( ParameterDefList )
   {
      StatementList
   }

where

ReturnType and FunctionName are the same as in a function prototype;
ParameterDefList is a list of parameter definitions (i.e., the parameter names must be supplied); and
StatementList is a sequence of valid C++ statements.

A function stub is a minimal function definition -- like a function prototype, but followed by a pair of empty braces, instead of a semicolon. For example, we might define the following stub for FeetToMeters():

   double FeetToMeters (double feet)
   true

Insert this stub at the end of the implementation file and then compile it using the command:

   Compile command: g++ -c metric.cpp

If all is well, then the function stub in metric.cpp should compile without generating any error messages. If you do get errors, find and correct them before continuing.

Take a moment and consider what we just did. We just compiled a file that contains no main program and the compiler didn't generate an error. How can this be?

The answer is the idea of separate compilation. Translation of a program is actually a two-step process:

compiling the source file creates an object file, and
linking the object file to any libraries it uses creates a binary executable file.

The -c switch tells g++ to just do the first step (i.e., stop after compiling), and so it produces the object file metric.o. What happens if you compile metric.cpp without the -c switch?

Now that we have a stub, we can "fill it in" using our algorithm and stepwise translation.

1. Receive feet from the caller.

This step is taken care of for us by the C++ function-call mechanism. When the caller evaluates an expression that calls our function, such as:

   FeetToMeters(2.5);

a copy of the argument 2.5 will automatically be stored in parameter feet in our function. That is, when our function begins execution, the value of feet will be the value of the argument with which the function was called (2.5, in this example).

2. Halt the program if feet is negative.

We can accomplish this step using the C++ assert() mechanism:

   assert(BooleanExpression);

which, given a boolean expression, allows execution to proceed normally if the boolean expression evaluates to true, but halts the program and displays a diagnostic message if it evaluates to false. We can thus test our function's precondition by adding the line

   assert(feet >= 0);

as the first statement in the function. To use assert(), you must #include the header file cassert (or assert.h, depending on how ANSI-compliant your compiler is).

3. Compute meters = feet * 0.3048.

Using the declaration statements and expressions that we learned about in lab 2, add a declaration statement to FeetToMeters() that performs step 2 of our algorithm. Recompile metric.cpp, and continue when its syntax is correct.

4. Return meters.

The third operation can be performed using the C++ return statement, whose general pattern is:

   return Expression;

where Expression is any valid C++ expression.

In the stub of FeetToMeters(), write a return statement that accomplishes the third operation. Then recompile metric.cpp to verify that what you have written is free of syntax errors. When it is, continue on in the exercise.

When metric.cpp is free of syntax errors, we are ready to test FeetToMeters(). To do so requires that we call FeetToMeters() from a program. The header file metric.h provides an interface to the function, since it contains a prototype of FeetToMeters(); and the implementation file metric.cpp provides the details of how FeetToMeters() is defined.

Click here for Part II

Prev | Next | Lab 3a

Home

Help

Lab 0

Lab 1

Lab 2

Lab 3a

Lab 3b

Lab 4

Lab 5

Lab 6