Annotation of libwww/Library/src/HTChunk.html, revision 2.18
2.8 timbl 1: <HTML>
2: <HEAD>
2.18 ! frystyk 3: <TITLE>Dynamic Array Class</TITLE>
! 4: <!-- Changed by: Henrik Frystyk Nielsen, 19-Aug-1995 -->
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
27: it is a part of the <A
2.17 frystyk 28: HREF="http://www.w3.org/hypertext/WWW/Library/">
29: W3C Reference Library</A>.
2.10 frystyk 30:
31: <PRE>
32: #ifndef HTCHUNK_H
2.9 frystyk 33: #define HTCHUNK_H
2.12 roeber 34:
2.9 frystyk 35: </PRE>
36:
2.18 ! frystyk 37: <H2>Private Data Structure</H2>
! 38:
! 39: This structure should not be referenced outside this module
! 40:
! 41: <PRE>
! 42: typedef struct {
2.1 timbl 43: int size; /* In bytes */
44: int growby; /* Allocation unit in bytes */
45: int allocated; /* Current size of *data */
46: char * data; /* Pointer to malloced area or 0 */
47: } HTChunk;
2.18 ! frystyk 48: </PRE>
2.1 timbl 49:
2.6 timbl 50: <H2>Create new chunk</H2>
2.18 ! frystyk 51:
! 52: Create a new chunk and specify the number of bytes to allocate at a
! 53: time when the chunk is later extended. Arbitrary but normally a
! 54: trade-off time vs. memory
2.6 timbl 55:
56: <PRE>
2.1 timbl 57: extern HTChunk * HTChunkCreate PARAMS((int growby));
2.18 ! frystyk 58: </PRE>
2.1 timbl 59:
2.18 ! frystyk 60: <H2>Free a chunk</H2>
2.1 timbl 61:
2.18 ! frystyk 62: Free a chunk created by <CODE>HTChunkCreate</CODE>from memory
2.6 timbl 63:
64: <PRE>
2.1 timbl 65: extern void HTChunkFree PARAMS((HTChunk * ch));
2.18 ! frystyk 66: </PRE>
2.1 timbl 67:
2.18 ! frystyk 68: <H2>Clear a chunk</H2>
2.1 timbl 69:
2.18 ! frystyk 70: Keep the chunk in memory but clear all data kept inside.
2.6 timbl 71:
72: <PRE>
2.1 timbl 73: extern void HTChunkClear PARAMS((HTChunk * ch));
2.18 ! frystyk 74: </PRE>
2.1 timbl 75:
2.18 ! frystyk 76: <H2>Ensure a chunk has a certain space in</H2>
2.1 timbl 77:
2.18 ! frystyk 78: Make sure that a chunk has a certain size. If this is not the case
! 79: then the chunk is expanded. Nothing is done if the current size if
! 80: bigger than the size requested.
2.6 timbl 81:
82: <PRE>
2.1 timbl 83: extern void HTChunkEnsure PARAMS((HTChunk * ch, int s));
2.18 ! frystyk 84: </PRE>
2.1 timbl 85:
2.18 ! frystyk 86: <H2>Append a character to a chunk</H2>
2.1 timbl 87:
2.18 ! frystyk 88: Add the character and increment the size of the chunk by one character
! 89:
! 90: <PRE>
! 91: extern void HTChunkPutc PARAMS((HTChunk * ch, char c));
2.6 timbl 92: </PRE>
2.1 timbl 93:
2.18 ! frystyk 94: <H2>Append a string to a chunk</H2>
! 95:
! 96: Add the string and increment the size of the chunk by the length of
! 97: the string (without the trailing zero)
2.1 timbl 98:
2.18 ! frystyk 99: <PRE>
! 100: extern void HTChunkPuts PARAMS((HTChunk * ch, const char *str));
2.6 timbl 101: </PRE>
2.18 ! frystyk 102:
! 103: <A NAME="Terminate"><H2>Zero Terminate a chunk</H2></A>
! 104:
! 105: As a chunk often is a dynamic string, it needs to be terminated by a
! 106: zero in order to be used in C. However, <B>by default</B> any chunk
! 107: <EM>is</EM> always zero terminated, so the only purpose of this
! 108: function is to increment the size counter with one corresponding to
! 109: the zero.
2.6 timbl 110:
111: <PRE>
2.18 ! frystyk 112: extern void HTChunkTerminate PARAMS((HTChunk * ch));
! 113: </PRE>
2.1 timbl 114:
2.18 ! frystyk 115: <H2>Return Pointer to Data</H2>
2.1 timbl 116:
2.18 ! frystyk 117: This define converts a chunk to a normal char pointer so that it can
! 118: be parsed to any ANSI C string function.
2.1 timbl 119:
2.18 ! frystyk 120: <PRE>
! 121: #define HTChunkData(me) ((me) ? (me)->data : NULL)
2.6 timbl 122: </PRE>
2.18 ! frystyk 123:
! 124: <H2>Return Current Size</H2>
! 125:
! 126: Returns the current size of the chunk
! 127:
2.6 timbl 128: <PRE>
2.18 ! frystyk 129: #define HTChunkSize(me) ((me) ? (me)->size : -1)
2.6 timbl 130: </PRE>
131:
132: <PRE>
2.18 ! frystyk 133: #endif
! 134: </PRE>
2.1 timbl 135:
2.18 ! frystyk 136: End of Declaration
2.6 timbl 137:
2.18 ! frystyk 138: </BODY>
2.8 timbl 139: </HTML>
Webmaster