CS14 - At-Home Programming Assignment 1

Read this assignment very carefully many times. You will be resonsible for everything on this page whether you read it or not

In this project you will write a program for a phone company. Your program will use a list of lists to maintain the database of phone numbers. The main list will refer to the area codes. The lists coming off of the main list will store the telephone numbers in that area code. Each phone number should store the prefix and suffix seperately. Here is an example illustration:

Your program should be able to support the following actions:

Add a phone number to the list. If necessary, a new area code will be created. For example, using the above list, adding the phone number 817-458-3101 would add a new node to the 817 area code list. Adding the phone number 350-921-6749 would add a new area code node of 350 and then off of that list, the phone number 921-6749 will be added. Be sure not to add duplicate numbers. Each new area code added will be added to the front of the list of area codes and each new phone number will be added to the front of the list of phone numbers.
Add phone numbers to the list from a user specified file. This operation adds to the current list being used. Duplicate numbers should not be added. The format of the file will be a phone number on each line in the following format: 909-787-1234
Remove a phone number from the list. If removing the phone number causes the corresponding area code to have an empty list, then you should also remove the area code node.
Search for a given phone number
Count how many phone numbers there are in the list
Count how many phone numbers there are in a given area code
Count how many phone numbers there are in a given area code and a given prefix.
Split an area code. For example, move all the phone numbers with the 353 prefix in the 909 area code to a new area code of 650. The new area code should not already exist and should be added to the head of the area code list. If splitting causes the old area code to have an empty list of phone numbers, the old area code should also be removed.

There are many List templates available (for example, the Standard Template Library offers a list template class). However, for this assignment, when you use a linked list, it will be your own code so that you can practice your programming and learn the concepts thoroughly. You may however, use any variation of a linked list (double linked list, sentinals, etc) as long as it interfaces with the main functions provided.

Skeleton code provided

So that your program will interface with our testing environment for grading, you must adhere to the following specifications and use the skeleton code provided. If you deviate from the specifications and your program does not interface with our testing environment, you program will not be graded. To ensure that your code will interface correctly, DO NOT alter any of the code provided to you. Please only ADD to the code.

Structure

Your program will consist of 3 basic classes and I have provided you with the skeleton code for those classes. DO NOT make any additional classes. You only need these 3 classes. You must download these files and complete the code in them.

phone_book.h - The first class will be the phonebook list class which will contain a pointer to the head of your area code nodes.
phone_book.cc - You are also being provided the cc file for the phonebook class because it contains the print function that has been written for you. DO NOT change this print function. However, note how the print functions are structured. I have a print function in the phonebook class that only prints the area codes for the lists. Then it calls a print function within the areanode class that prints out the phonenumbers in the area code. The phonenumbers are hidden from the phonebook class. You should follow this model with EVERY function that you write.
area_node.h - The second class will be an area code node that will hold the current area code, a pointer to the next area code in the list, and a pointer to the head of the list of phone numbers in that area code.
area_node.cc - You are also being provided the cc file for the area node class because it contains the print function that has been written for you. DO NOT change this print function.
number_node.h - Finally, you will have a phone number class which will hold the current phone number and a pointer to the next phone number in the list.
main.cc - This is the main function for the complete assignment that we will be testing your programs with. It contains function calls that test the code that you write. Since this is THE file we will be using for testing, you know how well you will do on the assignment because you will know how well you perform on the test cases. The output of your program should look like this. DO NOT, I repeat, DO NOT add anything to the main files that is necessary for your program to compile/function correctly. We will download a new copy of main.cc to test your program with.
phone_numbers.txt - This is the file that your program will read phone numbers from. We will use this file to test your program while grading.

Function prototypes

You will write the following functions for your PhoneBook class to interface with the main function. This is in no way an inclusive list of the functions that you will need to write. This is simply the minimum amount of information that I need to give you so that your code will interface with the main testing function. For each function, please follow the specifications listed above.

void removePhoneNumber ( int area, int prefix, int suffix ) - This function will remove a phone number from the phone book. The function parameters are:
- area - the area code of the number to be removed
- prefix - the prefix of the number to be removed
- suffix - the suffix of the number to be removed
void readFromFile ( string fileName ) - This function will read phone numbers in from a file and add them to the phone book. The function parameters are:
- fileName - the name of the file to read in from (NOTE: the file name is of type string. You may not change that)
void insertPhoneNumber ( int area, int prefix, int suffix ) - This function will insert a phone number into the phone book. The function parameters are:
- area - the area code of the number to be inserted
- prefix - the prefix of the number to be inserted
- suffix - the suffix of the number to be inserted
bool search ( int area, int prefix, int suffix ) - This function will search for a phone number in the phone book. The function will return true if the phone number is found and false if the phone number is not found. The function parameters are:
- area - the area code of the number to search for
- prefix - the prefix of the number to search for
- suffix - the suffix of the number to search for
int numNumbers ( ) - This function will return the total number of phone numbers in the phone book.
int numAreaCodeNumbers ( int area ) - This function will return the total number of phone numbers in the specified area code. The function parameters are:
- area - the area code in which to count phone numbers in
int numAreaCodeAndPrefixNumbers ( int area, int prefix ) - This function will return the total number of phone numbers in the specified area code that belong to a specified prefix. The function parameters are:
- area - the area code in which to count phone numbers in
- prefix - the prefix in which to count phone numbers in
void split ( int oldAreaCode, int prefix, int newAreaCode ) - This function will take phone numbers from a given prefix in a given area code and place them into a new area code. The function parameters are:
- oldAreaCode - the area code which contains the phone numbers that will be moved to a new area code
- prefix - the prefix of the phone numbers that will be moved to the new area code
- newAreaCode - the area code that the phone numbers will be moving to

