Functions & Libraries

Transcription

1 Chapter 6 Functions & Libraries F unctions are named "chunks" of code that calculate a value or that carry out an action. The essential characteristic of a C++ function is that it associates a computation specified by a block of code that forms the body of the function with a particular name. Functions can reduce bugs and make your maintenance more effective by allowing you to reuse proven code that you've written, instead of duplicating it. In this chapter we're going to look at packaging your functions into libraries, so that you can reuse them without resorting to "cut and paste". As usual, we'll start by working through a homework assignment. Upload the H09 starter code to your workspace. Once that's done, we'll write some functions to get some help with integers, and then place them into a library. Our library will have the following three functions: int firstdigit(int n), returning the first digit of its argument int lastdigit(int n), returning the last digit of its argument int numdigits(int n), returning the number of digits of its argument Here's how the functions will work. Calling firstdigit(1729) will return 1, calling lastdigit(1729) will return 9, while calling numdigits(1729) returns 4. Here are some hints that should help you write these functions: n % 10 returns the right-most digit of any integer n You can find the left-most digit by repeatedly dividing n by 10 until n is < 10. Dividing n by 10 until n is < 10, the number of iterations is the number digits. In the last chapter, you implemented functions that I already declared and documented for you. In this chapter, you'll learn how to declare, document and define and implement your own functions.

2 D E F I N I N G A L I B R A R Y P A G E 6-2 Defining a Library To define a library in C++, you supply two parts: the interface, which provides the information needed to use the library but leaves out the details about how the library works. the implementation, which specifies the underlying details. A typical interface will contain several definitions, including functions, types, and constants. In C++, the interface and implementation are usually written as two separate files: a header file and an implementation file. The header or interface file usually ends with.h, or, for libraries that contain template code,.hpp or.hxx The implementation file usually has the same root or base name, but a different extension. We'll use.cpp. in this class but other conventions include.cxx,.cc, and.c (a capital 'c'). Following this convention, our integer 411 library (for H09) interface will be declared in h09.h and defined or implemented in h09.cpp. Creating the Interface File When you open h09.h, you'll see that it is essentially an empty file. Get started by adding the file header documentation for Doxygen, and then just copying the three prototypes from the problem specification (at the beginning of this chapter.) Here is what the h09.h interface looks like after I've done that. Prototype Notes The prototypes for the three functions in our library look exactly as they would (except for the semicolon) if they appeared in our source file. There is one time, however, when the interface form of the prototype will be different: if the prototype includes any types from the standard library (such as string or vector). Comparing the interface version of the zipzap() function with its implementation: std::string zipzap(const std::string& str); // interface form string zipzap(const string& str) // implementation form

3 C H A P T E R 6 F U N C T I O N S & L I B R A R I E S Inside the interface, both the parameter and the return type use the name std::string to indicate that string comes from the std namespace. Interfaces should never use identifiers from that namespace without explicitly including the std:: qualifier. Here are three rules to remember. 1. Never add using namespace std to a header file. Because interface or header files are #included in other files, doing so changes the environment of that file. 2. Always add std:: in front of every library type parameter, such as std::string, but never in front of primitive types like double. 3. Remember for all library types, you must #include the appropriate header file inside your header file. The error interface uses the std::string type, so it must #include <string> Documenting the Interface The comments shown here can be processed by a documentation tool named Doxygen to generate HTML and other kinds of documentation. According to the Web site: Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D. Find more extensive information on the Web site. If you want to experiment on your own, use sudo apt-get install doxygen to install the software into your workspace. For now, I just want you to use these: The File Comment The interface file should have a file comment that contains these common Name of the file. Required if you are going to document functions, global variables and constants. Always use your date it was created, then edited (can be version information about the library (optional)

4 P R E P R O C E S S O R H E A D E R G U A R D S P A G E 6-4 Function Comments Each function should also be documented. Here are the tags you should generally a one line description. If you start your comment block with a single line ending in a period, you can omit the name and description of every parameter to your if the function returns a value, you should add this tag You may also want to include the a block of code that will be syntax highlighted in the generated documentation. This block must end with tag. Go ahead and add your own comments (in front of) each of the functions. On the next page, after I discuss preprocessor header guards, you'll see the comments that I added and you can check them against your own code. Preprocessor Header Guards Suppose you have the following situation: #include the header file a.h that has a single line: #include "b.h" File b.h should also have a single line: #include "a.h" I'm sure you see the problem. This is not an artificial situation. If you include <iostream>, it normally includes the <string> header, because the stream objects have to know how to read and write string objects. However, because the <string> header contains the prototype for the function getline(), the <string> header also needs to know about the istream and ostream classes, so it needs to include the <iostream> header which includes <string> once again ad infinitum. This is the same situation we started with. We something to make sure that the compiler doesn t include the same interface twice. Do that by adding three lines to every header file that are known as the interface boilerplate, or header guards. The basic structure looks like this: #ifndef FILE_IDENTIFIER #define FILE_IDENTIFIER // Entire contents of the header file #endif

