Vector edit 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 indexed edits and rearrangement
Indexed and multi-output handlers with callback-aware storage ownership.
Functions
-
static int DeleteOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Delete selected values by bitmap compaction, or destroy the receiver.
With no indices, destroys the vector. Otherwise parses inclusive ranges into a bitmap, then compacts surviving real or complex entries in place and reduces length without shrinking capacity. Flushes when configured and reports a full update. Returns a Tcl status. Index expressions may run Tcl; rejects length changes, destroyed/read-only receivers and invalid selections before accessing the original bitmap. Callback side effects are not undone.
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 through normal dispatch; the internal two-argument branch destroys the receiver.
objv – [in] Borrowed full command argument array. Entries from objv[2] are inclusive index/range selections to remove. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK after compaction or internal destruction, otherwise TCL_ERROR.
-
static int DupOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Copy the receiver into a named destination.
Creates a missing destination with the source type; skips the receiver itself. Copies the source selection and offset into prepared storage before releasing the previous allocation. Retains destination identity through mapping and notification callbacks. Returns a Tcl status. The command table permits one destination; source data need not be snapshotted because no callback occurs before the copy completes.
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 literal output vector name. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK after copying or a self-copy no-op, otherwise TCL_ERROR; publication may fail after commit.
-
static int IndexOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Read an inclusive selection or fill it with a scalar value.
Reads return a Tcl list, including one-element selections. Writes convert a real scalar or complex pair and return the original input object. The append position may grow storage by one value but cannot be read. Reports a ranged update for existing real writes or recognized appends, otherwise a full update. Rechecks lifetime, writability and saved bounds after conversion; append follows the current end. Complete data precedes custom storage release. Cache flushing and notification retain identity and preserve the Tcl 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 read, or 4 to assign.
objv – [in] Borrowed full command argument array. objv[2] is the index/range; optional objv[3] is the real scalar or complex pair to replicate. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK with a copied list for reads or the original value object for writes; TCL_ERROR on failure.
-
static int LengthOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Query or resize the receiver and return its resulting length.
Accepts a nonnegative Tcl_Size, reuses capacity or prepares larger storage, and zero-fills new entries before committing. Returns the requested length even if a post-commit callback destroys the vector. Flushes/notifies only a still-live identity, preserving the result across 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] 2 to query, or 3 to resize.
objv – [in] Borrowed full command argument array. Optional objv[2] is the new nonnegative logical length. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK with the queried or requested length, otherwise TCL_ERROR.
-
static int MergeOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Interleave equal-length, same-type source selections into the receiver.
Resolves sources and saves their first indices, then builds the complete interleaved array before replacing destination storage. Retains all resolved source identities and revalidates their selections after the final lookup. Supports self-merge, checks count/byte arithmetic, and frees scratch storage on all exits. Completed data precedes release/flush 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] At least 3.
objv – [in] Borrowed full command argument array. Entries from objv[2] are same-type vector references with equal selected lengths. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK after interleaving and publication, otherwise TCL_ERROR.
-
static int OffsetOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Query or assign the external numeric index offset.
Parses a Tcl_Size and returns the current offset as an integer. Does not move values, flush array entries or notify observers. The dispatcher treats the setter as a receiver mutation and rejects read-only vectors.
- 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 assign.
objv – [in] Borrowed full command argument array. Optional objv[2] is the new external Tcl_Size index offset. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK with the current offset, or TCL_ERROR for conversion failure.
-
static int PopulateOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Insert evenly spaced values between neighboring source values.
Requires integer density at least one. For nonempty length N, output length is (N-1)*(density+1)+1 with overflow checks; empty input produces empty output. Builds a complete same-type result before resolving the destination, allowing self-output without a temporary vector object. Interpolates real and imaginary components independently and retains the last endpoint. Publishes only after commit; callbacks see complete data. 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] 4; validated by the dispatcher.
objv – [in] Borrowed full command argument array. objv[2] names the destination; objv[3] is the positive number of inserted values per interval. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK after output publication, otherwise TCL_ERROR; output mapping can fail after commit.
-
static int SplitOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Append round-robin source subsequences to named destinations.
Requires source length divisible by destination count; no destinations is a no-op. Prechecks writable existing destinations and creates missing ones. Snapshots the source and retains all destination identities. Each append is complete before releasing its old storage; publication follows the write loop, flushing before notification. A later failure leaves earlier appends committed and published. Destroyed/recreated identities are never written again. Returns a Tcl status; this is not an all-output 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] At least 2; no destinations is a successful no-op.
objv – [in] Borrowed full command argument array. Entries from objv[2] are literal destination names receiving round-robin source subsequences. See Tcl command arguments for shared argument lifetime rules.
- Returns:
TCL_OK after appending and publishing all outputs, otherwise TCL_ERROR; earlier commits remain.
-
static int DeleteOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])