Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / LISTS4.ZIP / LISTS40.DOC < prev next >

Wrap

Text File | 1989-06-25 | 22.7 KB | 656 lines

LISTS version 4.0 The LISTS unit is designed to make work with doubly-linked lists a whole lot easier. Now, with Objects and version 4.0 of LISTS, LISTS itself has become a whole lot easier. Please note: An awful lot of effort has gone into the development and testing of LISTS. If you use LISTS and like it, a $15 registration fee is requested. When registered, you will receive the source code to LISTS via CompuServe's EasyPlex. Thank you. Table of Contents Page Section One: Interface. . . . . . . . . . . . . . . . . . . . 1 Section Two: ListObj description. . . . . . . . . . . . . . . 2 F_Entry. . . . . . . . . . . . . . . . . . . . . . . . . . 3 L_Entry. . . . . . . . . . . . . . . . . . . . . . . . . . 3 Init . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Delete . . . . . . . . . . . . . . . . . . . . . . . . . . 3 FirstEntry . . . . . . . . . . . . . . . . . . . . . . . . 4 LastEntry. . . . . . . . . . . . . . . . . . . . . . . . . 4 EntryAbs . . . . . . . . . . . . . . . . . . . . . . . . . 5 EntryRel . . . . . . . . . . . . . . . . . . . . . . . . . 5 MoveEntry. . . . . . . . . . . . . . . . . . . . . . . . . 6 Section Three: EntryObj description . . . . . . . . . . . . . 7 P_Entry. . . . . . . . . . . . . . . . . . . . . . . . . . 7 N_Entry. . . . . . . . . . . . . . . . . . . . . . . . . . 7 Add. . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Insert . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Remove . . . . . . . . . . . . . . . . . . . . . . . . . . 8 NextEntry. . . . . . . . . . . . . . . . . . . . . . . . . 9 PrevEntry. . . . . . . . . . . . . . . . . . . . . . . . . 9 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . 11 Static entries . . . . . . . . . . . . . . . . . . . . . 11 Dynamic entries. . . . . . . . . . . . . . . . . . . . . 12 Hopes . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 LISTS documentation Page 2 Section One: Interface ------------ --------- The following describes the Interface section of LISTS (the routines that can be called from another program.) Please note that there are no Procedures/Functions per se, but objects and methods instead. This switch from previous versions of LISTS makes full use of the new capabilities of TP 5.5 and allows for much greater flexibility in using LISTS. INTERFACE Type EntryPtr = ^EntryObj; ListObj = Object F_Entry : EntryPtr; L_Entry : EntryPtr; Constructor Init; Destructor Done; Virtual; Function FirstEntry:EntryPtr; Virtual; Function LastEntry:EntryPtr; Virtual; Function EntryAbs(Num:LongInt):EntryPtr; Virtual; Function EntryRel(Num:LongInt):EntryPtr; Virtual; Procedure MoveEntry(Source, Dest:EntryPtr); Virtual; End; EntryObj = Object P_Entry : EntryPtr; N_Entry : EntryPtr; Constructor Add(Var List:ListObj); Constructor Insert(Var List:ListObj; Loc:EntryPtr); Destructor Remove(Var List:ListObj); Function NextEntry:EntryPtr; Virtual; Function PrevEntry:EntryPtr; Virtual; End; Notice that all the methods are VIRTUAL, thus allowing the programmer to customize the routines. LISTS documentation Page 3 Section Two: ListObj Description ------------ ------------------- The ListObj is a data type of Object which include two data fields (F_Entry and L_Entry, both of which are of type EntryPtr) and seven methods (Init, the constructor, Delete, the destructor, FirstEntry, LastEntry, EntryAbs, EntryRel, and MoveEntry). All the methods are virtual to allow for simple extensions and modifications. ------------------------------------------------------------ F_Entry : EntryPtr ------------------------------------------------------------ This data field is a pointer to the first entry in the list. It should never be accessed by the programmer; use the method FirstEntry instead. ------------------------------------------------------------ L_Entry : EntryPtr ------------------------------------------------------------ This data field is a pointer to the last entry in the list. It should never be accessed by the programmer; use the method LastEntry instead. ------------------------------------------------------------ Constructor Init ------------------------------------------------------------ This routine initializes the List for processing by setting the data fields to NIL and preparing the Virtual Method Table (VMT). Init must be called prior to ANY activity for the List. Example Var List : ListObj; Begin List.Init; End. ------------------------------------------------------------ Destructor Delete ------------------------------------------------------------ This routine does nothing but release the memory used by the Virtual Method Table (VMT). Example Var LISTS documentation Page 4 List : ListObj; Begin List.Init; ... p List.Delete; End. ------------------------------------------------------------ Function FirstEntry:EntryPtr ------------------------------------------------------------ This function returns a pointer to the first entry in the list. Use this method instead of F_Entry. This function returns NIL if the List has been Initialized and is empty. Example Var List : ListObj; FirstEntryInList : EntryObj; Begin List.Init; ... FirstEntryInList:=List.FirstEntry; End. ------------------------------------------------------------ Function LastEntry:EntryPtr ------------------------------------------------------------ This function returns a pointer to the first entry in the list. Use this method instead of L_Entry. This function returns NIL the the List has been Initialized and is empty. Example Var List : ListObj; LastEntryInList : EntryObj; Begin List.Init; LISTS documentation Page 5 ... LastEntryInList:=List.LastEntry; End. ------------------------------------------------------------ Function EntryAbs(N:LongInt):EntryPtr; ------------------------------------------------------------ This function returns a pointer to the Nth entry in the List starting from the first as number one. N must be positive. Negative numbers will return the FirstEntry in the List. If N exceeds the number of Entries in the List, EntryAbs returns the LastEntry in the List. Example Var List : ListObj; TenthEntry : EntryObj; Begin List.Init; ... TenthEntry:=List.EntryAbs(10); End. ------------------------------------------------------------ Function EntryRel(Loc:EntryPtr; N:LongInt):EntryPtr ------------------------------------------------------------ This function returns a pointer to the Nth entry relative to Loc. N may be positive or negative. If the boundaries of the List are exceeded, a positive N value will return the LastEntry in the List while a negative N value will return the FirstEntry in the List Example Var List : ListObj; TenthFromLast : EntryObj; Begin List.Init; ... LISTS documentation Page 6 TenthFromLast:=List.EntryRel(List.LastEntry, -10); End. ------------------------------------------------------------ Procedure MoveEntry(Source, Dest:EntryPtr) ------------------------------------------------------------ This procedure moves the Source entry to the location of immediately preceding Dest. For example, Var L : ListObj; Begin L.Init; ... With L Do MoveEntry(FirstEntry, LastEntry); End. will move the FirstEntry in List, L to the next to the last position in L. To move Source to the last position in the List, use NIL as the value for Dest, for example, Var L : ListObj; Begin L.Init; ... With L Do MoveEntry(FirstEntry, NIL); End. Now the FirstEntry in the List has been moved to the LastEntry and there is a new FirstEntry. MoveEntry performs no range checks of any sort and therefore it is the programmer's responsibility to ensure that the arguments to MoveEntry are both of the same list. LISTS documentation Page 7 Section Three: EntryObj Description -------------- -------------------- Like the ListObj, all the methods in EntryObj are virtual. ------------------------------------------------------------ P_Entry : EntryObj ------------------------------------------------------------ Data field pointing to the previous entry in the List. FirstEntry^.P_Entry points to NIL. Should not be accessed by the programmer, use PrevEntry instead. ------------------------------------------------------------ N_Entry : EntryObj ------------------------------------------------------------ Data field pointing to the next entry in the List. LastEntry^.N_Entry points to NIL. Should not be accessed by the programmer, use NextEntry instead. ------------------------------------------------------------ Constructor Add(Var List:ListObj); ------------------------------------------------------------ This routine adds EntryObj into List at the end and sets up its own Virtual Method Table. If the List is empty, both List.FirstEntry and List.LastEntry point to the EntryObj. Example Type EntryRec = Object (EntryObj) {The new object is a descendant from EntryObj, which is defined in LISTS} I:Integer; End; Var List : ListObj; Entry: EntryRec; Begin List.Init; Entry.I:=1; Entry.Add(List); End; LISTS documentation Page 8 ------------------------------------------------------------ Constructor Insert(Var List:ListObj; Loc:EntryPtr) ------------------------------------------------------------ Like Add, this routine sets up the Virtual Method Table (VMT). Insert also inserts EntryObj into List immediately preceding Loc, if Loc is NIL, EntryObj is added to the end of List. No range checking is performed in Insert, it is the programmer's responsibility to ensure that Loc is in the same list as List. Example Type EntryRec = Object (EntryObj) {The new object is a descendant from EntryObj, which is defined in LISTS} I:Integer; End; Var List : ListObj; Entry: EntryRec; Begin List.Init; ... Entry.I:=2; Entry.Insert(List, List.LastEntry); End; ------------------------------------------------------------ Destructor Remove(Var List:ListObj) ------------------------------------------------------------ This routine removes EntryObj from List and frees up the memory required by EntryObj's Virtual Method Table. Example Type EntryRec = Object (EntryObj) I : Integer; End; Var List : ListObj; Entries : Array [1..10] of EntryRec; N : Integer; Begin List.Init; LISTS documentation Page 9 For N:=1 To 10 Do Begin Entries[N].I:=N; Entries[N].Add(List); End; Entries[5].Remove(List); End. At the end of the program, List would look like this: 1 2 3 4 6 7 8 9 10 ------------------------------------------------------------ Function NextEntry:EntryPtr ------------------------------------------------------------ This routine returns the entry immediately after EntryObj. If the EntryObj is the LastEntry in the list, a value of NIL is returned. Example Type EntryRec = Object (EntryObj) I : Integer; End; Var List : ListObj; Entries : Array [1..10] of EntryRec; N : Integer; Begin List.Init; For N:=1 To 10 Do Begin Entries[N].I:=N; Entries[N].Add(List); End; Writeln(EntryRec(Entries[5].NextEntry^).I); End. This program would output a "6". ------------------------------------------------------------ Function PrevEntry:EntryPtr ------------------------------------------------------------ This routine returns the entry immediately before EntryObj. If the EntryObj is the FirstEntry in the List, a value of NIL is returned. LISTS documentation Page 10 Example Type EntryRec = Object (EntryObj) I : Integer; End; Var List : ListObj; Entries : Array [1..10] of EntryRec; N : Integer; Begin List.Init; For N:=1 To 10 Do Begin Entries[N].I:=N; Entries[N].Add(List); End; Writeln(EntryRec(Entries[5].PrevEntry^).I); End. This program would output a "4". LISTS documentation Page 11 Examples -------- The following examples will hopefully make the use of LISTS a bit clearer. Static Entries -------------- Occasionally it might be useful to have static entries in a List, that is to have the entries declared in the VAR section of the program. The above examples are examples of static entries. To make use of static entries, simply define the TYPE of the entry as an object which is descendant of EntryObj, for example, Type EntryRec = Object (EntryObj) {Descendant from EntryObj} Name:String[30]; End; Then, in the VAR section, declare variables to be of type EntryRec which then can become part of a List. For example, Var Entry1, Entry2, Entry3 : EntryRec; NameList : ListObj; P : EntryPtr; Begin NameList.Init; Write('Enter first name:'); Readln(Entry1.Name); Write('Enter second name:'); Readln(Entry2.Name); Write('Entry third name:'); Readln(Entry3.Name); Entry1.Add(NameList); Entry2.Add(NameList); Entry3.Add(NameList); Writeln('The following is the REVERSED list of names.'); P:=NameList.LastEntry; While Not (P=nil) Do Begin Writeln(EntryRec(P^).Name); P:=P^.PrevEntry; End; End. LISTS documentation Page 12 Dynamic entries --------------- Infinitely more useful than Static entries are Dynamic entries. These entries use the heap to store the information contained in the List. Below is the above example written to use Dynamic entries. Notice that in the output section, after displaying the name, the program removes the Entry from the List and then removes the Entry from the heap. Type EntryRec = Object (EntryObj) {Descendant from EntryObj} Name:String[30]; End; Var Entry : ^EntryRec; Name : String[30]; NameList : ListObj; P : EntryPtr; Begin NameList.Init; Writeln('Enter names, blank line to stop.'); Repeat Readln(Name); If Not (Name='') Then Begin New(Entry, Add(NameList)); Entry^.Name:=Name; End; Until Name=''; Writeln('The following is the REVERSED list of names.'); P:=NameList.LastEntry; While Not (P=nil) Do Begin Writeln(EntryRec(P^).Name); Entry:=P; P:=P^.PrevEntry; Dispose(Entry, Remove); End; End. IMPORTANT NOTE: Due to the nature of LISTS, each Entry into the List must be descended from EntryObj. LISTS documentation Page 13 Hopes ----- I hope you find LISTS both useful and productive. If you have any questions or comments regarding the program, please address them to Mark Addleman via CompuServe (CIS number - 72777, 740) Thank you very much.