You must also write the following function for the AreaNode class.

int size ( ) - this function will return the number of phone numbers in the list for this area code. This function is important because it is used by the print function to nicely print the phone numbers to the screen.

Error checking

Please make sure to provide good error checking throughout. If an error occurs, i.e inserting a duplicate number or deleting a number that does not exist, print out an error message and return from the function. Do not exit! Make sure that your error message matches mine the in sample output EXACTLY.

Start Early!!

This project is most likely by far the largest programming assignment that you have ever been given and I am sure that it seems overwhelming. This project (along with every subsequent project you will be given this quarter) absolutely cannot be left until the last minute to complete. And, with the late penalty being a full letter grade per day, you don't want to turn your projects in late. Here is a quote from a previous quarter. Hopefully it will keep many of you from falling into the same situation...

"Unfortunately, I overestimated myself as a programmer, or understimated the complexity of the progarm depending on how you look at it so I don't think I'm going to have much done for this program. Oh well, live and learn I guess. I'll just try to use this experience as incentive not to procrastinate next time." -- Anonymous Student, Spring 2005

Notes on grading

Grading programming assignments can be a very time consuming operation if programs cannot be automatically tested with a test function. I would like to stress again how important it is for your programs to work with the main functions provided. Your programs will be graded with main.cc. You will receive points for the test cases that your code passes. If your code does not interface with main functions provided, you will not receive any functionality points.

DO NOT, I repeat, DO NOT add anything to the main files that is necessary for your program to compile/function correctly. We will download a new copy of main.cc to test your program with.

Your output MUST match mine EXACTLY. This is my output. Notice that I print out error messages. You must ensure that your error messages match mine down to the whitespace. You need to determine if yours is exactly like mine by using the diff command. Do a man on diff for more information (type "man diff" at the command prompt). Basically, you need to run the following command in Linux: "diff youroutput.out main.txt" and if the files are the same, nothing will be printed to the screen (That is your goal). However, you don't have to get all test cases working, you can get partial credit. Make sure that the output matches exactly for the test cases that you are able to get working. To capture your output to a file, you can use the output redirection available in the Linux shell. You can redirect your output using > . To capture your output for this project, your command would look similar to this: "phonebook > youroutput.out" where phonebook might be the name of your executable and youroutput.out is what normally would have been printed to the screen. You will receive points for every test case that you get working. VERY, VERY IMPORTANT - you will NOT receive points for a particular test if the diff command fails for that test.

To gets points for tests, you must be able to pass previous tests before subsequent tests can be run. If for any reason you can not get a test case working but you are able to get subsequent tests working, you must ensure that your code doesn't seg fault! That way, you can receive points for subsequent test cases.

Much of the grading of your program will be based on not just getting code to do the necessary functions correctly, but on your actual coding. Be sure to use good programming where possible (use of classes, functions, good parameter passing techniques, error checking, encapsulation, object oriented programming). Make sure your program is user friendly.

You must use a makefile to compile your program and you must at least use the compilation flags -W -Wall -Werror -pedantic. Programs will be graded under linux on hill.cs.ucr.edu. Significant points will be taken off if your program does not compile with a makefile or if you code under Windows.

Suggestions to follow while coding

Follow a modular programming style. Write one function for your program and completely test it before moving to the next function. This will isolate your debugging because most of the time the bug will be in the newly created module. However, if you forget a test case in an old module and do not completely test it, a new module can reveal old bugs. Watch out for this.
The main function provided assumes a certain order that you will code your program in. You in no way need to follow this same order while coding. I suggest that while code, you do not use my main function and write your own to test the code that you are writing. (Please make sure you conform to the provided function prototypes). After you have tested your code, try the main functions provided. Or, you may use my main functions and simply comment out everything except the current tests you are interested in.

What to turn in

You should have turned in what you have thus far on our program at least 6 hours before the due date (by 2pm). Then continue to work on your program and turn in more current versions as you get them working. Ideally, you should have your project done well before the due date.

You must turn in all .cc and .h files and your makefile. Furthermore, you must turn in a file called readme.txt that states which test cases your program passes and which test cases your program fails. In addition, you must follow any guidelines and include any information that is stated on the main page about at-home programming assignments.

DO NOT, I repeat, DO NOT turn in any files that are not required for the final compilation of your assignment. Do not turn in your temporary .cc files or your saved/older revisions of your .cc files. If you turn in files that aren't required for your assignment, it hinders the grading processes. You will be docked points if you turn in extraineous files.

A reminder about collaboration on home programming assignments

Please remember, at-home programming assignments are not lab assignments and you may not team-code with your lab partner or any other individual. Limited collaboration may be acceptable, but programs must represent YOUR OWN original work from THIS quarter (meaning if this is your second time taking the course, you MAY NOT turn in ANY code written for a previous quarter). Sharing code or team-coding are strictly not allowed. Copying code from ANY source (any book, current or past students, past solutions, web, etc) is strictly not allowed even with citation. Collaboration may consist of discussing the general approach to solving the problem, but should not involve communicating in code or even pseudo-code. Students may help others find bugs. Your code MUST be unique -- the odds of randomly producing similar code is very low. Computing, like surgery or driving a car or playing golf, can only be learned by doing it yourself!