Expression engine internal C reference
These helpers are private to rbcVecMath.c. They operate on evaluator-owned temporaries and must not be used as
named-vector mutation APIs. See Expression parser and adapter internals for parser state, adapter families and current limitations;
Vector expression C reference covers the shared entry points.
Parameter directions and Tcl ownership use C calling conventions. Parser cursors point into caller-owned expression storage; returned prefix objects and evaluator temporaries have distinct release requirements. A helper may modify temporary state before returning an error. See the cursor and failure-state descriptions in Expression parser and adapter internals.
- group Expression engine internals
Private evaluator helpers.
Registered vector types remain immutable.
Functions
-
static int GetArrayByteCount(Tcl_Interp *interp, Tcl_Size count, size_t elementSize, size_t *byteCountPtr)
Check a temporary-array allocation size.
Requires nonzero elementSize. Rejects negative count and size_t multiplication overflow with a Tcl error; writes byteCountPtr only on success. Does not allocate storage.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
count – [in] Nonnegative logical element count; negative values are rejected.
elementSize – [in] Nonzero element width in bytes, guaranteed by the caller.
byteCountPtr – [out] Required byte-count output, unchanged on failure.
- Returns:
TCL_OK with the product, otherwise TCL_ERROR; no allocation occurs.
-
static int GetDoubleArrayByteCount(Tcl_Interp *interp, Tcl_Size count, size_t *byteCountPtr)
Check the byte count for real expression storage.
Delegates to GetArrayByteCount with sizeof(double); output remains untouched on validation failure.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
count – [in] Logical double count, subject to nonnegative/overflow validation.
byteCountPtr – [out] Required output, unchanged on failure.
- Returns:
TCL_OK with the byte count, otherwise TCL_ERROR.
-
static int GetRotationOffset(Tcl_Interp *interp, double scalar, Tcl_Size length, Tcl_Size *offsetPtr)
Convert a scalar shift into a bounded rotation offset.
Initializes the output to zero. Length zero or one returns before finite validation. Otherwise rejects nonfinite counts, leaves nonpositive counts as a no-op for compatibility, reduces positive counts modulo length and truncates the remainder to Tcl_Size.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
scalar – [in] Requested rotation count; nonpositive values are a no-op.
length – [in] Nonnegative used length supplied by the caller; lengths at most one bypass finite validation.
offsetPtr – [out] Required offset output, initialized zero before validation.
- Returns:
TCL_OK with a bounded offset, or TCL_ERROR for a nonfinite count when length exceeds one.
-
static int RotateExpressionVector(Tcl_Interp *interp, VectorObject *vPtr, int operator, double scalar)
Rotate real or complex temporary storage in place.
Requires LEFT_SHIFT or RIGHT_SHIFT and an evaluator-owned vector. Allocates a hold buffer for the wrapped portion, then uses memmove for overlap. Validation/allocation errors precede data mutation; successful rotation leaves type, length and selection unchanged and sends no notifications.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
vPtr – [inout] Exclusively owned evaluator temporary, not a registered named vector.
operator – [in] LEFT_SHIFT or RIGHT_SHIFT token, guaranteed by the caller.
scalar – [in] Requested rotation count passed through GetRotationOffset.
- Returns:
TCL_OK after rotation or a no-op, otherwise TCL_ERROR before storage mutation.
-
static void FreeExpressionData(VectorObject *vPtr)
Release a temporary allocation according to its current policy.
Static storage is borrowed, dynamic storage uses ckfree, and a custom policy is invoked directly. Does not clear metadata or retain the record across custom callbacks. Evaluator temporaries normally own dynamic storage; this is not the guarded public reset path.
- Parameters:
vPtr – [inout] Exclusively owned evaluator temporary, not a registered named vector. No metadata is cleared; caller must not use the released pointer afterward.
-
static void ReleaseExpressionStorage(VectorObject *vPtr)
Release and clear an expression temporary’s storage metadata.
Resets data, length, capacity, selection and freeProc after FreeExpressionData. Leaves type and registration fields unchanged. Requires exclusive temporary ownership and no destructive release reentry.
- Parameters:
vPtr – [inout] Exclusively owned evaluator temporary, not a registered named vector. Caller guarantees that a custom storage release cannot destroy or reenter this temporary.
-
static void SetExpressionVectorType(VectorObject *vPtr, Rbc_VectorType type)
Discard storage when changing an unregistered temporary’s type.
Same type is a no-op. A change asserts no registry entry, command or mapped array, releases old storage, then sets type. Not valid for changing a named vector’s immutable type.
- Parameters:
vPtr – [inout] Exclusively owned evaluator temporary, not a registered named vector.
type – [in] Desired real or complex type; a change discards the existing values.
-
static int CopyExpressionVector(VectorObject *destPtr, VectorObject *srcPtr)
Copy a selected source into an evaluator temporary of matching type.
Changes the destination temporary’s type before private duplication. The caller retains the source for the synchronous copy. Failure can leave the temporary cleared or retyped; no named output is committed here.
- Parameters:
destPtr – [inout] Detached destination temporary; may be cleared or retyped even on failure.
srcPtr – [in] Live source with a valid inclusive selection, kept alive through synchronous copying.
- Returns:
TCL_OK after typed duplication, otherwise TCL_ERROR; no named output is published.
-
static int PromoteExpressionVectorToComplex(VectorObject *vPtr)
Promote a real temporary while preserving length and capacity.
Allocates complex capacity, copies used real values with zero imaginary parts and then releases old storage. Already-complex input is unchanged. Size/allocation failures leave old storage intact; requires exclusive temporary ownership across release.
- Parameters:
vPtr – [inout] Exclusively owned evaluator temporary, not a registered named vector.
- Returns:
TCL_OK after promotion or for already-complex input; TCL_ERROR on size/allocation failure.
-
static int SetExpressionRealScalar(VectorObject *vPtr, double value)
Replace an expression temporary with one real value.
Sets real type, resizes to one and stores the value. Returns Tcl status without checking finiteness; evaluation or the calling adapter owns that check.
- Parameters:
vPtr – [inout] Exclusively owned evaluator temporary, not a registered named vector.
value – [in] Double copied into the single-element result; finiteness is not checked.
- Returns:
TCL_OK after replacement, otherwise TCL_ERROR; earlier type changes are not rolled back.
-
static int SetExpressionComplexScalar(VectorObject *vPtr, Rbc_Complex value)
Replace an expression temporary with one complex value.
Sets complex type, resizes to one and stores the pair. Returns Tcl status; does not publish a named- vector change or validate component finiteness.
- Parameters:
vPtr – [inout] Exclusively owned evaluator temporary, not a registered named vector.
value – [in] Complex pair copied into the single-element result; finiteness is not checked.
- Returns:
TCL_OK after replacement, otherwise TCL_ERROR; earlier type changes are not rolled back.
-
static int ApplyComplexBinaryValue(Tcl_Interp *interp, int operator, Rbc_Complex a, Rbc_Complex b, Rbc_Complex *resultPtr)
Compute one supported complex arithmetic operation.
Handles addition, subtraction, multiplication, division and power. Rejects zero divisor and unsupported operators; power delegates domain checks. Writes the output on success and returns Tcl status. The enclosing evaluator checks final finiteness.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
operator – [in] PLUS, MINUS, MULT, DIVIDE or EXPONENT token; others report an error.
a – [in] Left scalar operand, copied by value.
b – [in] Right scalar operand, copied by value.
resultPtr – [out] Required result output; consume only on TCL_OK, which does not guarantee finiteness.
- Returns:
TCL_OK after arithmetic, otherwise TCL_ERROR for an unsupported operator or domain failure.
-
static int ApplyComplexNotOperator(Tcl_Interp *interp, VectorObject *vPtr)
Replace a complex temporary with real boolean negation values.
Allocates a separate real array and computes exact complex-zero tests before releasing the input. Sets capacity equal to length and resets selection to the complete result. Validation/allocation failure leaves the input untouched.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
vPtr – [inout] Exclusively owned evaluator temporary, not a registered named vector.
- Returns:
TCL_OK with real boolean values, otherwise TCL_ERROR before replacing storage. Input must be complex.
-
static int ApplyComplexBooleanOperator(Tcl_Interp *interp, int operator, VectorObject *vPtr, VectorObject *v2Ptr)
Compute broadcast complex equality or logical results as real values.
Requires EQUAL, NEQ, AND or OR. Length-one operands broadcast; other lengths must match. Computes into a new real array before replacing the left temporary. Equality compares both components exactly; truth means either component is nonzero. Both operands have already been evaluated, so this is not short-circuit evaluation.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
operator – [in] EQUAL, NEQ, AND or OR.
vPtr – [inout] Exclusively owned evaluator temporary, not a registered named vector.
v2Ptr – [in] Live right operand temporary; scalar broadcasting and shape rules depend on the operator.
- Returns:
TCL_OK after applying the operator, otherwise TCL_ERROR; the left temporary may be partially changed.
-
static int ApplyComplexShiftOperator(Tcl_Interp *interp, int operator, VectorObject *vPtr, VectorObject *v2Ptr)
Validate a real-valued scalar count and rotate the left temporary.
Requires a length-one right operand. A complex scalar with zero imaginary part is accepted; nonzero imaginary part is rejected. Rotation retains the left type and length.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
operator – [in] LEFT_SHIFT or RIGHT_SHIFT.
vPtr – [inout] Exclusively owned evaluator temporary, not a registered named vector.
v2Ptr – [in] Live right operand temporary; scalar broadcasting and shape rules depend on the operator.
- Returns:
TCL_OK after applying the operator, otherwise TCL_ERROR; the left temporary may be partially changed.
-
static int ApplyComplexBinaryOperator(Tcl_Interp *interp, int operator, VectorObject *vPtr, VectorObject *v2Ptr)
Dispatch complex arithmetic, boolean or rotation operations.
Either operand may be real. Arithmetic promotes the left temporary and broadcasts scalars, otherwise requires equal lengths; boolean operations return real storage and shifts retain the left type. Unsupported ordering/modulus operators fail. Elementwise arithmetic can partially change the temporary before an error; named destinations are committed by the outer layer only.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
operator – [in] An expression binary token; unsupported ordering/modulus operators are rejected.
vPtr – [inout] Exclusively owned evaluator temporary, not a registered named vector.
v2Ptr – [in] Live right operand temporary; scalar broadcasting and shape rules depend on the operator.
- Returns:
TCL_OK after applying the operator, otherwise TCL_ERROR; the left temporary may be partially changed.
-
static int ComplexValueIsFinite(Rbc_Complex value)
Test finiteness of both complex components.
Returns true only if both real and imaginary values are finite. Does not inspect errno or set a Tcl diagnostic.
- Parameters:
value – [in] Complex value whose two components are tested. The scalar is passed by value; no vector storage or ownership is transferred.
-
static void InstallIndexProc(Tcl_HashTable *tablePtr, char *string, Rbc_VectorIndexProc *procPtr)
Install or remove a named special-index procedure.
Requires an initialized string-key hash table. Stores a borrowed function pointer, or deletes the entry for NULL. Does not own or release callback state.
- Parameters:
tablePtr – [inout] Initialized string-key table owned by the vector subsystem.
string – [in] NUL-terminated index name; Tcl copies the key when creating an entry.
procPtr – [in] Borrowed callback to store, or NULL to remove the name. The table does not own callback state.
-
static Tcl_Size First(VectorObject *vPtr)
Find the first finite real value in the selected interval.
Requires valid real storage and first/last bounds. Returns its storage index or -1. Does not alter selection or cached extrema.
- Parameters:
vPtr – [in] Live real vector with a caller-validated inclusive first/last selection.
- Returns:
First finite storage index in the selection, or -1 when none exists.
-
static Tcl_Size Next(VectorObject *vPtr, Tcl_Size current)
Find the next finite real value after a current index.
Scans through last inclusive, returning a storage index or -1. Requires valid real storage and a current index from the same traversal.
- Parameters:
vPtr – [in] Live real vector with a caller-validated inclusive selection.
current – [in] Previous storage index; scanning starts at current+1 through last.
- Returns:
Next finite storage index, or -1 when no later finite value exists.
-
static int CopyExpressionResult(Tcl_Interp *interp, VectorObject *destPtr, VectorObject *srcPtr)
Copy an evaluated temporary into a fixed-type destination.
Matching types delegate to private duplication. Real results can populate a complex destination with zero imaginary parts; complex-to-real assignment is rejected. Resizing/copying does not flush mapped caches or notify. The caller checks destination lifetime and writability across expression callbacks.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
destPtr – [inout] Live writable fixed-type destination; caller protects lifetime across storage release.
srcPtr – [in] Evaluated source temporary with a valid selected interval, kept alive through copying.
- Returns:
TCL_OK after copying, or TCL_ERROR for incompatible types or resize/copy failure.
-
static void ExpressionDestinationChanged(Tcl_Interp *interp, ClientData clientData, Rbc_VectorNotify notify)
Record destruction of the original assignment destination.
clientData points to the caller’s live stack flag. Only DESTROY sets it. The destruction path releases the observer; the callback does not access the vector or keep an interpreter alive.
- Parameters:
interp – [in] Notification interpreter, unused here. See Interpreter arguments.
clientData – [inout] Caller-owned int destruction flag, valid for the temporary observer’s lifetime.
notify – [in] Notification kind; only RBC_VECTOR_NOTIFY_DESTROY sets the flag.
-
static int EvaluateExpression(Tcl_Interp *interp, char *string, Value *valuePtr)
Evaluate the complete writable expression into a caller-owned temporary.
Initializes parser state, calls NextValue and requires END. Rejects nonfinite components in the final result through MathError. The caller frees the temporary on success or failure. Substitutions and map callbacks execute Tcl; their side effects are not rolled back.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
string – [inout] NUL-terminated writable expression buffer, valid through evaluation; delimiters are restored.
valuePtr – [inout] Caller-owned Value containing a live evaluator temporary; caller releases it on every outcome.
- Returns:
TCL_OK with a complete finite result, otherwise a non-OK evaluation status; side effects remain.
-
static int NextValue(Tcl_Interp *interp, ParseInfo *parsePtr, int prec, Value *valuePtr)
Evaluate one precedence-delimited expression into an existing temporary.
Owns a second operand temporary for this recursive invocation and frees it on every exit. Stops at END, CLOSE_PAREN, COMMA or an operator whose precedence is at most prec; token/nextPtr describe the terminator already scanned. Evaluates both operands before applying operators, including logical operators. Errors can leave partial temporary data and Tcl side effects.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
parsePtr – [inout] Live parser state borrowing the writable expression; updated through the scanned terminator.
prec – [in] Precedence cutoff; -1 accepts a complete expression up to a delimiter.
valuePtr – [inout] Caller-owned Value containing a live evaluator temporary; caller releases it on every outcome.
- Returns:
TCL_OK for the parsed subexpression, otherwise a non-OK status; temporary contents may be partial.
-
static void SetMathError(Tcl_Interp *interp, const char *className, Tcl_Obj *messageObj)
Set an arithmetic message and structured Tcl error code.
Installs messageObj as result and as the third element of the ARITH/class/message error-code list. Accepts a newly created message object; Tcl result/error-code references retain it. Does not raise a completion code itself.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
className – [in] Borrowed NUL-terminated arithmetic error class, copied into the error-code list.
messageObj – [in] Message object retained by the Tcl result and error code; a new reference-count-zero object is valid.
-
static void MathError(Tcl_Interp *interp, double value)
Classify a floating-point failure using errno and the value.
Reports DOMAIN for EDOM or NaN, UNDERFLOW/OVERFLOW for ERANGE or infinity, otherwise UNKNOWN. Reads but does not clear errno. Callers that depend on errno must reset it before the operation.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
value – [in] Failed arithmetic value, interpreted together with the current errno; errno is not reset here.
-
static int ParseSubstitutionResult(Tcl_Interp *interp, Value *valuePtr)
Convert a retained Tcl result into an expression value.
Increments the result object reference before clearing the interpreter result, so conversion cannot invalidate its borrowed string. Releases the reference afterward and returns ParseString status. Does not retain arbitrary vector identities resolved by the conversion.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
valuePtr – [inout] Caller-owned Value containing a live evaluator temporary; caller releases it on every outcome.
- Returns:
Conversion status after clearing and parsing the retained interpreter result.
-
static int ParseBracketScript(Tcl_Interp *interp, const char *string, const char **termPtr)
Locate a matching close bracket and evaluate the enclosed Tcl script.
Input begins after the opening bracket. Uses Tcl_ParseCommand repeatedly to respect command syntax, writes termPtr after the closing bracket once found, then returns Tcl_EvalEx completion unchanged. Missing terminator reports an error. The caller provides valid input and interpreter lifetime through evaluation.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
string – [in] NUL-terminated buffer starting immediately after the opening bracket.
termPtr – [out] Required borrowed cursor output after the closing bracket; may be set before script failure.
- Returns:
Parsing error or the unchanged Tcl_EvalEx completion code, not necessarily only TCL_OK/TCL_ERROR.
-
static int ParseBracketValue(Tcl_Interp *interp, const char *string, const char **termPtr, Value *valuePtr)
Evaluate bracketed Tcl and convert its result to numeric storage.
Delegates bracket parsing/evaluation and then ParseSubstitutionResult. Non-OK Tcl completion propagates before numeric conversion.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
string – [in] NUL-terminated token buffer starting immediately after the opening bracket.
termPtr – [out] Required borrowed cursor after the matching delimiter; may be written before later evaluation failure.
valuePtr – [inout] Caller-owned Value containing a live evaluator temporary; caller releases it on every outcome.
- Returns:
Non-OK parsing/evaluation completion, or the numeric conversion status after successful evaluation.
-
static int ParseQuotedValue(Tcl_Interp *interp, const char *string, const char **termPtr, Value *valuePtr)
Parse and evaluate a quoted Tcl token sequence.
Input includes the opening quote. Uses Tcl parsing/substitution rules, releases parse storage after token evaluation, then converts the retained result. termPtr follows the closing quote on successful parsing; substitutions may execute Tcl.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
string – [in] NUL-terminated token buffer starting at the opening double quote.
termPtr – [out] Required borrowed cursor after the matching delimiter; may be written before later evaluation failure.
valuePtr – [inout] Caller-owned Value containing a live evaluator temporary; caller releases it on every outcome.
- Returns:
Non-OK parsing/evaluation completion, or the numeric conversion status after successful evaluation.
-
static int ParseBracedValue(Tcl_Interp *interp, const char *string, const char **termPtr, Value *valuePtr)
Parse a braced Tcl value and convert it to expression storage.
Input includes the opening brace. Uses Tcl_ParseBraces and evaluates its tokens, preserving brace substitution rules including backslash-newline handling. Converts through ParseSubstitutionResult after freeing successful parse storage.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
string – [in] NUL-terminated token buffer starting at the opening brace.
termPtr – [out] Required borrowed cursor after the matching delimiter; may be written before later evaluation failure.
valuePtr – [inout] Caller-owned Value containing a live evaluator temporary; caller releases it on every outcome.
- Returns:
Non-OK parsing/evaluation completion, or the numeric conversion status after successful evaluation.
-
static int NextToken(Tcl_Interp *interp, ParseInfo *parsePtr, Value *valuePtr)
Scan one operator, delimiter or numeric/vector value.
Advances nextPtr and records token; VALUE fills the supplied temporary. Bare numbers use SetExpressionRealScalar. Substitutions use ParseString, while other names first try function lookup then vector/range lookup and copying. Variable traces, commands and map functions can execute Tcl; this scanner has no independent interpreter lifetime guard.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
parsePtr – [inout] Parser cursor and token state borrowing a live writable expression buffer.
valuePtr – [inout] Caller-owned Value containing a live evaluator temporary; caller releases it on every outcome.
- Returns:
TCL_OK after scanning; VALUE fills the temporary, while operators/delimiters need not change it.
-
static double Fmod(double x, double y)
Compute the legacy floor-based real remainder.
Returns zero for a zero divisor; otherwise x-floor(x/y)*y. This differs from C fmod for negative operands. Does not report an error or validate finite input.
- Parameters:
x – [in] Real dividend.
y – [in] Real divisor; zero is handled by returning zero.
- Returns:
x-floor(x/y)*y for nonzero y, otherwise zero; this is not C fmod semantics.
-
static int ParseString(Tcl_Interp *interp, const char *string, Value *valuePtr)
Interpret substitution text as a scalar, complex pair or vector reference.
Tries a fully consumed strtod number, then a two-element complex list, then a fully consumed vector/range reference. Does not accept arbitrary numeric lists as vectors. The current real-number branch uses the same real scalar setter as bare numeric tokens, clearing any complex type and imaginary component left in a reused operand temporary.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
string – [in] Borrowed NUL-terminated substitution text, kept valid through conversion and lookup.
valuePtr – [inout] Caller-owned Value containing a live evaluator temporary; caller releases it on every outcome.
- Returns:
TCL_OK with copied scalar/pair/vector values, otherwise TCL_ERROR; arbitrary numeric lists are not vectors.
-
static Tcl_Obj *ParseMapPrefix(Tcl_Interp *interp, const char **nextPtr)
Parse and retain one Tcl command-prefix value.
Accepts braces, quotes, variable or bracket substitution, or a bare word ending at whitespace/comma/parenthesis. Substitutions run once in the current frame. Returns a reference- counted object and advances nextPtr, or NULL on failure. The caller decrements the reference; MapVector validates list structure and nonemptiness.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
nextPtr – [inout] Required cursor into a live expression buffer, advanced after successful prefix parsing.
- Returns:
Tcl object with one retained reference, released by the caller with Tcl_DecrRefCount, or NULL on failure.
-
static int MapVector(Tcl_Interp *interp, Tcl_Obj *prefix, VectorObject *vPtr)
Apply a Tcl command prefix to every value of a detached temporary.
Retains individual prefix words against recursive shimmering and appends one real or complex-pair argument per invocation. Builds a separate zero-initialized result, promoting on the first pair return. Requires finite numeric results; empty input yields an empty real result with no calls. Tcl errors gain an element index, other completion codes become MAP COMPLETION errors, and invalid results become MAP VALUE errors. Frees argument references and partial results on failure; callback side effects remain.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
prefix – [in] Borrowed nonempty Tcl command-prefix list, kept alive through extraction of its words.
vPtr – [inout] Exclusively owned evaluator temporary, not a registered named vector.
- Returns:
TCL_OK after replacing the temporary with complete finite callback results, otherwise TCL_ERROR. Callback side effects remain; callback completion codes other than TCL_OK are converted to errors.
-
static int ParseMapFunction(Tcl_Interp *interp, ParseInfo *parsePtr, Value *valuePtr)
Parse map(prefix, expression) before invoking element callbacks.
Retains the parsed prefix while evaluating the complete second argument. Requires comma and closing parenthesis; successful MapVector changes token to VALUE. Releases the prefix on every exit. Prefix and numeric-argument evaluation precede the per-element callbacks.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
parsePtr – [inout] Parser positioned after map’s opening parenthesis; success leaves token VALUE.
valuePtr – [inout] Caller-owned Value containing a live evaluator temporary; caller releases it on every outcome.
- Returns:
TCL_OK after argument evaluation and mapping, otherwise TCL_ERROR.
-
static int ParseMathFunction(Tcl_Interp *interp, char *start, ParseInfo *parsePtr, Value *valuePtr)
Try function syntax before falling back to vector-name parsing.
Requires a writable input string: temporarily replaces the opening parenthesis with NUL during lookup, then restores it. Recognizes map specially; ordinary names use the interpreter’s math table. TCL_RETURN means no recognized function, not a script return. Parses one expression argument and invokes its adapter after the close parenthesis. The hash entry is borrowed across argument evaluation; this helper does not guard registry teardown during callbacks.
- Parameters:
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
start – [inout] Writable expression span starting at a candidate function name; temporary NUL edits are restored.
parsePtr – [inout] Live parser state; success advances past the function argument and sets token VALUE.
valuePtr – [inout] Caller-owned Value containing a live evaluator temporary; caller releases it on every outcome.
- Returns:
TCL_OK for a completed function, TCL_RETURN for no recognized function, or TCL_ERROR on evaluation failure.
-
static int ComponentFunc(ClientData clientData, Tcl_Interp *interp, VectorObject *vPtr)
Apply a real component function to finite selected values.
Rejects complex input, resets errno and walks First/Next. Writes each result before errno/finite validation; failure can leave a partially transformed temporary. Does not notify or commit named output.
- Parameters:
clientData – [in] Borrowed ComponentProc function pointer, valid throughout synchronous dispatch; never freed here.
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
vPtr – [inout] Exclusively owned evaluator temporary, not a registered named vector.
- Returns:
TCL_OK on completion, otherwise TCL_ERROR; the adapter-specific contract defines partial mutation and finite checks.
-
static int ComplexComponentFunc(ClientData clientData, Tcl_Interp *interp, VectorObject *vPtr)
Apply paired real/complex component implementations.
Real input delegates to ComponentFunc. Complex input visits all used values, resets errno for each call, validates both components and stores each successful result. Errors can leave earlier elements changed.
- Parameters:
clientData – [in] Borrowed ComplexComponentFunction descriptor, valid throughout synchronous dispatch; never freed here.
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
vPtr – [inout] Exclusively owned evaluator temporary, not a registered named vector.
- Returns:
TCL_OK on completion, otherwise TCL_ERROR; the adapter-specific contract defines partial mutation and finite checks.
-
static int ScalarFunc(ClientData clientData, Tcl_Interp *interp, VectorObject *vPtr)
Reduce a real temporary to one real value.
Rejects complex input, computes the scalar before resizing and checks errno. Stores one value on successful resize; final finiteness is checked by EvaluateExpression. No named-vector notification is sent.
- Parameters:
clientData – [in] Borrowed ScalarProc function pointer, valid throughout synchronous dispatch; never freed here.
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
vPtr – [inout] Exclusively owned evaluator temporary, not a registered named vector.
- Returns:
TCL_OK on completion, otherwise TCL_ERROR; the adapter-specific contract defines partial mutation and finite checks.
-
static int ComplexScalarFunc(ClientData clientData, Tcl_Interp *interp, VectorObject *vPtr)
Reduce a real or complex temporary while retaining its type.
Selects the corresponding reducer, computes before resizing to one, and reports errno failures. A complex result remains a pair. Final nonfinite results are rejected by the enclosing evaluator.
- Parameters:
clientData – [in] Borrowed ComplexScalarFunction descriptor, valid throughout synchronous dispatch; never freed here.
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
vPtr – [inout] Exclusively owned evaluator temporary, not a registered named vector.
- Returns:
TCL_OK on completion, otherwise TCL_ERROR; the adapter-specific contract defines partial mutation and finite checks.
-
static int ComplexRealScalarFunc(ClientData clientData, Tcl_Interp *interp, VectorObject *vPtr)
Reduce either numeric type to one real result.
Computes the reduction before any type change or release, checks errno, then uses SetExpressionRealScalar. Operates on evaluator temporaries only; final finiteness belongs to EvaluateExpression.
- Parameters:
clientData – [in] Borrowed ComplexRealScalarFunction descriptor, valid throughout synchronous dispatch; never freed here.
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
vPtr – [inout] Exclusively owned evaluator temporary, not a registered named vector.
- Returns:
TCL_OK on completion, otherwise TCL_ERROR; the adapter-specific contract defines partial mutation and finite checks.
-
static int VectorFunc(ClientData clientData, Tcl_Interp *interp, VectorObject *vPtr)
Invoke a real-only whole-vector function adapter.
Rejects complex input and returns the selected function’s Tcl status. The function owns its mutation/allocation policy; this wrapper neither checks errno nor publishes notifications.
- Parameters:
clientData – [in] Borrowed VectorProc function pointer, valid throughout synchronous dispatch; never freed here.
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
vPtr – [inout] Exclusively owned evaluator temporary, not a registered named vector.
- Returns:
TCL_OK on completion, otherwise TCL_ERROR; the adapter-specific contract defines partial mutation and finite checks.
-
static int ComplexRealFunc(ClientData clientData, Tcl_Interp *interp, VectorObject *vPtr)
Convert component results from complex input into real temporary storage.
Real input delegates to ComponentFunc. Complex input allocates real capacity and validates each transformed value before releasing old storage. Failure frees the new buffer and retains the old one. On success preserves length/capacity/selection and changes only the temporary type and owned data.
- Parameters:
clientData – [in] Borrowed ComplexRealFunction descriptor, valid throughout synchronous dispatch; never freed here.
interp – [in] Evaluation/diagnostic interpreter; see Interpreter arguments.
vPtr – [inout] Exclusively owned evaluator temporary, not a registered named vector.
- Returns:
TCL_OK on completion, otherwise TCL_ERROR; the adapter-specific contract defines partial mutation and finite checks.
-
static int GetArrayByteCount(Tcl_Interp *interp, Tcl_Size count, size_t elementSize, size_t *byteCountPtr)
Data records and member contracts
These records describe stored state and resource ownership. Their presence in the reference does not make private layouts part of the installed C API.
-
struct ComplexComponentFunction
Paired real/complex expression implementations selected by input type.
-
struct ComplexRealFunction
Paired real/complex expression implementations selected by input type.
-
struct ComplexRealScalarFunction
Paired real/complex expression implementations selected by input type.
-
struct ComplexScalarFunction
Paired real/complex expression implementations selected by input type.
-
struct MathFunction
Static expression-function registration entry.
Implementation selectors
-
enum Tokens
Lexical token and operator identifiers consumed by the vector expression parser.
Values:
-
enumerator VALUE
-
enumerator OPEN_PAREN
-
enumerator CLOSE_PAREN
-
enumerator COMMA
-
enumerator END
-
enumerator UNKNOWN
-
enumerator MULT
-
enumerator DIVIDE
-
enumerator MOD
-
enumerator PLUS
-
enumerator MINUS
-
enumerator LEFT_SHIFT
-
enumerator RIGHT_SHIFT
-
enumerator LESS
-
enumerator GREATER
-
enumerator LEQ
-
enumerator GEQ
-
enumerator EQUAL
-
enumerator NEQ
-
enumerator OLD_BIT_AND
-
enumerator EXPONENT
-
enumerator OLD_BIT_OR
-
enumerator OLD_QUESTY
-
enumerator OLD_COLON
-
enumerator AND
-
enumerator OR
-
enumerator UNARY_MINUS
-
enumerator OLD_UNARY_PLUS
-
enumerator NOT
-
enumerator OLD_BIT_NOT
-
enumerator VALUE