CMSC 106

Project #5

Fall 2001

Due date: 11:00 PM, November 14, 2001

1. Purpose

In this project you will write a program which uses functions and which reads input until no more data is seen, and develop the program by testing the functions as each one is written.

The hurricane model in Project 4 could handle a single hurricane, but there are features you can add that will allow it to handle more than one storm. In order to add these features, you will need to implement a number of functions and modify your solution for Project 4 to use them.

2. Project description

As you read this section, you may also want to refer to the ``Sample output'' section below.

Your program will now have two different hurricanes moving around on the same map. Each storm will continue to move until it is unable to do so according to the rules given.

2.1 Program input changes

The differences in your program's input compared to the previous project are described in this section. Other than the details mentioned here, you can assume the input files for project 5 will be the same as the corresponding input files from project 4.

The input line containing the starting location and strength of the storm will be followed by another input line containing 4 integers which represent the starting location and strength of another storm. (Although in some ways it would be easier to write your program to handle any number of storms, it is only required to handle two storms.)

Otherwise, the input will consist of 1 or more sets of map and storm data as described in the requirements for Project 4. The program will read sets of input data terminated by an exclamation point ('!') until it reaches the end of the input file.

2.2 Program processing and output changes

The differences in your program's processing and output from before are described in this section.

Each storm makes one move at a time. Storm ``A'' moves first, followed by storm ``B'', etc. until one of the storms is unable to move. Then the other storm continues moving until it also is unable to move.
The table of storm positions (row and column), pressure, and wind speed must have two sets of columns in each row, one set for each storm. The columns must be aligned so that each row contains data for storm "A" followed by the data for storm "B". If one of the storms is no longer moving, the columns for that storm must be blank.
After both storms have finished moving, the program must print out two sets of messages and maps, one set for each storm. This means that each storm must keep track of its path on an individual copy of the map. Each set of messages (minimum and maximum pressure) and maps must be in the same format as before, but each set of output must be labeled to show which storm it is for. The label must have the words "Summary for" followed by "A" or "B". The words must be preceded and followed by 12 equal signs ('='), as shown in the sample output.
If one storm is no longer able to move because either:
- the next point would be off the edge of the map.
- the next point would be the same as any previous position of the storm.
- it is absorbed into the other storm as the result of a collision.
its track will stop at that point, but the other storm will continue to move until it is also unable to move.
One storm will absorb the other storm when it moves into the same location as the other storm. For example, suppose storm ``B'' is currently at row 7, column 4. The next move is for storm ``A'', and its new position is row 7, column 4. Then ``A'' will absorb ``B''. At this point, ``B'' will stop moving, but ``A'' will continue to move. In general:
- The storm being absorbed will no longer move or change strength.
- The new pressure and wind speed of the absorbing storm will be the minimum of the two pressures and the maximum of the two wind speeds, rather than the pressure and wind predicted by the usual rules involving land and water.
The program will stop calculating storm positions and strengths and print the final set of output only when both storms are unable to move.
Before each set of output (hurricane forecast or error message), the program must print a separator line, as it did in Project 3. This line consists of an integer (starting with 1 for the first set of input lines) followed immediately by a space which is then followed by a series of exactly 20 plus signs ('+'). This line must be followed by a blank line.

Any other requirements and tasks your program had to perform in Project 4 still apply to this project, even if they are not mentioned above, unless specifically contradicted or modified here.

3. Required functions and implementation

You are to implement and call at least six of the functions described below, which must perform as stated, and be named exactly as shown. If your program doesn't contain, and call, at least six of these functions, it will be graded as if it does not work on the primary input - even if that output is correct. You are only required to write six functions to have a ``working'' project. If you write at least six of them (and your output matches the sections of output identified as the primary output), you can receive over 50 of the 100 points. To earn full credit (up to 100 points) on the project, your program must produce the complete output shown and you must implement at least ten of the functions described below. These functions must be named as shown and function as described. Keep in mind that the more of these functions you write, the easier your program will be to test and implement correctly. You are permitted to write functions beyond those shown, but these additional functions will not count towards the required total. Your functions must perform the tasks described below, but you may add functionality so any of your functions do more than what's specified.

Your functions' parameters may be named anything you like and may be in any order you choose. If you want to add new parameters or remove parameters listed you may do so, so long as you follow the project requirements listed below, and as long as your function still performs the required task as described.

Functions should call the others described where appropriate. You should write and test each function separately, starting with the simpler ones, before implementing those which could depend upon them. As each is completed, you can modify your previous project by replacing code which performs the same task as the new function with a call to it instead.

In many cases it is apparent where each function should be used. For instance, the print_map function described performs processing similar to a fragment of your previous project's code. In this case, you should turn that code into the body of the print_map function, and replace those statements with a call to the function itself. In a few other cases it may not be immediately obvious how a function should be used. However, as you write other functions, you will come across a situation where you need to perform the processing described by that function, so you can just write and call it at that point.

