3.4 The Variable-length String Data Type

XSB uses variable-length strings to communicate with certain C subroutines when the size of the output that needs to be passed from the Prolog side to the C side is not known. Variable-length strings adjust themselves depending on the size of the data they must hold and are ideal for this situation. For instance, as we have seem the two subroutines xsb_query_string_string(query,buff,sep) and xsb_next_string(buff,sep) use the variable string data type, VarString, for their second argument. To use this data type, make sure that

#include "cinterf.h"

appears at the top of the program file. Variables of the VarString type are declared using a macro that must appear in the declaration section of the program:

XSB_StrDefine(buf);

There is one important consideration concerning VarString with the automatic storage class: they must be destroyed on exit (see XSB_StrDestroy, below) from the procedure that defines them, or else there will be a memory leak. It is not necessary to destroy static VarString's.

The public attributes of the type are int length and char *string. Thus, buf.string represents the actual contents of the buffer and buf.length is the length of that data. Although the length and the contents of a VarString string is readily accessible, the user must not modify these items directly. Instead, he should use the macros provided for that purpose:

• XSB_StrSet(VarString *vstr, char *str):  Assign the value of the regular null-terminated C string to the VarString vstr. The size of vstr is adjusted automatically.
• XSB_StrSetV(VarString *vstr1, VarString *vstr2):  Like XSB_StrSet, but the second argument is a variable-length string, not a regular C string.
• XSB_StrAppend(VarString *vstr, char *str):  Append the null-terminated string str to the VarString vstr. The size of vstr is adjusted.
• XSB_StrPrepend(VarString *vstr, char *str):  Like XSB_StrAppend, except that str is prepended.
• XSB_StrAppendV(VarString *vstr1, VarString *vstr2):  Like XSB_StrAppend, except that the second string is also a VarString.
• XSB_StrPrependV(VarString *vstr1, VarString *vstr2):  Like XSB_StrAppendV, except that the second string is prepended.
• XSB_StrCompare(VarString *vstr1, VarString *vstr2):  Compares two VarString. If the first one is lexicographically larger, then the result is positive; if the first string is smaller, than the result is negative; if the two strings have the same content (i.e., vstr1->string equals vstr2->string then the result is zero.
• XSB_StrCmp(VarString *vstr, char *str):  Like XSB_StrCompare but the second argument is a regular, null-terminated string.
• XSB_StrAppendBlk(VarString *vstr, char *blk, int size):  This is like XSB_StrAppend, but the second argument is not assumed to be null-terminated. Instead, size characters pointed to by blk are appended to vstr. The size of vstr is adjusted, but the content is not null terminated.
• XSB_StrPrependBlk(VarString *vstr, char *blk, int size):  Like XSB_StrPrepend, but blk is not assumed to point to a null-terminated string. Instead, size characters from the region pointed to by blk are prepended to vstr.
• XSB_StrNullTerminate(VarString *vstr):  Null-terminates the VarString string vstr. This is used in conjunction with XSB_StrAppendBlk, because the latter does not null-terminate variable-length strings.
• XSB_StrEnsureSize(VarString *vstr, int minsize):  Ensure that the string has room for at least minsize bytes. This is a low-level routine, which is used to interface to procedures that do not use VarString internally. If the string is larger than minsize, the size might actually shrink to the nearest increment that is larger minsize.
• XSB_StrShrink(VarString *vstr, int increment):  Shrink the size of vstr to the minimum necessary to hold the data. increment becomes the new increment by which vstr is adjusted. Since VarString is automatically shrunk by XSB_StrSet, it is rarely necessary to shrink a VarString explicitly. However, one might want to change the adjustment increment using this macro (the default increment is 128).
• XSB_StrDestroy(VarString *vstr):  Destroys a VarString. Explicit destruction is necessary for VarString's with the automatic storage class. Otherwise, memory leak is possible.