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:

• INIT

  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 structure.

• SIZE

  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.

• CHR

  char CHR(STRING *s);
  

  
  s

  Pointer to the string structure.

  This call returns the character at the current string character pointer.

• SNX

  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.

• GETPOS

  unsigned long GETPOS(STRING *s, unsigned long i);
  

  
  s

  Pointer to the string structure.

  
  i

  New string pointer value.

  This function returns the value of the current string character pointer.

• SETPOS

  void SETPOS(STRING *s, unsigned long i);
  

  
  s

  Pointer to the string structure.

  
  i

  New string pointer value.

  This function sets the string character pointer to the given value.