Vector access C reference

These declarations are private to RBC. See Vector names, indices and mapped arrays.

Parameter directions and Tcl ownership follow C calling conventions. Indices in these contracts are zero-based storage positions unless explicitly identified as external indices. Selection and append sentinels require caller validation before storage access.

void Rbc_VectorFlushCache(VectorObject *vPtr)

Discard cached array elements while retaining the current mapping.

Discard cached Tcl array entries while retaining vector data.

Preserves the vector and interpreter across variable traces. Reinstalls the end entry and RBC trace only while the same mapping remains live. This void helper does not notify clients, report trace errors, or save the Tcl result.

Discard cached array elements while retaining the current mapping.

Return immediately for an unmapped/destroying vector or deleted interpreter. Otherwise preserve the record and interpreter, copy the mapping name/flags, remove RBC’s trace and unset the array. User traces can destroy or remap the vector. Recreate the end entry and reinstall RBC’s trace only while the saved association still matches, rechecking after each callback-capable write. Release the copied name and preservation references on completion. The void interface does not propagate unset/write/trace status or preserve the Tcl result. No vector values are changed or client notification requested here; user-trace side effects are not rolled back.

Parameters:
  • vPtr – [inout] Borrowed live vector record on its owning interpreter thread; this call does not transfer ownership.

VectorObject *Rbc_VectorParseElement(Tcl_Interp *interp, VectorInterpData *dataPtr, const char *start, const char **endPtr, int flags)

Resolve a vector name and optional range into a borrowed vector.

Resolve the longest registered name and optional balanced selection.

Prefers the longest existing name at a balanced-parenthesis boundary, so parentheses may belong to the name itself. Sets the shared first/last selection; restores it on range or trailing-text errors. With endPtr, returns the unconsumed suffix there; without it, requires complete consumption. Returns NULL on failure. Index expressions may evaluate Tcl; no lifetime reference is acquired for the returned object.

Resolve a vector name and optional range into a borrowed vector.

Searches balanced name boundaries using the requested namespace flags, so exact literal parenthesized names take precedence over range suffixes. Defaults to the whole-vector selection, then parses any following parenthesized range from a retained copy while preserving the vector record. Restores the previous selection on range failure if the vector survives. With endPtr returns a borrowed pointer into the original string for expression parsing; without it rejects trailing text and restores selection. Returns a borrowed vector or NULL. Does not modify the input, create a slice object or retain the result for later callbacks.

Parameters:
  • interp – [in] Diagnostic interpreter, or NULL to suppress lookup diagnostics; see Interpreter arguments.

  • dataPtr – [in] Live owning interpreter registry, retained by the caller through index evaluation.

  • start – [in] NUL-terminated reference buffer, valid throughout the call.

  • endPtr – [out] Optional unconsumed-suffix output, written only on success; aliases start storage.

  • flags – [in] Namespace search mask: NS_SEARCH_CURRENT, NS_SEARCH_GLOBAL or NS_SEARCH_BOTH.

Returns:

Borrowed vector with committed selection, or NULL on failure.

int Rbc_VectorMapVariable(Tcl_Interp *interp, VectorObject *vPtr, const char *name)

Replace or remove a vector’s mapped Tcl array.

Replace a vector array mapping with callback-aware lifetime checks.

An empty or NULL name unmaps; parentheses in mapping names are rejected. Unsets the old mapping and target variable, creates an end entry, and installs RBC traces. Preserves the vector/interpreter and checks destruction or reentrant remapping after trace-capable operations. Returns TCL_OK or TCL_ERROR; failure does not restore the previous mapping.

Replace or remove a vector’s mapped Tcl array.

Borrow the live vector, interpreter and name; NULL or empty names request unmapping. Reject parentheses before changing an existing association. Copy the requested name and preserve the vector/interpreter while unmapping the old array, unsetting the target variable and creating its end entry. After callback boundaries, reject destruction or a competing reentrant mapping. On a successful initial write install RBC’s read/write/unset trace. Store the requested name even when that initial write fails, and return its Tcl status; a failure does not restore the old mapping or undo user trace effects. This changes the Tcl access surface, not vector storage or command identity. Callers must not infer that preservation keeps destroyed storage valid.

