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.

• init

  void (*init)(STRING *s, void *data, unsigned long size);
  

  This method initializes the string structure, and has the following parameters:

  
  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.

  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

  Zero (0).

  
  curpos

  Copied from chunk.

  
  cursize

  Copied from chunksize.

  
  dtb

  STRINGDRIVER identity pointer.

• next

  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. It is likely to call the setpos method if the desired character is not in the current chunk.

• setpos

  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.