Assignment 3 27/03/03

Assignment 3: Linked-list implementation of a sta k

The sta k data stru ture

A sta k is a data stru ture that stores a set of values. Unlike an array, whi h allows a ess to
any element within that data stru ture, ( i.e. a[5), only the last element that was added to
a sta k an be retrieved. In a similar manner, values that are added to the sta k an only be
added to the \top" of the sta k. One an think of a sta k as a data stru ture that behaves
like a sta k of books. You annot remove a book at the bottom of the sta k be ause the
sta k of books will fall over. You an only add or remove books from the top of the sta k.
In the abstra tion for the sta k data stru ture, values are added to the top of the sta k
with a ommand alled push, and they are removed from it with a ommand alled pop. As
an example, onsider an empty sta k A. In order to add a value to the sta k, we would use
the push ommand and push a value onto the sta k, with
push(A,5)

now the sta k looks like

5

If we added two more values with

push(A,2)
push(A,6)

the sta k would look like

6
2
5

A all to pop would return the top-most value on the sta k, whi h is 6, and the sta k would
now look like
2
5

Implementation of a sta k: Linked-lists

When it omes to developing the C ode to implement the abstra tion for the sta k data
type, there are many ways it an be done. One way is to store the values in the sta k in
an array and add and remove values from that array with the push and pop ommands.
Another way, whi h is the way you will be implementing a sta k in this assignment, is to

Assignment 3 27/03/03

employ a linked-list. A linked-list is somewhat of a dynami array that grows and shrinks
as values are added to it. Rather than being stored in a ontinuous blo k of memory, the
values in the dynami array are linked together with pointers. Ea h element of a linked list
is a stru ture that ontains a value and a link to its neighbor. The link is basi ally a pointer
to another stru ture that ontains a value and another pointer to another stru ture, and so
on. As an exmple, onsider a linked list representation of the three values on the sta k in
the previous example. In a linked-list, this would look like

Stack

myStack

Heap

head

value

value

value

next

next

next

The rst box on the left is a pointer of type sta kT * that is lo ated in stati memory whi h
points to the sta kT stru ture in dynami memory. This stru ture ontains a pointer to the
rst element of the sta k, or the head. The type for this stru ture is given by the sta kT
type,
typedef stru t {
nodeT *head;
} sta kT;

this ontains a pointer alled head to a stru ture of type nodeT, whi h is just a node in the
linked list, and this type is given by
typedef stru t _nodeT {
valueT value;
stru t _nodeT *next;
} nodeT;

where the valueT is just a type of your hoosing. In this assignment we will have employ
linked lists of hara ter values, so that the type denition for valueT is given by
typedef har valueT;

The box in the last node with the diagonal line indi ates that this pointer is the NULL pointer,
in that it does not point to anything.

Assignment 3 27/03/03

Assignment
Your job for this assignment is to use the above data stru tures and reate the following
publi fun tions to manipulate the sta k (whi h are de lared in sta k.h):
sta kT *NewSta k(void);
void Push(sta kT *sta k, valueT value);
valueT Pop(sta kT *sta k);
void EmptySta k(sta kT *sta k);
void FreeSta k(sta kT *sta k);
bool IsEmpty(sta kT *sta k);

and the following private fun tion whi h is de lared in sta k. :

stati nodeT *NewNode(void);

These fun tions are des ribed as follows:

1. NewSta k This fun tion should return a pointer to a sta kT type in the heap. The
head pointer should be initialized to NULL. After using this fun tion in the form
mySta k = NewSta k(), mySta k is a pointer of type sta kT * that points to a new
sta kT type in the heap. This fun tion should print out an error and should return
the NULL pointer if there is not enough spa e in memory to allo ate a new sta k.
2. Push This fun tion should take as its arguments a pointer to a sta kT type and a
value that is to be pushed onto the sta k. When you push a value onto the sta k, you
should:
 allo ate spa e for a nodeT type in the heap with the NewNode fun tion.
 Set the next eld of that new node to point to the head node in the sta k (NULL

if there is no head).
 Set the head eld of the sta k to point to the new node.

3. Pop This fun tion should take as its argument a pointer to the sta k and should return
the value from the top of the sta k. It should then:
 Return 0 and print out an error if the sta k is empty.
 Set the head eld to point to the next node.
 Free the spa e asso iated with the old node.

4. EmptySta k This fun tion should take as its argument a pointer to a sta kT and it
should free up the spa e asso iated with every node in the linked list in the sta k, but
it should not free up the spa e asso iated with the sta kT stru ture in memory, but
should set the head pointer to NULL.
5. FreeSta k This fun tion should take as its argument a pointer to a sta kT and should
free up the spa e asso iated with the sta kT stru t allo ated in dynami memory. This
fun tion should only free up memory asso iated with an empty sta k, and should print
an error to the s reen when the user attempts to free a non-empty sta k.

Assignment 3 27/03/03

6. IsEmpty This fun tion takes as its argument a pointer to a sta kT in memory and
returns true if it is empty, and false otherwise. Your sta k is dened as empty when
its head pointer is NULL. The fun tion returns a boolean enumerated type, whi h is
dened as
typedef enum {
false, true
} bool;

7. NewNode This fun tion should return a pointer to a nodeT type in dynami memory
and return NULL and print out an error if there is not enough memory to do so. Sin e
it is a private fun tion and it is only needed by the Push fun tion, then it should be
de lared as a stati fun tion so that it is private to sta k. .

Getting started
You should opy the following les to your dire tory:
/home/ os315/assignments/assignment3/main.
/home/ os315/assignments/assignment3/sta k.h
/home/ os315/assignments/assignment3/Makefile

Your job is to reate the le sta k. whi h ontains denitions of the fun tions dened in
sta k.h as well as the stati ally dened fun tion NewNode. You should in lude the sta k.h
header le as well as stdio.h in your version of sta k. . The fun tions you reate will be
used in the main. program whi h performs a few tests with your sta k fun tions. You should
not alter the main. le, sin e this is the le that will be used to grade your assignment.

Using the Makele

The le Makefile is used as a proje t manager in unix. It ompiles odes that have been
hanged and links pre ompiled obje t les together to make exe utables for you. After you
download the les, but before you have reated your sta k. le, you an ompile a test
program with
$ make test

When the make program starts, it looks in the Makefile for the target you request. Sin e
you request test, the make program looks in the Makefile where it says test:, and the
lines are given by
test:

main.o
$(CC) -o test main.o $(SOLUTION)

The format for statements in a Makefile are given as

Assignment 3 27/03/03

target: dependen ies

ommand

where the tabs (not spa es) before dependen ies and ommand are very important! Sin e
you requested the test target, the make program looks at this line, and sees that the le
that is required to reate it is main.o. The make program then looks to see if main.o is up
to date by he king the entry for it in the Makefile, whi h is given by
main.o: main. sta k.h
$(CC) - main.

This line says that the main.o obje t le depends on its sour e main. and the header le
sta k.h. If main. and sta k.h have been hanged sin e the last ompile, then main.o is
reated with the ommand listed, whi h is given by
g - main.

where the $(CC)$ variable has been lled in with g , and we see that this line simply
reates the obje t le main.o. On e main.o is reated (and hen e up to date), the ommand
beneath the test statement is exe uted. In this ase, the ommand is
$(CC) -o test main.o $(SOLUTION)

whi h, after repla ing the variables, is given by

g -o test main.o /home/ os315/assignments/assignment3/sta k.o

So when you type make test, the program test is reated by linking the obje t les main.o
and /home/ os315/assignments/assignment3/sta k.o. The sta k.o le is a pre ompiled
header le whi h ontains the solution. Your job is to write your own sta k. fun tion that
ompiles to reate your own sta k.o. To see how the solution is, run the test program
after you ompile it with
$ ./test

A series of tests will run and the s ore you re ieve for your run is also displayed along with
the test. When you would like to test your own version of sta k. , you an ompile it and
link it with the ommand make without any arguments. Without any arguments, make looks
at the line that says all. This target requires the main exe utable to be up to date (main
is what the $(EXEC) variable is). This exe utable is reated by ompiling and linking your
version of sta k. with main. . You an then test your own implementation by running
the ommand
$ ./main

You an also lean up your dire tory by typing make lean, and this will exe ute the
ommand
rm -f *.o *~ \#*# a.out test $(EXEC)

whi h will remove exe utables, obje t les, and ema s ba kup and autosave les.

Assignment 3 27/03/03

Deliverables and due date

You only need to submit your version of sta k. by 5:00 pm, Thursday, 3 April, 2003.
As you an see in the Makefile, you an type make submit at the ommand line and it will
look at the submit: target and see that this just means to exe ute
/home/ os315/bin/submit sta k.