/* ** (c) COPYRIGHT MIT 1995. ** Please first read the full copyright statement in the file COPYRIGH. */
The Chunk Class defines a way to automatically handle dynamic strings and
other data types. You create a chunk with an initial size and it will then
automatically grow to accommodate added data to the chunk. It is a general
utility module. It is guaranteed that the array is
at all times (and hence is a valid C type string). The method
HTChunkTerminate can be used to explicitly
add a terminating
'\0' and then to include this character in
the chunk size. If left out, the terminating character is not considered
part of the chunk.
Note: The names without a "_" (made as a
only provided for backwards compatibility and should not be used.
This module is implemented by HTChunk.c, and it is a part of the W3C Sample Code Library.
#ifndef HTCHUNK_H #define HTCHUNK_H
Create a new chunk and specify the number of bytes to allocate at a time when the chunk is later extended. Arbitrary but normally a trade-off time vs. memory
typedef struct _HTChunk HTChunk; extern HTChunk * HTChunk_new (int growby);
Free a chunk created by
extern void HTChunk_delete (HTChunk * ch);
Keep the chunk in memory but clear all data kept inside. This can be used if you know that you can reuse the allocated memory instead of allocating new memory. This zeros out all the allocated data (even data past the indicated size) and sets the size of the chunk to 0. If you have not used any bytes past the indicated size, it is more efficient to truncate the chunk to 0 instead.
extern void HTChunk_clear (HTChunk * ch);
Make sure that a chunk has enough memory allocated to grow by the indicated extra size. If this is not the case, then the chunk is expanded (in multiples of the chunk's "growby" size). Nothing is done if the current size plus the requested extra space fits within the chunk's currently allocated memory.
extern void HTChunk_ensure (HTChunk * ch, int extra_size);
Add the character and increment the size of the chunk by one character
extern void HTChunk_putc (HTChunk * ch, char c);
Add the string and increment the size of the chunk by the length of the string (without the trailing zero)
extern void HTChunk_puts (HTChunk * ch, const char *str);
Add the block and increment the size of the chunk by the len
extern void HTChunk_putb (HTChunk * ch, const char *block, int len);
This define converts a chunk to a normal char pointer so that it can be parsed to any ANSI C string function.
extern char * HTChunk_data (HTChunk * ch);
Returns the current size of the chunk
extern int HTChunk_size (HTChunk * ch);
If you want to cut off a piece of a chunk or extend it to make room
for some direct buffer manipulation, then you can use one of these
functions. Both of these calls set the size of the chunk to be
size, but the truncate call only allows you to make the
string shorter. If the string is made shorter, the formerly-used bytes
are cleared, so truncating a chunk to 0 is analogous to clearing it,
but slightly more efficient.
extern BOOL HTChunk_truncate (HTChunk * ch, int size); extern BOOL HTChunk_setSize (HTChunk * ch, int size);
As a chunk often is a dynamic string, it needs to be terminated by a zero in order to be used in C. However, by default any chunk is always zero terminated, so the only purpose of this function is to increment the size counter with one corresponding to the zero.
extern void HTChunk_terminate (HTChunk * ch);
A Chunk may be built from an allocated string. The chunk assumes control
of the passed string, eliminating the need for additional allocations and
When you take control of the CString from a chunk, the chunk is destroyed.
extern HTChunk * HTChunk_fromCString (char * str, int grow); extern char * HTChunk_toCString (HTChunk * ch);
A Chunk may be built from an allocted buffer. You must specify how much memory is allocated in the buffer (buflen) and what the size the new Chunk should be (size). All memory between size and buflen is zeroed. Note that is is legal to specify a size equal to the buflen if you don't expect the Chunk to be null terminated. The chunk takes control of the memory, and will free it when the Chunk is destroyed. Note that in order to avoid conflicts, the buffer's memory should be allocated using libwww's dedicated functions.
extern HTChunk * HTChunk_fromBuffer (char * buf, int buflen, int size, int grow);
Don't use these in new applications
#define HTChunkCreate(growby) HTChunk_new(growby) #define HTChunkFree(ch) HTChunk_delete(ch) #define HTChunkClear(ch) HTChunk_clear(ch) #define HTChunkEnsure(ch, s) HTChunk_ensure((ch), (s)) #define HTChunkPutc(ch, c) HTChunk_putc((ch), (c)) #define HTChunkPuts(ch, str) HTChunk_puts((ch), (str)) #define HTChunkTerminate(ch) HTChunk_terminate(ch) #define HTChunkData(ch) HTChunk_data(ch) #define HTChunkSize(ch) HTChunk_size(ch)