Vector command C reference
Selected private handlers and helpers from rbcVecCmd.c. See Vector instance commands and binary input for dispatch, partial updates and
callback limitations.
Parameter directions and interpreter ownership follow C calling conventions. For list-conversion helpers,
objc/objv describe only the value slice; they do not include a command name. Storage capacities count typed
values, while allocation helpers explicitly identify byte counts. See the ownership table in Vector instance commands and binary input
before releasing a prepared output.
- group Vector instance command paths
Selected private mutation and input helpers; see the developer manual for partial-update and callback lifetime limitations.
Functions
-
static int AddVectorSizes(Tcl_Interp *interp, Tcl_Size a, Tcl_Size b, Tcl_Size *resultPtr)
Add two nonnegative logical sizes without signed overflow.
Returns TCL_ERROR with a diagnostic for negative operands or a sum above TCL_SIZE_MAX; leaves the output unchanged on failure. Otherwise writes the sum and returns TCL_OK. Does not allocate or execute Tcl.
- Parameters:
interp – [in] Diagnostic interpreter; see Interpreter arguments.
a – [in] Nonnegative first logical count.
b – [in] Nonnegative second logical count.
resultPtr – [out] Required sum output, unchanged on failure.
- Returns:
TCL_OK with the sum, or TCL_ERROR for negative operands or overflow.
-
static int MultiplyVectorSizes(Tcl_Interp *interp, Tcl_Size a, Tcl_Size b, Tcl_Size *resultPtr)
Multiply nonnegative logical sizes with overflow checking.
Accepts zero operands, rejects negative operands and products above TCL_SIZE_MAX, and writes the result only on success. Returns a Tcl status with a diagnostic on failure; no allocation or callbacks occur.
- Parameters:
interp – [in] Diagnostic interpreter; see Interpreter arguments.
a – [in] Nonnegative first factor, including zero.
b – [in] Nonnegative second factor, including zero.
resultPtr – [out] Required product output, unchanged on failure.
- Returns:
TCL_OK with the product, or TCL_ERROR for negative operands or overflow.
-
static int GetArrayByteCount(Tcl_Interp *interp, Tcl_Size count, size_t elementSize, size_t *byteCountPtr)
Convert a logical count to a checked allocation byte count.
Requires a nonzero elementSize and writable output pointer. Rejects negative counts and multiplication exceeding SIZE_MAX. Writes the product only on success and returns a Tcl status. Does not allocate storage.
- Parameters:
interp – [in] Diagnostic interpreter; see Interpreter arguments.
count – [in] Logical element count; negative counts are rejected.
elementSize – [in] Nonzero size of one element in bytes, supplied by the caller.
byteCountPtr – [out] Required byte-count output, unchanged on failure.
- Returns:
TCL_OK with count times elementSize, or TCL_ERROR if it cannot be represented.
-
static int CheckCommandSource(VectorObject *vPtr)
Check logical liveness of a caller-retained vector.
Requires a valid preserved record and interpreter. Rejects vector destruction or interpreter deletion with RBC VECTOR DESTROYED. Does not retain the object itself, check a selection or validate numerical storage contents.
- Parameters:
vPtr – [in] Valid caller-retained record with a caller-retained owning interpreter.
- Returns:
TCL_OK if both owners remain logically live; otherwise TCL_ERROR with RBC VECTOR DESTROYED.
-
static int CheckCommandDestination(VectorObject *vPtr)
Check a retained destination for liveness and writability.
First delegates to CheckCommandSource, then enforces the vector read-only flag. Returns a Tcl status. Does not allocate, resize or publish changes; the caller maintains preservation references.
- Parameters:
vPtr – [in] Valid caller-retained destination and owning interpreter.
- Returns:
TCL_OK if live and writable, otherwise TCL_ERROR with a diagnostic.
-
static int PrepareCommandWrite(VectorObject *vPtr, Tcl_Size length, VectorData *dataPtr, Tcl_Size *sizePtr)
Prepare reusable or enlarged storage without releasing old data.
Requires a nonnegative requested length and a retained destination/interpreter. Checks writability, reuses existing capacity when sufficient, otherwise grows geometrically with overflow checks and copies the existing logical prefix. Does not initialize the added tail or change metadata. On success outputs either borrowed current storage or a new allocation; callers distinguish them when abandoning preparation. No storage-release callback occurs here.
- Parameters:
vPtr – [in] Live destination, with record and interpreter retained by the caller.
length – [in] Nonnegative requested used count, validated by the caller.
dataPtr – [out] Required prepared-storage output; consume only on TCL_OK. May alias current storage.
sizePtr – [out] Required prepared capacity in values, written on success.
- Returns:
TCL_OK with reused storage or an owned allocation; TCL_ERROR on protection or allocation failure.
-
static int PrepareCommandResize(VectorObject *vPtr, Tcl_Size length, VectorData *dataPtr, Tcl_Size *sizePtr)
Prepare storage using the explicit-resize capacity policy.
Requires a nonnegative length and a retained destination/interpreter. Checks writability and computes capacity from DEF_ARRAY_SIZE, with zero capacity for zero length. Reuses matching capacity or allocates and copies the retained prefix. Does not zero newly added values, install metadata or release old storage. The caller owns a newly allocated result until commit, but must not free a reused current pointer.
- Parameters:
vPtr – [in] Live destination, with record and interpreter retained by the caller.
length – [in] Nonnegative requested used count, validated by the caller.
dataPtr – [out] Required prepared-storage output; consume only on TCL_OK. May alias current storage.
sizePtr – [out] Required capacity output; may be written before allocation failure.
- Returns:
TCL_OK with reused storage, an owned allocation or NULL for zero capacity; otherwise TCL_ERROR.
-
static void FinishCommandWrite(VectorObject *vPtr, VectorData data, Tcl_Size length, Tcl_Size size)
Install completed storage before releasing the old allocation.
Caller validates dimensions, prepares all values and retains vector/interpreter. Installs data, length, capacity, whole-vector selection and invalid extrema. A changed pointer acquires TCL_DYNAMIC ownership; an unchanged pointer keeps its existing release procedure. Releases detached old storage according to its previous policy, preserving interpreter state across a custom release callback. Does not access vector storage after release, enforce writability or notify observers. Callback effects are not rolled back.
- Parameters:
vPtr – [inout] Caller-retained destination, already validated as writable before commit.
data – [in] Completed typed storage, either the current pointer or Tcl-allocated storage to transfer.
length – [in] Valid nonnegative used count, no greater than size.
size – [in] Valid capacity in values for data; NULL storage requires zero capacity.
-
static void NotifyCommandWrite(VectorObject *vPtr, Tcl_Size first)
Flush and publish a committed write while preserving command state.
Requires caller-retained vector/interpreter. Skips destroyed owners, flushes an enabled mapped cache, then checks liveness again before notification. A valid nonnegative first reports first through the current final index; all other values report a full update. Restores the saved interpreter result and return options across traces and immediate observers. Does not retain owners itself or undo callback changes.
- Parameters:
vPtr – [inout] Caller-retained vector and interpreter; logically destroyed owners are skipped.
first – [in] First changed zero-based storage index for a suffix, or -1 for a full update. Out-of-range indices also request a full update after cache flushing.
-
static int CheckCommandRange(VectorObject *vPtr, Tcl_Size first, Tcl_Size last)
Check two saved indices against current live storage bounds.
Requires a retained record. Rejects dead owners or either endpoint outside zero through length minus one, reporting RBC VECTOR RANGE for invalid bounds. Does not check endpoint ordering, writability or whether values changed since the indices were captured.
- Parameters:
vPtr – [in] Caller-retained vector and interpreter whose current length is checked.
first – [in] Saved zero-based storage index, required to lie within current used storage.
last – [in] Saved inclusive endpoint, independently checked against current used storage.
- Returns:
TCL_OK when both indices remain in bounds, otherwise TCL_ERROR; ordering is not checked.
-
static const char *CommandOutputName(Tcl_Interp *interp, const char *name, Tcl_DString *buffer)
Qualify an output name in the current namespace.
Initializes and fills the caller DString, preserving absolute names and prefixing relative names with the current namespace. Returns borrowed DString storage for the caller to free. Does not resolve namespaces, interpret selections or validate the name.
- Parameters:
interp – [in] Interpreter providing the current namespace; see Interpreter arguments.
name – [in] NUL-terminated output name, absolute or relative to the current namespace.
buffer – [out] Caller-owned DString initialized here; release with Tcl_DStringFree after using the result.
- Returns:
Qualified name borrowed from buffer, invalidated by its modification or release.
-
static VectorObject *GetCommandOutput(VectorObject *source, const char *name, int *isNewPtr)
Resolve or create a retained same-type command destination.
Qualifies the name in the current namespace, so a relative output does not fall back to a global vector. Existing outputs must be writable and match the source type; their commands and mapped arrays are retained. Missing outputs are created without array mapping. Returns a preserved vector and sets isNewPtr, or NULL on error. Caller releases the preservation reference; this helper does not publish output data.
- Parameters:
source – [in] Caller-retained source supplying the interpreter and required numeric type.
name – [in] NUL-terminated literal destination name, qualified in the current namespace.
isNewPtr – [out] Required creation flag; consume only after a non-NULL return.
- Returns:
Preserved destination record, released with Tcl_Release by the caller, or NULL on error.
-
static void ReleaseCommandOutputs(CommandOutput *outputs, Tcl_Size count)
Release an output-record array and its preservation references.
Releases every non-NULL vector slot, then frees the owned array. Requires count initialized slots, which may include repeated identities with separate references. Does not destroy newly created vectors or roll back their data.
- Parameters:
outputs – [in] Owned array from GetCommandOutputs, consumed and freed by this call.
count – [in] Number of initialized slots, each owning a preservation reference when non-NULL.
-
static CommandOutput *GetCommandOutputs(VectorObject *source, Tcl_Size count, Tcl_Obj *const names[])
Precheck existing destinations then collect retained output identities.
Allocates zero-initialized output records after checking the byte count. First validates existing literal destinations for type and writability, then resolves or creates each output. On failure releases collected references and the record array; already created vectors remain. Returns an owned array, including an allocation for count zero. Does not reject duplicate names or source/output aliasing; operation handlers impose their own rules.
- Parameters:
source – [in] Caller-retained source supplying the interpreter and required output type.
count – [in] Nonnegative number of output names and returned slots.
names – [in] Borrowed array of count Tcl name objects, kept valid during collection.
- Returns:
Owned array with preserved output records, or NULL on failure. Release with ReleaseCommandOutputs.
-
static int PublishCommandOutput(VectorObject *dest, int isNew)
Map and notify a completed output without resolving its name again.
Requires a retained destination/interpreter and already committed data. A destroyed owner is treated as successfully committed. New real vectors without parentheses receive their default mapped array; existing outputs and complex or parenthesized names do not get a new mapping. Mapping failure returns TCL_ERROR with its diagnostic. Otherwise publishes a full update while restoring prior interpreter state. Does not roll back committed data or callback effects.
- Parameters:
dest – [inout] Caller-retained destination with completed data already installed.
isNew – [in] Nonzero if this operation created dest and should consider default array mapping.
- Returns:
TCL_OK after publication or if already destroyed; TCL_ERROR for mapping failure after commit.
-
static int AllocateCommandData(VectorObject *vPtr, Tcl_Size length, VectorData *dataPtr)
Allocate uninitialized typed staging storage.
Checks byte-count overflow and attempts an owned allocation, reserving one byte for an empty result so NULL denotes failure. Returns a Tcl status. Does not modify vector metadata, check writability or invoke callbacks. The caller frees the allocation or transfers it at commit.
- Parameters:
vPtr – [in] Live vector supplying numeric type and diagnostic interpreter; storage is not changed.
length – [in] Nonnegative number of typed values to allocate; negative values are rejected.
dataPtr – [out] Required storage output; consume only on TCL_OK and release with ckfree unless transferred.
- Returns:
TCL_OK with an owned non-NULL allocation, including length zero; TCL_ERROR on failure.
-
static int ConvertCommandList(VectorObject *vPtr, Tcl_Size objc, Tcl_Obj *const objv[], VectorData *dataPtr)
Convert a complete argument list into owned typed staging storage.
Allocates storage and retains a private outer Tcl list representation before evaluating values. Each successful conversion is followed by a destination liveness/writability check. Failure frees staging storage and resets its pointer to NULL. Success returns owned data, or NULL for an empty list. Does not install values or length; callbacks may change the destination themselves. Caller retains the vector/interpreter throughout conversion.
- Parameters:
vPtr – [in] Caller-retained destination and interpreter supplying type and protection state.
objc – [in] Nonnegative number of values to convert; this is not a full command argument count.
objv – [in] Borrowed array of objc value objects; no command name or operation prefix is present.
dataPtr – [out] Required owned-storage output, initialized to NULL and reset to NULL on failure.
- Returns:
TCL_OK with staged data, or NULL data for zero values; TCL_ERROR on conversion or protection failure.
-
static int ComplexOpSupported(RbcVectorCmdOp *proc)
Test whether an instance handler accepts complex vectors.
Compare handler pointers against the explicit complex-operation allowlist. Aliases sharing a handler inherit its eligibility. This is a dispatch gate, not type validation for operands or output vectors. Adding a handler requires reviewing this list separately from the operation table and write checks.
- Parameters:
proc – [in] Handler identity to test against the complex-operation allowlist; never invoked here.
- Returns:
Nonzero for an allowed handler, zero otherwise.
-
int Rbc_VectorInstanceObjCmd(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Validate and dispatch one vector instance operation.
clientData is the live receiver. Resolve operation spelling and arity before checking complex support, then reject protected receiver writes according to the handler and argument count. Source-only operations check destinations in their own handlers. Reset the shared inclusive selection to the whole vector only after these checks succeed. Preserve the interpreter and receiver while calling the handler, release both, and return its status. Preservation retains the record, not storage after destruction; handlers must revalidate after callbacks. Rejected dispatch does not reset a prior selection.
See also
- Parameters:
clientData – [in] Live VectorObject owned by the instance command; retained while its handler runs.
interp – [in] Owning interpreter; see Interpreter arguments.
objc – [in] Full Tcl command argument count, including command and operation names.
objv – [in] Borrowed argument array; objv[0] is the command and objv[1] selects the operation. See Tcl command arguments for shared argument lifetime rules.
- Returns:
Handler status on successful dispatch; TCL_ERROR for dispatch, type or protection errors.
-
static int ReadOnlyOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Query or set reversible vector data protection.
With objv[2], parse a Tcl boolean before setting the flag; invalid input leaves the flag unchanged. Return the current boolean state for both forms. Changing protection does not change values, length or type, flush the array, or notify clients. Unlocking is allowed; this is not a lifetime/ownership lock. The dispatcher preserves the live receiver for this handler.
- 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 a query, or 3 to set protection.
objv – [in] Borrowed full command argument array. Optional objv[2] is the new Tcl boolean. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK with the current protection boolean, or TCL_ERROR for invalid boolean input.
-
static int TypeOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Return the receiver numeric type without converting storage.
Return real or complex as a Tcl string. Requires a live receiver and performs no mutation, cache flush or client notification. An unrecognized internal type is an invariant violation handled by Tcl_Panic, not a user conversion error.
- 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 with real or complex; an invalid internal type is a fatal invariant violation.
-
static int AppendOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Append vector ranges or Tcl lists in argument order.
Vector lookup precedes list conversion. Earlier arguments remain appended if a later argument fails. Reports the appended range when length grew, including the error path; otherwise successful calls report a full update. Flushes the mapped cache when configured. Notification may execute 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] At least 3.
objv – [in] Borrowed full command argument array. Entries from objv[2] are vector references or Tcl lists, processed in order. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK after all appends, or TCL_ERROR; earlier successful arguments remain committed.
-
static Tcl_Size ParseFormat(void *clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const *objv, void *dstPtr)
Select a supported native scalar type from a format and byte width.
Floating, signed and unsigned formats resolve against native C sizeof values. Returns the consumed argument count, or -1 on error. This is host representation, not a portable serialized type description; conversion to double may lose integer precision.
- Parameters:
clientData – [in] Unused callback data; no ownership transfer.
interp – [in] Diagnostic/evaluation interpreter; see Interpreter arguments.
objc – [in] Number of remaining option-value arguments; zero reports a missing value.
objv – [in] Borrowed option-value slice; objv[0] is the value, not the option name.
dstPtr – [out] Required NativeFmtValue output, written only for a supported native representation.
- Returns:
One consumed argument on success, or -1 on failure; not a Tcl status code.
-
static Tcl_Size ParseAt(void *clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const *objv, void *dstPtr)
Parse a binary-input starting storage position.
Uses vector index conversion, allowing positions from zero through length inclusive. Returns the consumed argument count, or -1 on error. Index expressions may evaluate Tcl.
- Parameters:
clientData – [in] Borrowed VectorObject retained by the binread caller through index evaluation.
interp – [in] Diagnostic/evaluation interpreter; see Interpreter arguments.
objc – [in] Number of remaining option-value arguments; zero reports a missing value.
objv – [in] Borrowed option-value slice; objv[0] is the value, not the option name.
dstPtr – [out] Required Tcl_Size output receiving a zero-based storage position, written only on success.
- Returns:
One consumed argument on success, or -1 on failure; not a Tcl status code.
-
static int BinreadOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Read native-format channel scalars into vector storage.
Retains a readable channel, temporarily sets binary translation, and restores the saved translation if the caller has not closed the channel. Real values use one scalar, complex values two interleaved scalars. A positive count performs one read; zero reads chunks until EOF or a zero-byte read. Rejects incomplete values rather than buffering partial records. Completed chunks remain on error and trigger cache flushing/notification while preserving the original error state. Success reports logical value count. Checks destination lifetime/read-only state and channel registration after reflected reads. The dispatcher retains the vector.
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] At least 3.
objv – [in] Borrowed full command argument array. objv[2] names the channel; later entries contain the optional count and binary-input switches. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK with the logical value count read, or TCL_ERROR; earlier complete chunks may remain committed.
-
static int ClearOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Flush the mapped-array cache without emptying vector storage.
Delegate to Rbc_VectorFlushCache even when automatic flushing is disabled. Read-only vectors are accepted because this is not a numerical write. The helper may invoke user variable traces, whose side effects are not undone. Return TCL_OK after the void helper; do not access the receiver afterward or claim that cache recreation errors are propagated. No value notification is requested by this handler.
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 requesting cache flushing; lower-level variable errors are not propagated.
-
static int ExprOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Evaluate an expression into the existing receiver, then publish.
Pass objv[2] to Rbc_ExprVector with the receiver as destination. Evaluation uses temporary result storage and validates destination survival, writability and compatible result type before assignment. Propagate an evaluation or assignment error without calling NotifyCommandWrite. On success, request a full update through that callback-aware helper and return TCL_OK. This path does not create a named result vector or return its values as a Tcl list; expression and notification callback side effects remain observable.
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[2] is the vector expression assigned to the existing receiver. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK after assignment and publication, otherwise TCL_ERROR; no result vector is created.
-
static int SetOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Replace values from a vector range or Tcl list.
Stages vector ranges (including self-copy) or converted list values before replacing storage. Failed conversion does not write destination data. Tcl callbacks retain their own side effects. Flushes/notifies only a still-live committed object; callbacks cannot redirect the operation by recreating a name.
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[2] is a vector reference or a Tcl list of replacement values. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK after replacement and publication, otherwise TCL_ERROR.
-
static int SortOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Sort real values and apply their permutation to companion vectors.
Retains resolved destination identities and validates all keys before any write. Reuses one scratch array to apply the permutation without callbacks; only then flushes and notifies surviving objects. Notifications may alter or destroy committed vectors, but never expose a partially applied permutation.
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] At least 2.
objv – [in] Borrowed full command argument array. Optional -reverse starts at objv[2]; following entries are companion vector references. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK after applying the permutation and publication, otherwise TCL_ERROR.
-
static int VariableOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Query, replace or remove the receiver mapped-array association.
With objv[2], delegate to Rbc_VectorMapVariable and propagate its error. An empty name removes the mapping; it does not rename the vector command. On success, copy the stored array name into the Tcl result when non-NULL; otherwise do not explicitly set a result. The name is the stored mapping spelling, not a newly qualified command name. Read-only and complex receivers are supported. Mapping can invoke traces and is not a rollback transaction.
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 to query, or 3 to replace/remove the mapping.
objv – [in] Borrowed full command argument array. Optional objv[2] is the array name; an empty string requests unmapping. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK with the stored mapping name when present, or TCL_ERROR from mapping.
-
static int AppendVector(VectorObject *destPtr, VectorObject *srcPtr)
Append a selected vector range without Tcl-list conversion.
Requires matching real/complex types. Saves source selection before resize and uses memmove against current storage, permitting self-append. Checks length/byte arithmetic. Returns a Tcl status; does not flush or notify.
- Parameters:
destPtr – [inout] Caller-retained writable destination and interpreter; old-storage release may run callbacks.
srcPtr – [in] Live matching-type source with a caller-validated inclusive selection; may equal destPtr.
- Returns:
TCL_OK after append commit, otherwise TCL_ERROR; publication remains the caller’s responsibility.
-
static int AppendList(VectorObject *vPtr, Tcl_Size objc, Tcl_Obj *const objv[])
Stage list values before appending the completed list.
Converts a complete list into temporary storage and rechecks lifetime and writable state after conversion. Appends to the current length, accounting for callback edits. Conversion failure does not append a partial list. Does not flush or notify; the instance dispatcher retains the destination.
- Parameters:
vPtr – [inout] Caller-retained destination and interpreter; value conversion may execute Tcl.
objc – [in] Nonnegative number of values, excluding command and operation names.
objv – [in] Borrowed value-only array, copied into a private list representation for conversion.
- Returns:
TCL_OK after commit, otherwise TCL_ERROR; callback side effects are not rolled back.
-
static int CopyValues(VectorObject *vPtr, char *byteArr, enum NativeFormats fmt, int size, Tcl_Size length, int swap, Tcl_Size *indexPtr)
Convert a binary scalar buffer into real vector storage.
Checks writable state, range and size arithmetic, extends storage as needed, and advances indexPtr. Optional byte swapping modifies the input buffer in place per scalar. Returns a Tcl status; does not flush or notify.
- Parameters:
vPtr – [inout] Live writable real destination; caller retains record and interpreter through commit.
byteArr – [inout] Writable suitably aligned native-format buffer with one scalar per value; swap modifies it.
fmt – [in] Supported native scalar format matching the supplied size and buffer representation.
size – [in] Positive native scalar width in bytes, validated against fmt by the caller.
length – [in] Nonnegative number of real values to copy.
swap – [in] Nonzero to reverse the bytes of each scalar in byteArr before conversion.
indexPtr – [inout] Required zero-based destination position, from zero through current length; advanced on success.
- Returns:
TCL_OK after copying and committing, otherwise TCL_ERROR; no cache flushing or notification.
-
static int CopyComplexValues(VectorObject *vPtr, char *byteArr, enum NativeFormats fmt, int size, Tcl_Size length, int swap, Tcl_Size *indexPtr)
Convert interleaved binary components into complex storage.
Requires a complex vector. Checks writable state and size arithmetic; extends storage and advances indexPtr by logical values. Swaps bytes within each scalar component, never exchanging real and imaginary components. Modifies the input buffer when swapping; does not flush or notify.
- Parameters:
vPtr – [inout] Live writable complex destination; caller retains record and interpreter through commit.
byteArr – [inout] Writable suitably aligned native-format buffer with two scalars per logical value; swap modifies it.
fmt – [in] Supported native scalar format matching the supplied size and buffer representation.
size – [in] Positive native scalar width in bytes, validated against fmt by the caller.
length – [in] Nonnegative number of complex values, not scalar components to copy.
swap – [in] Nonzero to reverse the bytes of each scalar in byteArr before conversion.
indexPtr – [inout] Required zero-based destination position, from zero through current length; advanced on success.
- Returns:
TCL_OK after copying and committing, otherwise TCL_ERROR; no cache flushing or notification.
-
static int CopyList(VectorObject *vPtr, Tcl_Size objc, Tcl_Obj *const objv[])
Convert a complete Tcl list before replacing vector storage.
Returns a Tcl status. Conversion failure leaves destination values/length unchanged except for the callbacks’ own changes. Transfers staged storage on success, with lifetime/read-only checks before commit. Does not notify; callers retain the destination and interpreter through callbacks.
- Parameters:
vPtr – [inout] Caller-retained destination and interpreter; value conversion may execute Tcl.
objc – [in] Nonnegative number of values, excluding command and operation names.
objv – [in] Borrowed value-only array, copied into a private list representation for conversion.
- Returns:
TCL_OK after commit, otherwise TCL_ERROR; callback side effects are not rolled back.
-
static int CompareVectorIndices(VectorObject *const *vectorArr, Tcl_Size nVectors, Tcl_Size i1, Tcl_Size i2)
Compare two storage indices lexicographically across real keys.
Requires valid indices in every key vector. Returns -1 or 1 at the first unequal comparable key, otherwise zero. A NaN comparison falls through to the next key because neither less-than nor greater-than succeeds. Does not break ties by original index or invoke callbacks.
- Parameters:
vectorArr – [in] Array of live real key vectors, in primary-to-secondary order.
nVectors – [in] Number of key vectors; every key must contain both requested storage indices.
i1 – [in] First zero-based storage index to compare.
i2 – [in] Second zero-based storage index to compare.
- Returns:
-1, 0 or 1 according to the first ordered unequal key; NaN comparisons advance to the next key.
-
static void SiftVectorIndices(Tcl_Size *indexArr, Tcl_Size start, Tcl_Size end, VectorObject *const *vectorArr, Tcl_Size nVectors)
Restore a max heap within an inclusive permutation boundary.
Requires child subtrees below start already to be heaps and valid key storage for each permutation entry. Moves the root down by comparing children through CompareVectorIndices. The root bound prevents overflow in twice-root-plus-one arithmetic. Does nothing when end is not above start; modifies only permutation entries and allocates nothing.
- Parameters:
indexArr – [inout] Permutation containing valid storage indices for all real key vectors.
start – [in] Nonnegative root position in the permutation; child subtrees must already be heaps.
end – [in] Inclusive final heap position, not a storage index; end <= start performs no work.
vectorArr – [in] Borrowed array of stable real key vectors covering every referenced storage index.
nVectors – [in] Number of key vectors in primary-to-secondary order.
-
static void SortVectorIndices(Tcl_Size *indexArr, Tcl_Size length, VectorObject *const *vectorArr, Tcl_Size nVectors)
Heap-sort an existing index array in ascending key order.
Heapifies the permutation, then moves successive maxima to the end and repairs the remaining heap. Uses constant auxiliary storage and O(length log length) comparisons, each examining up to nVectors keys. Requires stable valid real key storage for the call. Does not move vector values, invoke Tcl or guarantee stable ordering of equal keys.
- Parameters:
indexArr – [inout] Permutation array with length entries, rearranged in place without moving vector values.
length – [in] Nonnegative permutation length; fewer than two entries require no work.
vectorArr – [in] Borrowed array of stable real key vectors covering every referenced storage index.
nVectors – [in] Number of key vectors in primary-to-secondary order.
-
static int AddVectorSizes(Tcl_Interp *interp, Tcl_Size a, Tcl_Size b, Tcl_Size *resultPtr)
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 CommandOutput
Validated vector-command destination and rollback ownership.
-
struct NativeFmtValue
Native binary format descriptor.
Public Members
-
int size
Element width in bytes.
-
enum NativeFormats format
Binary numeric format selector.
-
int size
-
struct VectorInstOpSpec
Typed command dispatch entry with shared argument validation metadata.
Public Members
-
Rbc_OpSpecHeader header
Operation name, total argument bounds and usage suffix.
-
RbcVectorCmdOp *proc
Typed command handler for this operation.
-
Rbc_OpSpecHeader header
Implementation selectors
-
enum NativeFormats
Identifies the numeric format decoded by vector binread.
Values:
-
enumerator FMT_UNKNOWN
-
enumerator FMT_UCHAR
-
enumerator FMT_CHAR
-
enumerator FMT_USHORT
-
enumerator FMT_SHORT
-
enumerator FMT_UINT
-
enumerator FMT_INT
-
enumerator FMT_ULONG
-
enumerator FMT_LONG
-
enumerator FMT_ULONGLONG
-
enumerator FMT_LONGLONG
-
enumerator FMT_FLOAT
-
enumerator FMT_DOUBLE
-
enumerator FMT_UNKNOWN