The ovm_vstr_t type

The ovm_vstr_t type is the OrchIDS type of virtual character strings. Strings are fixed-size arrays of chars, and are implemented as the ovm_str_t type. On the opposite, virtual character strings are merely pointers to a subinterval of an actual character string.

It is defined this way in src/lang.h:

typedef struct ovm_vstr_s ovm_vstr_t;
struct ovm_vstr_s
{
  gc_header_t gc;
  ovm_var_t *delegate;
  size_t    len;
  char     *str;
};

Typically, the delegate field will be a non-NULL object of type ovm_str_t, holding a character string; the str field points into the latter string, and the len field is meant to tell how many bytes we wish to actually consider for a substring.  In general, if the delegate field is non-NULL, it should be an object that should be marked by the garbage collector if we wish the str field to keep pointing to some valid string.  For example, in issdl_vstr_from_regex, the delegate field is made to point to an object of type ovm_regex_t, and the str field points into its regex_str string.

If the delegate field is NULL, then the str field must point into some global, constant array of chars. Don’t make it point to any other kind of data: if you deallocate the latter (either manually, or if you let the garbage collector do it), str will be left as a dangling pointer.

The type ovm_vstr_t is a type of garbage-collectable data. To allocate a new object of type ovm_vstr_t, use the function:

ovm_var_t *ovm_vstr_new(gc_t *gc_ctx, ovm_var_t *delegate);

This creates a new ovm_vstr_t objecvt, with the given delegate. Calling res the result, one always has TYPE(res)==T_VSTR. The actual len and str fields are left uninitialized. One can access them using VSTRLEN(res) and VSTR(res), respectively, both to write into or to read from.

The return type of ovm_vstr_new() is the universal type ovm_var_t instead of ovm_vstr_t, for practical reasons.

The result is created white, and much be gc_touch()ed before storing it into a garbage-collectable object.