home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 17 / CD_ASCQ_17_101194.iso / vrac / ll_class.zip / LL_CLASS.DOC < prev    next >
Text File  |  1994-09-18  |  47KB  |  741 lines
  1. ╔═══════════════════════════════════════════════════════════════════════════╗
  2. ║                              LL_CLASS.DOC                                 ║
  3. ╠═══════════════════════════════════════════════════════════════════════════╣
  4. ║                                                                           ║
  5. ║  copyrighted August 1994  by Dynamic Solutions                            ║
  6. ║                              Rt 1, Box 185                                ║
  7. ║                              Osage City, Kansas 66523-9744                ║
  8. ║                              913-528-4304                                 ║
  9. ╚═══════════════════════════════════════════════════════════════════════════╝
  10. ███████████████████████████████████████████████████████████████████████████████
  11.  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
  12.   ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
  13.    ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  14.  
  15.     Distribution Format = LL_CLASS.ZIP which contains:     VERSION 1.0
  16.  
  17.          o  Software Module     =  LL_CLASS.OBJ
  18.          o  Include Files       =  LL_CLASS.H
  19.          o  Documentation       =  LL_CLASS.DOC
  20.          o  Test Program        =  LL_TEST.EXE
  21.          o  Sample Project File =  LL_TEST.PRJ
  22.                                                                  Sales Tax*
  23.     Registration Fee = $15 + $4 for shipping and handling         $ .89
  24.     Source Code  Fee = $10 in addition to the Registration Fee    $1.71
  25.     * Sales Tax is required by Kansas residents only
  26.  
  27.     NOTICE:    This  is  a  shareware  product  that  contains  routines as
  28.     described  below.    If  these  routines  prove  to be of value in your
  29.     computer world, then  a registration fee  would be appreciated  to help
  30.     pay  for  the  development  time  and  for future developments.  Please
  31.     carefully read the following  terms and conditions of  our registration
  32.     agreement at the end of this  document before using this software.   If
  33.     you  want  to  know  "the  rest  of  the  story"  and  wish to have the
  34.     well-documented source code and also a test program to demonstrate  the
  35.     use of the  functions in more  detail than you  find in this  document,
  36.     then please also send the source code fee to our "little software house
  37.     on the prairie" at ───
  38.  
  39.                               Dynamic Solutions
  40.                               Rt 1, Box 185
  41.                               Osage City, KS 66523
  42.  
  43.     PS- If there are any other products or utilities that you wish to have,
  44.     please let us know.  We are looking for other needs to fill.  We have a
  45.     variety of expertise from "down under" multi-tasking and TSR  assembler
  46.     code for DOS to "higher up" Presentation Manager code for OS/2.  We can
  47.     provide modules up to full blown applications.  Give us a try!!!
  48.  
  49.     Also, all  comments are  welcome.   Do you  like our  style?   Is there
  50.     something that we can do better to help you?  What don't you like about
  51.     our services?  All feedback is welcome.  Thanks for checking us out!!!
  52.  
  53.    ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  54.   ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
  55.  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
  56. ███████████████████████████████████████████████████████████████████████████████
  57.  
  58.  
  59.                      ╔══════════════════════════════════╗
  60.                      ║ WHAT THIS PRODUCT CAN DO FOR YOU ║
  61.                      ╚══════════════════════════════════╝
  62.  
  63.                              LL_CLASS Version 1.00
  64.  
  65.  
  66.     Welcome to the world of linked lists.  Have you ever wished you  didn't
  67.     have to worry  about how to  handle all those  pointers?  Well  here is
  68.     our DYNAMIC SOLUTION ───
  69.  
  70.         an OBJECT ORIENTED CLASS LIBRARY OF LINKED LIST ROUTINES in 'C'
  71.  
  72.                             that will provide ───>
  73.  
  74.          o Linked List Functions:
  75.  
  76.               - Create a linked list with ANY contents
  77.               - Print the contents in ANY manner you wish
  78.               - Delete a linked list
  79.               - Sort the linked list by ANY sort desired
  80.                 (Uses a temporary non-recursive B-Tree method)
  81.  
  82.          o Linked List Element/Node Functions:
  83.  
  84.               - Add a New Node to a Linked List at its Head
  85.               - Add a New Node to a Linked List at its Tail
  86.               - Insert a New Node into a Linked List
  87.                    o Before a given node
  88.                    o After  a given node
  89.  
  90.               - Delete the Head Node from a Linked List
  91.               - Delete the Tail Node from a Linked List
  92.               - Delete any Node from a Linked List
  93.  
  94.               - Swap or Trade positions of any 2 Linked List Nodes
  95.               - Move a Node anywhere within a Linked List
  96.                    o Before a given node
  97.                    o After  a given node
  98.               - Promote any Node to the Head of the Linked List
  99.               - Demote any Node to the Tail of the Linked List
  100.  
  101.               - Find ANY Desired Data in the Linked List
  102.               - Find the nth item in the Linked List as if it were a
  103.                 subscripted array
  104.  
  105.          o Stack Functions:                 o Queue Functions:
  106.  
  107.               - Push on a stack                  - Push on a queue
  108.               - Pop off a stack                  - Pop off a queue
  109.  
  110.     for ANY  linked list  with ANY  contents that  you define  in your  own
  111.     program.
  112.  
  113.  
  114.     The Linked List Class Library has control/ownership of the linked  list
  115.     and pointers to the data, but the calling program has control/ownership
  116.     over the  contents and  use of  that data.   Think  of it  as you (your
  117.     program) have control/ownership of your  money and you tell the  banker
  118.     (the class library) to deposit your money into your bank account.  That
  119.     banker has control/ownership of all banking functions, but you can tell
  120.     him what you  want done to  your own money  (your program data).   This
  121.     allows the application program to be able to define any data  structure
  122.     whatsoever and still be able to call the library routines to handle it.
  123.     Doesn't that sound great!  You no longer have to write linked list code
  124.     for each separate application  you have.  It  is written once and  then
  125.     done forever.   Your  next new  application only  defines new  data and
  126.     still calls the old library functions without any change at all in  the
  127.     linked list coding.  What a life!  Who likes to do things twice anyway?
  128.  
  129.     The  advantages  of  linked  lists  instead  of arrays, in case you are
  130.     wondering,  is  that  the  memory  for  linked lists is allocated on an
  131.     as-needed basis  (dynamically) and  not as  a maximum  lump sum  at the
  132.     beginning of the program as for  arrays.  Assume the maximum number  of
  133.     elements in a  list can get  up to 200.   Using arrays,  the entire 200
  134.     elements  must  be  allocated  for  in  memory  at the beginning of the
  135.     program, whether  all are  used or  not.   Using linked  lists, if five
  136.     elements are in a  list this time you  run the program, then  only five
  137.     elements will be allocated in memory.   For those of you familiar  with
  138.     manufacturing,  you  can  relate  the  array  to  the  "Just  In  Case"
  139.     methodology and the linked list to the "Just In Time" methodology.
  140.  
  141.     If speed is a factor in  your program, you should know that  insertions
  142.     and deletions into or out of the list can also be made much easier  and
  143.     faster than in an array.  To rearrange elements in a list using  arrays
  144.     requires actually moving data from one memory location to another until
  145.     the  elements  are  rearranged  in  their  proper  order.  To rearrange
  146.     elements in a linked list only requires changing a pointer to point  to
  147.     another element and the actual data stays in the same location.
  148.  
  149.     Another advantage of using linked lists instead of arrays, is that when
  150.     using arrays,  the programmer  must guesstimate  the maximum  number of
  151.     elements that might  ever be needed  using that program.   The compiler
  152.     must then allocate  the appropriate amount  of memory before  execution
  153.     even begins.   If the programmer  has underestimated, the  program will
  154.     eventually end abnormally.   If there  is an overestimate,  not only is
  155.     space monopolized from the beginning, but too much is set aside.
  156.  
  157.     To  understand  linked  lists  in  more  detail,  get a Data Structures
  158.     textbook.  If you have not used them before, it will be well worth your
  159.     time and trouble.  They are quite versatile.  Some texts call the items
  160.     in your list a  node, others call it  an element.  The  standard prefix
  161.     naming convention used here is  LL meaning Linked List, LList  pertains
  162.     to the entire list, and LLNode pertains to a node or element within the
  163.     given list.
  164.  
  165.  
  166.     The  following  diagram  shows  how  the  structures  defined  in   the
  167.     LL_CLASS.H file are inter-related.   The Data structure box is  totally
  168.     in the hands of the programmer for the application using this  library.
  169.     The routines defined in LL_CLASS.OBJ do not even care what is contained
  170.     in the Data structure box below.  That is the beauty of having a  class
  171.     library.    It  handles  the  "dirty  work"  for  you,  but  you,  as a
  172.     programmer, have control of what data it handles for you.
  173.  
  174.                                  List
  175.                                    │
  176.                                    │
  177.                                    v
  178.                                ┌───────┐
  179.                                │ LList │
  180.    ┌──────────────┬────────────┴───┬───┴─────────────┬───────────────┐
  181.    │              │                │                 │               │
  182.    │ LListPtrHead │  LListPtrTail  │   LListPtrCurr  │   LListLength │
  183.    │              │                │                 │           = 3 │
  184.    └──────┬───────┴───────┬────────┴─────────────────┴───────────────┘
  185.           │               │
  186.           │               │
  187.           └────┐          └────────────────────────────────────┐
  188.                │                                               │
  189.                v                                               v
  190.            ┌────────┐              ┌────────┐              ┌────────┐
  191.            │ LLNode │              │ LLNode │              │ LLNode │
  192.       ┌────┴────────┴─────┐   ┌────┴────────┴─────┐   ┌────┴────────┴─────┐
  193.       │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│   │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│   │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
  194.       │▒▒ LLNodePtrNext ▒▒├──>│▒▒ LLNodePtrNext ▒▒├──>│▒▒ LLNodePtrNext ▒▒├──> 0
  195.       │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│   │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│   │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
  196.       ├───────────────────┤   ├───────────────────┤   ├───────────────────┤
  197.       │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│   │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│   │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
  198. 0 <───┤▒▒ LLNodePtrPrev ▒▒│<──┤▒▒ LLNodePtrPrev ▒▒│<──┤▒▒ LLNodePtrPrev ▒▒│
  199.       │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│   │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│   │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
  200.       ├───────────────────┤   ├───────────────────┤   ├───────────────────┤
  201.       │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│   │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│   │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
  202.       │ LLNodePtrContents │   │ LLNodePtrContents │   │ LLNodePtrContents │
  203.       │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│   │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│   │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
  204.       └────────┬──────────┘   └────────┬──────────┘   └────────┬──────────┘
  205.                │                       │                       │
  206. Property of    │                       │                       │
  207. LL_CLASS.OBJ   │                       │                       │
  208.                │                       │                       │
  209.   .............│.......................│.......................│............
  210.                │                       │                       │
  211. Property of    │                       │                       │
  212. calling program│                       │                       │
  213.                v                       v                       v
  214.       ┌───────────────────┐   ┌───────────────────┐   ┌───────────────────┐
  215.       │░░░░░░░░░░░░░░░░░░░│   │░░░░░░░░░░░░░░░░░░░│   │░░░░░░░░░░░░░░░░░░░│
  216.       │░░Data structure░░░│   │░░Data structure░░░│   │░░Data structure░░░│
  217.       │░░░░░░░░░░░░░░░░░░░│   │░░░░░░░░░░░░░░░░░░░│   │░░░░░░░░░░░░░░░░░░░│
  218.       └───────────────────┘   └───────────────────┘   └───────────────────┘
  219.  
  220.  
  221.     Below are the descriptive headers  from each routine in the  LL_CLASS.C
  222.     source  code  file.    Within  the  source  code  you  find  much  more
  223.     documentation to make linked lists more understandable.  You will  find
  224.     the source  code for  the test  program quite  helpful with examples of
  225.     each useage.  It  provides enough information that  you can do quite  a
  226.     good job  of "monkey  see, monkey  do" type  programming using  it as a
  227.     guide.   The test  program also  creates a  data file,  LL_TEST., which
  228.     contains  all  output  from  the  use  of  the program to document your
  229.     testing.
  230.  
  231. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  232. ░                        LINKED LIST FUNCTIONS                              ░
  233. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  234.  
  235. ╔════════════════════════════════════════════════════════════════════════════╗
  236. ║                             LList_InitErrMsg                               ║
  237. ║────────────────────────────────────────────────────────────────────────────║
  238. ║  PURPOSE    :  Initializes error message structure when starting program   ║
  239. ║  PARAMETERS :  none                                                        ║
  240. ║  RETURNS    :  none                                                        ║
  241. ║  EXAMPLE USE:  LList_InitErrMsg ();                                        ║
  242. ╚════════════════════════════════════════════════════════════════════════════╝
  243.  
  244. ╔════════════════════════════════════════════════════════════════════════════╗
  245. ║                             LList_Create                                   ║
  246. ║────────────────────────────────────────────────────────────────────────────║
  247. ║  PURPOSE    :  Dynamically creates an empty Linked List (LList)            ║
  248. ║  PARAMETERS :  none                                                        ║
  249. ║  RETURNS    :  pointer to a newly created LList definition structure       ║
  250. ║  EXAMPLE USE:  if ( SampleList = LList_Create() )                          ║
  251. ║                {                                                           ║
  252. ║                    *..... created ok *                                     ║
  253. ║                }                                                           ║
  254. ║                else                                                        ║
  255. ║                {                                                           ║
  256. ║                    *..... error happened *                                 ║
  257. ║                }                                                           ║
  258. ╚════════════════════════════════════════════════════════════════════════════╝
  259.  
  260. ╔═════════════════════════════════════════════════════════════════════════════╗
  261. ║                             LList_Print                                     ║
  262. ║─────────────────────────────────────────────────────────────────────────────║
  263. ║  PURPOSE    :  Prints contents of an entire list from head to tail          ║
  264. ║  PARAMETERS :  pointer to LList definition structure                        ║
  265. ║                address to a function in the calling program that prints the ║
  266. ║                   contents of a single data structure                       ║
  267. ║  RETURNS    :  none                                                         ║
  268. ║  EXAMPLE USE:  LList_Print( SampleList, SamplePrint );                      ║
  269. ╚═════════════════════════════════════════════════════════════════════════════╝
  270.  
  271. ╔═════════════════════════════════════════════════════════════════════════════╗
  272. ║                             LList_Delete                                    ║
  273. ║─────────────────────────────────────────────────────────────────────────────║
  274. ║  PURPOSE    :  Deletes entire contents of a linked list and frees memory    ║
  275. ║  PARAMETERS :  pointer to LList definition structure                        ║
  276. ║  RETURNS    :  none                                                         ║
  277. ║  EXAMPLE USE:  LList_Delete ( SampleList  );  SampleList = NULL;            ║
  278. ╚═════════════════════════════════════════════════════════════════════════════╝
  279.  
  280. ╔════════════════════════════════════════════════════════════════════════════╗
  281. ║                              LList_Sort                                    ║
  282. ║────────────────────────────────────────────────────────────────────────────║
  283. ║  PURPOSE    :  Sorts an entire linked list using the given function        ║
  284. ║  PARAMETERS :  pointer to LList definition structure                       ║
  285. ║                pointer to calling program's function that determines       ║
  286. ║                   whether a data item goes to the left or right in the     ║
  287. ║                   desired sorted list                                      ║
  288. ║  RETURNS    :  none                                                        ║
  289. ║  EXAMPLE USE:  LList_Sort ( SampleList, SampleSort );                      ║
  290. ╚════════════════════════════════════════════════════════════════════════════╝
  291.  
  292. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  293. ░                      LINKED LIST NODE FUNCTIONS                           ░
  294. ░                                                                           ░
  295. ░ Linked Lists are similar to a bunch of little kids standing in line where ░
  296. ░ none of them knows where they are in the line, but each knows who stands  ░
  297. ░ in front of him/her and who stands in back of him/her.  The list/line can ░
  298. ░ be followed like a gossip line.                                           ░
  299. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  300.  
  301. ╔════════════════════════════════════════════════════════════════════════════╗
  302. ║                            LLNode_Insert                                   ║
  303. ║────────────────────────────────────────────────────────────────────────────║
  304. ║  PURPOSE    :  Creates and inserts a new linked list node                  ║
  305. ║                for example:  InsertPosition points to 3; inserts X         ║
  306. ║                   if Where = BEFORE                                        ║
  307. ║                     before:  1 2 3 4 5 6 7 8                               ║
  308. ║                     after :  1 2 X 3 4 5 6 7 8                             ║
  309. ║                   if Where = AFTER                                         ║
  310. ║                     before:  1 2 3 4 5 6 7 8                               ║
  311. ║                     after :  1 2 3 X 4 5 6 7 8                             ║
  312. ║  PARAMETERS :  pointer to LList definition structure                       ║
  313. ║                a predefined constant, either BEFORE or AFTER which         ║
  314. ║                    deterines whether the insert is before or after the     ║
  315. ║                    given location called InsertHere in this example        ║
  316. ║                pointer to position where to insert new node                ║
  317. ║                pointer to new data structure from calling program          ║
  318. ║  RETURNS    :  none                                                        ║
  319. ║  EXAMPLE USE:  LLNode_Insert ( SampleList, BEFORE, InsertHere, SampleData);║
  320. ╚════════════════════════════════════════════════════════════════════════════╝
  321.  
  322. ╔════════════════════════════════════════════════════════════════════════════╗
  323. ║                           LLNode_AddAtHead                                 ║
  324. ║────────────────────────────────────────────────────────────────────────────║
  325. ║  PURPOSE    :  Creates a new node and inserts as the new head              ║
  326. ║                for example:  new data is X                                 ║
  327. ║                     before:  1 2 3 4 5 6 7 8                               ║
  328. ║                     after :  X 1 2 3 4 5 6 7 8                             ║
  329. ║  PARAMETERS :  pointer to LList definition structure                       ║
  330. ║                pointer to the data contents controlled by calling program  ║
  331. ║  RETURNS    :  none                                                        ║
  332. ║  EXAMPLE USE:  LLNode_AddAtHead ( SampleList, NewData );                   ║
  333. ╚════════════════════════════════════════════════════════════════════════════╝
  334.  
  335. ╔════════════════════════════════════════════════════════════════════════════╗
  336. ║                           LLNode_AddAtTail                                 ║
  337. ║────────────────────────────────────────────────────────────────────────────║
  338. ║  PURPOSE    :  Creates a new node and inserts as the new tail              ║
  339. ║                for example:  new data is X                                 ║
  340. ║                     before:  1 2 3 4 5 6 7 8                               ║
  341. ║                     after :  1 2 3 4 5 6 7 8 X                             ║
  342. ║  PARAMETERS :  pointer to LList definition structure                       ║
  343. ║                pointer to the data contents controlled by calling program  ║
  344. ║  RETURNS    :  none                                                        ║
  345. ║  EXAMPLE USE:  LLNode_AddAtTail ( SampleList, NewData );                   ║
  346. ╚════════════════════════════════════════════════════════════════════════════╝
  347.  
  348. ╔════════════════════════════════════════════════════════════════════════════╗
  349. ║                            LLNode_DelNode                                  ║
  350. ║────────────────────────────────────────────────────────────────────────────║
  351. ║  PURPOSE    :  Deletes contents of a given linked list node & frees mem    ║
  352. ║                for example:  DeleteNode points to 3                        ║
  353. ║                     before:  1 2 3 4 5 6 7 8                               ║
  354. ║                     after :  1 2 4 5 6 7 8                                 ║
  355. ║  PARAMETERS :  pointer to LList definition structure                       ║
  356. ║                pointer to LLNode that you wish to delete                   ║
  357. ║  RETURNS    :  none                                                        ║
  358. ║  EXAMPLE USE:  LLNode_DelNode ( SampleList, PtrData );                     ║
  359. ╚════════════════════════════════════════════════════════════════════════════╝
  360.  
  361. ╔════════════════════════════════════════════════════════════════════════════╗
  362. ║                            LLNode_DelHead                                  ║
  363. ║────────────────────────────────────────────────────────────────────────────║
  364. ║  PURPOSE    :  Deletes contents of a linked list node at head & frees mem  ║
  365. ║                for example:                                                ║
  366. ║                     before:  1 2 3 4 5 6 7 8                               ║
  367. ║                     after :  2 3 4 5 6 7 8                                 ║
  368. ║  PARAMETERS :  pointer to LList definition structure                       ║
  369. ║  RETURNS    :  none                                                        ║
  370. ║  EXAMPLE USE:  LLNode_DelHead ( SampleList );                              ║
  371. ╚════════════════════════════════════════════════════════════════════════════╝
  372.  
  373. ╔════════════════════════════════════════════════════════════════════════════╗
  374. ║                            LLNode_DelTail                                  ║
  375. ║────────────────────────────────────────────────────────────────────────────║
  376. ║  PURPOSE    :  Deletes contents of a linked list node at tail & frees mem  ║
  377. ║                for example:                                                ║
  378. ║                     before:  1 2 3 4 5 6 7 8                               ║
  379. ║                     after :  1 2 3 4 5 6 7                                 ║
  380. ║  PARAMETERS :  pointer to LList definition structure                       ║
  381. ║  RETURNS    :  none                                                        ║
  382. ║  EXAMPLE USE:  LLNode_DelTail ( SampleList );                              ║
  383. ╚════════════════════════════════════════════════════════════════════════════╝
  384.  
  385. ╔════════════════════════════════════════════════════════════════════════════╗
  386. ║                              LLNode_Swap                                   ║
  387. ║────────────────────────────────────────────────────────────────────────────║
  388. ║  PURPOSE    :  swaps/trades positions of 2 linked list NODEs               ║
  389. ║                for example:  FromNode points to 3; ToNode points to 5      ║
  390. ║                     before:  1 2 3 4 5 6 7 8                               ║
  391. ║                     after :  1 2 5 4 3 6 7 8                               ║
  392. ║  PARAMETERS :  pointer to LList definition structure                       ║
  393. ║                pointer to linked list NODE at swap location #1             ║
  394. ║                pointer to linked list NODE at swap location #2             ║
  395. ║  RETURNS    :  none                                                        ║
  396. ║  EXAMPLE USE:  LLNode_Swap ( SampleList, ThisNode, ThatNode );             ║
  397. ╚════════════════════════════════════════════════════════════════════════════╝
  398.  
  399. ╔════════════════════════════════════════════════════════════════════════════╗
  400. ║                             LLNode_Move                                    ║
  401. ║────────────────────────────────────────────────────────────────────────────║
  402. ║  PURPOSE    :  moves a linked list NODE to a new position in the list      ║
  403. ║                   in front of the TO location                              ║
  404. ║                for example:  FromNode points to 3; ToNode points to 6      ║
  405. ║                   if Where = BEFORE                                        ║
  406. ║                     before:  1 2 3 4 5 6 7 8                               ║
  407. ║                     after :  1 2 4 5 3 6 7 8                               ║
  408. ║                   if Where = AFTER                                         ║
  409. ║                     before:  1 2 3 4 5 6 7 8                               ║
  410. ║                     after :  1 2 4 5 6 3 7 8                               ║
  411. ║  PARAMETERS :  pointer to LList definition structure                       ║
  412. ║                pointer to linked list NODE at from location                ║
  413. ║                a predefined constant, either BEFORE or AFTER which         ║
  414. ║                    deterines whether the move is before or aftr the given  ║
  415. ║                    location called ToNode in this example                  ║
  416. ║                pointer to linked list NODE at to   location                ║
  417. ║  RETURNS    :  none                                                        ║
  418. ║  EXAMPLE USE:  LLNode_Move ( SampleList, MoveNode, BEFORE, ToNode );       ║
  419. ╚════════════════════════════════════════════════════════════════════════════╝
  420.  
  421. ╔════════════════════════════════════════════════════════════════════════════╗
  422. ║                            LLNode_PromoteToHead                            ║
  423. ║────────────────────────────────────────────────────────────────────────────║
  424. ║  PURPOSE    :  Moves to given node to the head position                    ║
  425. ║                for example:  MoveNode points to 3                          ║
  426. ║                     before:  1 2 3 4 5 6 7 8                               ║
  427. ║                     after :  3 1 2 4 5 6 7 8                               ║
  428. ║  PARAMETERS :  pointer to LList definition structure                       ║
  429. ║                pointer to linked list NODE to be relocated                 ║
  430. ║  RETURNS    :  none                                                        ║
  431. ║  EXAMPLE USE:  LLNode_PromoteToHead ( SampleList, MoveNode );              ║
  432. ╚════════════════════════════════════════════════════════════════════════════╝
  433.  
  434. ╔════════════════════════════════════════════════════════════════════════════╗
  435. ║                            LLNode_DemoteToTail                             ║
  436. ║────────────────────────────────────────────────────────────────────────────║
  437. ║  PURPOSE    :  Moves to given node to the tail position                    ║
  438. ║                for example:  MoveNode points to 3                          ║
  439. ║                     before:  1 2 3 4 5 6 7 8                               ║
  440. ║                     after :  1 2 4 5 6 7 8 3                               ║
  441. ║  PARAMETERS :  pointer to LList definition structure                       ║
  442. ║                pointer to linked list NODE to be relocated                 ║
  443. ║  RETURNS    :  none                                                        ║
  444. ║  EXAMPLE USE:  LLNode_DemoteToTail (SampleList, MoveNode );                ║
  445. ╚════════════════════════════════════════════════════════════════════════════╝
  446.  
  447. ╔════════════════════════════════════════════════════════════════════════════╗
  448. ║                            LLNode_FindData                                 ║
  449. ║────────────────────────────────────────────────────────────────────────────║
  450. ║  PURPOSE    :  Locates the pointer that points to a linked list NODE that  ║
  451. ║                   contains the desired data                                ║
  452. ║  PARAMETERS :  pointer to LList definition structure                       ║
  453. ║                pointer to data to be located                               ║
  454. ║                pointer to a function in the calling program that contains  ║
  455. ║                   the code to compare or calculate, etc. for the search, ie║
  456. ║                   FindPerson is your application program's function        ║
  457. ║  RETURNS    :  pointer to linked list NODE that contains desired data      ║
  458. ║  EXAMPLE USE:  strcpy ( FindMe, "Tom" );                                   ║
  459. ║                PtrTom = LLNode_FindData ( SampleList, FindMe, FindPerson );║
  460. ╚════════════════════════════════════════════════════════════════════════════╝
  461.  
  462. ╔════════════════════════════════════════════════════════════════════════════╗
  463. ║                            LLNode_FindSub                                  ║
  464. ║────────────────────────────────────────────────────────────────────────────║
  465. ║  PURPOSE    :  Locates the pointer that points to a linked list NODE that  ║
  466. ║                   is the nth node in the list; like a subscripted array    ║
  467. ║  PARAMETERS :  pointer to LList definition structure                       ║
  468. ║                nth item desired, ie. subscript index                       ║
  469. ║                   where subscripts numbers start with 1                    ║
  470. ║  RETURNS    :  pointer to linked list NODE that contains desired data      ║
  471. ║  EXAMPLE USE:  PtrNth = LLNode_FindSub ( SampleList, 4 );                  ║
  472. ╚════════════════════════════════════════════════════════════════════════════╝
  473.  
  474. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  475. ░                                 STACK FUNCTIONS                           ░
  476. ░                                                                           ░
  477. ░ Stacks are LIFO (Last In First Out) structures, so all additions are made ░
  478. ░ at the tail and all deletions are also made at the tail, just like piling ░
  479. ░ orders on a desk.  As each order comes in, it is put on the top of the    ░
  480. ░ pile, but they are worked/deleted off the top also, so the first order in ░
  481. ░ the pile/list is on the bottom and the last to be worked.                 ░
  482. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  483.  
  484. ╔════════════════════════════════════════════════════════════════════════════╗
  485. ║                                 Stack_Push                                 ║
  486. ║────────────────────────────────────────────────────────────────────────────║
  487. ║  PURPOSE    :  Creates a new node and adds it onto a stack (at the tail)   ║
  488. ║                for example:  new data is X                                 ║
  489. ║                     before:  1 2 3 4 5 6 7 8                               ║
  490. ║                     after :  1 2 3 4 5 6 7 8 X                             ║
  491. ║  PARAMETERS :  pointer to LList definition structure                       ║
  492. ║                pointer to the data contents controlled by calling program  ║
  493. ║  RETURNS    :  none                                                        ║
  494. ║  EXAMPLE USE:  Stack_Push ( SampleList, NewData );                         ║
  495. ╚════════════════════════════════════════════════════════════════════════════╝
  496.  
  497. ╔════════════════════════════════════════════════════════════════════════════╗
  498. ║                                 Stack_Pop                                  ║
  499. ║────────────────────────────────────────────────────────────────────────────║
  500. ║  PURPOSE    :  Deletes contents of a stack (from tail) and frees memory    ║
  501. ║                for example:                                                ║
  502. ║                     before:  1 2 3 4 5 6 7 8                               ║
  503. ║                     after :  1 2 3 4 5 6 7                                 ║
  504. ║  PARAMETERS :  pointer to LList definition structure                       ║
  505. ║  RETURNS    :  none                                                        ║
  506. ║  EXAMPLE USE:  Stack_Pop ( SampleList );                                   ║
  507. ╚════════════════════════════════════════════════════════════════════════════╝
  508.  
  509. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  510. ░                              QUEUE FUNCTIONS                              ░
  511. ░                                                                           ░
  512. ░  Queues are FIFO (First In First Out) structures, so all additions are    ░
  513. ░  made at the tail and all deletions are made at the head, just like being ░
  514. ░  in line at the check out counter at the grocery store.                   ░
  515. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  516.  
  517. ╔════════════════════════════════════════════════════════════════════════════╗
  518. ║                                   Que_Push                                 ║
  519. ║────────────────────────────────────────────────────────────────────────────║
  520. ║  PURPOSE    :  Creates a new node and adds it onto a stack (at the tail)   ║
  521. ║                for example:  new data is X                                 ║
  522. ║                     before:  1 2 3 4 5 6 7 8                               ║
  523. ║                     after :  1 2 3 4 5 6 7 8 X                             ║
  524. ║  PARAMETERS :  pointer to LList definition structure                       ║
  525. ║                pointer to the data contents controlled by calling program  ║
  526. ║  RETURNS    :  none                                                        ║
  527. ║  EXAMPLE USE:  Que_Push ( SampleList, NewData );                           ║
  528. ╚════════════════════════════════════════════════════════════════════════════╝
  529.  
  530. ╔════════════════════════════════════════════════════════════════════════════╗
  531. ║                                  Que_Pop                                   ║
  532. ║────────────────────────────────────────────────────────────────────────────║
  533. ║  PURPOSE    :  Deletes contents of a Queue (at the head) and frees memory  ║
  534. ║                for example:                                                ║
  535. ║                     before:  1 2 3 4 5 6 7 8                               ║
  536. ║                     after :  2 3 4 5 6 7 8                                 ║
  537. ║  PARAMETERS :  pointer to LList definition structure                       ║
  538. ║  RETURNS    :  none                                                        ║
  539. ║  EXAMPLE USE:  Que_Pop ( SampleList );                                     ║
  540. ╚════════════════════════════════════════════════════════════════════════════╝
  541.  
  542.     ERROR HANDLING:
  543.  
  544.     Upon entry to each routine, a global error handling structure, LLErr is
  545.     initialized to contain Err = NULL for no error and Routine to point  to
  546.     the  name  of  the  current  function/routine  being  executed.  During
  547.     execution of each routine, if an error occurs, the LLErr.Err is set  to
  548.     point to the  appropriate error message  and the routine  exits back to
  549.     the calling  program.   It is  the duty/responsibility  of the  calling
  550.     program to handle  the error messages  in whatever manner  it sees fit.
  551.     The routines themselves will have  no way of knowing what  your program
  552.     needs to do  in the event  of an error,  but it does  report all errors
  553.     back to the  calling program.   Immediately after your  program calls a
  554.     class library routine it can test the contents of LLErr.  If  LLErr.Err
  555.     != NULL then an error has occurred.
  556.  
  557.  
  558.     NOTES BEFORE YOU START USING LL_CLASS.OBJ FUNCTIONS IN YOUR CODE:
  559.  
  560.     LL_CLASS.OBJ was compiled with  the LARGE memory model  using Borland's
  561.     Turbo C compiler  version 2.0.   If you need  it compiled with  another
  562.     memory model, you will need the source code.
  563.  
  564.     Be sure the LL_CLASS.H file is placed in the include subdirectory where
  565.     your compiler expects it to be.
  566.  
  567.     Be sure the LL_CLASS.OBJ file  is placed in the lib  subdirectory where
  568.     your compiler expects it to be also.
  569.  
  570.     Be  sure  the  two  following  lines  are  at  the  beginning  of  your
  571.     application source code.
  572.  
  573.          #include <LL_CLASS.H>
  574.          extern    LLErr   LL_Err;          /* EXTERNal in LL_CLASS.C/OBJ */
  575.  
  576.     LList_InitErrMsg ();  must be called in your application program before
  577.     any LL_CLASS functions are used.
  578.  
  579.                              ╔══════════════════╗
  580.                              ║ COPYRIGHT NOTICE ║
  581.                              ╚══════════════════╝
  582.  
  583.     This software  product is  protected by  the United  States of  America
  584.     Copyright  law  and  also  by  International  Treaty  provisions.  This
  585.     copyright notice MUST remain with this software product.  This software
  586.     may not be circulated in any incomplete or modified form, nor sold  for
  587.     profit, without  written permission  of Dynamic  Solutions except where
  588.     otherwise allowed by this agreement.  All rights not expressly  granted
  589.     here are reserved to Dynamic Solutions.
  590.  
  591.  
  592.                           ╔════════════════════════╗
  593.                           ║ REGISTRATION AGREEMENT ║
  594.                           ╚════════════════════════╝
  595.  
  596.     You are hereby allowed to
  597.  
  598.          1- use the Shareware Version of this software for a 10 day
  599.             evaluation period to determine if it is suitable for your
  600.             purposes (try before you buy)
  601.  
  602.          2- make as many copies of the Shareware Version of this software
  603.             and documentation as you wish
  604.  
  605.          3- give exact copies of the original Shareware Version to anyone
  606.  
  607.          4- distribute the Shareware Version of the software and
  608.             documentation in its unmodified form via electronic means.
  609.  
  610.     There is  no charge  for any  of the  above activities,  however if you
  611.     distribute this software to others, you are required to distribute  the
  612.     ENTIRE package consisting  of the files  as listed at  the top of  this
  613.     document.
  614.  
  615.     You are specifically prohibited from charging, or requesting donations,
  616.     for  any  such  copies,  however  made,  with  the exception of nominal
  617.     charges for download or disk  media and handling charges not  to exceed
  618.     $9.00.  You are specifically prohibited from distributing the  software
  619.     and/or  documentation  bundled  with  other  products  (commercial   or
  620.     otherwise) without prior written permission.
  621.  
  622.     Unregistered use of this software after the 10 day evaluation period is
  623.     in  violation  of  federal  copyright  laws.   This registration is not
  624.     transferrable.  This is  a good-faith registration agreement  dependent
  625.     upon  your  honesty.    Dynamic  Solutions  is trusting you to not take
  626.     advantage of us and therefore to not redistribute this material  except
  627.     by our terms herein stated on a good-faith basis.
  628.  
  629.  
  630.  
  631.     THIS IS NOT FREE  SOFTWARE.  THIS IS  NOT PUBLIC DOMAIN SOFTWARE.   You
  632.     are allowed to use this software for evaluation purposes without charge
  633.     for a period  of 10 days.   If you  use this software  after the 10 day
  634.     evaluation  period,  by  doing  so  you  have  agreed  to the terms and
  635.     conditions  stated  herein  and  the  requested  registration  fee   is
  636.     required.   Payments must  be in  US dollars  drawn on  a US  bank, and
  637.     should be sent to ───
  638.  
  639.                               Dynamic Solutions
  640.                               Rt 1, Box 185
  641.                               Osage City, KS 66523-9744
  642.  
  643.     One registered copy may either be used by a single person who uses  the
  644.     software personally on one or more computers, or installed on a  single
  645.     workstation used nonsimultaneously by multiple people, but not both.
  646.  
  647.     This agreement shall be governed by the laws of the State of Kansas.
  648.  
  649.     Payment of  the requested  registration fee  for this  product verifies
  650.     that the user has agreed to these terms and makes the user eligible for
  651.     support and for being  notified of any upgrades  to the product and  of
  652.     any new additional products produced by Dynamic Solutions.  Credit card
  653.     ordering and quantity discounts are NOT available at this time.
  654.  
  655.  
  656.                                 ╔════════════╗
  657.                                 ║ DISCLAIMER ║
  658.                                 ╚════════════╝
  659.  
  660.     Following true  professional programming  procedures, this  product has
  661.     been extensively tested  in various environments  and is "bug-free"  to
  662.     the best of our knowledge.
  663.  
  664.     This software and the accompanying  files are sold "AS IS"  and without
  665.     warranties as to performance or merchantability or any other warranties
  666.     whether expressed  or implied.   Because  of the  various hardware  and
  667.     software environments into which this  product may be put, no  warranty
  668.     of fitness for a particular purpose is offered.
  669.  
  670.     Good, professional data processing procedure dictates that any  program
  671.     be thoroughly tested with non-critical  data before relying on it.  The
  672.     user must assume the  entire risk of using  the software.  In  NO event
  673.     shall Dynamic Solutions be liable for any loss of profits or any  other
  674.     commercial damage,  including but  not limited  to special, incidental,
  675.     consequential or other damages.
  676.  
  677.     Because  some  states  or  countries  do  not  allow  the  exclusion or
  678.     limitation of  liability for  consequential or  incidental damages,  no
  679.     permission for use of our products  will be granted in those states  or
  680.     countries but donations would be appreciated.
  681.  
  682.     In order  to legally  use this  product for  any purpose  other than to
  683.     evaluate  it,  you  must  register  it  with  Dynamic  Solutions.  Upon
  684.     registration, you  will receive  support, upgrade  notices, new product
  685.     notifications, and,  if ordered,  the complete,  well-documented source
  686.     code.  Fill out the following and return it with your registration  fee
  687.     (and source code fee if desired) to ───
  688.                                          ╔════════════════════╗
  689.                                          ║DYNAMIC SOLUTIONS   ║
  690.                                          ║Rt 1, Box 185       ║
  691.                                          ║Osage City, KS 66523║
  692.                                          ╚════════════════════╝
  693.                                     ┌────────────┐    ┌────────────┐
  694.          Circle desired package ──> │   PKG #1   │    │   PKG #2   │
  695.                                     ├────────────┤    ├────────────┤
  696.                                     │LL_CLASS.OBJ│    │LL_CLASS.OBJ│
  697.                                     │LL_CLASS.H  │    │LL_CLASS.H  │
  698.                                     │LL_CLASS.DOC│    │LL_CLASS.DOC│
  699.                                     │LL_TEST.EXE │    │LL_TEST.EXE │
  700.                                     │LL_TEST.PRJ │    │LL_TEST.PRJ │
  701.                                     │            │    │LL_CLASS.C  │
  702.                                     │            │    │LL_TEST.C   │
  703.                                     ├────────────┤    ├────────────┤
  704.          SHIPPING & HANDLING        │  $  4.00   │    │  $  4.00   │
  705.          REGISTRATION FEE           │  $ 15.00   │    │  $ 15.00   │
  706.          SOURCE CODE  FEE           │            │    │  $ 10.00   │
  707.                                     ├────────────┤    ├────────────┤
  708.          TOTAL DUE                  │  $ 19.00   │    │  $ 29.00   │
  709.                                     ├────────────┤    ├────────────┤
  710.          KANSAS RESIDENTS ONLY      │            │    │            │
  711.             SALES TAX               │  $   .89   │    │  $  1.71   │
  712.             TOTAL DUE               │  $ 19.89   │    │  $ 30.71   │
  713.                                     └────────────┘    └────────────┘
  714.                                              ┌─────────────┐
  715.                                              │             │
  716.                              AMOUNT ENCLOSED │$            │
  717.                                              └─────────────┘
  718.     ┌──────────┬─────────────────────────────────────────────────────────┐
  719.     │          │                                                         │
  720.     │ NAME     │                                                         │
  721.     ├──────────┼─────────────────────────────────────────────────────────┤
  722.     │          │                                                         │
  723.     │ COMPANY  │                                                         │
  724.     ├──────────┼─────────────────────────────────────────────────────────┤
  725.     │          │                                                         │
  726.     │ ADDRESS  │                                                         │
  727.     ├──────────┼──────────────────────────────────────┬──────────────────┤
  728.     │          │                                      │                  │
  729.     │ CITY, ST │                                      │ ZIP              │
  730.     ├──────────┼──────────────────────────────────────┼──────────────────┤
  731.     │          │                                      │                  │
  732.     │ PHONE    │                                      │DISK MEDIA DESIRED│
  733.     ├──────────┴─────────────────┬────────────────────┤   (Circle one)   │
  734.     │                            │                    │                  │
  735.     │ VERSION YOU CURRENTLY HAVE │                    │  3.5"    5.25"   │
  736.     ├────────────────────────────┴────────────────────┴──────────────────┤
  737.     │                                                                    │
  738.     │ COMMENTS (We value your opinions and suggestions.)                 │
  739.     │                                                                    │
  740.  
  741.