Annotation of libwww/Library/src/HTChunk.html, revision 2.40
2.8 timbl 1: <HTML>
2: <HEAD>
2.35 frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 13-Jul-1996 -->
2.33 frystyk 4: <TITLE>W3C Sample Code Library libwww Chunk Class</TITLE>
2.11 frystyk 5: </HEAD>
2.6 timbl 6: <BODY>
2.31 frystyk 7: <H1>
8: The Chunk Class
9: </H1>
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>
2.31 frystyk 16: <P>
2.35 frystyk 17: The Chunk Class defines a way to automatically handle dynamic strings and
18: other data types. You create a chunk with an initial size and it will then
2.38 kahan 19: automatically grow to accommodate added data to the chunk. It is a general
20: utility module. It is guaranteed that the array is <CODE>'\0' </CODE>terminated
2.31 frystyk 21: at all times (and hence is a valid C type string). The method
22: <A HREF="HTChunk.html#Terminate">HTChunkTerminate</A> can be used to explicitly
23: add a terminating <CODE>'\0'</CODE> and then to include this character in
24: the chunk size. If left out, the terminating character is <I>not</I> considered
25: part of the chunk.
26: <P>
27: <B>Note</B>: The names without a "_" (made as a <CODE>#define</CODE>'s) are
28: only provided for backwards compatibility and should not be used.
29: <P>
30: This module is implemented by <A HREF="HTChunk.c">HTChunk.c</A>, and it is
2.34 frystyk 31: a part of the <A HREF="http://www.w3.org/Library/"> W3C Sample Code
2.31 frystyk 32: Library</A>.
2.10 frystyk 33: <PRE>
34: #ifndef HTCHUNK_H
2.9 frystyk 35: #define HTCHUNK_H
2.40 ! vbancrof 36:
! 37: #ifdef __cplusplus
! 38: extern "C" {
! 39: #endif
2.18 frystyk 40: </PRE>
2.31 frystyk 41: <H2>
42: Create new chunk
43: </H2>
44: <P>
45: Create a new chunk and specify the number of bytes to allocate at a time
46: when the chunk is later extended. Arbitrary but normally a trade-off time
47: vs. memory
2.6 timbl 48: <PRE>
2.35 frystyk 49: typedef struct _HTChunk HTChunk;
50:
2.22 frystyk 51: extern HTChunk * HTChunk_new (int growby);
2.18 frystyk 52: </PRE>
2.31 frystyk 53: <H2>
54: Free a chunk
55: </H2>
56: <P>
2.37 kahan 57: Free a chunk created by <CODE>HTChunk_new</CODE>from memory
2.6 timbl 58: <PRE>
2.22 frystyk 59: extern void HTChunk_delete (HTChunk * ch);
2.18 frystyk 60: </PRE>
2.31 frystyk 61: <H2>
62: Clear a chunk
63: </H2>
64: <P>
65: Keep the chunk in memory but clear all data kept inside. This can be used
66: if you know that you can reuse the allocated memory instead of allocating
2.38 kahan 67: new memory. This zeros out all the allocated data (even data past the
68: indicated size) and sets the size of the chunk to 0. If you have not used
69: any bytes past the indicated size, it is more efficient to truncate the
70: chunk to 0 instead.
2.6 timbl 71: <PRE>
2.22 frystyk 72: extern void HTChunk_clear (HTChunk * ch);
2.18 frystyk 73: </PRE>
2.31 frystyk 74: <H2>
75: Ensure a Chunk has a Certain Amount of Free Space
76: </H2>
77: <P>
2.38 kahan 78: Make sure that a chunk has enough memory allocated to grow by the
79: indicated extra size. If this is not the case, then the chunk is expanded
80: (in multiples of the chunk's "growby" size). Nothing is done if the
81: current size plus the requested extra space fits within the chunk's
82: currently allocated memory.
2.6 timbl 83: <PRE>
2.38 kahan 84: extern void HTChunk_ensure (HTChunk * ch, int extra_size);
2.18 frystyk 85: </PRE>
2.31 frystyk 86: <H2>
87: Append a character to a chunk
88: </H2>
89: <P>
2.18 frystyk 90: Add the character and increment the size of the chunk by one character
91: <PRE>
2.22 frystyk 92: extern void HTChunk_putc (HTChunk * ch, char c);
2.6 timbl 93: </PRE>
2.31 frystyk 94: <H2>
95: Append a string to a chunk
96: </H2>
97: <P>
98: Add the string and increment the size of the chunk by the length of the string
99: (without the trailing zero)
2.18 frystyk 100: <PRE>
2.25 frystyk 101: extern void HTChunk_puts (HTChunk * ch, const char *str);
2.22 frystyk 102: </PRE>
2.31 frystyk 103: <H2>
104: Append a block to a chunk
105: </H2>
106: <P>
2.22 frystyk 107: Add the block and increment the size of the chunk by the len
108: <PRE>
2.25 frystyk 109: extern void HTChunk_putb (HTChunk * ch, const char *block, int len);
2.31 frystyk 110:
2.6 timbl 111: </PRE>
2.31 frystyk 112: <H2>
2.35 frystyk 113: Return Pointer to Data
114: </H2>
115: <P>
116: This define converts a chunk to a normal char pointer so that it can be parsed
117: to any ANSI C string function.
118: <PRE>
119: extern char * HTChunk_data (HTChunk * ch);
120: </PRE>
121: <H2>
122: Return Current Size
123: </H2>
124: <P>
125: Returns the current size of the chunk
126: <PRE>
127: extern int HTChunk_size (HTChunk * ch);
128: </PRE>
129: <H2>
2.38 kahan 130: Setting the Size of a Chunk
2.35 frystyk 131: </H2>
132: <P>
2.38 kahan 133: If you want to cut off a piece of a chunk or extend it to make room
134: for some direct buffer manipulation, then you can use one of these
135: functions. Both of these calls set the size of the chunk to be
136: <CODE>size</CODE>, but the truncate call only allows you to make the
137: string shorter. If the string is made shorter, the formerly-used bytes
138: are cleared, so truncating a chunk to 0 is analogous to clearing it,
139: but slightly more efficient.
2.35 frystyk 140: <PRE>
2.38 kahan 141: extern BOOL HTChunk_truncate (HTChunk * ch, int size);
142: extern BOOL HTChunk_setSize (HTChunk * ch, int size);
2.35 frystyk 143: </PRE>
144: <H2>
2.31 frystyk 145: Zero Terminate a chunk
146: </H2>
147: <P>
148: As a chunk often is a dynamic string, it needs to be terminated by a zero
149: in order to be used in C. However, <B>by default</B> any chunk is
150: <I>always</I> zero terminated, so the only purpose of this function is to
151: increment the size counter with one corresponding to the zero.
2.6 timbl 152: <PRE>
2.35 frystyk 153: extern void HTChunk_terminate (HTChunk * ch);
2.31 frystyk 154: </PRE>
155: <H2>
2.35 frystyk 156: CString Conversions
2.31 frystyk 157: </H2>
158: <P>
2.37 kahan 159: A Chunk may be built from an allocated string. The chunk assumes control
2.38 kahan 160: of the passed string, eliminating the need for additional allocations and
2.27 eric 161: string copies.<BR>
2.39 kahan 162: When you take control of the CString from a chunk, the chunk is destroyed.
2.27 eric 163: <PRE>
2.32 frystyk 164: extern HTChunk * HTChunk_fromCString (char * str, int grow);
165: extern char * HTChunk_toCString (HTChunk * ch);
2.6 timbl 166: </PRE>
2.31 frystyk 167: <H2>
2.39 kahan 168: Creating a Chunk from an allocated buffer
169: </H2>
170: <P>
171: A Chunk may be built from an allocted buffer. You must specify how much
172: memory is allocated in the buffer (buflen) and what the size the new
173: Chunk should be (size). All memory between size and buflen is zeroed.
174: Note that is is legal to specify a size equal to the buflen if you don't
175: expect the Chunk to be null terminated. The chunk takes control of the
176: memory, and will free it when the Chunk is destroyed. Note that in order
177: to avoid conflicts, the buffer's memory should be allocated using
178: libwww's dedicated functions.
179: <PRE>
180: extern HTChunk * HTChunk_fromBuffer (char * buf, int buflen, int size, int grow);
181: </PRE>
182: <H2>
2.35 frystyk 183: Old Interface Names
2.31 frystyk 184: </H2>
185: <P>
2.35 frystyk 186: Don't use these in new applications
2.6 timbl 187: <PRE>
2.35 frystyk 188: #define HTChunkCreate(growby) HTChunk_new(growby)
189: #define HTChunkFree(ch) HTChunk_delete(ch)
190: #define HTChunkClear(ch) HTChunk_clear(ch)
191: #define HTChunkEnsure(ch, s) HTChunk_ensure((ch), (s))
192: #define HTChunkPutc(ch, c) HTChunk_putc((ch), (c))
193: #define HTChunkPuts(ch, str) HTChunk_puts((ch), (str))
194: #define HTChunkTerminate(ch) HTChunk_terminate(ch)
2.36 frystyk 195: #define HTChunkData(ch) HTChunk_data(ch)
196: #define HTChunkSize(ch) HTChunk_size(ch)
2.6 timbl 197: </PRE>
198: <PRE>
2.40 ! vbancrof 199: #ifdef __cplusplus
! 200: }
2.18 frystyk 201: #endif
2.40 ! vbancrof 202:
! 203: #endif /* HTCHUNK_H */
2.18 frystyk 204: </PRE>
2.31 frystyk 205: <P>
206: <HR>
2.29 frystyk 207: <ADDRESS>
2.40 ! vbancrof 208: @(#) $Id: HTChunk.html,v 2.39 2000/09/01 13:47:14 kahan Exp $
2.29 frystyk 209: </ADDRESS>
2.31 frystyk 210: </BODY></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