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