Parameters:
  • interp – [inout] Borrowed interpreter for lookup, evaluation and diagnostics; caller keeps it valid throughout the call.

  • vPtr – [inout] Borrowed live vector record on its owning interpreter thread; this call does not transfer ownership.

  • name – [in] Borrowed array name, copied before callbacks; NULL or empty removes the current mapping. Parentheses are rejected.

int Rbc_VectorGetIndex(Tcl_Interp *interp, VectorObject *vPtr, const char *string, Tcl_Size *indexPtr, int flags, Rbc_VectorIndexProc **procPtrPtr)

Translate an external index into a storage index or special callback.

Translate an external index with optional Tcl expression evaluation.

Numeric indices subtract the vector offset with overflow checks. end-based indices are relative to length; ++end denotes the append position. INDEX_CHECK bounds ordinary indices; callers must handle append and special indices separately. An optional procPtrPtr receives a registered special index procedure and indexPtr receives SPECIAL_INDEX. Expression fallback evaluates Tcl in the owning interpreter even with NULL diagnostic interp. Returns TCL_OK or TCL_ERROR. Retains the vector/interpreter during expression evaluation and rejects destruction before using its result.

Translate an external index into a storage index or special callback.

Requires a live vector, NUL-terminated string and output index. Clears an optional special-procedure output initially. Empty input fails; end-prefixed forms use Tcl_GetIntForIndex and always check bounds; ++end returns length. Registered special names are recognized only with a procedure output and return SPECIAL_INDEX without calling the procedure. Other input is parsed as Tcl_Size or evaluated in the owning interpreter, then subtracts the current external offset with overflow checks. INDEX_CHECK enforces the upper bound for ordinary numeric indices. Retains vector/interpreter during evaluation and rejects deletion; a NULL diagnostic interpreter does not disable evaluation. Writes indexPtr only on success. Callers must distinguish append/special indices from dereferenceable storage indices.

Parameters:
  • interp – [in] Optional diagnostic interpreter; see Interpreter arguments.

  • vPtr – [inout] Live vector supplying length, offset and owning evaluation interpreter.

  • string – [in] NUL-terminated index text, valid throughout evaluation.

  • indexPtr – [out] Required output, written only on success; may be an append or special sentinel.

  • flags – [in] INDEX_CHECK requests ordinary numeric upper-bound validation.

  • procPtrPtr – [out] Optional callback output, cleared on entry and set for a registered special name.

Returns:

TCL_OK for a recognized index; TCL_ERROR for conversion, bounds or destruction failure.

int Rbc_VectorGetIndexRange(Tcl_Interp *interp, VectorObject *vPtr, const char *string, int flags, Rbc_VectorIndexProc **procPtrPtr)

Set the vector’s inclusive first/last selection.

Parse and commit an inclusive shared selection.

INDEX_COLON enables first:last syntax with omitted endpoints. A single index selects one value. Commits selection only after both endpoints and ordering succeed; returns TCL_ERROR otherwise. Selection is shared mutable object state, not a retained slice. Callers must handle empty vectors and special/append indices before accessing storage. Index conversion may run Tcl.

Set the vector’s inclusive first/last selection.

With INDEX_COLON uses the first colon as the separator; omitted endpoints mean storage zero and the current final index, with zero used for an empty upper endpoint. Otherwise parses one index and sets both endpoints. Range endpoints do not accept registered special procedures. Does not modify the input buffer. Parses endpoints into locals, validates ordering and, for a nonempty checked vector, current bounds before committing first/last. Expression callbacks may themselves change selection, values or length and are not rolled back. Returns a Tcl status. This helper does not turn empty, append or special selections into valid storage intervals; callers validate before accessing data.

Parameters:
  • interp – [in] Optional diagnostic interpreter; see Interpreter arguments.

  • vPtr – [inout] Live vector whose shared first/last selection is committed on success.

  • string – [in] NUL-terminated index or range text, unchanged by the parser.

  • flags – [in] INDEX_COLON enables ranges; INDEX_CHECK requests numeric bounds validation.

  • procPtrPtr – [out] Optional special-index callback output, cleared on entry; ranges leave it NULL.

Returns:

TCL_OK after committing selection, otherwise TCL_ERROR; callback side effects are not undone.

int Rbc_GetDouble(Tcl_Interp *interp, Tcl_Obj *objPtr, double *valuePtr)

