1. Purpose

This project will allow you to gain a fuller understanding of the relationship in C between arrays and pointers by writing a program which uses pointers and C's character and string processing library functions. In order to make sure you are using the string functions already defined for you in the <string.h>, you may no use any loops that traverse an array character by character.

You will be writing a program that will help a person who is trying to make an index for a book. He needs to be able to find words that start with a specific letter and count how many times each of those words appear and report which line contained that word (similar to how an index tells what page contains a word).

2. Project description

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

Your program will read an individual letter as the first argument to the command on the shell command line (this is done with the argv and argc as presented on page 264 or your textbook). If there is no argument given on the command line when the program is called, the program should print out an error message including the exact phrase ``not enough'' and the program should exit without processing the input file, and it must set the status variable to 1. If there was more than 1 argument, the program should print out an error message containing the exact phrase ``too many'' and exit without processing the input file, and it must set the status variable to 2. If there was exactly one argument, but that argument is not a single charcter (any ASCII character), the program should print an error message including the exact phrase ``too long'' and exit without processing the input file, and it must set the status variable to 3. If there was exactly one argument which was one character long, but that character was not an alphabetic character, the program should print an error message containing the exact word ``alphabetic'' and exit without processing the input file, and it must set the status variable to 4.

If the argument was a single alphabetic character, the program should continue and find words that start with that alphabetic character in either its uppercase or its lowercase form (case insensitive searching). The program should find all words that begin with that letter and put them into an alphabetized list where it also records the line numbers where each of the words was found. It will need to keep track of how many of each word was found on each line and be able to print that number with the possibly modified input line to output.

2.1 Program input

The text to be evaluated will all come from a single file. It will be a file in paragraph form. It will contain no blank lines, no line will be over 65 characters in length, the only whitespace characters in the file will be spaces (the space bar) and new lines (the return key). Be aware that you do not know how many lines are in the file or how many words are on each line.

Before you process the line you need to remove some specific undesirable characters from the input file. Any dash ``-'' in the input should be replaced by a single space. Any star ``*'' in the input file should be removed (completely without leaving a space).

Once the cleanup is done, the line should be processed. This cleaned form of the line is also what needs to be printed as the contents of the line along with the count of how many words are on that line starting with the selected character.

Words are delimited by whitespace (space(s) and/or end-of-line). Any apostrophes that appear within a word such as ``don't'' should remain as part of the word. The other punctuation that can appear in the file: period ``.'', comma ``,'', parentheses ``('' and ``)'', and the quotation marks ``"'' must be removed when evaluating a word. When these punctuation characters are removed, they must be completely removed so that a space DOES NOT remain in the place of the removed punctuation. Other punctuation will not appear in the input file. All words with numeric characters should be ignored completely (should not be counted as starting with that letter). A single word will not be split between two lines.

No line will be over 65 characters, no individual word over 20 characters, each word won't appear more than 50 times in the complete input file, and there won't be more than 30 words unique which begin with the chosen letter of the alphabet.

2.2 Processing and output

THE MAIN RULE - YOU MAY NOT USE ANY CHARACTER BY CHARACTER TRAVERSALS OF ANY CHARACTER ARRAY !!! If you are using the name of a character array with an index i.e. arr[i] and you have a loop that uses i++ - you are traversing the array character by character. If you are using pointers to a character array char *pntr and you have a loop that uses pntr++, you are traversing the array character by character.
You must use at least 6 string.h fuctions from the following list: strlen, strchr, strcat, strcpy, strncat, strncpy, strcmp, strncmp, strcspn, strpbrk, strrchr, strspn, strstr, or strtok.
Each line must be cleaned to remove the dashes and the stars as described above.
When this line has been processed, the number of counted words and the line in this clean form will be displayed to the screen. These values will be displayed with the number first followed by the line corresponding to that number with the two items lined up in columns. The number of words is just the number of words that started with the specified letter, not necessarily the unique words. (If the same word appears more than once on the same line, it should be counted just the same as if it was two different words.)
After the whole input file has been processed, a single line containing 10 dashes ``-'' should be displayed as a separator followed on the next line by the word ``SUMMARY''.
The summary consists of the alphabetical list of words found in the input. In the first column should be an integer which tells how many times that word was found. Lined up neatly in the second column is the word itself in all lowercase letters. Immediately following the word (not in a separate column) should be a dash ``-'' followed by the word ``Line'' and that followed by the list of line numbers where that word was found. If a given word appears more than once on the same line. The same number will appear twice. The line numbers must be in non-decreasing order. (Non-decreasing means increasing order with possible duplicates sequentially in the list.)

3. 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 defined, prototypes must be listed at the top of the program file, and at most one return statement may be used in any function, including main.

Even if you already know what they are, you may not use any C language features other than those introduced in Chapters 1 through 13 of your textbook, plus those in Section 23.4 and any function in Section 23.5 whose name begins with ``str'', and the language features 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 may not use the exit() library function at all. Lastly, no global variables may be used. Using any of these disallowed C features will result in losing credit.

