Annotation of libwww/Library/src/HTChunk.html, revision 2.28
2.8 timbl 1: <HTML>
2: <HEAD>
2.26 frystyk 3: <TITLE>W3C Reference Library libwww Dynamic Array Class</TITLE>
2.24 frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 5-Feb-1996 -->
2.28 ! hallam 5: <!-- Changed by: Eric Prud'hommeaux, 28-Mar-1996 -->
2.11 frystyk 6: </HEAD>
2.6 timbl 7: <BODY>
2.11 frystyk 8:
2.18 frystyk 9: <H1>Dynamic Array Class</H1>
2.10 frystyk 10:
2.11 frystyk 11: <PRE>
12: /*
2.16 frystyk 13: ** (c) COPYRIGHT MIT 1995.
2.11 frystyk 14: ** Please first read the full copyright statement in the file COPYRIGH.
15: */
16: </PRE>
17:
2.14 frystyk 18: This module implements a flexible array. It is a general utility
19: module. A chunk is a structure which may be extended. These routines
20: create and append data to chunks, automatically reallocating them as
21: necessary. It is garanteed that the array is <B>'\0'</B> terminated
22: at all times, so the terminating function, <A
23: HREF="HTChunk.html#Terminate">HTChunkTerminate</A> is only necessary
24: to adjust the size in the chunk structure (the <B>'\0'</B> counts as a
25: character when counting the size of the chunk. <P>
2.10 frystyk 26:
2.11 frystyk 27: This module is implemented by <A HREF="HTChunk.c">HTChunk.c</A>, and
2.20 frystyk 28: it is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C
2.23 frystyk 29: Reference Library</A>. <P>
30:
31: <IMG SRC="../../Icons/32x32/caution.gif" ALT="NOTE"> The names
32: without a "_" (made as a <CODE>#define</CODE>'s) are only provided for
33: backwards compatibility and should not be used.
2.10 frystyk 34:
35: <PRE>
36: #ifndef HTCHUNK_H
2.9 frystyk 37: #define HTCHUNK_H
2.12 roeber 38:
2.9 frystyk 39: </PRE>
40:
2.18 frystyk 41: <H2>Private Data Structure</H2>
42:
2.23 frystyk 43: This structure should not be referenced outside this module!
2.18 frystyk 44:
45: <PRE>
46: typedef struct {
2.1 timbl 47: int size; /* In bytes */
48: int growby; /* Allocation unit in bytes */
49: int allocated; /* Current size of *data */
50: char * data; /* Pointer to malloced area or 0 */
51: } HTChunk;
2.18 frystyk 52: </PRE>
2.1 timbl 53:
2.28 ! hallam 54: <A NAME="new"></A>
2.6 timbl 55: <H2>Create new chunk</H2>
2.18 frystyk 56:
57: Create a new chunk and specify the number of bytes to allocate at a
58: time when the chunk is later extended. Arbitrary but normally a
59: trade-off time vs. memory
2.6 timbl 60:
61: <PRE>
2.22 frystyk 62: #define HTChunkCreate(growby) HTChunk_new(growby)
63: extern HTChunk * HTChunk_new (int growby);
2.18 frystyk 64: </PRE>
2.1 timbl 65:
2.28 ! hallam 66: <A NAME="delete"></A>
2.18 frystyk 67: <H2>Free a chunk</H2>
2.1 timbl 68:
2.18 frystyk 69: Free a chunk created by <CODE>HTChunkCreate</CODE>from memory
2.6 timbl 70:
71: <PRE>
2.22 frystyk 72: #define HTChunkFree(ch) HTChunk_delete(ch)
73: extern void HTChunk_delete (HTChunk * ch);
2.18 frystyk 74: </PRE>
2.1 timbl 75:
2.28 ! hallam 76: <A NAME="clear"></A>
2.18 frystyk 77: <H2>Clear a chunk</H2>
2.1 timbl 78:
2.18 frystyk 79: Keep the chunk in memory but clear all data kept inside.
2.6 timbl 80:
81: <PRE>
2.22 frystyk 82: #define HTChunkClear(ch) HTChunk_clear(ch)
83: extern void HTChunk_clear (HTChunk * ch);
2.18 frystyk 84: </PRE>
2.1 timbl 85:
2.18 frystyk 86: <H2>Ensure a chunk has a certain space in</H2>
2.1 timbl 87:
2.18 frystyk 88: Make sure that a chunk has a certain size. If this is not the case
89: then the chunk is expanded. Nothing is done if the current size if
90: bigger than the size requested.
2.6 timbl 91:
92: <PRE>
2.22 frystyk 93: #define HTChunkEnsure(ch, s) HTChunk_ensure(ch, s)
94: extern void HTChunk_ensure (HTChunk * ch, int s);
2.18 frystyk 95: </PRE>
2.1 timbl 96:
2.18 frystyk 97: <H2>Append a character to a chunk</H2>
2.1 timbl 98:
2.18 frystyk 99: Add the character and increment the size of the chunk by one character
100:
101: <PRE>
2.22 frystyk 102: #define HTChunkPutc(ch, c) HTChunk_putc(ch, c)
103: extern void HTChunk_putc (HTChunk * ch, char c);
2.6 timbl 104: </PRE>
2.1 timbl 105:
2.18 frystyk 106: <H2>Append a string to a chunk</H2>
107:
108: Add the string and increment the size of the chunk by the length of
109: the string (without the trailing zero)
2.1 timbl 110:
2.18 frystyk 111: <PRE>
2.22 frystyk 112: #define HTChunkPuts(ch, str) HTChunk_puts(ch, str)
2.25 frystyk 113: extern void HTChunk_puts (HTChunk * ch, const char *str);
2.22 frystyk 114: </PRE>
115:
2.28 ! hallam 116: <A NAME="putb"></A>
2.22 frystyk 117: <H2>Append a block to a chunk</H2>
118:
119: Add the block and increment the size of the chunk by the len
120:
121: <PRE>
2.25 frystyk 122: extern void HTChunk_putb (HTChunk * ch, const char *block, int len);
2.6 timbl 123: </PRE>
2.18 frystyk 124:
2.28 ! hallam 125: <A NAME="putc"></A>
2.18 frystyk 126: <A NAME="Terminate"><H2>Zero Terminate a chunk</H2></A>
127:
128: As a chunk often is a dynamic string, it needs to be terminated by a
129: zero in order to be used in C. However, <B>by default</B> any chunk
130: <EM>is</EM> always zero terminated, so the only purpose of this
131: function is to increment the size counter with one corresponding to
132: the zero.
2.6 timbl 133:
134: <PRE>
2.24 frystyk 135: #define HTChunkTerminate(ch) HTChunk_terminate(ch)
136: #define HTChunk_terminate(ch) HTChunk_putc((ch), '\0')
2.18 frystyk 137: </PRE>
2.1 timbl 138:
2.18 frystyk 139: <H2>Return Pointer to Data</H2>
2.1 timbl 140:
2.18 frystyk 141: This define converts a chunk to a normal char pointer so that it can
142: be parsed to any ANSI C string function.
2.1 timbl 143:
2.18 frystyk 144: <PRE>
2.22 frystyk 145: #define HTChunkData(me) ((me) ? (me)->data : NULL)
146: #define HTChunk_data(me) ((me) ? (me)->data : NULL)
2.27 eric 147: </PRE>
148:
149: <A NAME="CString"><H2>CString conversions</H2></A>
150:
151: A Chunk may be build from an allocated string. The chunk assumes control
152: of the passes string, elminating the need for additional allocations and
153: string copies.<BR>
154: Once a string is built, the chunk may be destroyed and the string kept
155: around.
156:
157: <PRE>
158: extern HTChunk * HTChunk_fromCString (char * str, int grow);
159: extern char * HTChunk_toCString (HTChunk * ch);
2.6 timbl 160: </PRE>
2.18 frystyk 161:
162: <H2>Return Current Size</H2>
163:
164: Returns the current size of the chunk
165:
2.6 timbl 166: <PRE>
2.22 frystyk 167: #define HTChunkSize(me) ((me) ? (me)->size : -1)
168: #define HTChunk_size(me) ((me) ? (me)->size : -1)
2.6 timbl 169: </PRE>
170:
171: <PRE>
2.18 frystyk 172: #endif
173: </PRE>
2.1 timbl 174:
2.18 frystyk 175: End of Declaration
2.6 timbl 176:
2.18 frystyk 177: </BODY>
2.8 timbl 178: </HTML>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTChunk.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src