5 C H A P T E R 6 F U N C T I O N S & L I B R A R I E S This pattern of lines will appear in every interface. Header guards are instructions to the preprocessor, a program that examines your code before it is sent to the compiler. The boilerplate consists of the #ifndef and #define lines at the beginning of the interface, combined with the matching #endif line at the end. The #ifndef preprocessor directive checks whether the FILE_IDENTIFIER symbol has been defined. When the preprocessor reads this interface file for the first time, the answer is no. The next line, however, tells the preprocessor to define that symbol. Thus, if the preprocessor is later asked to #include the same interface, the FILE_IDENTIFIER symbol will already be defined, and the preprocessor will skip over the contents of the interface this time around. A common convention is to simply capitalize the name of the file itself, replacing the dot with an underscore. You may use another convention if you like. The specific name you are asked to check is not as important as making sure that the name will be unique when you build your project. The Finished Interface Here's my version of the finished interface file (for the first function). #ifndef H09_H #define H09_H /** h06.h Stephen Gilbert Fall 2017 */ /** * Returns the first digit in any integer n. n the integer to check. May be negative. the first digit of the integer n. * int a = firstdigit(215); // returns 2 * int b = firstdigit(-79); // returns 7 (not -7) */ int firstdigit(int n); // Rest of the functions here #endif

6 T H E I M P L E M E N T A T I O N P A G E 6-6 The Implementation To implement the functions in our library we need to follow the same steps you did for homework assignments in the last chapter. You need to: Create an implementation file using the extension.cpp. Your starter code for H09 already comes with h09.cpp. Remember to add a file comment to the top of the file, and to #include the interface file for the library. Next, copy the prototypes from each of the functions into the implementation file. You don't need to bring across the documentation. Stub out each of the functions, by removing the semicolon at the end of the function, adding braces, and creating and returning a result from each function that requires it. This is a purely mechanical process, and you want to practice it until it becomes second nature. You should memorize this part, so you don't have to expend any brain cells to complete it. Warning. Make sure your stub includes a return statement of the correct type, or your function will crash at runtime. Planning your Functions Start the implementation by creating a plan and documenting it, adding implementation comments to each function. These comments are intended for programmers, not for the clients of the function. Don't use DOXYGEN tags, but describe the algorithms and important implementation details. Here, for instance is my plan for lastdigit(): /* * Return the right-most digit of n. * * 1. If n is negative, convert to a positive * 2. Return n % 10 */ In the picture here I've used multiline comments, but single-line comments may be easier since most editors will comment and un-comment a portion of code, using only a single keystroke. In the CS50 ide, that keystroke is Shift+/.

7 C H A P T E R 6 F U N C T I O N S & L I B R A R I E S Implementing lastdigit I'd encourage you to write your comments first, and then implement the function. Of course, with small functions like this, you often will plan it out, and then simply write the code directly from the comment. int lastdigit(int n) { int result = n < 0? -n : n; return result % 10; } In this case, I've used the conditional operator to set the result to convert n to a positive number. I could also easily have used the abs() function in <cstdlib>. The only problem with using abs() is that there are separate versions in <cmath> (for integer), and in <cstdlib> for (floating-point numbers), and I find it easy to get them confused some times. Parameters and Local Variables Notice that instead of changing n itself, I've created a separate variable named result. This is generally considered better style, because it doesn't confuse the concept of a parameter or input variable, with that of a local variable used for the function output. Of course, since n is a value parameter, in this case it doesn't make any actual difference to the code. Later in this chapter, you'll learn about reference parameters where it will. Introducing the Limit Loop The other two functions are a little more difficult. Both of them require you to learn about a new kind of loop bounds, called limit bounds. Loops that do some processing and then check the results against some boundary condition are limit loops. Here is a limit loop which computes the sum of the digits in an integer, n: int sum = 0; while (n > 0) { sum += n % 10; n /= 10; } This loop depends on the following observations: The expression n % 10 always returns the last digit in a positive integer n. The expression n / 10 returns a number without its final digit.

