Annotation of libwww/Library/src/HTChunk.html, revision 2.35
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
! 19: automatically grow to accomodate added data to the chunk. It is a general
2.31 frystyk 20: utility module. It is garanteed that the array is <CODE>'\0' </CODE>terminated
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.18 frystyk 53: Free a chunk created by <CODE>HTChunkCreate</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
63: new memory.
2.6 timbl 64: <PRE>
2.22 frystyk 65: extern void HTChunk_clear (HTChunk * ch);
2.18 frystyk 66: </PRE>
2.31 frystyk 67: <H2>
68: Ensure a Chunk has a Certain Amount of Free Space
69: </H2>
70: <P>
71: Make sure that a chunk has a certain size. If this is not the case then the
72: chunk is expanded. Nothing is done if the current size if bigger than the
73: size requested.
2.6 timbl 74: <PRE>
2.22 frystyk 75: extern void HTChunk_ensure (HTChunk * ch, int s);
2.18 frystyk 76: </PRE>
2.31 frystyk 77: <H2>
78: Append a character to a chunk
79: </H2>
80: <P>
2.18 frystyk 81: Add the character and increment the size of the chunk by one character
82: <PRE>
2.22 frystyk 83: extern void HTChunk_putc (HTChunk * ch, char c);
2.6 timbl 84: </PRE>
2.31 frystyk 85: <H2>
86: Append a string to a chunk
87: </H2>
88: <P>
89: Add the string and increment the size of the chunk by the length of the string
90: (without the trailing zero)
2.18 frystyk 91: <PRE>
2.25 frystyk 92: extern void HTChunk_puts (HTChunk * ch, const char *str);
2.22 frystyk 93: </PRE>
2.31 frystyk 94: <H2>
95: Append a block to a chunk
96: </H2>
97: <P>
2.22 frystyk 98: Add the block and increment the size of the chunk by the len
99: <PRE>
2.25 frystyk 100: extern void HTChunk_putb (HTChunk * ch, const char *block, int len);
2.31 frystyk 101:
2.6 timbl 102: </PRE>
2.31 frystyk 103: <H2>
2.35 ! frystyk 104: Return Pointer to Data
! 105: </H2>
! 106: <P>
! 107: This define converts a chunk to a normal char pointer so that it can be parsed
! 108: to any ANSI C string function.
! 109: <PRE>
! 110: extern char * HTChunk_data (HTChunk * ch);
! 111: </PRE>
! 112: <H2>
! 113: Return Current Size
! 114: </H2>
! 115: <P>
! 116: Returns the current size of the chunk
! 117: <PRE>
! 118: extern int HTChunk_size (HTChunk * ch);
! 119: </PRE>
! 120: <H2>
! 121: Truncate Chunk
! 122: </H2>
! 123: <P>
! 124: If for some reason you want to cut off a piece of a chunk then you can
! 125: use this function. It sets the size of the chunk to be
! 126: <CODE>position</CODE>. Clearing the chunk is equivalent to a position
! 127: of 0.
! 128: <PRE>
! 129: extern BOOL HTChunk_truncate (HTChunk * ch, int position);
! 130: </PRE>
! 131: <H2>
2.31 frystyk 132: Zero Terminate a chunk
133: </H2>
134: <P>
135: As a chunk often is a dynamic string, it needs to be terminated by a zero
136: in order to be used in C. However, <B>by default</B> any chunk is
137: <I>always</I> zero terminated, so the only purpose of this function is to
138: increment the size counter with one corresponding to the zero.
2.6 timbl 139: <PRE>
2.35 ! frystyk 140: extern void HTChunk_terminate (HTChunk * ch);
2.31 frystyk 141: </PRE>
142: <H2>
2.35 ! frystyk 143: CString Conversions
2.31 frystyk 144: </H2>
145: <P>
146: A Chunk may be build from an allocated string. The chunk assumes control
2.27 eric 147: of the passes string, elminating the need for additional allocations and
148: string copies.<BR>
2.31 frystyk 149: Once a string is built, the chunk may be destroyed and the string kept around.
2.27 eric 150: <PRE>
2.32 frystyk 151: extern HTChunk * HTChunk_fromCString (char * str, int grow);
152: extern char * HTChunk_toCString (HTChunk * ch);
2.6 timbl 153: </PRE>
2.31 frystyk 154: <H2>
2.35 ! frystyk 155: Old Interface Names
2.31 frystyk 156: </H2>
157: <P>
2.35 ! frystyk 158: Don't use these in new applications
2.6 timbl 159: <PRE>
2.35 ! frystyk 160: #define HTChunkCreate(growby) HTChunk_new(growby)
! 161: #define HTChunkFree(ch) HTChunk_delete(ch)
! 162: #define HTChunkClear(ch) HTChunk_clear(ch)
! 163: #define HTChunkEnsure(ch, s) HTChunk_ensure((ch), (s))
! 164: #define HTChunkPutc(ch, c) HTChunk_putc((ch), (c))
! 165: #define HTChunkPuts(ch, str) HTChunk_puts((ch), (str))
! 166: #define HTChunkTerminate(ch) HTChunk_terminate(ch)
! 167: #define HTChunkData(me) HTChunk_data(ch)
! 168: #define HTChunkSize(me) HTChunk_size(ch)
2.6 timbl 169: </PRE>
170: <PRE>
2.18 frystyk 171: #endif
172: </PRE>
2.31 frystyk 173: <P>
174: <HR>
2.29 frystyk 175: <ADDRESS>
2.35 ! frystyk 176: @(#) $Id: HTChunk.html,v 2.34 1998/05/14 02:10:20 frystyk Exp $
2.29 frystyk 177: </ADDRESS>
2.31 frystyk 178: </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