Annotation of libwww/Library/src/HTChunk.html, revision 2.31
2.8 timbl 1: <HTML>
2: <HEAD>
2.31 ! frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 12-Apr-1996 -->
! 4: <TITLE>W3C Reference 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>
! 17: The Chunk Class defines a way to automatically handle dynamic strings
! 18: and other data types. You create a chunk with an initial size and it will
! 19: then automatically grow to accomodate added data to the chunk. It is a general
! 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
! 31: a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C Reference
! 32: Library</A>.
2.10 frystyk 33: <PRE>
34: #ifndef HTCHUNK_H
2.9 frystyk 35: #define HTCHUNK_H
2.12 roeber 36:
2.9 frystyk 37: </PRE>
2.31 ! frystyk 38: <H2>
! 39: The Chunk Class
! 40: </H2>
! 41: <P>
! 42: This structure should not be referenced outside this module! We only keep
! 43: it here to maintain high performance. <B>Don't </B>use it directly!
2.18 frystyk 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.31 ! frystyk 52: <H2>
! 53: Create new chunk
! 54: </H2>
! 55: <P>
! 56: Create a new chunk and specify the number of bytes to allocate at a time
! 57: when the chunk is later extended. Arbitrary but normally a trade-off time
! 58: vs. memory
2.6 timbl 59: <PRE>
2.22 frystyk 60: #define HTChunkCreate(growby) HTChunk_new(growby)
61: extern HTChunk * HTChunk_new (int growby);
2.18 frystyk 62: </PRE>
2.31 ! frystyk 63: <H2>
! 64: Free a chunk
! 65: </H2>
! 66: <P>
2.18 frystyk 67: Free a chunk created by <CODE>HTChunkCreate</CODE>from memory
2.6 timbl 68: <PRE>
2.22 frystyk 69: #define HTChunkFree(ch) HTChunk_delete(ch)
70: extern void HTChunk_delete (HTChunk * ch);
2.18 frystyk 71: </PRE>
2.31 ! frystyk 72: <H2>
! 73: Clear a chunk
! 74: </H2>
! 75: <P>
! 76: Keep the chunk in memory but clear all data kept inside. This can be used
! 77: if you know that you can reuse the allocated memory instead of allocating
! 78: new memory.
2.6 timbl 79: <PRE>
2.22 frystyk 80: #define HTChunkClear(ch) HTChunk_clear(ch)
81: extern void HTChunk_clear (HTChunk * ch);
2.18 frystyk 82: </PRE>
2.31 ! frystyk 83: <H2>
! 84: Ensure a Chunk has a Certain Amount of Free Space
! 85: </H2>
! 86: <P>
! 87: Make sure that a chunk has a certain size. If this is not the case then the
! 88: chunk is expanded. Nothing is done if the current size if bigger than the
! 89: size requested.
2.6 timbl 90: <PRE>
2.22 frystyk 91: #define HTChunkEnsure(ch, s) HTChunk_ensure(ch, s)
92: extern void HTChunk_ensure (HTChunk * ch, int s);
2.18 frystyk 93: </PRE>
2.31 ! frystyk 94: <H2>
! 95: Append a character to a chunk
! 96: </H2>
! 97: <P>
2.18 frystyk 98: Add the character and increment the size of the chunk by one character
99: <PRE>
2.22 frystyk 100: #define HTChunkPutc(ch, c) HTChunk_putc(ch, c)
101: extern void HTChunk_putc (HTChunk * ch, char c);
2.6 timbl 102: </PRE>
2.31 ! frystyk 103: <H2>
! 104: Append a string to a chunk
! 105: </H2>
! 106: <P>
! 107: Add the string and increment the size of the chunk by the length of the string
! 108: (without the trailing zero)
2.18 frystyk 109: <PRE>
2.22 frystyk 110: #define HTChunkPuts(ch, str) HTChunk_puts(ch, str)
2.25 frystyk 111: extern void HTChunk_puts (HTChunk * ch, const char *str);
2.22 frystyk 112: </PRE>
2.31 ! frystyk 113: <H2>
! 114: Append a block to a chunk
! 115: </H2>
! 116: <P>
2.22 frystyk 117: Add the block and increment the size of the chunk by the len
118: <PRE>
2.25 frystyk 119: extern void HTChunk_putb (HTChunk * ch, const char *block, int len);
2.31 ! frystyk 120:
2.6 timbl 121: </PRE>
2.31 ! frystyk 122: <H2>
! 123: Zero Terminate a chunk
! 124: </H2>
! 125: <P>
! 126: As a chunk often is a dynamic string, it needs to be terminated by a zero
! 127: in order to be used in C. However, <B>by default</B> any chunk is
! 128: <I>always</I> zero terminated, so the only purpose of this function is to
! 129: increment the size counter with one corresponding to the zero.
2.6 timbl 130: <PRE>
2.24 frystyk 131: #define HTChunkTerminate(ch) HTChunk_terminate(ch)
132: #define HTChunk_terminate(ch) HTChunk_putc((ch), '\0')
2.18 frystyk 133: </PRE>
2.31 ! frystyk 134: <H2>
! 135: Return Pointer to Data
! 136: </H2>
! 137: <P>
! 138: This define converts a chunk to a normal char pointer so that it can be parsed
! 139: to any ANSI C string function.
! 140: <PRE>
! 141: #define HTChunkData(me) ((me) ? (me)->data : NULL)
! 142: #define HTChunk_data(me) ((me) ? (me)->data : NULL)
! 143: </PRE>
! 144: <H2>
! 145: CString conversions
! 146: </H2>
! 147: <P>
! 148: A Chunk may be build from an allocated string. The chunk assumes control
2.27 eric 149: of the passes string, elminating the need for additional allocations and
150: string copies.<BR>
2.31 ! frystyk 151: Once a string is built, the chunk may be destroyed and the string kept around.
2.27 eric 152: <PRE>
153: extern HTChunk * HTChunk_fromCString (char * str, int grow);
154: extern char * HTChunk_toCString (HTChunk * ch);
2.6 timbl 155: </PRE>
2.31 ! frystyk 156: <H2>
! 157: Return Current Size
! 158: </H2>
! 159: <P>
2.18 frystyk 160: Returns the current size of the chunk
2.6 timbl 161: <PRE>
2.31 ! frystyk 162: #define HTChunkSize(me) ((me) ? (me)->size : -1)
! 163: #define HTChunk_size(me) ((me) ? (me)->size : -1)
2.6 timbl 164: </PRE>
165: <PRE>
2.18 frystyk 166: #endif
167: </PRE>
2.31 ! frystyk 168: <P>
! 169: <HR>
2.29 frystyk 170: <ADDRESS>
2.31 ! frystyk 171: @(#) $Id: HTChunk.html,v 2.30 1996/05/15 17:32:13 frystyk Exp $
2.29 frystyk 172: </ADDRESS>
2.31 ! frystyk 173: </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