8 I N T R O D U C I N G T H E L I M I T L O O P P A G E 6-8 In this case, the condition that is being tested is the value of n, which is changed each time through the loop. Once n reach its limit (0), the loop terminates. Here are some other limit loop uses. Successive approximations that compare a calculation to the result from the previous iteration, and stop when the results are approximately equal. Bisection methods that are used to calculate approximations, and compare them to some previously known value (such as π). Non-convergence tests that monitor the direction of a series of calculations. Here is the plan I created for each function. Using limit loops, you should be able to complete these. If you get stuck, ask for help on Piazza. The firstdigit Function /* * Returns the first digit of n. * * 1. If n is negative, convert it to a positive * 2. While n is >= 10 * 3. Divide n by 10 * 4. Return n. */ The numdigits Function /* * Returns the number of digits in n. * * We'll assume that 0 is 1 digit. Can't have 0 digits. * 1. If number is negative, convert it. * 2. Create a counter, set to 1. * 3. While number is >= 10 * 4. Divide by 10 * 5. Increase counter * 4. Return the counter. */ Once you've completed the functions, be sure to check your code (make test) and submit the results (make submit) before the deadline.

9 C H A P T E R 6 F U N C T I O N S & L I B R A R I E S Part 2 - More Function Features W hile we have already covered the basics of using functions in C++, there are several additional features you might want to use. Function overloading allows you to use the same name for several different functions, provided that each version of the function takes a different type or number of parameters. Default parameters allow you to write a single function that can be called in several different ways. And, finally and most importantly, reference parameters allow you to write functions that pass information back to the caller through the parameter list, instead of through the return statement. Function Overloading In C++, it is legal to give the same name to more than one function as long as the pattern of arguments is different. This is called function overloading. The pattern of arguments taken by a function which refers only to the number and types of the arguments and not the parameter names is called its signature. For example, both <cmath> and <cstdlib> have several versions of the function abs(). In <cstdlib> library you'll find these three versions of abs(): int abs(int n); long abs(long n); long long abs(long long n); while <cmath> has these five versions: double abs(double x); float abs(float x); long double abs(long double x); double abs(t x); There are even versions for complex numbers in the library <complex>. The only difference between these functions is the type of argument used as the parameter. The compiler chooses which version to invoke by looking at the types of the arguments the caller provides. If abs() is called with an int, the compiler calls the int version of the functions and returns a value of type int. If you call abs() with a double, then the compiler will choose the version that takes a double.

10 D E F A U L T P A R A M E T E R S P A G E 6-10 If you call abs() with an integer, and only include <cmath>, but forget <cstdlib>, then a special generic version of abs() that takes a type T parameter will be called. The difference between the generic version, and the overloaded abs(int) version, is that the generic version always returns a double, not an int. The advantage of using overloading is that it makes it easier for programmers to keep track of different function names for the same operation when applied in slightly different contexts. Without overloading we'd need to have different function names for each version: iabs, fabs, dabs, labs, llabs, and so on. Default parameters In addition to overloading, C++ makes it possible to specify that certain parameters are optional. Such parameter declarations still appear in the function header line, but include a value to be used if no value is supplied when calling the function. These optional parameters are called default parameters. To indicate that a parameter is optional, you include an initial value in the declaration of that parameter in the function prototype, exactly as if you were initializing a local variable. For example, you might define a procedure with the following prototype: void formatincolumns(int ncolumns = 2); The formatincolumns() procedure takes the number of columns as an argument, but the =2 in the prototype declaration means that this argument may be omitted. If you leave it out and call formatincolumns(); the parameter variable ncolumns will automatically be initialized to 2. Default Parameter Rules When you use default parameters, it helps to keep the following rules in mind: The default value appears only in the function prototype and not in the function definition. Default parameters must appear at the end of the parameter list and cannot be followed by a non-default parameter. It is always possible and often preferable to achieve the same effect through overloading. Suppose, for example, that you want to define a procedure named setinitiallocation() that takes an x and a y coordinate as arguments. The prototype presumably looks like this:

