Programmer 7500/MAX_PROGRAMMERS.iso/PASCAL/LISTS12.ZIP/LISTS.DOC

Text File | 1993-01-04 | 11.5 KB | 418 lines

Documentation for Lists.Pas (ver 1.0)
Written by Mark Addleman [72777,740]

     This  set  of routines is released into  the  public  domain
under the concept of NameWare.  The NameWare ideal is simple, the
user  has full privileges to this software and can use it  anyway
he/she  feels  like.  The user also has the right  to  distribute
this software to whomever he/she feels like; as long as it is  in
its  original  form.  This means the author has  worked  hard  on
these routines and would really like some credit for his work.

                                   Thanks,
                                   Mark Addleman



     The idea of a generic set of routines for a linked list came
to  me  in a vision.  After working many long hours  writing  and
rewriting essentially the same routines for a set of linked lists
that  I  had to use, I decided that it was time to sit  down  and
write one set of routines that I could use for them all (I'm sure
the  fact that it was 3:00am didn't hurt much, either).   I  hope
that these will help you as much as they have simplified my life.
Suggestions are welcome.



ListRec  (type declaration)
---------------------------------------
ListRec  is  the  backbone of the entire package.   This  is  the
programmer's  connection with the linked list.  It consists of  4
fields,  FirstItem (which points to the first item in the  list),
LastItem  (points to the last item in the list), Item (points  to
the  item  currently  being referenced), and  ListOK  (a  boolean
variable  which lets you know of any errors in using  the  list).
To  use  a  list  in your program, you  would  simply  declare  a
variable as ListRec:

     Program DemoList;
     Uses Lists;

     Var
        MyList               :   ListRec;



InitList(Var List:ListRec)
---------------------------------------
InitList  is a procedure that must be called prior to  using  any
list.  InitList will set all pointers to NIL and prepare the list
for use.

     Program DemoList;
     Uses List;

     Var
        MyList               :   ListRec;

     Begin
        InitList(MyList);
     End.



AddToList(NewItem:Pointer;
          Var List:ListRec);
---------------------------------------
AddToList  is one of two procedures to use for putting things  on
your list.  AddToList first takes the argument of a pointer which
should point to the item you want to add.  The second argument is
the list that you want to add it.  AddToList will stick this item
at the end of the list, thus the most recent addition to the list
will be the last; second most recent, second to list and so on.
AddToList does not move the current item pointer.
It  is  important  to note that the items  in  ListRec  are  only
pointers  to  the actual items on the list, therefore  each  item
that  you  want  to place on the list  must  have  an  associated
pointer variable.

     Program DemoList;
     Uses List;

     Var
        MyList               :   ListRec;
        Item                 :   ^Byte;
        I                    :   Byte;

     Begin
        InitList(MyList);

        For I:=1 To 10 Do Begin
           New(Item);
           Item^:=I;

           AddToList(Item, List);
        End;
     End.

The  above  program  would  produce  a  list  of  10  numbers  in
consecutive order.



InsertInList(NewItem:Pointer;
             Var List:ListRec);
---------------------------------------
InsertInList is the second method of placing an item on the list.
Unlike   AddToList,   InsertInList  will  place  the   new   item
immediately preceding the current item on the list.

InsertInList also does not move the current item pointer.

     Program DemoList;
     Uses List;

     Var
        MyList               :   ListRec;
        Item                 :   ^Byte;
        I                    :   Byte;

     Begin
        InitList(MyList);

        For I:=1 To 10 Do Begin
           New(Item);
           Item^:=I;

           AddToList(Item, MyList);
        End;

        New(Item);
        Item^:=0;
        InsertInList(Item, MyList);
     End.

The above program would produce the following list:
     0  1  2  3  4  5  6  7  8  9  10



DeleteItemFromList(Var List:ListRec);
---------------------------------------
DeleteItemFromList  does just that.  It deletes the item that  is
currently  being  pointed to.  The rest of the list is  moved  up
one.  For example, the following list:
     0  1  2  3  4  5
          ^
          Currently pointed to

After DeleteItemFromList, the list would look like:
     0   1  3  4  5
            ^
            Currently pointed to



NextItemPtr(List:ListRec):Pointer
---------------------------------------
NextItemPtr is a function that returns the a pointer to the  next
item  in  the list.  If there isn't a next item (already  at  the
last item on the list), NextItemPtr will return NIL.

For example, if you had the list:
     0  1  2  3  4  5
              ^
              Currently pointed to

NextItemPtr  would  return the pointer to 4.   However,  in  this
instance, NextItemPtr would return NIL.
     0  1  2  3  4  5
                    ^
                    Currently pointed to



PrevItemPtr(List:ListRec):Pointer
---------------------------------------
PrevItemPtr  returns a pointer to the previous item on the  list.
It  works just like NextItemPtr, except it returns NIL  when  you
are at the first item of the list.



LastItemPtr(List:ListRec):Pointer
---------------------------------------
LastItemPtr returns a pointer to the last item on the list.



FirstItemPtr(List:ListRec):Pointer
---------------------------------------
FirstItemPtr returns a pointer to the first item on the list (big
surprise, right?).



