CMSC 106 Project #6 - String Library Fall 2002

Due date: Monday, November 25th at 11:00 pm

1 Due Date is Early!

Please read the due date above carefully.

2 Purpose


This project will give you plenty of practice using pointers, and will illustrate the concept of a ``library''.

3 Project description


Programmers frequently make use of ``libraries'' to extend the language they are using to handle some specific set of tasks. For example, we use the library stdio to enable us to do high-level input and output with the language C. As you have seen in class, we use the string library to enable us to do sophisticated string manipulation.

For this project, you will write your own string library, which could take the place of the standard string library. As you are creating your library of functions you will not be allowed to call any of the functions that are provided in the standard string library. Although you will be re-creating functions that are already available, we feel that this assignment is a perfect way for you to practice using pointers. (You may even develop a greater appreciation for having such libraries at your disposal!)


As you are implementing this project, you should write TWO files:

mystringlib.c    [The library of string functions]
driver.c         [A small program that will test your string functions]

3.1 mystringlib.c

mystringlib.c will contain the definitions for functions with the prototypes listed below. This file must contain only the definitions for the functions below, and nothing else. In particular, this file must NOT contain the function ``main''. You may include one or more ``helper'' functions if you wish. (A helper function is a small function that is called by one or more of the functions in your library to perform a specific task. A helper function is not considered part of the library; it is not intended to be called outside of the library itself.) Please note that the prototypes below are not exactly the same as the prototypes for the corresponding functions that we find in string.h. We have made small changes to simplify your task. Here are prototypes for the functions that you will define in the file mystringlib.c:
int mystrlen(const char *);
char *mystrcpy(char *, const char *);
char *mystrncpy(char *, const char *, int);
char *mystrcat(char *, const char *, int *);  [Three parameters!  Different from the usual strcat]
int mystrcmp(const char *, const char *);
char *mystrchr(char *, char);
char *mystrstr(char *, const char *);
char *replace(char *, const char *, const char *);  [Not part of the standard string library]

Your functions should behave precisely like the corresponding functions that are part of the library string.h (with a couple of minor exceptions, described in the section below.)

For example, your implementation of mystrlen should work exactly like the function strlen. For information about how these functions behave, please refer to your textbook, Appendix D. Again, we have modified the prototypes very slightly to make it easier for you; you must use the prototypes as they appear above.

Please recall that the string functions in the standard library do not do any error checking of any kind. In particular, it is up to the person who uses these functions to ensure that there is adequate space available for the string manipulations. Similarly, your functions will just assume that anyone who is using your library will be careful to allocate sufficient space in memory. Your functions should not do any error checking of any kind.

To avoid repetition, some of your functions will call other functions that you have already written. However, you may NOT use any of the functions that are declared in string.h at any time! If we allowed you to call functions like strlen and strcpy then this project would be much too easy, wouldn't it?

To ensure that you get plenty of practice using pointers, you may not use square brackets ('[' and ']') at any time while writing your function library. You may want to use the square brackets while writing driver.c, however.

3.1.1 Exceptions

3.2 driver.c

The file driver.c will contain the function main (plus any other functions that you find useful.) The purpose of this file is to make various calls to the functions in your string library to test them as thoroughly as possible. How you choose to write this file is entirely up to you! Keep in mind that any functions included in this file are for your own testing purposes only, and should not be called by any of the functions in your string library. You should continually make changes to this file so that it will carefully test the portion of the string library that you are currently working on. So that you can call the functions in your library from inside the file driver.c, the first line in the file driver.c should be:
#include ``mystringlib.c''

(Note that we use quotes instead of angled brackets to include a file that we have written ourselves.) Now to test your library with the driver that you have written, all you have to do is type:

cc -std1 -trapuv driver.c

You will only submit the file mystringlib.c. We will use our own drivers to test your library very thoroughly, so please do not try to submit your driver.

3.2.1 An example of a very simple driver