create_map: Will set up a map of the appropriate size using the geography data (land and water points) read from the input file. It will need the number of rows and columns and the map itself as arguments.
set_wind: Will set up the values for wind direction at each point on the map. It will need the number of rows and columns and the array of wind directions as arguments.
initialize_storm: Will set up the intial conditions for a storm. It will need to set the starting row and column of the storm, the initial pressure and wind values (including minimum and maximum), and the starting location on the path.
num_points: Will return an integer indicating how many points are available at a given position to make the strength calculation. The arguments include the current location and the number of rows and columns in the map.
num_water_points: Will return an integer indicating how many of the points involved in the strength calculation at a given position are over water. The arguments include the current location, the number of rows and columns in the map, and the map itself.
num_land_points: Will return an integer indicating how many of the points involved in the strength calculation at a given position are over land. The arguments include the current location, the number of rows and columns in the map, and the map itself.
move_storm: Will apply the forecast rules to determine the new location of a storm. It returns an integer which indicates whether or not the move was possible. The arguments include the wind direction, the current row and column, the storm path, and the number of rows and columns in the map.
absorb: Will process a collision by applying the rules for absorbing one storm into the other. The arguments include the paths of the two storms, the current row and column for each storm, and the pressure and wind values.
print_map: Will print out the map with the final path of a storm. The arguments include the map, the storm path, and the number of rows and columns.
modify_strength: Will apply the forecasting rules to determine the new pressure and wind values for a storm. The arguments include the current pressure and wind values and the number of land and water points.
check_strength: Will apply the rules for checking minimum pressure and wind speed. The arguments include the pressure and wind values.
valid_position: Will return an integer indicating whether a given row and column are valid locations on the map. The arguments include the row and column values and the number of rows and columns on the map.
is_collision: Will return an integer indicating if a given move will result in a collision with the other storm. The arguments include the new row and column of this storm and the current row and column of the other storm.

You can find other functions which could be written as well.

4. Project requirements

All your C programs in this course should be written in ANSI C, which means they must compile and run correctly with cc -std1 -trapuv on the OIT UNIX Class Cluster. You will lose credit if your program generates any warning messages when it is compiled. Prototypes must appear for all functions used, and at most one return statement may be used in any function. Even if you already know what they are, you may not use any C language features other than those introduced in Chapters 1 through 9 of your textbook, plus those presented in lecture while these chapters were covered. In addition neither the goto nor the continue statement may be used, and the break statement may not be used in any loop. Your program must contain only one single return statement at the end of main, and may not use the exit() library function at all. You must use character constants (i.e., 'A'), rather than numeric ASCII values anywhere character values are needed. Lastly, no global variables may be used. Using C features not in these chapters, or using global variables, the goto statement, the exit() library function, multiple returns, or break or continue in loops, will result in losing credit.

Your program must have a comment near the top which contains your name, login ID, student ID, your section number, your TA's name, and an original description of the action and operation of the program. Do not put your alias in this comment! In addition, you must have a short comment before each function explaining its action and operation. Your program should be written using good programming style and formatting, as discussed in class and throughout your textbook. For this project, style is considered to consist of:

adequate descriptive comments throughout (in addition to the comments mentioned above), to describe what your program is doing and how
neat and proper indentation and formatting, including correctly aligning braces using any of the bracing styles illustrated in your textbook
writing clear and readable code
use of meaningful descriptive variable and parameter names
use of symbolic constants for all ``special'' values which don't change and which are used in more than one place in your code, and for all array dimensions
avoiding disallowed C language features, including global variables, as discussed above
using prototypes for all functions
avoiding duplication of code by having a function do that task which is then called one or more times
avoiding testing things you already know to be true and things you already know to be false (e.g. testing the opposite of the if condition in the corresponding else clause)
avoiding multiple return statements in any function

5. Developing your program

You may want to skip this section at first, read the rest of the project, and come back to study it carefully when you are about to begin writing your program.

Because this project is larger than the previous projects, being able to determine what part of your code is causing an error is much more important. If you need to come to office hours, you will be expected to be able to tell us where the error is, or what you have done to try to locate it. This means having tested your functions, as explained below, so that you know which ones already work for sure. It also means it is absolutely necessary to develop your program in stages so that you are not trying to write and test all of the code at one time.

5.1 Program development strategy

