Annotation of libwww/Library/src/HTChunk.html, revision 2.38
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.18 frystyk 36: </PRE>
2.31 frystyk 37: <H2>
38: Create new chunk
39: </H2>
40: <P>
41: Create a new chunk and specify the number of bytes to allocate at a time
42: when the chunk is later extended. Arbitrary but normally a trade-off time
43: vs. memory
2.6 timbl 44: <PRE>
2.35 frystyk 45: typedef struct _HTChunk HTChunk;
46:
2.22 frystyk 47: extern HTChunk * HTChunk_new (int growby);
2.18 frystyk 48: </PRE>
2.31 frystyk 49: <H2>
50: Free a chunk
51: </H2>
52: <P>
2.37 kahan 53: Free a chunk created by <CODE>HTChunk_new</CODE>from memory
2.6 timbl 54: <PRE>
2.22 frystyk 55: extern void HTChunk_delete (HTChunk * ch);
2.18 frystyk 56: </PRE>
2.31 frystyk 57: <H2>
58: Clear a chunk
59: </H2>
60: <P>
61: Keep the chunk in memory but clear all data kept inside. This can be used
62: if you know that you can reuse the allocated memory instead of allocating
2.38 ! kahan 63: new memory. This zeros out all the allocated data (even data past the
! 64: indicated size) and sets the size of the chunk to 0. If you have not used
! 65: any bytes past the indicated size, it is more efficient to truncate the
! 66: chunk to 0 instead.
2.6 timbl 67: <PRE>
2.22 frystyk 68: extern void HTChunk_clear (HTChunk * ch);
2.18 frystyk 69: </PRE>
2.31 frystyk 70: <H2>
71: Ensure a Chunk has a Certain Amount of Free Space
72: </H2>
73: <P>
2.38 ! kahan 74: Make sure that a chunk has enough memory allocated to grow by the
! 75: indicated extra size. If this is not the case, then the chunk is expanded
! 76: (in multiples of the chunk's "growby" size). Nothing is done if the
! 77: current size plus the requested extra space fits within the chunk's
! 78: currently allocated memory.
2.6 timbl 79: <PRE>
2.38 ! kahan 80: extern void HTChunk_ensure (HTChunk * ch, int extra_size);
2.18 frystyk 81: </PRE>
2.31 frystyk 82: <H2>
83: Append a character to a chunk
84: </H2>
85: <P>
2.18 frystyk 86: Add the character and increment the size of the chunk by one character
87: <PRE>
2.22 frystyk 88: extern void HTChunk_putc (HTChunk * ch, char c);
2.6 timbl 89: </PRE>
2.31 frystyk 90: <H2>
91: Append a string to a chunk
92: </H2>
93: <P>
94: Add the string and increment the size of the chunk by the length of the string
95: (without the trailing zero)
2.18 frystyk 96: <PRE>
2.25 frystyk 97: extern void HTChunk_puts (HTChunk * ch, const char *str);
2.22 frystyk 98: </PRE>
2.31 frystyk 99: <H2>
100: Append a block to a chunk
101: </H2>
102: <P>
2.22 frystyk 103: Add the block and increment the size of the chunk by the len
104: <PRE>
2.25 frystyk 105: extern void HTChunk_putb (HTChunk * ch, const char *block, int len);
2.31 frystyk 106:
2.6 timbl 107: </PRE>
2.31 frystyk 108: <H2>
2.35 frystyk 109: Return Pointer to Data
110: </H2>
111: <P>
112: This define converts a chunk to a normal char pointer so that it can be parsed
113: to any ANSI C string function.
114: <PRE>
115: extern char * HTChunk_data (HTChunk * ch);
116: </PRE>
117: <H2>
118: Return Current Size
119: </H2>
120: <P>
121: Returns the current size of the chunk
122: <PRE>
123: extern int HTChunk_size (HTChunk * ch);
124: </PRE>
125: <H2>
2.38 ! kahan 126: Setting the Size of a Chunk
2.35 frystyk 127: </H2>
128: <P>
2.38 ! kahan 129: If you want to cut off a piece of a chunk or extend it to make room
! 130: for some direct buffer manipulation, then you can use one of these
! 131: functions. Both of these calls set the size of the chunk to be
! 132: <CODE>size</CODE>, but the truncate call only allows you to make the
! 133: string shorter. If the string is made shorter, the formerly-used bytes
! 134: are cleared, so truncating a chunk to 0 is analogous to clearing it,
! 135: but slightly more efficient.
2.35 frystyk 136: <PRE>
2.38 ! kahan 137: extern BOOL HTChunk_truncate (HTChunk * ch, int size);
! 138: extern BOOL HTChunk_setSize (HTChunk * ch, int size);
2.35 frystyk 139: </PRE>
140: <H2>
2.31 frystyk 141: Zero Terminate a chunk
142: </H2>
143: <P>
144: As a chunk often is a dynamic string, it needs to be terminated by a zero
145: in order to be used in C. However, <B>by default</B> any chunk is
146: <I>always</I> zero terminated, so the only purpose of this function is to
147: increment the size counter with one corresponding to the zero.
2.6 timbl 148: <PRE>
2.35 frystyk 149: extern void HTChunk_terminate (HTChunk * ch);
2.31 frystyk 150: </PRE>
151: <H2>
2.35 frystyk 152: CString Conversions
2.31 frystyk 153: </H2>
154: <P>
2.37 kahan 155: A Chunk may be built from an allocated string. The chunk assumes control
2.38 ! kahan 156: of the passed string, eliminating the need for additional allocations and
2.27 eric 157: string copies.<BR>
2.38 ! kahan 158: When you take control of the CString from a chunk, it is destroyed.
2.27 eric 159: <PRE>
2.32 frystyk 160: extern HTChunk * HTChunk_fromCString (char * str, int grow);
161: extern char * HTChunk_toCString (HTChunk * ch);
2.6 timbl 162: </PRE>
2.31 frystyk 163: <H2>
2.35 frystyk 164: Old Interface Names
2.31 frystyk 165: </H2>
166: <P>
2.35 frystyk 167: Don't use these in new applications
2.6 timbl 168: <PRE>
2.35 frystyk 169: #define HTChunkCreate(growby) HTChunk_new(growby)
170: #define HTChunkFree(ch) HTChunk_delete(ch)
171: #define HTChunkClear(ch) HTChunk_clear(ch)
172: #define HTChunkEnsure(ch, s) HTChunk_ensure((ch), (s))
173: #define HTChunkPutc(ch, c) HTChunk_putc((ch), (c))
174: #define HTChunkPuts(ch, str) HTChunk_puts((ch), (str))
175: #define HTChunkTerminate(ch) HTChunk_terminate(ch)
2.36 frystyk 176: #define HTChunkData(ch) HTChunk_data(ch)
177: #define HTChunkSize(ch) HTChunk_size(ch)
2.6 timbl 178: </PRE>
179: <PRE>
2.18 frystyk 180: #endif
181: </PRE>
2.31 frystyk 182: <P>
183: <HR>
2.29 frystyk 184: <ADDRESS>
2.38 ! kahan 185: @(#) $Id: HTChunk.html,v 2.37 2000/07/04 15:26:00 kahan Exp $
2.29 frystyk 186: </ADDRESS>
2.31 frystyk 187: </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