Convert an object to a double, with Tcl expression fallback.

Tries Tcl_GetDoubleFromObj first, then clears its error and calls Tcl_ExprDoubleObj. Returns a Tcl status. Expression evaluation can execute commands; callers own lifetime and writable-state checks after conversion.

Parameters:
  • interp – [in] Evaluation and diagnostic interpreter; see Interpreter arguments.

  • objPtr – [in] Input value or expression, kept alive by the caller through evaluation.

  • valuePtr – [out] Required double output; consume it only after TCL_OK.

Returns:

TCL_OK on conversion, otherwise TCL_ERROR with an interpreter diagnostic.

int Rbc_GetComplex(Tcl_Interp *interp, Tcl_Obj *objPtr, Rbc_Complex *valuePtr)

Convert a two-item list or a real scalar to a complex value.

Each pair component uses Rbc_GetDouble; scalar input receives zero imaginary part. Returns a Tcl status. Conversion may execute Tcl and can modify the real output component before failure of the imaginary component.

Parameters:
  • interp – [in] Evaluation and diagnostic interpreter; see Interpreter arguments.

  • objPtr – [in] Input pair or scalar, kept alive by the caller through component evaluation.

  • valuePtr – [out] Required output; its real component may be written before imaginary conversion fails.

Returns:

TCL_OK with both components, otherwise TCL_ERROR; the output is not transactional.

Tcl_Obj *Rbc_NewComplexObj(Rbc_Complex value)

Create a reference-count-zero two-double Tcl list.

The result owns copies of the real and imaginary values; the caller follows normal Tcl object ownership rules.

Parameters:
  • value – [in] Real and imaginary components copied into the result.

Returns:

New two-element Tcl list with reference count zero; no vector storage is borrowed.

Tcl_Obj *Rbc_NewVectorValueObj(VectorObject *vPtr, Tcl_Size index)

Create a reference-count-zero Tcl value for one storage index.

Returns a double for real vectors or a two-double list for complex vectors. The caller supplies a live vector and valid zero-based index. Does not check bounds and does not expose or retain vector storage.

Parameters:
  • vPtr – [in] Live real or complex source with valid storage.

  • index – [in] Valid zero-based storage index, independent of the external offset and selection.

Returns:

New reference-count-zero Tcl double or complex pair containing a copy.

Tcl_Obj *Rbc_GetValues(VectorObject *vPtr, Tcl_Size first, Tcl_Size last)

Copy an inclusive storage interval into a new Tcl list.

Copy an inclusive storage interval into a Tcl list.

Returns a reference-count-zero list, empty when first exceeds last. The caller validates storage bounds and lifetime. Complex entries are pairs; real entries are doubles. Does not change the vector selection.

Copy an inclusive storage interval into a new Tcl list.

Requires live storage and caller-validated bounds. Appends a newly copied scalar or complex pair for each zero-based index, without consulting the external offset or changing selection. Returns a new reference-count-zero list, empty for a reversed interval. No storage is shared with the returned values and no observers are notified.

Parameters:
  • vPtr – [in] Live real or complex source, kept valid throughout copying.

  • first – [in] First zero-based storage index; validated by the caller when the interval is nonempty.

  • last – [in] Inclusive final storage index; values below first produce an empty list.

Returns:

New reference-count-zero Tcl list of copied values.

Tcl_Size *Rbc_VectorSortIndex(VectorObject **vPtrPtr, Tcl_Size nVectors)

Allocate a lexicographic permutation for real vector keys.

Allocate an ascending permutation for a real-vector selection.

Requires nVectors greater than zero, live vectors, and valid storage for every index in the first vector’s inclusive selection. Returns a Tcl-allocated index array for the caller to free, including an allocation for an empty successful sort; NULL reports failure in the first vector’s interpreter. Does not reorder data. Heap sorting is not stable; comparisons do not define a total ordering for NaNs. Complex keys are rejected.

Allocate a lexicographic permutation for real vector keys.

Requires at least one live vector and valid corresponding indices in every key vector. Rejects complex keys, uses the first vector selection to build storage indices, and sorts them lexicographically without moving values. Returns an owned allocation to free with ckfree, including a non-NULL allocation for an empty successful sort; NULL denotes failure. Does not check key lengths or retain vectors. Ordering is unstable and NaNs do not form a total order.