Suppose that you have only written the function mystrlen and you want to develop a driver to test it. The following is a simple example to get you started. (Note that it does not do a very thorough job of testing mystrlen!)

#include ``mystringlib.c''
#include <stdio.h>

int main()
{
  char a[50] = ``Testing'';

  printf(``%d\n'', mystrlen(a));
  return 0;
}

If you compile and run this small driver, the executable should display the value 7. If it doesn't, then you know there is something wrong with your implementation of the function mystrlen.

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. 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, 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 may not use ANY of the functions that are declared in string.h.

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



5 The ``primary case''

Our method of grading this project will be very different from what we have done in the past. We will test your function library with a variety of different drivers that will make calls to your functions. As usual, we want to provide you with an opportunity to test your project with the ``primary case'' so that you can check your output. Instead of providing a primary_input file as we have done in the past, we are giving you a file called primary.o. This is a machine language version of the driver we will use as the ``primary case'' for testing your library.

To use this driver with your library, first copy the file primary.o to the same directory as your library, and then type:

cc -std1 -trapuv mystringlib.c primary.o

This will generate an executable, a.out. If you run a.out, it should produce output that matches the file primary_output. Notice that there is no input file required - the driver has the primary input hard-coded inside. To use our driver, you must have finished writing all of the functions that are supposed to be included in your library. We don't recommend using our driver during the development process. As you are writing your library of functions, you should be continually re-writing your own driver(s) to test the specific component that you are working on at the time.

IMPORTANT: You are not expected to write a driver that produces the primary_output file. You are only expected to submit a working library of string functions, called mystringlib.c. When your library is linked with our driver (as described above), the resulting executable should produce the output you see below. This output shows the results of several succesive calls to the functions in your library. There are two strings, a and b, which are manipulated during the program execution. After each succesive function call, the new values of a and b are displayed, along with the return value. Here are the contents of the file primary_output:

mystrcpy(a,''pizza'');
return value: pizza
value of a: pizza
value of b: Unknown

mystrcpy(b,''taco'');
return value: taco
value of a: pizza
value of b: taco

mystrlen(a);
return value: 5
value of a: pizza
value of b: taco

mystrcpy(b,a);
return value: pizza
value of a: pizza
value of b: pizza

mystrcat(a,b,&c);
return value: pizzapizza
value of a: pizzapizza
value of b: pizza

mystrcmp(``doghouse'',''dog'');
return value: 1
value of a: pizzapizza
value of b: pizza

mystrcmp(``Fred'',''Fritz'');
return value: -1
value of a: pizzapizza
value of b: pizza

mystrcmp(``Tony'',''Tony'');
return value: 0
value of a: pizzapizza
value of b: pizza

mystrchr(``abcdefghijklmn'','g');
return value: ghijklmn
value of a: pizzapizza
value of b: pizza

mystrchr(``abcdefghijklmn'','x');
return value: NULL
value of a: pizzapizza
value of b: pizza

mystrncpy(b,''dog'',7);
return value: dog
value of a: pizzapizza
value of b: dog

mystrncpy(b,''hello there'',2);
return value: heg
value of a: pizzapizza
value of b: heg

mystrstr(``how are you today?'',''you'');
return value: you today?
value of a: pizzapizza
value of b: heg

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


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


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


6.3 Program debugging


  1. 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).

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

  3. 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').

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

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


6.4 Helpful hints



7 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:


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

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

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

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

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


8 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!

IMPORTANT: You must only submit the file mystringlib.c. DO NOT TRY TO SUBMIT YOUR DRIVER. The file mystringlib.c must contain implementations for the functions that are prototyped on the first page of this project description, and nothing else (other than helper functions). In particular, mystringlib.c MUST NOT CONTAIN THE FUNCTION ``main''.

To submit your project, you must type:

submit 6 mystringlib.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!



Steve Scolnik 2002-11-18