Vector queries and numerical generators

These instance handlers live in rbcVecCmd.c; they are distinct from the expression evaluator in Vector expression evaluation and transform operations in FFT workspace and output ownership. Their C contracts are collected in Vector numerical operation C reference. The callback ownership rules in Vector indexed edits and rearrangement also apply here.

Arithmetic returns values

ArithOp() implements the instance arithmetic operators by constructing a Tcl list. It does not replace the receiver. A vector operand is resolved first and its selected length must match the receiver; otherwise the argument is converted to a scalar and broadcast over the receiver.

A two-item Tcl list is explicitly a complex scalar. For example, {3 -4} means 3-4i, not the expression 3-4. Complex operands produce pairs, including when their imaginary component is zero. Real-only arithmetic uses native double operators, whereas ComplexArithmetic() explicitly reports division by an exactly zero complex value. The paths do not impose identical exceptional-value policies. Operand evaluation can execute Tcl. Receiver lifetime is checked again afterward; arithmetic then reads current storage without further callbacks. The result list is released on every error, including complex division by zero.

Ranges and searches

RangeOp() includes both endpoints and returns descending source order when the first endpoint exceeds the last. This differs from the shared colon-range parser, which rejects reversed selections. Returned objects copy values and do not retain vector storage. Endpoints are evaluated in sequence; the first is revalidated after evaluating the second. A destroyed receiver, stale endpoint or append position produces an error before reading storage.

Real SearchOp() accepts one target or two interval bounds. It returns external indices with the vector offset, or matching values with -value. Complex search accepts a single target and compares real and imaginary components separately; complex interval ordering is deliberately unsupported.

InRange() supplies the historical tolerance. For an interval narrower than DBL_EPSILON, it tests absolute distance from the upper bound strictly below that epsilon. Otherwise it normalizes by interval width, accepts positions down to -DBL_EPSILON, and permits a small excess above one. It does not swap bounds or implement an independent finite-value policy. Search() checks positive offset addition for overflow before returning indices. Receiver lifetime is rechecked after bound conversion. A clearly reversed real interval explicitly returns an empty result, regardless of conversion side effects on the interpreter result.

Normalization and random values

NormalizeOp() refreshes source extrema and computes (value-min)/(max-min). With no destination it returns a Tcl list. With a name it stages the full result before resolving a real destination and transferring completed storage. There is no explicit constant-vector or nonfinite-input policy in the handler: callers should not infer a special all-zero result for a zero range. Complex receivers are rejected by the instance dispatcher’s supported-operation check.

RandomOp() preserves length and numeric type, replacing each component with Rbc_RandomDouble(). Real vectors use one sample per value and complex vectors two. The shared generator produces samples in [0,1) using the C library random state; it is not a cryptographic source or a generator owned by each vector. The handler flushes and reports a full update after filling storage.

Sequence length and endpoint policy

For real numeric bounds, SeqOp() computes the count as trunc((finish-start)/step)+1. The truncation is toward zero, retaining the legacy calculation rather than applying floor or endpoint snapping. A nonpositive count leaves the old vector unchanged. Positive counts generate start+i*step for each index, so the requested endpoint is included only when the count calculation places a sample there.

Numeric bounds and step must be finite, step must be nonzero, and the derived count must fit the supported Tcl size before conversion. Literal end has a different meaning: fill the existing length. It bypasses the numeric-bound count checks and allows a zero step. This distinction matters when documenting or changing validation; the two forms currently do not apply identical checks.

Complex sequences use the default step 1+0i. Each varying component supplies a count through GetComplexSequenceComponentLength(); when both vary, their counts must match. A constant component with zero step imposes no count, while zero step with unequal bounds is an error. If both components are constant with zero step, a numeric finish cannot determine a count and is rejected. Literal end instead uses the existing length, including for a zero complex step.

Both generators recheck receiver lifetime and writability after argument conversion. They reuse capacity where possible and fill prepared storage before committing it and releasing the old allocation. Cache flushing and notification skip destroyed identities and preserve the command result.

Scalar helper contracts

GetArithmeticScalar() distinguishes an explicit pair from a scalar before calling Rbc_GetComplex(). Its complex flag describes the input syntax, even if the imaginary component is zero; the flag is not evidence that conversion succeeded. Conversion can execute Tcl and partially write its output, so callers must inspect the status before using the value.

Rbc_ComplexAdd(), Rbc_ComplexSub() and Rbc_ComplexMul() perform ordinary double arithmetic on copied values. Rbc_ComplexDiv() uses a ratio-based denominator to reduce avoidable intermediate overflow and underflow. It requires the caller to reject zero and does not report nonfinite results. ComplexArithmetic() adds the zero-divisor error check for the instance arithmetic path. These are distinct contracts, not interchangeable error-reporting interfaces.

Rbc_ComplexFromReal() supplies a zero imaginary component, while Rbc_VectorValueAsComplex() copies one caller-validated storage index and promotes real storage if necessary. Neither helper changes a vector’s type or transfers ownership. Rbc_ComplexIsZero() tests exact zero in both components; it is not a magnitude tolerance test. The declarations are collected in Vector access C reference.