11 C H A P T E R 6 F U N C T I O N S & L I B R A R I E S void setinitiallocation(double x, double y); Now suppose that you want to change this definition so that the initial location defaults to the origin (0, 0). One way to accomplish that goal is to add initializers to the prototype, like this, so that x and y are both default arguments. void setinitiallocation(double x = 0, double y = 0); The problem with this is that it makes it possible to call setinitiallocation() with only one argument, which would almost certainly be confusing to anyone reading the code. It is better to just define an overloaded version of the function like this: void setinitiallocation() { setinitiallocation(0, 0); } Reference Parameters In C++, whenever you pass a simple variable from one function to another, the function gets a copy of the calling value. Assigning a new value to the parameter as part of the function changes the local copy but has no effect on the calling argument. For example, if you try to write a procedure that initializes a variable to zero like this: void settozero(int var) { var = 0; } the procedure ends up having no effect whatever. If you call it like this: settozero(x); the parameter variable named var is initialized to a copy of whatever value is stored in the variable x. The assignment statement var = 0; inside the function sets the local parameter variable to 0 but leaves x unchanged in the calling program. That's why, in the lastdigit() function, we could have used the parameter variable n to do our calculations, instead of creating a separate result variable.

12 R E F E R E N C E P A R A M E T E R S P A G E 6-12 The practice of making a copy of arguments when calling a function, and then placing those copies into the appropriate parameter variable is known as pass by value or call by value, and the parameter x is known as a value parameter. Reference Parameters If you want to change the value of the calling argument, you can change the parameter from a value parameter into a reference parameter by adding an ampersand between the type and the name in the function header, like this: void settozero(int& var) { var = 0; } Unlike value parameters, reference parameters are not copied. What happens instead is that the function receives a reference to the original variable, which means that the memory used for that variable is shared between the function and its caller. The parameter variable is not a new variable, but simply an alias for an existing variable. L-values and R-values This style of parameter passing is known as call by reference. When you use call by reference, the argument corresponding to the reference parameter must be an assignable value, such as a variable; this is called a modifiable L-value. (The L means it can appear on the left of an assignment.) Calling settozero(x) correctly sets the integer variable x to 0. However calling settozero(y) does not work because even though y can appear on the left-hand-side of an assignment expression, it cannot be modified once it has been given a value. The constant y is an L-value, but it is non-modifiable. Finally, it is illegal to call setto- Zero(3) because 3 is not assignable; since it can only appear on the right-hand-side of an assignment operation, we call it an R-value.

13 C H A P T E R 6 F U N C T I O N S & L I B R A R I E S Input & Output Parameters To return more than one value from a function, we can use reference parameters to pass values back and forth through the argument list. As an example, suppose that you are writing a program to solve the quadratic equation ax 2 + bx + c = 0 You want to structure that program into three IPO phases like this. Using top-down design, your main might look like: int main() { double a, b, c, root1, root2; getcoefficients(a, b, c); solvequadratic(a, b, c, root1, root2); printroots(root1, root2); } return 0; The variables a, b and c will hold our three coefficients, while the variables root1 and root2 will hold the two roots. The getcoefficients function will ask the user for the three values and place them into the three variables a, b and c, which are passed by reference. If a function needs to return more than one piece of information, it can use reference parameters. Here is one possible implementation of the function: /** * getcoefficients(a, b, c) * Reads the coefficients into three reference parameters. * x the first coefficient. y the second coefficient. z the third coefficient. */ void getcoefficients(double& x, double& y, double& z) { cout << "Enter three coefficients separated by spaces: "; cin >> x >> y >> z; } Note that when you call getcoeffients, information does not flow from main into the function; instead, information flows out of the function into main, through the three output parameters x, y, and z, which are not new variables, but are simply new names or aliases for the variables a, b, and c that were used when calling the function.

