1 /*
2  * $LynxId: HTChunk.h,v 1.20 2010/09/24 08:37:39 tom Exp $
3  *
4  *				     HTChunk: Flexible array handling for libwww
5  *					CHUNK HANDLING:
6  *					FLEXIBLE ARRAYS
7  *
8  * This module implements a flexible array.  It is a general utility module.  A
9  * chunk is a structure which may be extended.	These routines create and
10  * append data to chunks, automatically reallocating them as necessary.
11  *
12  */
13 #ifndef HTCHUNK_H
14 #define HTCHUNK_H 1
15 
16 #ifndef HTUTILS_H
17 #include <HTUtils.h>
18 #endif
19 
20 #include <UCMap.h>
21 
22 #ifdef __cplusplus
23 extern "C" {
24 #endif
25     typedef struct _HTChunk HTChunk;
26 
27     struct _HTChunk {
28 	int size;		/* In bytes                     */
29 	int growby;		/* Allocation unit in bytes     */
30 	int allocated;		/* Current size of *data        */
31 	char *data;		/* Pointer to malloc'd area or 0 */
32 	int failok;		/* allowed to fail without exiting program? */
33 	HTChunk *next;		/* pointer to the next chunk */
34     };
35 
36 /*
37  * Initialize a chunk's allocation data and allocation-increment.
38  */
39     extern void HTChunkInit(HTChunk *ch, int grow);
40 
41 /*
42  *
43  * Create new chunk
44  *
45  *   ON ENTRY,
46  *
47  *   growby		The number of bytes to allocate at a time when the chunk
48  *			is later extended.  Arbitrary but normally a trade-off
49  *			of time vs memory.
50  *
51  *   ON EXIT,
52  *
53  *   returns		A chunk pointer to the new chunk,
54  *
55  */
56 
57     extern HTChunk *HTChunkCreate(int growby);
58 
59 /*
60  *  Create a chunk for which an allocation error is not a fatal application
61  *  error if failok != 0, but merely resets the chunk.  When using a chunk
62  *  created this way, the caller should always check whether the contents
63  *  are ok each time after data have been appended.
64  *  The create call may also fail and will reurn NULL in that case. - kw
65  */
66     extern HTChunk *HTChunkCreateMayFail(int growby, int failok);
67 
68 /*
69  *  Like HTChunkCreate but with initial allocation - kw
70  *
71  */
72     extern HTChunk *HTChunkCreate2(int growby, size_t needed);
73 
74 /*
75  *
76  * Free a chunk
77  *
78  *   ON ENTRY,
79  *
80  *   ch			A valid chunk pointer made by HTChunkCreate()
81  *
82  *   ON EXIT,
83  *
84  *   ch			is invalid and may not be used.
85  *
86  */
87 
88     extern void HTChunkFree(HTChunk *ch);
89 
90 /*
91  *
92  * Clear a chunk
93  *
94  *   ON ENTRY,
95  *
96  *   ch			A valid chunk pointer made by HTChunkCreate()
97  *
98  *   ON EXIT,
99  *
100  *   *ch		The size of the chunk is zero.
101  *
102  */
103 
104     extern void HTChunkClear(HTChunk *ch);
105 
106 /*
107  *
108  * Realloc a chunk
109  *
110  *   ON ENTRY,
111  *
112  *   ch			A valid chunk pointer made by HTChunkCreate()
113  *
114  *   growby		growby
115  *
116  *   ON EXIT,
117  *
118  *   *ch		Expanded by growby
119  *
120  */
121 
122     extern BOOL HTChunkRealloc(HTChunk *ch, int growby);
123 
124 /*
125  *
126  * Ensure a chunk has a certain space in
127  *
128  *   ON ENTRY,
129  *
130  *   ch			A valid chunk pointer made by HTChunkCreate()
131  *
132  *   s			The size required
133  *
134  *   ON EXIT,
135  *
136  *   *ch		Has size at least s
137  *
138  */
139 
140     extern void HTChunkEnsure(HTChunk *ch, int s);
141 
142 /*
143  *
144  * Append a character to a  chunk
145  *
146  *   ON ENTRY,
147  *
148  *   ch			A valid chunk pointer made by HTChunkCreate()
149  *
150  *   c			The character to be appended
151  *
152  *   ON EXIT,
153  *
154  *   *ch		Is one character bigger
155  *
156  */
157     extern void HTChunkPutc(HTChunk *ch, unsigned c);
158 
159     extern void HTChunkPutb(HTChunk *ch, const char *b, int l);
160 
161     extern void HTChunkPutUtf8Char(HTChunk *ch, UCode_t code);
162 
163 /*
164  * Append a string to a  chunk
165  *
166  *   ON ENTRY,
167  *
168  *   ch			A valid chunk pointer made by HTChunkCreate()
169  *
170  *   str		Points to a zero-terminated string to be appended
171  *
172  *   ON EXIT,
173  *
174  *   *ch		Is bigger by strlen(str)
175  *
176  */
177 
178     extern void HTChunkPuts(HTChunk *ch, const char *str);
179 
180 /*
181  *
182  * Append a zero character to a  chunk
183  *
184  */
185 
186 /*
187  *
188  *   ON ENTRY,
189  *
190  *   ch			A valid chunk pointer made by HTChunkCreate()
191  *
192  *   ON EXIT,
193  *
194  *   *ch		Is one character bigger
195  *
196  */
197 
198     extern void HTChunkTerminate(HTChunk *ch);
199 
200 /* like the above but no realloc: extend to another chunk if necessary */
201 /*
202  *
203  * Append a character (string, data) to a chunk
204  *
205  *   ON ENTRY,
206  *
207  *   ch                        A valid chunk pointer made by HTChunkCreate()
208  *
209  *   c                 The character to be appended
210  *
211  *   ON EXIT,
212  *
213  *   returns           original chunk or a pointer to the new chunk
214  *                     (orginal chunk is referenced to the new one
215  *                     by the field 'next')
216  *
217  */
218     extern HTChunk *HTChunkPutc2(HTChunk *ch, int c);
219     extern HTChunk *HTChunkPuts2(HTChunk *ch, const char *str);
220     extern HTChunk *HTChunkPutb2(HTChunk *ch, const char *b, int l);
221 
222 /* New pool infrastructure: UNlike the above, store data using alignment */
223     extern HTChunk *HTChunkPutb0(HTChunk *ch, const char *b, int l);
224 
225 #ifdef __cplusplus
226 }
227 #endif
228 #endif				/* HTCHUNK_H */
229