Programmer 7500/MAX_PROGRAMMERS.iso/PASCAL/LSTS20.ZIP/LISTS20.DOC

Text File | 1988-07-16 | 12.9 KB | 487 lines

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

Released into public domain
July 16, 1988

Please distribute in complete form (as you received it).

Any comments, suggestions, criticisms, or anything, please send to let me know.


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 code
for a set of linked lists, I decided that it was time to sit down and write one
set of routines that I could use with them all (that the that it was 3:00am
helped a lot too).  I hope that these routines help your programming as much as
they have helped mine.

Lists ver 2.0 extends on the previous versions in many ways.  It includes many
new routines and subtle changes to others.  If you previously used Lists,
first, I thank you, and second I suggest you re-read this documentation for the
differences between the two versions.

One major difference is that no external code is required for accessing the
itself.  AddToList (which was renamed to AddItem) and InsertInList (renamed to
InsertItem) now take a Size parameter as an argument.  This Size parameter is
the size of the item and it allows the item itself to be incorporated in the
list.  If this doesn't make sense, here is an example:
     Program DemoList;
     Uses Lists;

     Var
        MyList   :  ListRec;
        I        :  Byte;

     Begin
        InitList(MyList);

        For I:=1 To 10 Do AddItem(MyList, I, SizeOf(I);
     End.
No longer must you worry about the pointers and getting memory that you did in
previous versions.

Other differences include:
     The following procedures have been renamed:
          ListOK         becomes OK
          InsertInList   becomes InsertItem
          AddToList      becomes AddItem
     The MoveTo______ routines have been replaced with MoveToItem
     The ______ItemPtr routines have been replaced with Item
     Routines for accessing a stack have been implemented
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 current item) and OK boolean variable which lets you
know of if errors occur while accessing the list).

To use a list in your program, you 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 before using any list.  InitList
sets all points to NIL and prepares the list for use.

     Program DemoList;
     Uses Lists;

     Var
        MyList               :   ListRec;

     Begin
        InitList(MyList);
     End.





AddItem(Var List:ListRec;
        Var Item;
        Size:Word);
---------------------------------------
AddItem is a procedure used for putting things on the list.  The first
parameter of AddItem is the List you want to append an Item to.  The second
parameter is the Item you want to add.  And third is the size of the Item to be
added.

AddItem placed Item at the end of the list.
AddItem does not move the current item pointer.

     Program DemoList;
     Uses Lists;

     Var
        MyList               :   ListRec;
        I                    :   Byte;

     Begin
        InitList(MyList);
        For I:=1 To 10 Do AddItem(MyList, I, SizeOf(I));
     End.

This program creates the following list:
   1  2  3  4  5  6  7  8  9  10
   ^
   Current item





InsertItem(Var List:ListRec;
           Var Item;
           Size:Word;
           Location:Pointer);
---------------------------------------
InsertItem is another procedure for placing an item on the list.  Unlike
AddItem, InsertItem places the item immediately before the item specified in
Location.  For example:
     Program DemoList;
     Uses Lists;

     Var
        MyList               :   ListRec;
        I                    :   Byte;

     Begin
        InitList(MyList);
        For I:=1 To 10 Do AddItem(MyList, I, SizeOf(I));

        I:=76;
        InsertItem(MyList, I, SizeOf(I), LastItem(Stack));
     End.

This program would create the following list:
   1  2  3  4  5  6  7  8  9  76  10
   ^
   Current item

See CurrentItem, FirstItem, LastItem, PrevItem, and NextItem
InsertItem does not move the current item pointer.
DeleteItem(Var List:ListRec;
           Location:Pointer);
---------------------------------------
DeleteItem deletes the item in List at Location.  For example:
     Program DemoList;
     Uses Lists;

     Var
        MyList               :   ListRec;
        I                    :   Byte;

     Begin
        InitList(MyList);
        For I:=1 To 10 Do AddItem(MyList, I, SizeOf(I));

        DeleteItem, I, SizeOf(I), LastItem(Stack));
     End.

This program produces the following list:
   1  2  3  4  5  6  7  8  9
   ^
   Current item

See CurrentItem, FirstItem, LastItem, NextItem, PrevItem
DeleteItem does not move the current item pointer.





DeleteList(Var List:ListRec)
---------------------------------------
DeleteList removes the entire List from memory and initializes the List for use
again.





CurrentItem(List:ListRec):Pointer;
---------------------------------------
CurrentItem returns the location of the item currently pointed to in List.

     Program DemoList;
     Uses Lists;

     Var
        MyList               :   ListRec;
        I                    :   Byte;

     Begin
        InitList(MyList);
        For I:=1 To 10 Do AddItem(MyList, I, SizeOf(I));

        I:=76;
        InsertItem(MyList, I, SizeOf(I), CurrentItem(MyList));
     End.
This program would produce the following list:
   76   1   2   3   4   5   6   7   8   9   10
        ^
        Current item