Parameters:
  • vPtrPtr – [in] Array of live real key vectors in primary-to-secondary comparison order.

  • nVectors – [in] Positive array length; all keys must cover the first vector’s selected storage indices.

Returns:

Owned Tcl-allocated index array, released with ckfree, or NULL on failure.

void Rbc_ReplicateValue(VectorObject *vPtr, Tcl_Size first, Tcl_Size last, double value)

Overwrite an inclusive interval of real storage.

Requires a live real vector, writable destination and valid zero-based bounds, all checked by the caller. Reversed intervals do no work. Performs only direct assignments: does not enforce read-only state, resize, invalidate extrema, flush mapped arrays, increment dirty or notify clients. Callers must publish the change separately.

Parameters:
  • vPtr – [inout] Live writable real vector; caller enforces protection and publishes the change.

  • first – [in] First zero-based storage index, validated by the caller for a nonempty interval.

  • last – [in] Inclusive final storage index; a reversed interval performs no writes.

  • value – [in] Double assigned to every selected storage slot.

void Rbc_VectorUpdateRange(VectorObject *vPtr)

Recompute whole-vector finite extrema and their first indices.

Scans real storage in ascending index order, ignores NaNs and infinities, and keeps the earliest index on equal extrema. Empty or entirely nonfinite real vectors, and all complex vectors, receive NaN bounds and indices -1. Clears UPDATE_RANGE after installing the cache. Requires live valid storage; does not change values, selection, dirty count or notifications.

Parameters:
  • vPtr – [inout] Live vector whose whole-storage extrema cache and invalidation flag are updated.

Scalar complex helpers

These private helpers copy scalars by value. They neither allocate vector storage nor invoke Tcl callbacks. Arithmetic results are not checked for finiteness; callers choose their own error policy. See Vector queries and numerical generators.

Rbc_Complex Rbc_ComplexFromReal(double value)

Promote a real scalar without allocation.

Parameters:
  • value – [in] Real component copied into the result.

Returns:

Complex value with the supplied real component and zero imaginary component.

int Rbc_ComplexIsZero(Rbc_Complex value)

Test both components for exact zero.

Parameters:
  • value – [in] Scalar tested by value; signed zeros compare equal.

Returns:

Nonzero only when both components equal zero; NaNs do not compare equal.

Rbc_Complex Rbc_ComplexAdd(Rbc_Complex a, Rbc_Complex b)

Compute a complex sum without Tcl callbacks.

Parameters:
  • a – [in] Left operand passed by value.

  • b – [in] Right operand passed by value.

Returns:

Complex sum a+b; overflow, underflow and nonfinite results are not reported as errors.

Rbc_Complex Rbc_ComplexSub(Rbc_Complex a, Rbc_Complex b)

Compute a complex difference without Tcl callbacks.

Parameters:
  • a – [in] Left operand passed by value.

  • b – [in] Right operand passed by value.

Returns:

Complex difference a-b; overflow, underflow and nonfinite results are not reported as errors.

Rbc_Complex Rbc_ComplexMul(Rbc_Complex a, Rbc_Complex b)

Compute a complex product without Tcl callbacks.

Parameters:
  • a – [in] Left operand passed by value.

  • b – [in] Right operand passed by value.

Returns:

Complex product a*b; overflow, underflow and nonfinite results are not reported as errors.

Rbc_Complex Rbc_ComplexDiv(Rbc_Complex a, Rbc_Complex b)

Compute a complex quotient without Tcl callbacks.

Uses a ratio-based denominator to reduce avoidable overflow/underflow; it does not guarantee finite results.

Parameters:
  • a – [in] Left operand passed by value.

  • b – [in] Right operand passed by value. Caller must reject an exactly zero divisor.

Returns:

Complex quotient a/b; overflow, underflow and nonfinite results are not reported as errors.

Rbc_Complex Rbc_VectorValueAsComplex(VectorObject *vPtr, Tcl_Size index)

Copy one storage value with real-to-complex promotion.

Parameters:
  • vPtr – [in] Live real or complex source; no lifetime reference is acquired.

  • index – [in] Valid zero-based storage index supplied by the caller, independent of offset and selection.

Returns:

Copied complex scalar; real sources receive zero imaginary part.