Your program must make use of C's string library functions anywhere possible. You will lose substantial credit if you write code duplicating their effects, rather than just calling them (e.g., if you write loops to copy or compare strings, search for something in a string, find the length of a string, etc., you will lose credit). The character library functions (textbook section 23.4) may also be used, but you will not be penalized if you duplicate their effects rather than using them. You will lose substantial credit if you use any traversals of an array character by character.

In additon to using the string library functions, your program must be written using user-defined functions where approprriate. Your program must define and call at least four functions you have written; writing more than four such functions would be extremely good practice and the best way to avoid errors in developing your program. If your program doesn't contain, and call, at least four such functions, it will be graded as if it does not work on the primary input- even if its output is correct. Below are ideas for some possible functions; feel free to use others. You are permitted to write as many functions as you want, and if you write any of the functions suggested below they need not perform the exact tasks as described.

a function which cleans the dashes and stars out of the original line as described above
a function which cleans out the punctuation which is not allowed within a word
a function which removes the indicated character from the string passed without leaving a space
a function which gets the next one word from the line
a function which determines if there are any numeric characters within the word
a function which finds the correct place to insert this word into the alphabetized list
a function which inserts the new word into the correct place in the alphabetized list
a function which makes all of the characters of a word lower case
a function which prints the final summary information

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 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 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 and global variables as discussed above
using prototypes for all functions
using character constants (e.g., 'A'), rather than the characters' numeric ASCII values anywhere that specific character values are needed.

4. 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.

Mistakes with string library functions or pointers are very likely to result in a fatal program execution error (core dump). A statement may look completely correct, but just because some string or pointer contains a certain value the program will fail. This makes it extremely important to use debug printf statements to narrow down where in your program the error occurs, before you can even begin to figure out what's wrong and how to fix it.

4.1 Possible development steps

Be sure to test each function as it is implemented, before integrating it with the rest of the program! It is frequently very easy to test a function which has character array parameters, because you can often call it by passing any string literals you like into the parameters. As an example, say you write a function named split, which is supposed to find the position where a string is to be split in half (perhaps it has another integer parameter as well). You can call your function several times, as split("This is a character string", 15) or split("Try another character string", 12), and print the result which your function produces each time. It's easy to see by hand what result your function should produce, so test it with a number of strings and be certain it gives the right answer every time. You can write a little test program file to call your function, or just add these test calls right at the beginning of main. Once you are positive your function works, then you can call it as part of your project and be confident that your program will be likely to work fine.

4.2 Finding compilation errors

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

X is being converted to "pointer to char"

(where X is a statement using one of the string library functions)

You probably forgot the #include <string.h> at the top of your program file.

"X" is not an lvalue, but occurs in a context that requires one.

You are trying to assign something to the name of an array. You can assign something (a pointer value, or NULL) to a pointer variable, but not to the name of an array. Maybe you meant the variable on the left of an assignment to be declared as a pointer instead of an array.

4.3 Program debugging

Don't forget that, for technical reasons, all debug printf statements must end with a newline character, or their results may not show up on the screen if the program has a fatal execution error (core dump).
As mentioned above, core dumps are a common result from problems with strings and pointers. If a program with several functions has a core dump, and you don't know where the problem is, you can add a debug printf statement at the beginning of each function and at the end of each function, before it returns. These debug print statements can just say something like ``Starting function X'' and ``Leaving function X''. Run your program again, and if the output shows that some function was entered but never completed, that function, or one of the functions it calls, may be where your problem lies. Remember the terminating \n when inserting debug printf statements.
If you are having trouble getting a string to print in its entirety, try printing the first character or characters from that string using either pointer or subscript notation. This could tell you if the string is at least starting in the correct place. The problem could involve a missing or misplaced null character ('\0').
Draw lots of pictures to trace exactly where things are in memory, and be sure never to attempt to dereference or follow a pointer which is not pointing at something valid!
If after you have tried these techniques, and tested each of your functions, you still can't figure out why your program doesn't work, bring a printout to our office hours, and we can help you learn how to track the problem down.

4.4 Helpful hints

Be sure that every variable used in your program is initialized when it's declared!
Be sure to check that any pointers used do not contain NULL before dereferencing them!
Read the relevant material in the text and solve the homework problems before writing the project! This will allow you to have a firm grasp of the material, and you will find the project much easier and quicker to write as a result.
If your program doesn't compile, you need to first compare the statement which causes the syntax error with a correct example of that type of statement from your lecture notes or the textbook or from examples in your discussion section. In most cases this will allow you to see the mistake (which is related in some way to the difference between the correct statement and yours) without coming in to office hours to wait for someone to tell you what it is.

5. 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.

6. Submitting your project

Your project must be electronically submitted by the date above, before 11:00 pm, to avoid losing credit as described in 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 ``6'' 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 ``index.c'', submit would be run as submit 6 index.c.

Before you submit your project, you must exactly follow the specific submission checklist in the ``Testing projects before submitting'' handout separately posted by your instructor!

7. Sample output

The p6.primary.input file will be available in your class posting account.

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

For this project, the primary input consists of the contents of the input file given in the class posting account with the argument lowercase ``m'' given as the one and only command line argument. Note that this primary input does not exercise several conditions discussed above which your program should work for in order to earn credit for the secondary inputs.

Steve Scolnik
2001-04-13

Web Accessibility