FirstItem(List:ListRec):Pointer;
---------------------------------------
FirstItem returns the location of the first item in List.

     Program DemoList;
     Uses Lists;

     Var
        MyList               :   ListRec;
        I                    :   Byte;

     Begin
        InitList(MyList);
        For I:=1 To 10 Do AddItem(MyList, I, SizeOf(I));

        I:=76;
        InsertItem(MyList, I, SizeOf(I), FirstItem;
     End.
This program would produce the following list:
   76   1   2   3   4   5   6   7   8   9   76   10
        ^
        Current item




LastItem(List:ListRec):Pointer;
---------------------------------------
LastItem returns the location of the last item in List.

     Program DemoList;
     Uses Lists;

     Var
        MyList               :   ListRec;
        I                    :   Byte;

     Begin
        InitList(MyList);
        For I:=1 To 10 Do AddItem(MyList, I, SizeOf(I));

        I:=76;
        InsertItem(MyList, I, SizeOf(I), CurrentItem(MyList));
     End.
This program would produce the following list:
   1   2   3   4   5   6   7   8   9   76   10
   ^
   Current item
NextItem(Item:Pointer):Pointer
---------------------------------------
NextItem takes CurrentItem or FirstItem as an argument and returns the
following item.  For example:

     Program DemoList;
     Uses Lists;

     Var
        MyList               :   ListRec;
        I                    :   Byte;

     Begin
        InitList(MyList);
        For I:=1 To 10 Do AddItem(MyList, I, SizeOf(I));

        I:=76;
        InsertItem(MyList, I, SizeOf(I), NextItem(FirstItem(MyList)));
     End.

This program would produce the following list:
   1   76   2   3   4   5   6   7   8   9   10
   ^
   Current item





PrevItem(Item:Pointer):Pointer
---------------------------------------
PrevItem takes either CurrentItem or LastItem as an argument and returns the
preceding argument.

     Program DemoList;
     Uses Lists;

     Var
        MyList               :   ListRec;
        I                    :   Byte;

     Begin
        InitList(MyList);
        For I:=1 To 10 Do AddItem(MyList, I, SizeOf(I));
        I:=76;
        InsertItem(MyList, I, SizeOf(I), NextItem(LastItem(MyList)));
     End.

This program would produce the following list:
   1   2   3   4   5   6   7   8   9   76   10
   ^
   Current item
MoveToItem(Var List:ListRec;
           Location:Pointer);
---------------------------------------
MoveToItem the current item in List to Location.  Location can be CurrentItem,
FirstItem, or LastItem in any combination with NextItem or PrevItem.
MoveToItem will set OK to false if Location is outside of List.

For example to move the current item forward through a list until the end is
reached:

     Program DemoList;
     Uses Lists;

     Var
        MyList               :   ListRec;
        I                    :   Byte;

     Begin
        InitList(MyList);
        For I:=1 To 10 Do AddItem(MyList, I, SizeOf(I));

        MoveToItem(MyList, FirstItem(MyList));
        While MyList.OK Do Begin
           MoveToItem(MyList, NextItem(CurrentItem(MyList));
        End;
     End.

This program moves backward through the list:

     Program DemoList;
     Uses Lists;

     Var
        MyList               :   ListRec;
        I                    :   Byte;

     Begin
        InitList(MyList);
        For I:=1 To 10 Do AddItem(MyList, I, SizeOf(I));

        MoveToItem(MyList, LastItem(MyList));
        While MyList.OK Do Begin
           MoveToItem(MyList, PrevItem(CurrentItem(MyList));
        End;
     End.


MoveToItem(PrevItem(LastItem(MyList))) would move the current item to the
second to the last item on the list, Where
MoveToItem(NextItem(FirstItem(MyList))) would move the current item to the
second item on the list.
GetItem(Var List:ListRec;
        Location:Pointer;
        Var Item)
---------------------------------------
GetItem is a procedure for reading an item off of the list.  The item read is
specified in Location and the item is put into Item.

For example:
     Program DemoList;
     Uses Lists;

     Var
        MyList               :   ListRec;
        I                    :   Byte;

     Begin
        InitList(MyList);
        For I:=1 To 10 Do AddItem(MyList, I, SizeOf(I));

        MoveToItem(MyList, FirstItem(MyList));
        While MyList.OK Do Begin
           GetItem(MyList, I, CurrentItem(MyList));
           Write(I,' ');
           MoveToItem(MyList, NextItem(CurrentItem(MyList));
        End;
     End.

This program would produce the following output:
   1 2 3 4 5 6 7 8 9 10





Item(List:ListRec;
     Location:Pointer):Pointer
----------------------------------------
Item is a function that returns the location of any item in the list.  It's
purpose is similar to GetItem, only implemented as a function.

For example:
     Program DemoList;
     Uses Lists;

     Var
        MyList               :   ListRec;
        I                    :   Byte;

     Begin
        InitList(MyList);
        For I:=1 To 10 Do AddItem(MyList, I, SizeOf(I));

        MoveToItem(MyList, FirstItem(MyList));
        While MyList.OK Do Begin
           I:=Byte(Item(MyList, CurrentItem(MyList))^);
           Write(I,' ');
           MoveToItem(MyList, NextItem(CurrentItem(MyList));
        End;
     End.

This program would produce the following output:
   1 2 3 4 5 6 7 8 9 10
The following procedures are implemented for the purpose of simulating a stack
or queue.  Push and Pop are implemented for a Last In First Out buffer.  Queue
and DeQueue are implemented for a First In Last Out buffer.  They can be
intermixed to produce Last In Last Out and First In First Out.





InitStack(Var Stack:ListRec)
---------------------------------------
InitStack does exactly what InitList does.  It is provided for clarity.





Push(Var Stack:ListRec;
     Var Item;
     Size:Word)
---------------------------------------
Push calls AddItem to place Item at the end of the list.





Pop(Var Stack:ListRec;
    Var Item);
---------------------------------------
Pop removes the last item the Stack and places it in Item.





Queue(Var Stack:ListRec;
      Var Item;
      Size:Word)
---------------------------------------
Queue calls InsertItem to place Item at the beginning of the list





DeQueue(Var Stack:ListRec;
        Var Item)
---------------------------------------
DeQueue removes the first item on Stack and places it in Item.




Again, any questions, comments, criticisms, anything, please let me know.

Mark Addleman
[72777, 740]