Vector numerical operation C reference
These private handlers are implemented in rbcVecCmd.c. Their runtime limitations are described in
Vector indexed edits and rearrangement.
Instance handlers receive the full command argument array: command name at objv[0], operation at objv[1], then
operation arguments. The dispatcher retains the receiver and interpreter; callbacks can still destroy their logical
state. See C calling conventions and Vector instance commands and binary input.
- group Vector queries and numerical generators
Queries and generators with callback-aware storage ownership.
Functions
-
static int GetArithmeticScalar(Tcl_Interp *interp, Tcl_Obj *objPtr, Rbc_Complex *valuePtr, int *isComplexPtr)
Distinguish an explicit complex pair before scalar expression parsing.
Marks a two-item Tcl list as complex even if the imaginary part is zero, then delegates conversion to Rbc_GetComplex. Thus a pair such as {3 -4} is not treated as the arithmetic expression 3-4. Returns a Tcl status; conversion may execute Tcl and partially populate the output on failure.
- Parameters:
interp – [in] Evaluation interpreter; see Interpreter arguments.
objPtr – [in] Borrowed scalar or pair kept alive through component evaluation.
valuePtr – [out] Required complex output; may be partially written on conversion failure.
isComplexPtr – [out] Required flag, set from pair syntax before conversion, not from the imaginary value.
- Returns:
TCL_OK on conversion, otherwise TCL_ERROR; consume valuePtr only on success.
-
static int ComplexArithmetic(Tcl_Interp *interp, int operator, Rbc_Complex a, Rbc_Complex b, Rbc_Complex *resultPtr)
Apply one supported arithmetic operator to two complex scalars.
Accepts +, -, * and /. Returns TCL_ERROR with divide-by-zero diagnostic for an exactly zero complex divisor; otherwise writes resultPtr and returns TCL_OK. An unsupported internal operator panics. Does not invoke callbacks.
- Parameters:
interp – [in] Diagnostic interpreter; see Interpreter arguments.
operator – [in] Character code for +, -, * or /.
a – [in] Left operand copied by value.
b – [in] Right operand; a zero divisor is rejected for division.
resultPtr – [out] Required result output, unchanged for rejected division by zero.
- Returns:
TCL_OK after arithmetic, or TCL_ERROR for zero division; finiteness is not guaranteed.
-
static int ArithOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const *objv)
Return element-wise arithmetic as a Tcl list without assigning it.
Resolves a vector operand before scalar conversion. A vector selection must match receiver length; scalars are broadcast. Produces complex pairs if either operand is complex, otherwise doubles. Real arithmetic uses native double operators; complex division explicitly rejects a zero divisor. Returns a Tcl status. Rechecks receiver lifetime after operand evaluation; arithmetic then reads current storage without callbacks. Owns the result list through error cleanup, including complex division failure.
See also
- Parameters:
vPtr – [inout] Receiver retained by the dispatcher; this handler’s contract specifies any mutation.
interp – [in] Owning interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] 3; validated by the dispatcher.
objv – [in] Borrowed full command argument array. objv[1] selects +, -, * or /; objv[2] is a vector reference or scalar operand. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK with a list of copied arithmetic results, otherwise TCL_ERROR.
-
static int NormalizeOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Normalize real values by the cached source minimum and range.
Computes (value-min)/(max-min) after refreshing source extrema. Without a destination, returns a Tcl list and does not modify the receiver. Otherwise creates/resizes a real destination, fills it, and flushes/notifies existing outputs. No explicit zero-range or finite-value policy is implemented here. Stages the complete result before output resolution and commits it before invoking storage release or mapping callbacks. Returns a Tcl status.
See also
- Parameters:
vPtr – [inout] Receiver retained by the dispatcher; this handler’s contract specifies any mutation.
interp – [in] Owning interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] 2 for list output, or 3 for vector output.
objv – [in] Borrowed full command argument array. Optional objv[2] is a literal real destination name; no destination means a copied Tcl list. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK with a list or after output publication, otherwise TCL_ERROR.
-
static int RandomOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Replace existing values with samples from the shared random generator.
Keeps length and type. Real entries receive one Rbc_RandomDouble sample; complex entries receive separate samples for real and imaginary components. Samples lie in [0,1); this is not a cryptographic generator. Flushes when configured and reports a full update. The dispatcher checks writable state; skips notification if a cache-flush callback destroys the receiver.
See also
- Parameters:
vPtr – [inout] Receiver retained by the dispatcher; this handler’s contract specifies any mutation.
interp – [in] Owning interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] 2; validated by the dispatcher.
objv – [in] Borrowed full command argument array. No arguments after the operation name; this handler does not inspect the array. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK after replacing existing values and requesting publication.
-
static int RangeOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Return an inclusive interval of copied Tcl values.
Parses both external indices and traverses forward or backward according to their order. Real entries are doubles; complex entries are two-item lists. Returns a Tcl status and a list without writing vector data. Index parsing can evaluate Tcl; revalidates both endpoints and receiver lifetime after evaluation before reading any values. The append position is not readable.
See also
- Parameters:
vPtr – [inout] Receiver retained by the dispatcher; this handler’s contract specifies any mutation.
interp – [in] Owning interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] 4; validated by the dispatcher.
objv – [in] Borrowed full command argument array. objv[2] and objv[3] are inclusive first and last index expressions. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK with copied values, otherwise TCL_ERROR.
-
static int ComplexSearchOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Search for a complex value by matching both scalar components.
Accepts one target only; interval search is rejected. Uses InRange separately for real and imaginary equality. Returns external indices with checked positive offset addition, or pairs with -value. Target conversion may run Tcl; rechecks receiver lifetime before scanning its current storage without further callbacks. Returns a Tcl status.
- Parameters:
vPtr – [inout] Live complex receiver retained by the instance dispatcher with its interpreter.
interp – [in] Owning evaluation interpreter; see Interpreter arguments.
objc – [in] Full command argument count inherited from the delegating handler.
objv – [in] Borrowed full command array. Optional -value at index 2, then exactly one complex target; two-bound searches fail.
- Returns:
TCL_OK on completion, otherwise TCL_ERROR; conversion callbacks can have independent side effects.
-
static int SearchOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Find real values in a tolerant interval or delegate complex matching.
Returns external indices including the offset, or values with -value. One bound means an equality search using InRange tolerance. A sufficiently reversed interval returns TCL_OK without scanning. Checks positive index offset overflow. Bound conversion may evaluate Tcl; checks receiver lifetime afterward and scans current storage without further callbacks. Reversed bounds explicitly return an empty result.
See also
- Parameters:
vPtr – [inout] Receiver retained by the dispatcher; this handler’s contract specifies any mutation.
interp – [in] Owning interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] 3 to 5, subject to the optional flag and target count.
objv – [in] Borrowed full command argument array. Optional -value at objv[2] requests values; remaining arguments specify one target or two real bounds. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK with matching external indices or values, otherwise TCL_ERROR.
-
static int GetComplexSequenceComponentLength(Tcl_Interp *interp, const char *componentName, double start, double finish, double step, int *hasLengthPtr, Tcl_Size *lengthPtr)
Derive one component’s finite, representable sequence count.
Initializes hasLengthPtr false and lengthPtr zero. Rejects nonfinite bounds or step. Zero step is accepted only for equal bounds and leaves the component unconstrained. Otherwise sets hasLengthPtr true and computes trunc((finish-start)/step)+1, clamping nonpositive counts to zero and rejecting excessive counts before integer conversion. Returns a Tcl status.
- Parameters:
interp – [in] Diagnostic interpreter; see Interpreter arguments.
componentName – [in] Borrowed component label used in zero-step diagnostics.
start – [in] First component value, required finite.
finish – [in] Last requested component bound, required finite.
step – [in] Component increment, required finite; zero is allowed only for constant bounds.
hasLengthPtr – [out] Required constraint flag, initialized false; may change before a later size error.
lengthPtr – [out] Required count output, initialized zero; consume both outputs only on TCL_OK.
- Returns:
TCL_OK with an optional count constraint, otherwise TCL_ERROR.
-
static int ComplexSeqOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Generate a complex progression with compatible component lengths.
Defaults step to 1+0i. Numeric finish requires each varying component to imply the same count; a zero-step constant component imposes no count. Both constant components with zero step cannot determine a numeric-finish count. Literal end instead uses current length and permits a zero step. Positive counts resize, fill each component and flush/notify; zero count is a no-op. Rechecks lifetime and writability after argument conversion. Fills prepared storage before committing and releasing the old allocation. Returns a Tcl status.
- Parameters:
vPtr – [inout] Live complex receiver retained by the instance dispatcher with its interpreter.
interp – [in] Owning evaluation interpreter; see Interpreter arguments.
objc – [in] Full command argument count inherited from the delegating handler.
objv – [in] Borrowed full command array. Start at index 2, finish or end at index 3, and optional step at index 4.
- Returns:
TCL_OK on completion, otherwise TCL_ERROR; conversion callbacks can have independent side effects.
-
static int SeqOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Generate a real arithmetic progression or delegate complex generation.
Defaults step to one. Literal end fills the current length; numeric finish uses trunc((finish-start)/step)+1 with finite and size checks. A nonpositive calculated count leaves data unchanged. Positive counts resize and fill values as start+i*step, then flush/notify. The end form bypasses count-derived finite and zero-step validation. Returns a Tcl status; converting arguments may execute Tcl. Rechecks lifetime and writability after conversion, fills prepared storage, and commits before custom storage-release callbacks.
See also
- Parameters:
vPtr – [inout] Receiver retained by the dispatcher; this handler’s contract specifies any mutation.
interp – [in] Owning interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] 4 or 5.
objv – [in] Borrowed full command argument array. objv[2] is start; objv[3] is finish or end; optional objv[4] is step. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK after generation or a zero-count no-op, otherwise TCL_ERROR.
-
static int InRange(double value, double min, double max)
Test scalar membership using the legacy search tolerance.
When max-min is below DBL_EPSILON, compares absolute distance from max strictly below DBL_EPSILON. Otherwise accepts normalized positions at least -DBL_EPSILON and less than one plus DBL_EPSILON. Does not reorder bounds, check finiteness, allocate storage or invoke Tcl. Returns a Boolean integer.
- Parameters:
value – [in] Candidate scalar.
min – [in] Lower bound as supplied; not reordered or checked for finiteness.
max – [in] Upper bound as supplied; used as the equality target for a near-zero or negative range.
- Returns:
Nonzero for membership under the legacy tolerance rule, zero otherwise.
-
static int GetArithmeticScalar(Tcl_Interp *interp, Tcl_Obj *objPtr, Rbc_Complex *valuePtr, int *isComplexPtr)