PC Media 4

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

/ PC Media 4 / PC MEDIA CD04.iso / share / prog / ll_class / ll_class.doc < prev next >

Wrap

Text File | 1994-09-18 | 46.3 KB | 741 lines

╔═══════════════════════════════════════════════════════════════════════════╗ ║ LL_CLASS.DOC ║ ╠═══════════════════════════════════════════════════════════════════════════╣ ║ ║ ║ copyrighted August 1994 by Dynamic Solutions ║ ║ Rt 1, Box 185 ║ ║ Osage City, Kansas 66523-9744 ║ ║ 913-528-4304 ║ ╚═══════════════════════════════════════════════════════════════════════════╝ ███████████████████████████████████████████████████████████████████████████████ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Distribution Format = LL_CLASS.ZIP which contains: VERSION 1.0 o Software Module = LL_CLASS.OBJ o Include Files = LL_CLASS.H o Documentation = LL_CLASS.DOC o Test Program = LL_TEST.EXE o Sample Project File = LL_TEST.PRJ Sales Tax* Registration Fee = $15 + $4 for shipping and handling $ .89 Source Code Fee = $10 in addition to the Registration Fee $1.71 * Sales Tax is required by Kansas residents only NOTICE: This is a shareware product that contains routines as described below. If these routines prove to be of value in your computer world, then a registration fee would be appreciated to help pay for the development time and for future developments. Please carefully read the following terms and conditions of our registration agreement at the end of this document before using this software. If you want to know "the rest of the story" and wish to have the well-documented source code and also a test program to demonstrate the use of the functions in more detail than you find in this document, then please also send the source code fee to our "little software house on the prairie" at ─── Dynamic Solutions Rt 1, Box 185 Osage City, KS 66523 PS- If there are any other products or utilities that you wish to have, please let us know. We are looking for other needs to fill. We have a variety of expertise from "down under" multi-tasking and TSR assembler code for DOS to "higher up" Presentation Manager code for OS/2. We can provide modules up to full blown applications. Give us a try!!! Also, all comments are welcome. Do you like our style? Is there something that we can do better to help you? What don't you like about our services? All feedback is welcome. Thanks for checking us out!!! ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ███████████████████████████████████████████████████████████████████████████████ ╔══════════════════════════════════╗ ║ WHAT THIS PRODUCT CAN DO FOR YOU ║ ╚══════════════════════════════════╝ LL_CLASS Version 1.00 Welcome to the world of linked lists. Have you ever wished you didn't have to worry about how to handle all those pointers? Well here is our DYNAMIC SOLUTION ─── an OBJECT ORIENTED CLASS LIBRARY OF LINKED LIST ROUTINES in 'C' that will provide ───> o Linked List Functions: - Create a linked list with ANY contents - Print the contents in ANY manner you wish - Delete a linked list - Sort the linked list by ANY sort desired (Uses a temporary non-recursive B-Tree method) o Linked List Element/Node Functions: - Add a New Node to a Linked List at its Head - Add a New Node to a Linked List at its Tail - Insert a New Node into a Linked List o Before a given node o After a given node - Delete the Head Node from a Linked List - Delete the Tail Node from a Linked List - Delete any Node from a Linked List - Swap or Trade positions of any 2 Linked List Nodes - Move a Node anywhere within a Linked List o Before a given node o After a given node - Promote any Node to the Head of the Linked List - Demote any Node to the Tail of the Linked List - Find ANY Desired Data in the Linked List - Find the nth item in the Linked List as if it were a subscripted array o Stack Functions: o Queue Functions: - Push on a stack - Push on a queue - Pop off a stack - Pop off a queue for ANY linked list with ANY contents that you define in your own program. The Linked List Class Library has control/ownership of the linked list and pointers to the data, but the calling program has control/ownership over the contents and use of that data. Think of it as you (your program) have control/ownership of your money and you tell the banker (the class library) to deposit your money into your bank account. That banker has control/ownership of all banking functions, but you can tell him what you want done to your own money (your program data). This allows the application program to be able to define any data structure whatsoever and still be able to call the library routines to handle it. Doesn't that sound great! You no longer have to write linked list code for each separate application you have. It is written once and then done forever. Your next new application only defines new data and still calls the old library functions without any change at all in the linked list coding. What a life! Who likes to do things twice anyway? The advantages of linked lists instead of arrays, in case you are wondering, is that the memory for linked lists is allocated on an as-needed basis (dynamically) and not as a maximum lump sum at the beginning of the program as for arrays. Assume the maximum number of elements in a list can get up to 200. Using arrays, the entire 200 elements must be allocated for in memory at the beginning of the program, whether all are used or not. Using linked lists, if five elements are in a list this time you run the program, then only five elements will be allocated in memory. For those of you familiar with manufacturing, you can relate the array to the "Just In Case" methodology and the linked list to the "Just In Time" methodology. If speed is a factor in your program, you should know that insertions and deletions into or out of the list can also be made much easier and faster than in an array. To rearrange elements in a list using arrays requires actually moving data from one memory location to another until the elements are rearranged in their proper order. To rearrange elements in a linked list only requires changing a pointer to point to another element and the actual data stays in the same location. Another advantage of using linked lists instead of arrays, is that when using arrays, the programmer must guesstimate the maximum number of elements that might ever be needed using that program. The compiler must then allocate the appropriate amount of memory before execution even begins. If the programmer has underestimated, the program will eventually end abnormally. If there is an overestimate, not only is space monopolized from the beginning, but too much is set aside. To understand linked lists in more detail, get a Data Structures textbook. If you have not used them before, it will be well worth your time and trouble. They are quite versatile. Some texts call the items in your list a node, others call it an element. The standard prefix naming convention used here is LL meaning Linked List, LList pertains to the entire list, and LLNode pertains to a node or element within the given list. The following diagram shows how the structures defined in the LL_CLASS.H file are inter-related. The Data structure box is totally in the hands of the programmer for the application using this library. The routines defined in LL_CLASS.OBJ do not even care what is contained in the Data structure box below. That is the beauty of having a class library. It handles the "dirty work" for you, but you, as a programmer, have control of what data it handles for you. List │ │ v ┌───────┐ │ LList │ ┌──────────────┬────────────┴───┬───┴─────────────┬───────────────┐ │ │ │ │ │ │ LListPtrHead │ LListPtrTail │ LListPtrCurr │ LListLength │ │ │ │ │ = 3 │ └──────┬───────┴───────┬────────┴─────────────────┴───────────────┘ │ │ │ │ └────┐ └────────────────────────────────────┐ │ │ v v ┌────────┐ ┌────────┐ ┌────────┐ │ LLNode │ │ LLNode │ │ LLNode │ ┌────┴────────┴─────┐ ┌────┴────────┴─────┐ ┌────┴────────┴─────┐ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │▒▒ LLNodePtrNext ▒▒├──>│▒▒ LLNodePtrNext ▒▒├──>│▒▒ LLNodePtrNext ▒▒├──> 0 │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ ├───────────────────┤ ├───────────────────┤ ├───────────────────┤ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ 0 <───┤▒▒ LLNodePtrPrev ▒▒│<──┤▒▒ LLNodePtrPrev ▒▒│<──┤▒▒ LLNodePtrPrev ▒▒│ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ ├───────────────────┤ ├───────────────────┤ ├───────────────────┤ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │ LLNodePtrContents │ │ LLNodePtrContents │ │ LLNodePtrContents │ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ └────────┬──────────┘ └────────┬──────────┘ └────────┬──────────┘ │ │ │ Property of │ │ │ LL_CLASS.OBJ │ │ │ │ │ │ .............│.......................│.......................│............ │ │ │ Property of │ │ │ calling program│ │ │ v v v ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐ │░░░░░░░░░░░░░░░░░░░│ │░░░░░░░░░░░░░░░░░░░│ │░░░░░░░░░░░░░░░░░░░│ │░░Data structure░░░│ │░░Data structure░░░│ │░░Data structure░░░│ │░░░░░░░░░░░░░░░░░░░│ │░░░░░░░░░░░░░░░░░░░│ │░░░░░░░░░░░░░░░░░░░│ └───────────────────┘ └───────────────────┘ └───────────────────┘ Below are the descriptive headers from each routine in the LL_CLASS.C source code file. Within the source code you find much more documentation to make linked lists more understandable. You will find the source code for the test program quite helpful with examples of each useage. It provides enough information that you can do quite a good job of "monkey see, monkey do" type programming using it as a guide. The test program also creates a data file, LL_TEST., which contains all output from the use of the program to document your testing. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ░ LINKED LIST FUNCTIONS ░ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ╔════════════════════════════════════════════════════════════════════════════╗ ║ LList_InitErrMsg ║ ║────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : Initializes error message structure when starting program ║ ║ PARAMETERS : none ║ ║ RETURNS : none ║ ║ EXAMPLE USE: LList_InitErrMsg (); ║ ╚════════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════════╗ ║ LList_Create ║ ║────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : Dynamically creates an empty Linked List (LList) ║ ║ PARAMETERS : none ║ ║ RETURNS : pointer to a newly created LList definition structure ║ ║ EXAMPLE USE: if ( SampleList = LList_Create() ) ║ ║ { ║ ║ *..... created ok * ║ ║ } ║ ║ else ║ ║ { ║ ║ *..... error happened * ║ ║ } ║ ╚════════════════════════════════════════════════════════════════════════════╝ ╔═════════════════════════════════════════════════════════════════════════════╗ ║ LList_Print ║ ║─────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : Prints contents of an entire list from head to tail ║ ║ PARAMETERS : pointer to LList definition structure ║ ║ address to a function in the calling program that prints the ║ ║ contents of a single data structure ║ ║ RETURNS : none ║ ║ EXAMPLE USE: LList_Print( SampleList, SamplePrint ); ║ ╚═════════════════════════════════════════════════════════════════════════════╝ ╔═════════════════════════════════════════════════════════════════════════════╗ ║ LList_Delete ║ ║─────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : Deletes entire contents of a linked list and frees memory ║ ║ PARAMETERS : pointer to LList definition structure ║ ║ RETURNS : none ║ ║ EXAMPLE USE: LList_Delete ( SampleList ); SampleList = NULL; ║ ╚═════════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════════╗ ║ LList_Sort ║ ║────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : Sorts an entire linked list using the given function ║ ║ PARAMETERS : pointer to LList definition structure ║ ║ pointer to calling program's function that determines ║ ║ whether a data item goes to the left or right in the ║ ║ desired sorted list ║ ║ RETURNS : none ║ ║ EXAMPLE USE: LList_Sort ( SampleList, SampleSort ); ║ ╚════════════════════════════════════════════════════════════════════════════╝ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ░ LINKED LIST NODE FUNCTIONS ░ ░ ░ ░ Linked Lists are similar to a bunch of little kids standing in line where ░ ░ none of them knows where they are in the line, but each knows who stands ░ ░ in front of him/her and who stands in back of him/her. The list/line can ░ ░ be followed like a gossip line. ░ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ╔════════════════════════════════════════════════════════════════════════════╗ ║ LLNode_Insert ║ ║────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : Creates and inserts a new linked list node ║ ║ for example: InsertPosition points to 3; inserts X ║ ║ if Where = BEFORE ║ ║ before: 1 2 3 4 5 6 7 8 ║ ║ after : 1 2 X 3 4 5 6 7 8 ║ ║ if Where = AFTER ║ ║ before: 1 2 3 4 5 6 7 8 ║ ║ after : 1 2 3 X 4 5 6 7 8 ║ ║ PARAMETERS : pointer to LList definition structure ║ ║ a predefined constant, either BEFORE or AFTER which ║ ║ deterines whether the insert is before or after the ║ ║ given location called InsertHere in this example ║ ║ pointer to position where to insert new node ║ ║ pointer to new data structure from calling program ║ ║ RETURNS : none ║ ║ EXAMPLE USE: LLNode_Insert ( SampleList, BEFORE, InsertHere, SampleData);║ ╚════════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════════╗ ║ LLNode_AddAtHead ║ ║────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : Creates a new node and inserts as the new head ║ ║ for example: new data is X ║ ║ before: 1 2 3 4 5 6 7 8 ║ ║ after : X 1 2 3 4 5 6 7 8 ║ ║ PARAMETERS : pointer to LList definition structure ║ ║ pointer to the data contents controlled by calling program ║ ║ RETURNS : none ║ ║ EXAMPLE USE: LLNode_AddAtHead ( SampleList, NewData ); ║ ╚════════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════════╗ ║ LLNode_AddAtTail ║ ║────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : Creates a new node and inserts as the new tail ║ ║ for example: new data is X ║ ║ before: 1 2 3 4 5 6 7 8 ║ ║ after : 1 2 3 4 5 6 7 8 X ║ ║ PARAMETERS : pointer to LList definition structure ║ ║ pointer to the data contents controlled by calling program ║ ║ RETURNS : none ║ ║ EXAMPLE USE: LLNode_AddAtTail ( SampleList, NewData ); ║ ╚════════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════════╗ ║ LLNode_DelNode ║ ║────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : Deletes contents of a given linked list node & frees mem ║ ║ for example: DeleteNode points to 3 ║ ║ before: 1 2 3 4 5 6 7 8 ║ ║ after : 1 2 4 5 6 7 8 ║ ║ PARAMETERS : pointer to LList definition structure ║ ║ pointer to LLNode that you wish to delete ║ ║ RETURNS : none ║ ║ EXAMPLE USE: LLNode_DelNode ( SampleList, PtrData ); ║ ╚════════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════════╗ ║ LLNode_DelHead ║ ║────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : Deletes contents of a linked list node at head & frees mem ║ ║ for example: ║ ║ before: 1 2 3 4 5 6 7 8 ║ ║ after : 2 3 4 5 6 7 8 ║ ║ PARAMETERS : pointer to LList definition structure ║ ║ RETURNS : none ║ ║ EXAMPLE USE: LLNode_DelHead ( SampleList ); ║ ╚════════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════════╗ ║ LLNode_DelTail ║ ║────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : Deletes contents of a linked list node at tail & frees mem ║ ║ for example: ║ ║ before: 1 2 3 4 5 6 7 8 ║ ║ after : 1 2 3 4 5 6 7 ║ ║ PARAMETERS : pointer to LList definition structure ║ ║ RETURNS : none ║ ║ EXAMPLE USE: LLNode_DelTail ( SampleList ); ║ ╚════════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════════╗ ║ LLNode_Swap ║ ║────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : swaps/trades positions of 2 linked list NODEs ║ ║ for example: FromNode points to 3; ToNode points to 5 ║ ║ before: 1 2 3 4 5 6 7 8 ║ ║ after : 1 2 5 4 3 6 7 8 ║ ║ PARAMETERS : pointer to LList definition structure ║ ║ pointer to linked list NODE at swap location #1 ║ ║ pointer to linked list NODE at swap location #2 ║ ║ RETURNS : none ║ ║ EXAMPLE USE: LLNode_Swap ( SampleList, ThisNode, ThatNode ); ║ ╚════════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════════╗ ║ LLNode_Move ║ ║────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : moves a linked list NODE to a new position in the list ║ ║ in front of the TO location ║ ║ for example: FromNode points to 3; ToNode points to 6 ║ ║ if Where = BEFORE ║ ║ before: 1 2 3 4 5 6 7 8 ║ ║ after : 1 2 4 5 3 6 7 8 ║ ║ if Where = AFTER ║ ║ before: 1 2 3 4 5 6 7 8 ║ ║ after : 1 2 4 5 6 3 7 8 ║ ║ PARAMETERS : pointer to LList definition structure ║ ║ pointer to linked list NODE at from location ║ ║ a predefined constant, either BEFORE or AFTER which ║ ║ deterines whether the move is before or aftr the given ║ ║ location called ToNode in this example ║ ║ pointer to linked list NODE at to location ║ ║ RETURNS : none ║ ║ EXAMPLE USE: LLNode_Move ( SampleList, MoveNode, BEFORE, ToNode ); ║ ╚════════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════════╗ ║ LLNode_PromoteToHead ║ ║────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : Moves to given node to the head position ║ ║ for example: MoveNode points to 3 ║ ║ before: 1 2 3 4 5 6 7 8 ║ ║ after : 3 1 2 4 5 6 7 8 ║ ║ PARAMETERS : pointer to LList definition structure ║ ║ pointer to linked list NODE to be relocated ║ ║ RETURNS : none ║ ║ EXAMPLE USE: LLNode_PromoteToHead ( SampleList, MoveNode ); ║ ╚════════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════════╗ ║ LLNode_DemoteToTail ║ ║────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : Moves to given node to the tail position ║ ║ for example: MoveNode points to 3 ║ ║ before: 1 2 3 4 5 6 7 8 ║ ║ after : 1 2 4 5 6 7 8 3 ║ ║ PARAMETERS : pointer to LList definition structure ║ ║ pointer to linked list NODE to be relocated ║ ║ RETURNS : none ║ ║ EXAMPLE USE: LLNode_DemoteToTail (SampleList, MoveNode ); ║ ╚════════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════════╗ ║ LLNode_FindData ║ ║────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : Locates the pointer that points to a linked list NODE that ║ ║ contains the desired data ║ ║ PARAMETERS : pointer to LList definition structure ║ ║ pointer to data to be located ║ ║ pointer to a function in the calling program that contains ║ ║ the code to compare or calculate, etc. for the search, ie║ ║ FindPerson is your application program's function ║ ║ RETURNS : pointer to linked list NODE that contains desired data ║ ║ EXAMPLE USE: strcpy ( FindMe, "Tom" ); ║ ║ PtrTom = LLNode_FindData ( SampleList, FindMe, FindPerson );║ ╚════════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════════╗ ║ LLNode_FindSub ║ ║────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : Locates the pointer that points to a linked list NODE that ║ ║ is the nth node in the list; like a subscripted array ║ ║ PARAMETERS : pointer to LList definition structure ║ ║ nth item desired, ie. subscript index ║ ║ where subscripts numbers start with 1 ║ ║ RETURNS : pointer to linked list NODE that contains desired data ║ ║ EXAMPLE USE: PtrNth = LLNode_FindSub ( SampleList, 4 ); ║ ╚════════════════════════════════════════════════════════════════════════════╝ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ░ STACK FUNCTIONS ░ ░ ░ ░ Stacks are LIFO (Last In First Out) structures, so all additions are made ░ ░ at the tail and all deletions are also made at the tail, just like piling ░ ░ orders on a desk. As each order comes in, it is put on the top of the ░ ░ pile, but they are worked/deleted off the top also, so the first order in ░ ░ the pile/list is on the bottom and the last to be worked. ░ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ╔════════════════════════════════════════════════════════════════════════════╗ ║ Stack_Push ║ ║────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : Creates a new node and adds it onto a stack (at the tail) ║ ║ for example: new data is X ║ ║ before: 1 2 3 4 5 6 7 8 ║ ║ after : 1 2 3 4 5 6 7 8 X ║ ║ PARAMETERS : pointer to LList definition structure ║ ║ pointer to the data contents controlled by calling program ║ ║ RETURNS : none ║ ║ EXAMPLE USE: Stack_Push ( SampleList, NewData ); ║ ╚════════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════════╗ ║ Stack_Pop ║ ║────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : Deletes contents of a stack (from tail) and frees memory ║ ║ for example: ║ ║ before: 1 2 3 4 5 6 7 8 ║ ║ after : 1 2 3 4 5 6 7 ║ ║ PARAMETERS : pointer to LList definition structure ║ ║ RETURNS : none ║ ║ EXAMPLE USE: Stack_Pop ( SampleList ); ║ ╚════════════════════════════════════════════════════════════════════════════╝ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ░ QUEUE FUNCTIONS ░ ░ ░ ░ Queues are FIFO (First In First Out) structures, so all additions are ░ ░ made at the tail and all deletions are made at the head, just like being ░ ░ in line at the check out counter at the grocery store. ░ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ╔════════════════════════════════════════════════════════════════════════════╗ ║ Que_Push ║ ║────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : Creates a new node and adds it onto a stack (at the tail) ║ ║ for example: new data is X ║ ║ before: 1 2 3 4 5 6 7 8 ║ ║ after : 1 2 3 4 5 6 7 8 X ║ ║ PARAMETERS : pointer to LList definition structure ║ ║ pointer to the data contents controlled by calling program ║ ║ RETURNS : none ║ ║ EXAMPLE USE: Que_Push ( SampleList, NewData ); ║ ╚════════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════════╗ ║ Que_Pop ║ ║────────────────────────────────────────────────────────────────────────────║ ║ PURPOSE : Deletes contents of a Queue (at the head) and frees memory ║ ║ for example: ║ ║ before: 1 2 3 4 5 6 7 8 ║ ║ after : 2 3 4 5 6 7 8 ║ ║ PARAMETERS : pointer to LList definition structure ║ ║ RETURNS : none ║ ║ EXAMPLE USE: Que_Pop ( SampleList ); ║ ╚════════════════════════════════════════════════════════════════════════════╝ ERROR HANDLING: Upon entry to each routine, a global error handling structure, LLErr is initialized to contain Err = NULL for no error and Routine to point to the name of the current function/routine being executed. During execution of each routine, if an error occurs, the LLErr.Err is set to point to the appropriate error message and the routine exits back to the calling program. It is the duty/responsibility of the calling program to handle the error messages in whatever manner it sees fit. The routines themselves will have no way of knowing what your program needs to do in the event of an error, but it does report all errors back to the calling program. Immediately after your program calls a class library routine it can test the contents of LLErr. If LLErr.Err != NULL then an error has occurred. NOTES BEFORE YOU START USING LL_CLASS.OBJ FUNCTIONS IN YOUR CODE: LL_CLASS.OBJ was compiled with the LARGE memory model using Borland's Turbo C compiler version 2.0. If you need it compiled with another memory model, you will need the source code. Be sure the LL_CLASS.H file is placed in the include subdirectory where your compiler expects it to be. Be sure the LL_CLASS.OBJ file is placed in the lib subdirectory where your compiler expects it to be also. Be sure the two following lines are at the beginning of your application source code. #include <LL_CLASS.H> extern LLErr LL_Err; /* EXTERNal in LL_CLASS.C/OBJ */ LList_InitErrMsg (); must be called in your application program before any LL_CLASS functions are used. ╔══════════════════╗ ║ COPYRIGHT NOTICE ║ ╚══════════════════╝ This software product is protected by the United States of America Copyright law and also by International Treaty provisions. This copyright notice MUST remain with this software product. This software may not be circulated in any incomplete or modified form, nor sold for profit, without written permission of Dynamic Solutions except where otherwise allowed by this agreement. All rights not expressly granted here are reserved to Dynamic Solutions. ╔════════════════════════╗ ║ REGISTRATION AGREEMENT ║ ╚════════════════════════╝ You are hereby allowed to 1- use the Shareware Version of this software for a 10 day evaluation period to determine if it is suitable for your purposes (try before you buy) 2- make as many copies of the Shareware Version of this software and documentation as you wish 3- give exact copies of the original Shareware Version to anyone 4- distribute the Shareware Version of the software and documentation in its unmodified form via electronic means. There is no charge for any of the above activities, however if you distribute this software to others, you are required to distribute the ENTIRE package consisting of the files as listed at the top of this document. You are specifically prohibited from charging, or requesting donations, for any such copies, however made, with the exception of nominal charges for download or disk media and handling charges not to exceed $9.00. You are specifically prohibited from distributing the software and/or documentation bundled with other products (commercial or otherwise) without prior written permission. Unregistered use of this software after the 10 day evaluation period is in violation of federal copyright laws. This registration is not transferrable. This is a good-faith registration agreement dependent upon your honesty. Dynamic Solutions is trusting you to not take advantage of us and therefore to not redistribute this material except by our terms herein stated on a good-faith basis. THIS IS NOT FREE SOFTWARE. THIS IS NOT PUBLIC DOMAIN SOFTWARE. You are allowed to use this software for evaluation purposes without charge for a period of 10 days. If you use this software after the 10 day evaluation period, by doing so you have agreed to the terms and conditions stated herein and the requested registration fee is required. Payments must be in US dollars drawn on a US bank, and should be sent to ─── Dynamic Solutions Rt 1, Box 185 Osage City, KS 66523-9744 One registered copy may either be used by a single person who uses the software personally on one or more computers, or installed on a single workstation used nonsimultaneously by multiple people, but not both. This agreement shall be governed by the laws of the State of Kansas. Payment of the requested registration fee for this product verifies that the user has agreed to these terms and makes the user eligible for support and for being notified of any upgrades to the product and of any new additional products produced by Dynamic Solutions. Credit card ordering and quantity discounts are NOT available at this time. ╔════════════╗ ║ DISCLAIMER ║ ╚════════════╝ Following true professional programming procedures, this product has been extensively tested in various environments and is "bug-free" to the best of our knowledge. This software and the accompanying files are sold "AS IS" and without warranties as to performance or merchantability or any other warranties whether expressed or implied. Because of the various hardware and software environments into which this product may be put, no warranty of fitness for a particular purpose is offered. Good, professional data processing procedure dictates that any program be thoroughly tested with non-critical data before relying on it. The user must assume the entire risk of using the software. In NO event shall Dynamic Solutions be liable for any loss of profits or any other commercial damage, including but not limited to special, incidental, consequential or other damages. Because some states or countries do not allow the exclusion or limitation of liability for consequential or incidental damages, no permission for use of our products will be granted in those states or countries but donations would be appreciated. In order to legally use this product for any purpose other than to evaluate it, you must register it with Dynamic Solutions. Upon registration, you will receive support, upgrade notices, new product notifications, and, if ordered, the complete, well-documented source code. Fill out the following and return it with your registration fee (and source code fee if desired) to ─── ╔════════════════════╗ ║DYNAMIC SOLUTIONS ║ ║Rt 1, Box 185 ║ ║Osage City, KS 66523║ ╚════════════════════╝ ┌────────────┐ ┌────────────┐ Circle desired package ──> │ PKG #1 │ │ PKG #2 │ ├────────────┤ ├────────────┤ │LL_CLASS.OBJ│ │LL_CLASS.OBJ│ │LL_CLASS.H │ │LL_CLASS.H │ │LL_CLASS.DOC│ │LL_CLASS.DOC│ │LL_TEST.EXE │ │LL_TEST.EXE │ │LL_TEST.PRJ │ │LL_TEST.PRJ │ │ │ │LL_CLASS.C │ │ │ │LL_TEST.C │ ├────────────┤ ├────────────┤ SHIPPING & HANDLING │ $ 4.00 │ │ $ 4.00 │ REGISTRATION FEE │ $ 15.00 │ │ $ 15.00 │ SOURCE CODE FEE │ │ │ $ 10.00 │ ├────────────┤ ├────────────┤ TOTAL DUE │ $ 19.00 │ │ $ 29.00 │ ├────────────┤ ├────────────┤ KANSAS RESIDENTS ONLY │ │ │ │ SALES TAX │ $ .89 │ │ $ 1.71 │ TOTAL DUE │ $ 19.89 │ │ $ 30.71 │ └────────────┘ └────────────┘ ┌─────────────┐ │ │ AMOUNT ENCLOSED │$ │ └─────────────┘ ┌──────────┬─────────────────────────────────────────────────────────┐ │ │ │ │ NAME │ │ ├──────────┼─────────────────────────────────────────────────────────┤ │ │ │ │ COMPANY │ │ ├──────────┼─────────────────────────────────────────────────────────┤ │ │ │ │ ADDRESS │ │ ├──────────┼──────────────────────────────────────┬──────────────────┤ │ │ │ │ │ CITY, ST │ │ ZIP │ ├──────────┼──────────────────────────────────────┼──────────────────┤ │ │ │ │ │ PHONE │ │DISK MEDIA DESIRED│ ├──────────┴─────────────────┬────────────────────┤ (Circle one) │ │ │ │ │ │ VERSION YOU CURRENTLY HAVE │ │ 3.5" 5.25" │ ├────────────────────────────┴────────────────────┴──────────────────┤ │ │ │ COMMENTS (We value your opinions and suggestions.) │ │ │