Annotation of libwww/Library/src/HTList.html, revision 2.30
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.30 ! eric 71: extern BOOL HTList_quickRemoveElement (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.30 ! eric 82: <PRE>
! 83: #define HTList_isEmpty(me) (me ? me->next == NULL : YES)
2.19 frystyk 84: extern int HTList_count (HTList *me);
85: </PRE>
2.26 frystyk 86: <H2>
87: Reference List Elements By Index
88: </H2>
89: <P>
90: In some situations is is required to use an index in order to refer to a
91: list element. This is for example the case if an element can be registered
92: multiple times.
2.30 ! eric 93: <PRE>extern int HTList_indexOf (HTList * me, void * object);
! 94: extern void * HTList_objectAt (HTList * me, int position);
! 95: extern HTList * HTList_elementOf (HTList * me, void * object, HTList ** pLast);
! 96: #define HTList_objectOf(me) (me ? me->object: NULL)
2.19 frystyk 97: </PRE>
2.26 frystyk 98: <H2>
2.27 frystyk 99: Find List Elements
2.26 frystyk 100: </H2>
2.27 frystyk 101: <P>
102: This method returns the <I>last</I> element to the list or NULL if list is
103: empty
2.30 ! eric 104: <PRE>
! 105: #define HTList_lastObject(me) \
2.26 frystyk 106: ((me) && (me)->next ? (me)->next->object : NULL)
2.12 frystyk 107: </PRE>
2.27 frystyk 108: <P>
109: This method returns the <I>first</I> element to the list or NULL if list
110: is empty
111: <PRE>extern void * HTList_firstObject (HTList * me);
112: </PRE>
2.26 frystyk 113: <H2>
114: Traverse list
115: </H2>
116: <P>
117: Fast macro to traverse the list. Call it first with copy of list header:
118: it returns the first object and increments the passed list pointer. Call
119: it with the same variable until it returns NULL.
2.19 frystyk 120: <PRE>
121: #define HTList_nextObject(me) \
2.26 frystyk 122: ((me) && ((me) = (me)->next) ? (me)->object : NULL)
2.12 frystyk 123: </PRE>
2.26 frystyk 124: <H2>
2.28 frystyk 125: Insertion Sort a List
126: </H2>
127: <P>
128: This function sorts a list using the insertion sort mechanism. The comparison
129: function is passed as a parameter and you can find the definition of
130: <CODE>HTComparer</CODE> in the <A HREF="HTArray.html">HTArray</A> module.
131: Insertion sort is good method whenever a list is nearly in the correct order
132: and few items are many positions away from their sorted location. If the
133: list gets very long then you may wanna use a quicksort instead.
134: <PRE>extern BOOL HTList_insertionSort(HTList * list, HTComparer * comp);
135: </PRE>
136: <H2>
2.26 frystyk 137: Free list
138: </H2>
2.12 frystyk 139: <PRE>
2.22 frystyk 140: #define HTList_free(x) HT_FREE(x)
2.1 timbl 141:
142: #endif /* HTLIST_H */
2.25 frystyk 143: </PRE>
2.26 frystyk 144: <P>
145: <HR>
2.25 frystyk 146: <ADDRESS>
2.30 ! eric 147: @(#) $Id: HTList.html,v 2.29 1996/12/03 05:46:25 eric Exp $
2.25 frystyk 148: </ADDRESS>
2.26 frystyk 149: </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