home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / code / desklib / !DeskLib / h / LinkList < prev    next >
Encoding:
Text File  |  1994-05-29  |  5.1 KB  |  149 lines
  1. /*
  2.     ####             #    #     # #
  3.     #   #            #    #       #          The FreeWare C library for 
  4.     #   #  ##   ###  #  # #     # ###             RISC OS machines
  5.     #   # #  # #     # #  #     # #  #   ___________________________________
  6.     #   # ####  ###  ##   #     # #  #                                      
  7.     #   # #        # # #  #     # #  #    Please refer to the accompanying
  8.     ####   ### ####  #  # ##### # ###    documentation for conditions of use
  9.     ________________________________________________________________________
  10.  
  11.     File:    LinkList.h
  12.     Author:  Copyright © 1992 John Winters
  13.     Version: 1.33 (30 May 1994)
  14.     Purpose: Linked list management routines
  15. */
  16.  
  17.  
  18. #ifndef __dl_linklist_h
  19. #define __dl_linklist_h
  20.  
  21. #ifndef __dl_core_h
  22. #include "Core.h"
  23. #endif
  24.  
  25.  
  26. /*  Implementation notes
  27.  *  ====================
  28.  *  This module provides support for a linked list structure.
  29.  *  YOU must supply an anchor for the list (a variable of type
  30.  *  linklist_header). This is used to record pointers to the start and end
  31.  *  of the list.
  32.  *  The list itself is made up of your own structures, defined as follows:
  33.  *    struct listelement
  34.  *    {
  35.  *      linklist_header header;
  36.  *      ... Your own data here ...
  37.  *    } listelement;
  38.  *
  39.  *  a list-terminating pointer is represented as NULL
  40.  *
  41.  *  The header's next field stores a pointer to the FIRST item
  42.  *           its previous field stores a pointer to the LAST item
  43.  *           (both these pointers will be nulls if the list is empty)
  44.  *
  45.  *  To insert items into the list, you must malloc memory for one of your
  46.  *  own listelement data structures, then call the appropriate function
  47.  *  To delete an item from the list, call the unlink function, and then free
  48.  *  all memory used by your structure.
  49.  */
  50.  
  51.  
  52. typedef struct linklist_header
  53. {
  54.   struct linklist_header *next;
  55.   struct linklist_header *previous;
  56. } linklist_header ;
  57.  
  58.  
  59.  
  60.   /*  Add an item to a linked list- at head or tail of list.
  61.    *    AddToHead inserts the given item at the head of the list
  62.    *    AddToTail inserts the given item at the end of the list
  63.    *
  64.    *    InsertBefore inserts the given item BEFORE the item "pos"
  65.    *    InsertAfter inserts the given item AFTER the item "pos"
  66.    */
  67. extern void LinkList_AddToHead(linklist_header *anchor, linklist_header *item);
  68. extern void LinkList_AddToTail(linklist_header *anchor, linklist_header *item);
  69. extern void LinkList_InsertBefore(linklist_header *anchor,
  70.                                   linklist_header *pos,
  71.                                   linklist_header *item);
  72. extern void LinkList_InsertAfter(linklist_header *anchor,
  73.                                  linklist_header *pos,
  74.                                  linklist_header *item);
  75.  
  76.  
  77.   /*  LinkList_InList
  78.    *  Returns TRUE if the item is curently in the list. Note that this does
  79.    *  NOT check item contents, merely compares item pointers.
  80.    *  To check item contents, you must chain through the list yourself.
  81.    */
  82. extern BOOL LinkList_InList(linklist_header *anchor, linklist_header *item);
  83.  
  84.  
  85.   /*  LinkList_ListLength
  86.    *  Returns the number of items in the list. It follows all the links
  87.    *  and counts them... if you need this value a lot, I suggest you modify
  88.    *  LinkList to keep a count in the anchor...
  89.    */
  90. extern int LinkList_ListLength(linklist_header *anchor);
  91.  
  92.  
  93.  
  94.   /*  LinkList_Unlink
  95.    *  Unlinks the item "item" from the given list.
  96.    *  You must then free the memory used by it yourself.
  97.    */
  98. extern void LinkList_Unlink(linklist_header *anchor, linklist_header *item);
  99.  
  100.  
  101.   /*  Return pointers to the first/last item in the list
  102.    *    extern void *LinkList_FirstItem(linklist_header *anchor);
  103.    *    extern void *LinkList_LastItem(linklist_header *anchor);
  104.    */
  105. #define LinkList_FirstItem(x) ((void *)(x)->next)
  106. #define LinkList_LastItem(x) ((void *)(x)->previous)
  107.  
  108.  
  109.   /*  LinkList_Init
  110.    *  Initialises a list anchor. Should be called before anchor used
  111.    *    extern void LinkList_Init(linklist_header *item);
  112.    */
  113. #define LinkList_Init(x)  \
  114.   {                       \
  115.     (x)->next = NULL;     \
  116.     (x)->previous = NULL; \
  117.   }
  118.  
  119.  
  120.   /*  LinkList_InitItem
  121.    *  Initialises a list item. Should be called before item used,
  122.    *  except when that item is immediately linked into a list
  123.    *    extern void LinkList_InitItem(linklist_header *item);
  124.    */
  125. #define LinkList_InitItem(x) \
  126.   {                          \
  127.     (x)->next = NULL;        \
  128.     (x)->previous = NULL;    \
  129.   }
  130.  
  131.  
  132.   /*  Return the next/previous item of a given one. If the current item is at
  133.    *  the head/tail of the list, NULLPOINTER will be returned.
  134.    *    extern void *LinkList_NextItem(linklist_header *item);
  135.    *    extern void *LinkList_PreviousItem(linklist_header *item);
  136.    *
  137.    *  Old definitions:
  138.    *    #define LinkList_NextItem(x) ((void *)(x)->next)
  139.    *    #define LinkList_PreviousItem(x) ((void *)(x)->previous)
  140.    *
  141.    *  NEW definitions:
  142.    *    you can now use   LinkList_NextItem(&item);
  143.    *    instead of        LinkList_NextItem(&item->header);
  144.    */
  145. #define LinkList_NextItem(x) ((void *) ((linklist_header *)(x))->next)
  146. #define LinkList_PreviousItem(x) ((void *) ((linklist_header *)(x))->previous)
  147.  
  148. #endif
  149.