home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / desklib / !DeskLib / h_doc / LinkList < prev    next >
Encoding:
Text File  |  1996-08-27  |  5.6 KB  |  184 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.     History:
  16.         27 Aug 1996    JS    InsertBefore/After now work if pos is NULL.
  17. */
  18.  
  19.  
  20. #ifndef __Desk_LinkList_h
  21. #define __Desk_LinkList_h
  22.  
  23. #ifdef __cplusplus
  24.     extern "C" {
  25. #endif
  26.  
  27.  
  28. #ifndef __Desk_Core_h
  29.     #include "Desk.Core.h"
  30. #endif
  31.  
  32.  
  33. /*  Implementation notes
  34.  *  ====================
  35.  *  This module provides support for a linked list structure.
  36.  *  YOU must supply an anchor for the list (a variable of type
  37.  *  Desk_linklist_header). This is used to record pointers to the start and end
  38.  *  of the list.
  39.  *  The list itself is made up of your own structures, defined as follows:
  40.  *    struct listelement
  41.  *    {
  42.  *      Desk_linklist_header header;
  43.  *      ... Your own data here ...
  44.  *    } listelement;
  45.  *
  46.  *  a list-terminating pointer is represented as NULL
  47.  *
  48.  *  The header's next field stores a pointer to the FIRST item
  49.  *           its previous field stores a pointer to the LAST item
  50.  *           (both these pointers will be nulls if the list is empty)
  51.  *
  52.  *  To insert items into the list, you must malloc memory for one of your
  53.  *  own listelement data structures, then call the appropriate function
  54.  *  To delete an item from the list, call the unlink function, and then free
  55.  *  all memory used by your structure.
  56.  */
  57.  
  58.  
  59. typedef struct Desk_linklist_header
  60. {
  61.   struct Desk_linklist_header *next;
  62.   struct Desk_linklist_header *previous;
  63. } Desk_linklist_header ;
  64.  
  65.  
  66.  
  67. extern void Desk_LinkList_AddToHead(Desk_linklist_header *anchor, Desk_linklist_header *item);
  68. /*
  69. inserts the given item at the head of the list
  70. */
  71.  
  72. extern void Desk_LinkList_AddToTail(Desk_linklist_header *anchor, Desk_linklist_header *item);
  73. /*
  74. inserts the given item at the end of the list
  75. */
  76.  
  77. extern void Desk_LinkList_InsertBefore(Desk_linklist_header *anchor,
  78.                                   Desk_linklist_header *pos,
  79.                                   Desk_linklist_header *item);
  80. /*
  81. inserts the given item BEFORE the item "pos"
  82. If 'pos' is NULL, adds to head of list.
  83. */
  84.  
  85. extern void Desk_LinkList_InsertAfter(Desk_linklist_header *anchor,
  86.                                  Desk_linklist_header *pos,
  87.                                  Desk_linklist_header *item);
  88. /*
  89. inserts the given item AFTER the item "pos"
  90. If 'pos' is NULL, adds to tail of list.
  91. */
  92.  
  93.  
  94.  
  95. extern Desk_bool Desk_LinkList_InList( const Desk_linklist_header *anchor, const Desk_linklist_header *item);
  96.   /*
  97.    *  Returns Desk_bool_TRUE if the item is curently in the list. Note that this does
  98.    *  NOT check item contents, merely compares item pointers.
  99.    *  To check item contents, you must chain through the list yourself.
  100.    */
  101.  
  102.  
  103. extern int Desk_LinkList_ListLength( const Desk_linklist_header *anchor);
  104.   /*
  105.    *  Returns the number of items in the list. It follows all the links
  106.    *  and counts them... if you need this value a lot, I suggest you modify
  107.    *  LinkList to keep a count in the anchor...
  108.    */
  109.  
  110.  
  111.  
  112. extern void Desk_LinkList_Unlink(Desk_linklist_header *anchor, Desk_linklist_header *item);
  113.   /*
  114.    *  Unlinks the item "item" from the given list.
  115.    *  You must then free the memory used by it yourself.
  116.    */
  117.  
  118.  
  119. #define Desk_LinkList_FirstItem(x) ((void *)(x)->next)
  120.   /*  Return pointer to the first item in the list
  121.    */
  122.  
  123. #define Desk_LinkList_LastItem(x) ((void *)(x)->previous)
  124.   /*  Return pointer to the last item in the list
  125.    */
  126.  
  127.  
  128. #define Desk_LinkList_Init(x)  \
  129.   {                       \
  130.     (x)->next = NULL;     \
  131.     (x)->previous = NULL; \
  132.   }
  133.   /*
  134.    *  Initialises a list anchor. Should be called before anchor used
  135.    *    extern void Desk_LinkList_Init(Desk_linklist_header *item);
  136.    */
  137.  
  138.  
  139. #define Desk_LinkList_InitItem(x) \
  140.   {                          \
  141.     (x)->next = NULL;        \
  142.     (x)->previous = NULL;    \
  143.   }
  144.   /*
  145.    *  Initialises a list item. Should be called before item used,
  146.    *  except when that item is immediately linked into a list
  147.    *    extern void Desk_LinkList_InitItem(Desk_linklist_header *item);
  148.    */
  149.  
  150.  
  151. #define Desk_LinkList_NextItem(x) ((void *) ((Desk_linklist_header *)(x))->next)
  152.   /*  Return the next item of a given one. If the current item is at
  153.    *  the tail of the list, NULLPOINTER will be returned.
  154.    *    extern void *Desk_LinkList_NextItem(Desk_linklist_header *item);
  155.    *
  156.    *  Old definition:
  157.    *    #define Desk_LinkList_NextItem(x) ((void *)(x)->next)
  158.    *
  159.    *  NEW definition:
  160.    *    you can now use   Desk_LinkList_NextItem(&item);
  161.    *    instead of        Desk_LinkList_NextItem(&item->header);
  162.    */
  163.  
  164.  
  165. #define Desk_LinkList_PreviousItem(x) ((void *) ((Desk_linklist_header *)(x))->previous)
  166.   /*  Return the previous item of a given one. If the current item is at
  167.    *  the head of the list, NULLPOINTER will be returned.
  168.    *    extern void *Desk_LinkList_PreviousItem(Desk_linklist_header *item);
  169.    *
  170.    *  Old definition:
  171.    *    #define Desk_LinkList_PreviousItem(x) ((void *)(x)->previous)
  172.    *
  173.    *  NEW definition:
  174.    *    you can now use   Desk_LinkList_PreviousItem(&item);
  175.    *    instead of        Desk_LinkList_PreviousItem(&item->header);
  176.    */
  177.  
  178. #ifdef __cplusplus
  179. }
  180. #endif
  181.  
  182.  
  183. #endif
  184.