Annotation of libwww/Library/src/HTList.html, revision 2.35
2.6 timbl 1: <HTML>
2: <HEAD>
2.27 frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 2-Jul-1996 -->
2.32 frystyk 4: <TITLE>W3C Sample Code 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
2.33 frystyk 22: a part of the <A HREF="http://www.w3.org/Library/"> W3C Sample Code
2.26 frystyk 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.35 ! vbancrof 30: #ifdef __cplusplus
! 31: extern "C" {
! 32: #endif
! 33:
2.1 timbl 34: typedef struct _HTList HTList;
35:
36: struct _HTList {
37: void * object;
38: HTList * next;
39: };
2.19 frystyk 40: </PRE>
2.26 frystyk 41: <H2>
42: Creation and Deletion Methods
43: </H2>
44: <P>
2.19 frystyk 45: These two functions create and deletes a list
46: <PRE>
47: extern HTList * HTList_new (void);
2.20 frystyk 48: extern BOOL HTList_delete (HTList *me);
2.12 frystyk 49: </PRE>
2.26 frystyk 50: <H2>
51: Add an Element to List
52: </H2>
53: <P>
54: A new list element is added to the beginning of the list so that it is first
55: element just after the head element.
2.27 frystyk 56: <PRE>extern BOOL HTList_addObject (HTList *me, void *newObject);
2.21 frystyk 57: </PRE>
2.26 frystyk 58: <P>
59: <A NAME="appendObject"></A> You can also append an element to the end of
60: the list (the end is the first entered object) by using the following function:
2.29 eric 61: <PRE>
62: extern BOOL HTList_appendObject (HTList * me, void * newObject);
2.19 frystyk 63: </PRE>
2.34 kahan 64: <P>The following two functions, contributed by Vic
65: Bancroft (bancroft@america.net) that do the same operation as above, but return
66: a pointer to the new HTList element that was added or appended. This allows
67: one to keep a reference to the end of the list outside of the list itself,
68: which can be used to speed up certain list operations.
69: <PRE>
70: extern HTList * HTList_addList (HTList * me, void * newObject);
71: extern HTList * HTList_appendList (HTList * me, void * newObject);
72: </PRE>
2.26 frystyk 73: <H2>
74: Remove List Elements
75: </H2>
2.27 frystyk 76: <P>
2.28 frystyk 77: You can delete elements in a list using the following methods. The
78: first method only removes the first entry that it finds matching the
79: <CODE>oldObject</CODE> whereas the second method removes all
80: occurances of <CODE>oldObject</CODE>.
81:
82: <PRE>
83: extern BOOL HTList_removeObject (HTList * me, void * oldObject);
2.30 eric 84: extern BOOL HTList_quickRemoveElement (HTList * me, HTList * last);
2.28 frystyk 85: extern BOOL HTList_removeObjectAll (HTList * me, void * oldObject);
86:
87: extern void * HTList_removeLastObject (HTList * me);
88: extern void * HTList_removeFirstObject (HTList * me);
2.19 frystyk 89: </PRE>
2.26 frystyk 90: <H2>
91: Size of a List
92: </H2>
93: <P>
2.19 frystyk 94: Two small function to ask for the size
2.30 eric 95: <PRE>
96: #define HTList_isEmpty(me) (me ? me->next == NULL : YES)
2.19 frystyk 97: extern int HTList_count (HTList *me);
98: </PRE>
2.26 frystyk 99: <H2>
100: Reference List Elements By Index
101: </H2>
102: <P>
103: In some situations is is required to use an index in order to refer to a
104: list element. This is for example the case if an element can be registered
105: multiple times.
2.31 eric 106: <PRE>
107: extern int HTList_indexOf (HTList * me, void * object);
108: extern int HTList_indexOfElement (HTList * me, HTList * element);
2.30 eric 109: extern void * HTList_objectAt (HTList * me, int position);
110: extern HTList * HTList_elementOf (HTList * me, void * object, HTList ** pLast);
111: #define HTList_objectOf(me) (me ? me->object: NULL)
2.19 frystyk 112: </PRE>
2.26 frystyk 113: <H2>
2.27 frystyk 114: Find List Elements
2.26 frystyk 115: </H2>
2.27 frystyk 116: <P>
117: This method returns the <I>last</I> element to the list or NULL if list is
118: empty
2.30 eric 119: <PRE>
120: #define HTList_lastObject(me) \
2.26 frystyk 121: ((me) && (me)->next ? (me)->next->object : NULL)
2.12 frystyk 122: </PRE>
2.27 frystyk 123: <P>
124: This method returns the <I>first</I> element to the list or NULL if list
125: is empty
126: <PRE>extern void * HTList_firstObject (HTList * me);
127: </PRE>
2.26 frystyk 128: <H2>
129: Traverse list
130: </H2>
131: <P>
132: Fast macro to traverse the list. Call it first with copy of list header:
133: it returns the first object and increments the passed list pointer. Call
134: it with the same variable until it returns NULL.
2.19 frystyk 135: <PRE>
136: #define HTList_nextObject(me) \
2.26 frystyk 137: ((me) && ((me) = (me)->next) ? (me)->object : NULL)
2.12 frystyk 138: </PRE>
2.26 frystyk 139: <H2>
2.28 frystyk 140: Insertion Sort a List
141: </H2>
142: <P>
143: This function sorts a list using the insertion sort mechanism. The comparison
144: function is passed as a parameter and you can find the definition of
145: <CODE>HTComparer</CODE> in the <A HREF="HTArray.html">HTArray</A> module.
146: Insertion sort is good method whenever a list is nearly in the correct order
147: and few items are many positions away from their sorted location. If the
148: list gets very long then you may wanna use a quicksort instead.
149: <PRE>extern BOOL HTList_insertionSort(HTList * list, HTComparer * comp);
150: </PRE>
151: <H2>
2.26 frystyk 152: Free list
153: </H2>
2.12 frystyk 154: <PRE>
2.22 frystyk 155: #define HTList_free(x) HT_FREE(x)
2.1 timbl 156:
2.35 ! vbancrof 157: #ifdef __cplusplus
! 158: }
! 159: #endif
! 160:
2.1 timbl 161: #endif /* HTLIST_H */
2.25 frystyk 162: </PRE>
2.26 frystyk 163: <P>
164: <HR>
2.25 frystyk 165: <ADDRESS>
2.35 ! vbancrof 166: @(#) $Id: HTList.html,v 2.34 2000/06/15 13:48:44 kahan Exp $
2.25 frystyk 167: </ADDRESS>
2.26 frystyk 168: </BODY></HTML>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTList.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src