home *** CD-ROM | disk | FTP | other *** search
/ World of Shareware - Software Farm 2 / wosw_2.zip / wosw_2 / CPROG / VISIONS.ZIP / VIS_LIST.TXT < prev    next >
Text File  |  1990-05-20  |  23KB  |  680 lines
  1. /*------------------------ VIS_LIST.TXT ------------------------*/
  2. /*                                                              */
  3. /*  This file contains the VISIONS List Library Manual          */
  4. /*                                                              */
  5. /*         Copyright 1990 Dan Vogel & David Bernazzani          */
  6. /*                                                              */
  7. /*   Date        Initials        Comments                       */
  8. /*                                                              */
  9. /*  03/13/90       DCV       Initial Release 0.00.              */
  10. /*--------------------------------------------------------------*/
  11.  
  12.                         Overview
  13.  
  14.  
  15.    The VISIONS list library is a simple library, written in C, to 
  16. provide generic list handling on PC/XT/AT class machines.  The library was 
  17. originally written in Microsoft C 5.1.  The VISIONS list library uses 
  18. the VISIONS Window library.
  19.    The list library, although simple, provides the programmer an easy way 
  20. of handling lists of any type of data structure.  The list library provides 
  21. the programmer with the ability to create lists, sort lists, add items to 
  22. lists, remove items from lists, and display list items.  All this is done 
  23. with a minimum of programmer knowledge of the actual structure of the list.  
  24. In fact, the definition of the list structure is not made available to the 
  25. library user, in order to abstract away these complications.
  26.  
  27.  
  28.  
  29.  
  30.                         Theory of Operation
  31.  
  32.  
  33.    While it is not necessary for the programmer to know the details of the 
  34. list structure, a brief description of this structure will help to explain 
  35. some of the list routines.  A list is composed of three separate structures 
  36. in VISIONS, a list head, list links, and list elements.  A list head is used 
  37. to define the start of a list as well as some of the operations that may be 
  38. performed upon this list.  A list link is a pointer structure used to connect 
  39. list elements together in a doubly linked chain.  Finally a list element is 
  40. the data of which the programmer wishes to create a list.  The list 
  41. element(s) may be any type of data, although all data is treated as an 
  42. unsigned character pointer by VISIONS.  The list head and list links 
  43. are never directly manipulated by the programmer, only by VISIONS, although 
  44. the programmer must keep a pointer reference to define the list he wishes to 
  45. operate upon at any given time.  A list might appear as below:
  46.  
  47.    LIST_HEAD:
  48.    +------------+
  49.    |List delete |
  50.    |List compare|
  51.    |List display|
  52.    |List Pointer|-----+
  53.    +------------+     |  LIST_LINK:         LIST_LINK:
  54.                       +->+--------+         +--------+
  55.                          |Next    |-------->|Next    |----> etc.
  56.                   NULL<--|Last    |<--------|Last    |
  57.                          |Element |--+      |Element |--+
  58.                          +--------+  |      +--------+  |
  59.                                      |                  |
  60.                                      |  ELEMENT:        |  ELEMENT:
  61.                                      +->+------+        +->+------+
  62.                                         |"One" |           |"Two" |
  63.                                         +------+           +------+
  64.  
  65.   Storage for list heads and list links is allocated from the heap.  Thus 
  66. a list's maximum length is bounded by the availability of heap storage, 
  67. not by the size of any preallocated array.  Since list links may be 
  68. frequently allocated and deallocated, the VISIONS list library performs its 
  69. own garbage collection for list links.  This allows previously allocated and 
  70. deallocated list links to be reused without be returned to the heap.  This 
  71. helps prevents extreme memory fragmentation.
  72.    The following is a brief overview of the operation of the list 
  73. library routines.  This is intended to help the user to understand 
  74. the library's operation better, so that it may be used more effectively.  
  75. One key point to remember in reviewing these routines is that list elements 
  76. are almost always manipulated by list link pointers, not by pointers to the 
  77. actual list elements.  As an example, using the VISIONS routine ListTop of 
  78. the above list structure would return a pointer to the first list link (which 
  79. in turn points to the first element "One"), not to the the first list 
  80. element.  Once your list manipulation is complete, you may recover your list 
  81. element data by using the routine GetListItem.  This abstracts list 
  82. manipulation apart from data manipulation.
  83.  
  84.    The VISIONS list system is intended to create and use lists of any type 
  85. of items.  List functions may be broken up into the following groups.
  86.  
  87.    List Definition:
  88.         DefineList - Define a list header with operations that may be
  89.                      performed on the list.
  90.  
  91.    List Building:
  92.         AddToList  -   Add an element to the list before the passed list 
  93.                        link pointer.
  94.         AppendToList - Append a new element to th eend of the list.
  95.  
  96.    List Item Selection:
  97.         FindInList - Find the list link associated with a list element.
  98.         ListBottom - Return pointer to list link at end of list.
  99.         ListLast   - Return pointer to list link preceeding passed link.
  100.         ListNext   - Return pointer to list link following passed link.
  101.         ListNth    - Return pointer to nth list link in list.
  102.         ListTop    - Return poiinter to list link at start of list.
  103.  
  104.    List Display:
  105.         DisplayList     - Display all elements in passed list in the 
  106.                           define window, as formatted by list display 
  107.                           routine.
  108.         DisplayListItem - Format a list element into a buffer for display.
  109.  
  110.    List Deletion:
  111.         DeleteList     - Delete a list and all of its contents.
  112.         DeleteFromList - Delete a list link and it element from its list.
  113.  
  114.    List Miscellaneous:
  115.         CountList      - Count the number of elements in the passed list.
  116.         GetListItem    - Return a pointer to the list element held by the 
  117.                          passed list link.
  118.         RemoveFromList - Remove a list link and its element from its list 
  119.                          without deleting the element.  The link is returned 
  120.                          to free memory.
  121.         SortList       - Sort a list according to a passed comparison 
  122.                          routine.
  123.  
  124.  
  125.   The next section defines these routines in greater detail.
  126.  
  127.  
  128.  
  129.                         Routine Definitions
  130.  
  131.    In order to use the below routines you must include the file 
  132. "USERLIST.H" in your source code with the following statement.
  133.  
  134.                 #include "USERLIST.H"
  135.  
  136. This will automatically include the window definitions files at the 
  137. same time.  Examples of the use of these routines are available in the 
  138. VISIONS demonstration program, in the file DEMOLIST.C.
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145. /*------------------------------------------------------------------------*/
  146.                         AddToList
  147.  
  148. Purpose:  This routine inserts a new item into the current list before 
  149.   the list item pointer passed.
  150.  
  151. Calling Sequence: 
  152.    status = AddToList(list_root, list_ptr, new_item);
  153.  
  154. Inputs:
  155.    LIST_HEAD *list_root;  - This is the head of the list added to.
  156.  
  157.    LIST_LINK *list_ptr;  - This is a pointer to insert the item before.
  158.  
  159.    unsigned char *new_item;  - This is a pointer to the item to be inserted 
  160.  in the list.
  161.  
  162. Outputs:
  163.    int status;  - This is the result of the function.  Possible values are:
  164.         0               Success
  165.         BAD_HEAD_PTR    Pointer to list passed is invalid.
  166.         BAD_LINK_PTR    Pointer to link passed is invalid.
  167.         <others>        As returned by called routines.
  168.  
  169. Functions called:
  170.    AllocateLink.
  171.  
  172. /*------------------------------------------------------------------------*/
  173.  
  174.  
  175.  
  176.  
  177. /*------------------------------------------------------------------------*/
  178.                         AppendToList
  179.  
  180. Purpose:  This routine adds an item to the end of the list.
  181.  
  182. Calling Sequence: 
  183.    status = AppendToList(list_top, new_item);
  184.  
  185. Inputs:
  186.    LIST_HEAD *list_top;  - This is a pointer to the head of the list to 
  187. append to.
  188.  
  189.    unsigned char *new_item;  - This is the item to be appended to the list.
  190.  
  191. Outputs:
  192.    int status;  - This is the result of the function.  Possible values are:
  193.         0               Success
  194.         BAD_HEAD_PTR    Pointer to list passed is invalid.
  195.         <others>        As returned by called routines.
  196.  
  197. Functions called:
  198.    AllocateLink.
  199.  
  200. /*------------------------------------------------------------------------*/
  201.  
  202.  
  203.  
  204.  
  205. /*------------------------------------------------------------------------*/
  206.                         CountList
  207.  
  208. Purpose:  This routine passes back a count of items in the passed list.
  209.  
  210. Calling Sequence: 
  211.    status = CountList(list_ptr);
  212.  
  213. Inputs:
  214.    LIST_HEAD *list_ptr;  - This is a pointer to the list head to be counted.
  215.  
  216. Outputs:
  217.    int status;  - This is the result of the function.  Possible values are:
  218.         >=0             Success, this is the count of items in the list.
  219.         BAD_HEAD_PTR    Pointer to list passed is invalid.
  220.         <others>        As returned by called routines.
  221.  
  222. Functions called:
  223.    ListTop, ListNext.
  224.  
  225. /*------------------------------------------------------------------------*/
  226.  
  227.  
  228.  
  229.  
  230. /*------------------------------------------------------------------------*/
  231.                         DefineList
  232.  
  233. Purpose:  This routine initializes a new list structure, and allocates 
  234.   space for it.
  235.  
  236. Calling Sequence: 
  237.    status =  DefineList(new_list,compare_f,delete_f,display_f);
  238.  
  239. Inputs:
  240.    The following three functions are passed to this routine to be stored 
  241. as part of the list defining the operations that can be performed on this 
  242. list.  These operations include comparing two items in the list, deleting 
  243. a list item, and generating a displayable buffer from a list item.
  244.  
  245.    int (*compare_f)(unsigned char *,unsigned char *);
  246.    int (*delete_f)(unsigned char *);
  247.    int (*display_f)(unsigned char *,char *);
  248.  
  249. Outputs:
  250.    LIST_HEAD **new_list;  - This is the head of the new list created.
  251.  
  252.    int status;  - This is the result of the function.  Possible values are:
  253.            0            Success
  254.         <Others>        As returned by called routines.
  255.  
  256. Functions called:
  257.    AllocateList.
  258.  
  259. /*------------------------------------------------------------------------*/
  260.  
  261.  
  262.  
  263.  
  264. /*------------------------------------------------------------------------*/
  265.                         DeleteFromList
  266.  
  267. Purpose:  This routine removes a link from a list, releases the link to 
  268.   the free link list, and passes the link's item pointer to the list delete 
  269.   routine.
  270.  
  271. Calling Sequence: 
  272.    status = DeleteFromList(list_ptr, remove_item);
  273.  
  274. Inputs:
  275.    LIST_HEAD *list_ptr;  - This is a pointer to the list to remove the 
  276.         item from.
  277.  
  278.    unsigned char *remove_item;  - This is a pointer to the item to be deleted
  279.         from the list.
  280.  
  281. Outputs:
  282.    int status;  - This is the result of the function.  Possible values are:
  283.         0               Success
  284.         BAD_HEAD_PTR    Pointer to list passed is invalid.
  285.         <others>        As returned by called routines.
  286.  
  287. Functions called:
  288.    FindInList,  <list delete routine>.
  289.  
  290. /*------------------------------------------------------------------------*/
  291.  
  292.  
  293.  
  294.  
  295. /*------------------------------------------------------------------------*/
  296.                         DeleteList
  297.  
  298. Purpose:  This routine deletes an entire list, releasing its storage 
  299.  back to the heap.
  300.  
  301. Calling Sequence: 
  302.    status = DeleteList(del_list);
  303.  
  304. Inputs:
  305.    LIST_HEAD *del_list;  - This is a pointer to the list to be 
  306.         deleted.
  307.  
  308. Outputs:
  309.    int status;  - This is the result of the function.  Possible values are:
  310.         0               Success
  311.         BAD_HEAD_PTR    Pointer to list passed is invalid.
  312.         <others>        As returned by called routines.
  313.  
  314. Functions called:
  315.    ListTop,  DeleteFromList.
  316.  
  317. /*------------------------------------------------------------------------*/
  318.  
  319.  
  320.  
  321.  
  322. /*------------------------------------------------------------------------*/
  323.                         DisplayList
  324.  
  325. Purpose:  This routine displays the passed list in the specified window.
  326.  
  327. Calling Sequence: 
  328.    status = DisplayList(topy, col, height, width, bkcol, txtcol, border, 
  329.                 title, d_list)
  330.  
  331. Inputs:
  332.    BYTE topy, col, height, width;  - These are the coordinates of the window 
  333.         in which to display the list.
  334.  
  335.    long int bkcol, txtcol;  - These are the colors to use for the window.
  336.  
  337.    BYTE border;  - This is the border type to use (NOBORDER,SINGLEBORDER,
  338.         or DOUBLEBORDER).
  339.  
  340.    char *title;  - This is the title to display in the window (or NULL).
  341.  
  342.    LIST_HEAD *d_list;  - This is a pointer to the list to be displayed.
  343.  
  344. Outputs:
  345.    int status;  - This is the result of the function.  Possible values are:
  346.         0               Success
  347.         BAD_HEAD_PTR    Pointer to list passed is invalid.
  348.         <others>        As returned by called routines.
  349.  
  350. Functions called:
  351.    DefineWindow,  DisplayWindow,  ListTop,  ListNext,  DisplayListItem,  
  352.    WindMesg,  RemoveWindow,  DeleteWindow.
  353.  
  354. /*------------------------------------------------------------------------*/
  355.  
  356.  
  357.  
  358.  
  359. /*------------------------------------------------------------------------*/
  360.                         DisplayListItem
  361.  
  362. Purpose:  This routine generates a displayable buffer of the item in the 
  363.  passed list link pointer using the list's display routine.
  364.  
  365. Calling Sequence: 
  366.    status = DisplayListItem(list_ptr, disp_link, buffer);
  367.  
  368. Inputs:
  369.    LIST_HEAD *list_ptr;  - This is the list containing the item to be 
  370.         displayed.
  371.  
  372.    LIST_LINK *disp_link;  - This is the link of the item to be displayed.
  373.  
  374. Outputs:
  375.    char *buffer;  - This is the buffer in which the displayable string 
  376.         is placed.
  377.  
  378.    int status;  - This is the result of the function.  Possible values are:
  379.         0               Success
  380.         BAD_HEAD_PTR    Pointer to list passed is invalid.
  381.         BAD_LINK_PTR    Pointer to link passed is invalid.
  382.         <others>        As returned by called routines.
  383.  
  384. Functions called:
  385.    <list display function>
  386.  
  387. /*------------------------------------------------------------------------*/
  388.  
  389.  
  390.  
  391.  
  392. /*------------------------------------------------------------------------*/
  393.                         FindInList
  394.  
  395. Purpose:  This routine finds the list pointer in a list that holds the 
  396.  passed item pointer.
  397.  
  398. Calling Sequence: 
  399.    status = FindInList(list_ptr, find_item, list_fnd);
  400.  
  401. Inputs:
  402.    LIST_HEAD *list_ptr;  - This is the list to be searched.
  403.  
  404.    unsigned char *find_item;  - This is the item to be found.
  405.  
  406. Outputs:
  407.    LIST_LINK **list_fnd;  - This is a pointer to the pointer to the 
  408.         found item.
  409.  
  410.    int status;  - This is the result of the function.  Possible values are:
  411.         0                       Success
  412.         LIST_ITEM_NOT_FOUND     Didn't find the item in the list.
  413.         BAD_HEAD_PTR            Pointer to list passed is invalid.
  414.         <others>                As returned by called routines.
  415.  
  416. Functions called:
  417.    ListTop,  ListNext.
  418.  
  419. /*------------------------------------------------------------------------*/
  420.  
  421.  
  422.  
  423.  
  424. /*------------------------------------------------------------------------*/
  425.                         GetListItem
  426.  
  427. Purpose:  This routine returns a pointer to the item contained in the passed 
  428.  list link.
  429.  
  430. Calling Sequence: 
  431.    status = GetListItem(list_ptr, new_item);
  432.  
  433. Inputs:
  434.    LIST_LINK *list_ptr;  - This is a pointer to the list link to get the 
  435.         item pointer from.
  436.  
  437. Outputs:
  438.    unsigned char **new_item;  - This is a pointer to the pointer to hold the
  439.         returned item pointer.
  440.  
  441.    int status;  - This is the result of the function.  Possible values are:
  442.         0               Success
  443.         BAD_LINK_PTR    Pointer to link passed is invalid.
  444.         <others>        As returned by called routines.
  445.  
  446. Functions called:
  447.    None.
  448.  
  449. /*------------------------------------------------------------------------*/
  450.  
  451.  
  452.  
  453.  
  454. /*------------------------------------------------------------------------*/
  455.                         ListBottom
  456.  
  457. Purpose:  This routine passes back a pointer to the last link in the
  458.   passed list.
  459.  
  460. Calling Sequence: 
  461.    status = ListBottom(list_ptr, bot_link);
  462.  
  463. Inputs:
  464.    LIST_HEAD *list_ptr;  - This is a pointer to the list head.
  465.  
  466. Outputs:
  467.    LIST_LINK **bot_link;  - This is the returned pointer to the last
  468.         element of the passed list.
  469.  
  470.    int status;  - This is the result of the function.  Possible values are:
  471.         0               Success
  472.         BAD_HEAD_PTR    Pointer to list passed is invalid.
  473.         <others>        As returned by called routines.
  474.  
  475. Functions called:
  476.    ListTop, ListNext.
  477.  
  478. /*------------------------------------------------------------------------*/
  479.  
  480.  
  481.  
  482.  
  483. /*------------------------------------------------------------------------*/
  484.                         ListLast
  485.  
  486. Purpose:  This routine passes back a pointer to the previous link in the
  487.   passed list.
  488.  
  489. Calling Sequence: 
  490.    status = ListLast(curr_link, last_link);
  491.  
  492. Inputs:
  493.    LIST_LINK *curr_link;  - This is a pointer to the current link.
  494.  
  495. Outputs:
  496.    LIST_LINK **last_link;  - This is the returned pointer to the link 
  497.         preceeding the current link.
  498.  
  499.    int status;  - This is the result of the function.  Possible values are:
  500.         0               Success
  501.         BAD_LINK_PTR    Pointer to link passed is invalid.
  502.         <others>        As returned by called routines.
  503.  
  504. Functions called:
  505.    None.
  506.  
  507. /*------------------------------------------------------------------------*/
  508.  
  509.  
  510.  
  511.  
  512. /*------------------------------------------------------------------------*/
  513.                         ListNext
  514.  
  515. Purpose:  This routine passes back a pointer to the next link in the
  516.   passed list.
  517.  
  518. Calling Sequence: 
  519.    status = ListNext(curr_link, next_link);
  520.  
  521. Inputs:
  522.    LIST_LINK *curr_link;  - This is a pointer to the current link.
  523.  
  524. Outputs:
  525.    LIST_LINK **next_link;  - This is the returned pointer to the link 
  526.         following the current link.
  527.  
  528.    int status;  - This is the result of the function.  Possible values are:
  529.         0               Success
  530.         BAD_LINK_PTR    Pointer to link passed is invalid.
  531.         <others>        As returned by called routines.
  532.  
  533. Functions called:
  534.    None.
  535.  
  536. /*------------------------------------------------------------------------*/
  537.  
  538.  
  539.  
  540.  
  541. /*------------------------------------------------------------------------*/
  542.                         ListNth
  543.  
  544. Purpose:  This routine passes back a pointer to the nth link in the
  545.   passed list, where n ranges from 0 to the number of items in the list 
  546.   minus 1.
  547.  
  548. Calling Sequence: 
  549.    status = ListNth(list_ptr, list_num, ret_link);
  550.  
  551. Inputs:
  552.    LIST_HEAD *list_ptr;  - This is a pointer to the list head.
  553.  
  554.    int list_num;  - This is the number of the desired item in the list.
  555.  
  556. Outputs:
  557.    LIST_LINK **ret_link;  - This is the returned pointer to the nth element.
  558.  
  559.    int status;  - This is the result of the function.  Possible values are:
  560.         0               Success
  561.         LIST_TOO_SHORT  List is not long enough!
  562.         BAD_HEAD_PTR    Pointer to list passed is invalid.
  563.         <others>        As returned by called routines.
  564.  
  565. Functions called:
  566.    ListTop,  ListNext.
  567.  
  568. /*------------------------------------------------------------------------*/
  569.  
  570.  
  571.  
  572.  
  573. /*------------------------------------------------------------------------*/
  574.                         ListTop
  575.  
  576. Purpose:  This routine passes back a pointer to the first link in the
  577.   passed list.
  578.  
  579. Calling Sequence: 
  580.    status = ListTop(list_ptr, top_link);
  581.  
  582. Inputs:
  583.    LIST_HEAD *list_ptr;  - This is a pointer to the list head.
  584.  
  585. Outputs:
  586.    LIST_LINK **top_link;  - This is the returned pointer to the first
  587.         element of the passed list.
  588.  
  589.    int status;  - This is the result of the function.  Possible values are:
  590.         0                Success
  591.         BAD_HEAD_PTR     Pointer to list passed is invalid.
  592.  
  593. Functions called:
  594.    None.
  595.  
  596. /*------------------------------------------------------------------------*/
  597.  
  598.  
  599.  
  600.  
  601. /*------------------------------------------------------------------------*/
  602.                         RemoveFromList
  603.  
  604. Purpose:  This routine removes a link from a list, and releases the link to 
  605.   the free link list.
  606.  
  607. Calling Sequence: 
  608.    status = RemoveFromList(list_ptr, remove_item);
  609.  
  610. Inputs:
  611.    LIST_HEAD *list_ptr;  - This is a pointer to the list to remove the 
  612.         item from.
  613.  
  614.    unsigned char *remove_item;  - This is a pointer to the item to be 
  615.         removed from the list.
  616.  
  617. Outputs:
  618.    int status;  - This is the result of the function.  Possible values are:
  619.         0               Success
  620.         BAD_HEAD_PTR    Pointer to list passed is invalid.
  621.         <others>        As returned by called routines.
  622.  
  623. Functions called:
  624.    FindInList.
  625.  
  626. /*------------------------------------------------------------------------*/
  627.  
  628.  
  629.  
  630.  
  631. /*------------------------------------------------------------------------*/
  632.                         SortList
  633.  
  634. Purpose:  This routine does a bubble sort of the passed list based upon the 
  635.  passed comparison function.
  636.  
  637. Calling Sequence: 
  638.    status = SortList(list_ptr,compare_f);
  639.  
  640. Inputs:
  641.    LIST_HEAD *list_ptr;  - This is a pointer to the list head to be sorted.
  642.  
  643.    int (*compare_f)(unsigned char *,unsigned char *);  - This is the 
  644.         comparison function to be used in the sort.  It must return 
  645.         <0 if first argument should preceed second, =0 for two items are 
  646.         equal, and >0 for first item should follow second.
  647.  
  648. Outputs:
  649.    int status;  - This is the result of the function.  Possible values are:
  650.         0                Success
  651.         BAD_HEAD_PTR     Pointer to list passed is invalid.
  652.  
  653. Functions called:
  654.    ListTop,  ListNext,  <passed comparison function>
  655.  
  656. /*------------------------------------------------------------------------*/
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.                         Error Codes
  664.  
  665.    The following is the list of error codes that can be returned from the 
  666. VISIONS list library.  Errors from calls to the windows library will be 
  667. passed back unchanged.  These error values can be found in the VISIONS 
  668. window manual.
  669.  
  670. Error Name              Value       Description.
  671.  
  672. BAD_LINK_PTR             -11        Pointer to list link is bad.
  673. BAD_HEAD_PTR             -12        Pointer to list head is bad.
  674.  
  675. UNABLE_TO_ALLOCATE_LINK  -21        Out of heap for link allocation.
  676. UNABLE_TO_ALLOCATE_LIST  -22        Out of heap for head allocation.
  677. LIST_TOO_SHORT           -23        List is shorter than needed item number.
  678. LIST_ITEM_NOT_FOUND      -24        Item not found in passed list.
  679.  
  680.