The ovm_vbstr_t type

The ovm_vbstr_t type is the OrchIDS type of virtual binary strings. Binary strings are fixed-size arrays of bytes, and are implemented as the ovm_bstr_t type.  On the opposite, virtual binary strings are merely pointers to a subinterval of an actual binary string.

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

typedef struct ovm_vbstr_s ovm_vbstr_t;
struct ovm_vbstr_s
{
  gc_header_t gc;
  ovm_var_t *delegate;
  size_t    len;
  uint8_t  *str;
};

Typically, the delegate field will be a non-NULL object of type ovm_bstr_t, holding a binary 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 data at all.

If the delegate field is NULL, then the str field must point into some global, constant array of bytes.  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_vbstr_t is a type of garbage-collectable data. To allocate a new object of type ovm_vbstr_t, use the function:

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

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

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

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