CurrentItemPtr(List:ListRec):Pointer
---------------------------------------
CurrentItemPtr returns a pointer to (Think quickly....) the  item
that  is  currently being pointed to.  Type  Casting  (see  Turbo
Pascal  manual) is of the greatest help when using any  of  these
functions.     As    NextItemPtr,    PrevItemPtr,    LastItemPtr,
FirstItemPtr,  and CurrentItemPtr return a generic pointer  type,
you can type cast it into any type you wish.

For example:
     Program DemoList;
     Uses List;

     Var
        MyList               :   ListRec;
        Item                 :   ^Byte;
        I                    :   Byte;

     Begin
        InitList(MyList);

        For I:=1 To 10 Do Begin
           New(Item);
           Item^:=I;

           AddToList(Item, MyList);
        End;

        New(Item);
        Item^:=0;
        InsertInList(Item, MyList);

        Writeln(Byte(CurrentItemPtr(MyList)^));
     End.

This  program  would  output  '0'.   Notice  that  CurrentItemPtr
returns  the address of the item and CurrentItemPtr^ is the  form
used in the type cast.



MoveToNextItem(Var List:ListRec)
---------------------------------------
This  procedure  does  exactly what it is called,  it  moves  the
current  item to the next item on the list.  The field ListOK  is
set to false when the end of the list is reached.

     Program DemoList;
     Uses List;

     Var
        MyList               :   ListRec;
        Item                 :   ^Byte;
        I                    :   Byte;

     Begin
        InitList(MyList);

        For I:=1 To 10 Do Begin
           New(Item);
           Item^:=I;

           AddToList(Item, MyList);
        End;

        New(Item);
        Item^:=0;
        InsertInList(Item, MyList);

        While MyList.ListOK Do Begin
           Write(Byte(CurrentItemPtr(MyList)^));
           Write(' ');
           MoveToNextItem(MyList);
        End;
     End.

This program will display the output
     0 1 2 3 4 5 6 7 8 9 10



MoveToPrevItem(Var List:ListRec)
---------------------------------------
This  procedure is exactly like MoveToNextItem, except  opposite.
MoveToPrevItem will move the current item pointer to the previous
item and will set ListOK to false if the beginning is reached.



MoveToFirstItem(Var List:ListRec)
---------------------------------------
This  procedure moves the current item pointer to the first  item
in the list.  It will set ListOK to false if the list is empty.



MoveToLastItem(Var List:ListRec)
---------------------------------------
MoveToLastItem  will  move the current item pointer to  the  last
item  in  the list.  It will set ListOK to false if the  list  is
empty.



MoveToItem(Item:Pointer; Var List:ListRec)
---------------------------------------
MoveToItem will move List's current item to Item.  ListOK will be
set to false if Item isn't in List.

     Program DemoList;
     Uses List;

     Var
        MyList               :   ListRec;
        Item, 5thItem        :   ^Byte;
        I                    :   Byte;

     Begin
        InitList(MyList);

        For I:=1 To 10 Do Begin
           New(Item);
           Item^:=I;

           If I=5 Then 5thItem:=Item;

           AddToList(Item, MyList);
        End;

        MoveToItem(5thItem, MyList);
     End.

This  program  will create a list of 10 consecutive  numbers  and
then move the current pointer in MyList to the 5th item (in  this
case number 5).

I  am not sure why I included this procedure in the  package.   I
used it once, but I can't remember why.  If you have some use for
it, please let me know.



ItemInList(Item:Pointer;
           List:ListRec):Boolean
---------------------------------------
This function returns True if Item is in List and False if it  is
not.   Again,  if you have any use for the routine, I'd  like  to
know what it is.



DisposeOfList(Var List:ListRec);
---------------------------------------
When you're all done playing with your lists, you need to get rid
of it.  This routine does just that.  It reclaims all memory used
by the list and calls InitList to reset the list.

It  is important to note that DisposeOfList only reclaims  memory
used by the List, not by the items in the list.  For example:

     Program DemoList;
     Uses List;

     Var
        MyList               :   ListRec;
        Item                 :   ^Byte;
        I                    :   Byte;

     Begin
        InitList(MyList);

        For I:=1 To 10 Do Begin
           New(Item);
           Item^:=I;

           AddToList(Item, MyList);
        End;

        DisposeOfList(MyList);
     End.

This   program  won't  reclaim  the  memory  set  aside  by   the
'New(Item)' statement.  The method for reclaiming all memory used
by a list and its Items is as follows:

     Program DemoList;
     Uses List;

     Var
        MyList               :   ListRec;
        Item                 :   ^Byte;
        I                    :   Byte;

     Begin
        InitList(MyList);

        For I:=1 To 10 Do Begin
           New(Item);
           Item^:=I;

           AddToList(Item, MyList);
        End;

        MoveToFirstItem(MyList);
        While MyList.ListOK Do Begin
           Item:=CurrentItemPtr(MyList);
           Dispose(Item); {The argument to Dispose must be a variable}
           MoveToNextItem(MyList);
        End;

        DisposeOfList(MyList);
     End.




Again,  I  hope  these routines are helpful.   If  you  have  any
comments or suggestions please contact me through CompuServe.

Mark Addleman
[72777,740]