Annotation of libwww/Library/src/HTList.html, revision 2.29
2.6 timbl 1: <HTML>
2: <HEAD>
2.27 frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 2-Jul-1996 -->
2.26 frystyk 4: <TITLE>W3C Reference Library libwww List Class</TITLE>
2.6 timbl 5: </HEAD>
6: <BODY>
2.26 frystyk 7: <H1>
8: The List Class
9: </H1>
2.7 frystyk 10: <PRE>
11: /*
2.13 frystyk 12: ** (c) COPYRIGHT MIT 1995.
2.7 frystyk 13: ** Please first read the full copyright statement in the file COPYRIGH.
14: */
15: </PRE>
2.26 frystyk 16: <P>
17: The list class defines a generic container for storing collections of things
18: in order. In principle it could be implemented in many ways, but in practice
19: knowing that it is a linked list is important for speed.
20: <P>
21: This module is implemented by <A HREF="HTList.c">HTList.c</A>, and it is
22: a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C Reference
23: Library</A>.
2.1 timbl 24: <PRE>
25: #ifndef HTLIST_H
26: #define HTLIST_H
27:
2.28 frystyk 28: #include "HTArray.h"
29:
2.1 timbl 30: typedef struct _HTList HTList;
31:
32: struct _HTList {
33: void * object;
34: HTList * next;
35: };
2.19 frystyk 36: </PRE>
2.26 frystyk 37: <H2>
38: Creation and Deletion Methods
39: </H2>
40: <P>
2.19 frystyk 41: These two functions create and deletes a list
42: <PRE>
43: extern HTList * HTList_new (void);
2.20 frystyk 44: extern BOOL HTList_delete (HTList *me);
2.12 frystyk 45: </PRE>
2.26 frystyk 46: <H2>
47: Add an Element to List
48: </H2>
49: <P>
50: A new list element is added to the beginning of the list so that it is first
51: element just after the head element.
2.27 frystyk 52: <PRE>extern BOOL HTList_addObject (HTList *me, void *newObject);
2.21 frystyk 53: </PRE>
2.26 frystyk 54: <P>
55: <A NAME="appendObject"></A> You can also append an element to the end of
56: the list (the end is the first entered object) by using the following function:
2.29 ! eric 57: <PRE>
! 58: extern BOOL HTList_appendObject (HTList * me, void * newObject);
2.19 frystyk 59: </PRE>
2.26 frystyk 60: <H2>
61: Remove List Elements
62: </H2>
2.27 frystyk 63: <P>
2.28 frystyk 64: You can delete elements in a list using the following methods. The
65: first method only removes the first entry that it finds matching the
66: <CODE>oldObject</CODE> whereas the second method removes all
67: occurances of <CODE>oldObject</CODE>.
68:
69: <PRE>
70: extern BOOL HTList_removeObject (HTList * me, void * oldObject);
2.29 ! eric 71: extern BOOL HTList_quickRemoveObject (HTList * me, HTList * last);
2.28 frystyk 72: extern BOOL HTList_removeObjectAll (HTList * me, void * oldObject);
73:
74: extern void * HTList_removeLastObject (HTList * me);
75: extern void * HTList_removeFirstObject (HTList * me);
2.19 frystyk 76: </PRE>
2.26 frystyk 77: <H2>
78: Size of a List
79: </H2>
80: <P>
2.19 frystyk 81: Two small function to ask for the size
2.27 frystyk 82: <PRE>#define HTList_isEmpty(me) (me ? me->next == NULL : YES)
2.19 frystyk 83: extern int HTList_count (HTList *me);
84: </PRE>
2.26 frystyk 85: <H2>
86: Reference List Elements By Index
87: </H2>
88: <P>
89: In some situations is is required to use an index in order to refer to a
90: list element. This is for example the case if an element can be registered
91: multiple times.
2.27 frystyk 92: <PRE>extern int HTList_indexOf (HTList *me, void *object);
2.19 frystyk 93: extern void * HTList_objectAt (HTList *me, int position);
94: </PRE>
2.26 frystyk 95: <H2>
2.27 frystyk 96: Find List Elements
2.26 frystyk 97: </H2>
2.27 frystyk 98: <P>
99: This method returns the <I>last</I> element to the list or NULL if list is
100: empty
101: <PRE>#define HTList_lastObject(me) \
2.26 frystyk 102: ((me) && (me)->next ? (me)->next->object : NULL)
2.12 frystyk 103: </PRE>
2.27 frystyk 104: <P>
105: This method returns the <I>first</I> element to the list or NULL if list
106: is empty
107: <PRE>extern void * HTList_firstObject (HTList * me);
108: </PRE>
2.26 frystyk 109: <H2>
110: Traverse list
111: </H2>
112: <P>
113: Fast macro to traverse the list. Call it first with copy of list header:
114: it returns the first object and increments the passed list pointer. Call
115: it with the same variable until it returns NULL.
2.19 frystyk 116: <PRE>
117: #define HTList_nextObject(me) \
2.26 frystyk 118: ((me) && ((me) = (me)->next) ? (me)->object : NULL)
2.12 frystyk 119: </PRE>
2.26 frystyk 120: <H2>
2.28 frystyk 121: Insertion Sort a List
122: </H2>
123: <P>
124: This function sorts a list using the insertion sort mechanism. The comparison
125: function is passed as a parameter and you can find the definition of
126: <CODE>HTComparer</CODE> in the <A HREF="HTArray.html">HTArray</A> module.
127: Insertion sort is good method whenever a list is nearly in the correct order
128: and few items are many positions away from their sorted location. If the
129: list gets very long then you may wanna use a quicksort instead.
130: <PRE>extern BOOL HTList_insertionSort(HTList * list, HTComparer * comp);
131: </PRE>
132: <H2>
2.26 frystyk 133: Free list
134: </H2>
2.12 frystyk 135: <PRE>
2.22 frystyk 136: #define HTList_free(x) HT_FREE(x)
2.1 timbl 137:
138: #endif /* HTLIST_H */
2.25 frystyk 139: </PRE>
2.26 frystyk 140: <P>
141: <HR>
2.25 frystyk 142: <ADDRESS>
2.29 ! eric 143: @(#) $Id: HTList.html,v 2.28 1996/10/07 02:04:52 frystyk Exp $
2.25 frystyk 144: </ADDRESS>
2.26 frystyk 145: </BODY></HTML>
Webmaster