String Structures A string structure is analogous to a char*, and is used in some functions as an input argument. It represents a string of data in a way that does not necessarily require the entire string to be in memory at once. This is essential for small machines with highly-restricted memory limits (e.g. DOS). String Structure Access To use a string structure, the caller needs to know a string driver and needs to know the driver-dependent data used by that string structure. A simple string driver is mail_string, a string driver that takes an in-memory char* string as the driver-dependent data. The DOS port uses string drivers that take a struct holding a file descriptor and a file offset. Often the user of a string driver is the same module that defined it, so usually the programmer knows about its conventions. The following calls are used to access a string structure: void INIT (STRING *s,STRINGDRIVER *d,void *data,unsigned long size); s pointer to the string structure to be initialized d pointer to the string driver data pointer to driver-dependent data, from which the driver can determine string data size size of the string This call initializes the string stucture. unsigned long SIZE (STRING *s); s pointer to the string structure This call returns the number of characters remaining in the string after the current string character pointer. char CHR (STRING *s); s pointer to the string structure This call returns the character at the current string character pointer. char SNX (STRING *s); s pointer to the string structure This call returns the character at the current string character pointer, and increments the string character pointer. unsigned long GETPOS (STRING *s); s pointer to the string structure i new string pointer value This returns the value of the current string character pointer. void SETPOS (STRING *s,unsigned long i); s pointer to the string structure i new string pointer value This method sets the string character pointer to the given value. String Structure Internals A string structure holds the following data: void *data; used by the string driver as it likes unsigned long data1; used by the string driver as it likes unsigned long size; static, holds the total length of the string from the INIT call char *chunk; current chunk of in-memory data; this is used for buffering to avoid unnecessary calls to the string driver's next method. unsigned long chunksize; size of an in-memory data chunk unsigned long offset; position of first character of the chunk in the overall string char *curpos; current position; this is what CHR() will access unsigned long cursize; number of characters remaining in the current string STRINGDRIVER *dtb; the string driver for this string structure A string structure is manipulated by a string driver, which has the following access methods: void (*init) (STRING *s,void *data,unsigned long size); s pointer to the string structure to be initialized data pointer to driver-dependent data, from which the driver can determine string data size size of the string This method initializes the string stucture. It can use the data, data1, and chunksize values as it likes. The remaining values must be set up as follows: size static, copied from the size argument chunk pointer to a buffer loaded with initial data chunksize size of the buffer offset 0 curpos copied from chunk cursize copied from chunksize dtb STRINGDRIVER identity pointer char (*next) (STRING *s); s pointer to the string structure This method returns the character at the current string character pointer, and increments the string character pointer. This method is likely to call the setpos method if the desired character is not in the current chunk. void (*setpos) (STRING *s,unsigned long i); s pointer to the string structure i new string pointer value This method sets the string character pointer to the given value. If the pointer is not in the current chunk, then a new chunk is loaded and the associated values (chunk, offset, curpos, cursize) are adjusted accordingly.