14 R E F E R E N C E P A R A M E T E R S P A G E 6-14 There are two other features you should notice in this function: Instead of separate input statements, you can read three variables using a single input statement as I've done here. The values typed or entered by the user must be separated from each other by whitespace, not commas. Spaces, tabs or newlines all work fine. When documenting your function parameters, the documentation tool we are using (DOXYGEN) allows you to annotate each of the parameters with the direction of the information flow: [in], [in,out], [out]. If you don't annotate a parameter it is assumed to be an input parameter. Input and Output Parameters The solvequadratic function uses both input and output parameters. The arguments a, b, and c are used as input to the function and give it access to the three coefficients, while the arguments root1 and root2 are output parameters and allow the function to pass back the two roots of the quadratic equation to main. /** * Solves the quadratic equation for roots a, b, and c. * a the first coefficient b the second coefficient c the third coefficient x1 the first root x2 the second root */ void solvequadratic(double a, double b, double c, double& x1, double& x2) { if (a == 0) error("the coefficient for a must be non-zero."); double disc = b * b - 4 * a * c; if (disc < 0) error("this equation has no real roots."); } double sqrtdisc = sqrt(disc); x1 = (-b + sqrtdisc) / (2 * a); x2 = (-b - sqrtdisc) / (2 * a); Introducing Error Handling This program also introduces a new strategy for reporting errors. Whenever the code encounters a condition that makes further progress impossible, it calls a function named error() that prints a message indicating the nature of the problem and then terminates the execution of the program. The code for error looks like this:

15 C H A P T E R 6 F U N C T I O N S & L I B R A R I E S void error(const string& msg) { cerr << msg << endl; exit(exit_failure); } The code for error() uses three C++ features that we have not yet talked about. The parameter variable msg is passed by const reference. We'll always use const reference parameters when we have large objects that we don't want to copy (that's what the & does), and, when we want to make sure that the function does not modify the parameter in the caller (that's the const). The cerr stream is similar to cout, but is reserved for reporting errors. The exit() function terminates the execution of the main program immediately, using the value of the parameter to report the program status. The constant EXIT_FAILURE, defined in the <cstdlib> library, is used to indicate that some kind of failure occurred. The error() function, of course, would be useful in many applications beyond this. Although you could easily copy the code into another program, it would make much more sense to save the error function in a library. On your Own Going Postal For the second program in this chapter (H10), I'm going to leave you on your own. Upload the starter code to your workspace, and then complete the following problem Going Postal using the same techniques you learned in this chapter. (I have already supplied the headers and documentation, however.) For faster sorting of letters, the United States Postal Service encourages companies that send large volumes of mail to use a bar code denoting the zip code as shown here: The encoding scheme for a five-digit zip code is shown below.

16 O N Y O U R O W N G O I N G P O S T A L P A G E 6-16 There are full-height frame bars on each side. The five encoded digits are followed by a check digit, which is computed by adding up all digits, and choose a check digit to make the sum a multiple of 10. For example, the number has a sum of 19, so the check digit is 1 to make the sum equal to 20. Each digit of the zip code, and the check digit, is encoded according to the following table where 0 denotes a half bar and 1 a full bar. To solve this problem, you'll write three functions: string codefordigit(int digit) which takes one digit and returns the appropriate code for that digit, using the table above. Use ':' for the half-bars and ' ' for the full bars.

17 C H A P T E R 6 F U N C T I O N S & L I B R A R I E S int checkdigit(int zip) which calculates the check digit according to the rules shown above. string barcode(int zip) which returns an entire bar code by breaking the number into individual digits, encoding that digit, and adding it to the string return value. Finally, calculate and encode the check digit, surround the entire code with the frame bars, and return it. You'll find the starter code in the download folder. Start with the codefordigit() function first. Run the tests for that. Next, calculate the checkdigit() function and run the tests for that. Finally, finish up the barcode() function. If you get stuck, ask for help on Piazza. Study Guide Questions Interface files end with while implementation and client files end with. Describe the parts that make up an interface header guard. Write one for zzy.h List several documentation tags and describe their meanings. Add the appropriate documentation and tags for the following function: int countvowels(const string& str); Functions that have the same name are said to be. We distinguish between multiple functions with the same name by examining the function's. You can call a single function in several different ways, by giving the function. To allow a function to change an argument passed to it, declare the parameter as. Arguments that are passed to functions taking reference parameters must be. A named constant, which can only be assigned a value once, is known as a. A value that can only be used on the right-side of an assignment is called a(n), Look at the code below and choose the best prototype to use in this situation. Note that these are NOT overloaded functions; only one will be used.

18 S T U D Y G U I D E Q U E S T I O N S P A G E 6-18 Look at the code below and choose the best prototype to use in this situation. Note that these are NOT overloaded functions; only one will be used. Examine the prototypes for the overloaded functions shown here. All of these functions appear in the same file. They are legal and they compile. Which function is invoked when making the following calls? fn(1, 2, 3, 4); fn(1, 2, 3); double n = 3.5; fn(1, 2, n); fn();