As discussed in the earlier project assignments, it is very important to type in only a part of your program at a time and compile and test it, and verify that it is correct, before going on. For a program with functions, this means writing only one function at a time. It also means making sure that function is correct before calling it from your main function or another function. The way to determine if it is correct or not is to add test calls, or temporary statements just for the purpose of testing this function, to your program. You can add these calls at the beginning of your main function. The idea is that, having written a function, you know what it is supposed to do. Call it, passing some sample values as arguments and print its return value if it has one, to make sure that it does its whatever it was supposed to do correctly. If it's supposed to change some values in an array, print the array after the test call to insure the function did what it should have. You should be able to figure out by hand what results the function was supposed to produce for the call you wrote. If it doesn't do what you think it ought, you need to find out why before going on!

It may be best for you to implement the shorter functions first. After you write and test these you will have more practice with functions, and can go on to write those which are a little more complex.

Another good strategy would be to first implement the functions which duplicate behavior which your Project #4 had, since you should already have a working version for that project. Identify which statements in your Project #4 perform the same task as one of the functions described above and turn those statements into a function, replacing the statements by calls to that function. If your function is correct, you should get the same results as your Project #4 produced before. Only after you have written all such functions should you begin to adjust your program to take into account the ways in which your program is supposed to behave differently than Project #4.

Due to the complexities of reading character input, and the possibility of error which may occur, it's extremely important to carefully print the input values which your program reads to insure it's reading its input data correctly! Often one of the first steps of writing a program can be to simply write the code which reads the input and test it by printing the input values as they are read, because if the input isn't read properly clearly no code after that will be able to work right, even if written correctly.

5.2 Finding compilation errors

Here are several common compilation errors having to do with functions produced by the cc compiler on our class machines and what they mean:

In this declaration, the type of ``X'' is not compatible with the type of a previous declaration of ``X''

(where X is the name of one of your functions, and this error occurs where the function is declared)

This means you called a function before it was defined, or before the compiler saw a prototype for it. The solution is to add a prototype for every function at the top of the program file as soon as it is written, which tells the compiler everything it needs to know about the function so it won't become confused in this way.

In this declaration, the number of parameters differs from an earlier declaration of this function

The function as written has a different number of parameters than the prototype which you wrote for it.

Non-void function ``X'' does not contain a return statement

You wrote a function which you specified should have a return value, but you didn't include a return statement anywhere inside it. If you want the function to return a value, you have to add a return statement. Or, if you don't need it to return anything after all, change its declaration to indicate that it doesn't return anything.

In the declaration of ``X'', the array bounds are incorrectly specified

(where X is the name of a two-dimensional array parameter in one of your function definitions)

You can omit the first subscript of a two-dimensional array parameter when defining a function, but not the second one. This error is usually caused by trying to write a two-dimensional array parameter with two empty sets of brackets, such as arr[][]. The number of columns must appear inside the second set of brackets.

In this statement, ``X'' does not point to an object type

(where X is the name of an array parameter in some function)

This is typically caused by the same problem as the previous error.

5.3 Program testing

Just because a function works correctly for one or two sets of inputs doesn't mean it always works right. You will need to think of a variety of different possibilities for the function's input values (arguments) and make sure it produces the right results in every case. A few minutes spent adding statements which test each function with varying values will be well worth it, if it saves you hours of trying to track down a bug later! Once you are convinced your function works correctly, just delete the test calls, and integrate the new function into the rest of your program by calling it where it is needed.

To illustrate the fact that correct results in one or two cases don't mean a function always works correctly, imagine that for some program you have to write a function which counts how many times a given number is located inside an array containing 10 integers, and returns the result. Its parameters are an array of integers and the value which should be searched for inside the array. Here is the function you wrote:


int count_quantity(int arr[], int num) {

  /* This function returns the count of how many occurrences of its
   * second parameter are found in its first array parameter.  The
   * array is assumed to have ten elements.
   */

  int count= 0, index= 1;

  while (index < 10) {

    if (arr[index - 1] == num)
      count++;

    index++;
  }

  return count;
}

To test this function you could write a small main function containing an array, call the function with that array and a value to search for inside it, and print the answer which was returned. You can tell what results it should produce from examining the array. For example:


int main() {
  int array[10] = {3, 1, 5, 1, 4, 7, 9, 4, 2, 1};

  printf("number %d was found %d times\n", 3, count_quantity(array, 3));
  printf("number %d was found %d times\n", 4, count_quantity(array, 4));

  printf("%d\n", count_quantity(array, 4));

  return 0;
}

You would see that the first test call returns and prints 1, and there is in fact only one 3 inside the array. The second one prints 2, and there are two 4s in the array. You might conclude that your function was correct, however, this is not the case! Altering the call to search for different values, or adding separate test calls, reveals that the call:


printf("number %d was found %d times\n", 1, count_quantity(array, 1));

would also print 2, however, there are three 1s in the array, therefore 3 should be the correct result printed! The problem is that the last array element is never examined, since the loop stops immediately when index reaches 10, and arr[8] was the last element tested. You could verify this by adding a debug printf statement in the loop printing each array element as it is examined. In this case, changing the loop condition to ``while (index < 11)'' would be one way of fixing the problem.

