Vector expression C reference

These are private interfaces in rbcVectorInt.h, not installed stubs entries. See Vector expression evaluation for temporary ownership and Tcl callback boundaries.

The caller keeps the interpreter and vector subsystem alive across Tcl substitutions and map callbacks. A successful evaluated temporary is owned by the caller and released with Rbc_VectorFree(); a destination passed to assignment remains caller-owned. The internal helpers described in Expression engine internal C reference do not replace these entry-point contracts.

int Rbc_VectorEvaluate(Tcl_Interp *interp, char *string, VectorObject **resultPtr)

Evaluate an expression once into an owned, unregistered vector temporary.

The temporary has no registered command or mapped array. Final values must be finite. Tcl substitutions and map callbacks can have arbitrary side effects; failure cleans up the temporary but does not undo those effects. The caller keeps the interpreter and its vector subsystem alive throughout evaluation and until the returned temporary has been released.

Parameters:
  • interp – Owning interpreter, used for lookup, Tcl evaluation and errors.

  • string – NUL-terminated expression buffer, kept valid throughout the call. The parser temporarily edits delimiters and restores them; storage must be writable.

  • resultPtr – Required output pointer, set to NULL before evaluation.

Returns:

TCL_OK with an owned real or complex vector, or TCL_ERROR with no returned vector. Release a successful result with Rbc_VectorFree.

int Rbc_ExprVector(Tcl_Interp *interp, char *string, Rbc_Vector *vecPtr)

Evaluate an expression and copy it to an existing vector or return a Tcl list.

Evaluates into a detached temporary before writing the destination. Checks writability before evaluation and again before copying, and observes destination destruction during Tcl substitutions or map callbacks. Copies matching types or promotes real values into an existing complex destination; a complex result cannot be stored in a real destination. Named vector type is unchanged. Callback side effects are not rolled back on failure.

Does not flush a mapped-array cache or notify destination clients. The instance expr operation performs those steps after successful return. The caller must keep the interpreter and vector subsystem alive; the destruction observer protects destination identity, not interpreter lifetime.

Parameters:
  • interp – Owning interpreter, kept alive by the caller during evaluation.

  • string – NUL-terminated writable expression buffer, valid for the call.

  • vecPtr – Existing destination in this interpreter, or NULL for list output.

Returns:

TCL_OK on success, otherwise TCL_ERROR with a diagnostic. With NULL destination the interpreter result is a list of numbers or complex pairs. Destination form does not promise a particular successful Tcl result.

Registry initialization

These routines populate separate tables during vector-subsystem setup. Table keys are owned by Tcl; stored descriptors and procedure pointers are borrowed. Destroying the tables must not free these static values. Registration does not execute callbacks or transfer ownership of any vectors.

void Rbc_VectorInstallMathFunctions(Tcl_HashTable *tablePtr)

Register the built-in expression function descriptors.

Stores borrowed pointers into the static mathFunctions table, replacing entries with matching names. The hash table owns its keys but must not free descriptor values. This installs adapters and their clientData together; it does not evaluate a function.

Parameters:
  • tablePtr – [inout] Initialized string-key table owned by the vector subsystem.

void Rbc_VectorInstallSpecialIndices(Tcl_HashTable *tablePtr)

Register the built-in numeric special indices.

Installs min, max, mean, sum and prod callbacks, replacing entries with matching names. Callback pointers are borrowed and have no per-entry allocation to release. Special-index invocation and expression reduction are distinct callers even when they share a numerical helper.

Parameters:
  • tablePtr – [inout] Initialized string-key table owned by the vector subsystem.