The crucial point is that testing the function by calling it in only a few cases is not sufficient to conclude that it is correct.

5.4 Program debugging

If random or unexpected values are printed some of the most common reasons are:

One of your loops is examining elements which don't belong to the array (it has gone off either side of the array). Trace your code by hand with a diagram of the current values of the array, or add debug printf statements to see the values of the array subscripts which you are using, to see where the error might be happening.
You have a function which returns values in some cases but not in others. This can be avoided by using only one return statement at the end of each function (as required above) to pass back a value which was computed or determined, rather than several return statements in different places in the same function.
You may be printing or using values of variables which were not initialized. Initialize all variables, or print the value of each variable before using it, to see where you are using one that hasn't been initialized.

6. Academic integrity statement

Any evidence of unauthorized use of computer accounts or cooperation on projects will be submitted to the Student Honor Council, which could result in an XF for the course, suspension, or expulsion from the University. Projects are to be written INDIVIDUALLY. For academic honesty purposes, projects are to be considered comparable to a take-home exam. Any cooperation or exchange of ideas which would be prohibited on an exam is also prohibited on a project assignment, and WILL BE REPORTED to the Honor Council.

VIOLATIONS OF ACADEMIC HONESTY INCLUDE:

failing to do all or any of the work on a project by yourself, other than assistance from the instructional staff.

using any ideas or any part of another student's project, or copying any other individual's work in any way.

giving any parts or ideas from your project, including test data, to another student.

having programs on an open account or on a PC that other students can access.

transferring any part of a project to or from another student or individual by any means, electronic or otherwise.

IT IS THE RESPONSIBILITY, UNDER THE UNIVERSITY HONOR POLICY, OF ANY STUDENT WHO LEARNS OF AN INCIDENT OF ACADEMIC DISHONESTY TO REPORT IT TO THEIR INSTRUCTOR.

7. Submitting your project

Your project must be electronically submitted by the date above, to aviod losing credit as described on the syllabus. No projects more than two days late will be accepted for credit without prior permission or a valid medical excuse, as described on your syllabus. Only the project which you electronically submit, according to the procedures provided, can be graded; it is your responsibility to test your program and verify that it works properly before submitting. Lost passwords or other system problems do not constitute valid justifications for late projects, so do not put off working on your program or wait to submit it at the last minute!

Turn in your assignment using the ``submit'' program as before, except using ``5'' for the project number. You are to submit only the .c file containing your source code, not the executable version of your program! If your program is in a file named ``storm2.c'', submit would be run as submit 5 storm2.c.

8. Sample output

Assuming the name of the executable version of the program is ``storm2.x'', here is a sample execution for one input data set.

Be sure to test your program against a variety of inputs, so you are sure it works in all circumstances!

% cat p5.in1 10 10 ********** ********** ********** ********** *****----- *****----- *****----- *****----- *****----- *****----- W W W W W W W W W W W W W W W W W W W W SW SW SW SW SW SW SW SW SW SW SW SW SW SW SW SW SW SW SW SW S S S S S S S S S S S S S S S S S S S S SE SE SE SE SE SE SE SE SE SE SE SE SE SE SE SE SE SE SE SE E E E E E E E E E E E E E E E E E E E E 7 8 990 75 8 5 980 90 !

% storm2.x < p5.in1 1 ++++++++++++++++++++ Map setup complete: 10 10 Row Column Pressure Wind Row Column Pressure Wind 7 8 990 mb 75 kt 8 5 980 mb 90 kt 6 7 985 mb 80 kt 8 4 977 mb 93 kt 5 6 980 mb 85 kt 8 3 980 mb 90 kt 4 6 975 mb 90 kt 8 2 985 mb 85 kt 3 6 972 mb 93 kt 8 1 990 mb 80 kt 2 7 975 mb 90 kt 8 0 995 mb 75 kt 1 8 980 mb 85 kt 1 9 985 mb 80 kt ============ Summary for A ============ Minimum pressure 972 at row 3 column 6 Maximum pressure 990 at row 7 column 8 0123456789 0 ********** 1 ********GH 2 *******F** 3 ******E*** 4 *****-D--- 5 *****-C--- 6 *****--B-- 7 *****---A- 8 *****----- 9 *****----- ============ Summary for B ============ Minimum pressure 977 at row 8 column 4 Maximum pressure 995 at row 8 column 0 0123456789 0 ********** 1 ********** 2 ********** 3 ********** 4 *****----- 5 *****----- 6 *****----- 7 *****----- 8 FEDCBA---- 9 *****-----

For this project, the primary input consists of the contents of the file shown above. This file will be posted in your instructor's class posting account- do not try to type it in yourself!

Steve Scolnik
2001-11-02

Web Accessibility