Container C reference

These interfaces are private. See Chains and keyed lists for ownership and traversal.

void Rbc_ChainInit(Rbc_Chain *chainPtr)

Initialize caller-owned storage as an empty chain.

Does not free existing links. Use Reset to clear an initialized chain.

Parameters:
  • chainPtr – [inout] Required caller-owned record to initialize; no existing links are released.

void Rbc_ChainReset(Rbc_Chain *chainPtr)

Free all linked records and leave an empty initialized chain.

NULL is harmless. External clientData is not freed. Inline storage created by ChainAllocLink is part of each freed record; run any payload cleanup first.

Parameters:
  • chainPtr – [inout] Initialized chain to clear, or NULL; container storage remains owned by the caller.

void Rbc_ChainDestroy(Rbc_Chain *chainPtr)

Reset and free a heap-allocated chain, accepting NULL.

Do not use on stack or embedded storage. External payload ownership remains with the caller.

Parameters:
  • chainPtr – [inout] Heap-allocated chain to consume, or NULL; all linked records and the container become invalid.

Allocate a detached zeroed link with aligned trailing storage.

With nonzero size, clientData points into the same allocation; do not free it separately. With zero size clientData is NULL. Size overflow panics. Link it into a chain or release the detached allocation with ckfree.

Parameters:
  • size – [in] Requested trailing payload bytes, excluding the link header and alignment padding; zero creates a plain link.

Detach a link without freeing its record or payload.

Supply its actual chain; links do not store owner identity and this helper cannot validate membership. Clears next/previous pointers. The detached link may be reinserted or freed by the caller.

Parameters:
  • chainPtr – [inout] Required actual owning chain; membership is not checked.

  • linkPtr – [inout] Required member link; detached with NULL neighbors and returned to caller ownership.

Unlink and free a link record, including any inline trailing storage.

Requires a valid link and its actual chain. Does not free external clientData. All borrowed pointers into the link become invalid.

Parameters:
  • chainPtr – [inout] Required actual owning chain; membership is not checked.

  • linkPtr – [inout] Required member link; allocation and inline payload are consumed; external payload ownership is unchanged.

Rbc_ListNode Rbc_ListCreateNode(Rbc_List list, const char *key)

Allocate a keyed node for a list without inserting it.

String and integer-array keys are copied into the allocation; one-word keys retain only the pointer value. Duplicate keys are permitted. The node already records the intended list: insert it before using ListUnlinkNode/DeleteNode, or free this never-inserted allocation directly with ckfree.

Parameters:
  • list – [in] Required initialized list supplying key type and initial owner identity; no node is inserted.

  • key – [in] Key matching the list type: readable NUL-terminated string, pointer-sized identity, or readable native int array; only identity keys may be NULL.

void Rbc_ListReset(Rbc_List list)

Free linked nodes and copied keys while retaining the list key type.

Accepts NULL. Does not free clientData or objects denoted by one-word keys. Nodes allocated but never inserted are not visited.

Parameters:
  • list – [inout] Initialized list to clear, or NULL; retains the container and key type but frees linked nodes.

void Rbc_ListUnlinkNode(Rbc_ListNode node)

Detach an inserted node without freeing it or its payload.

Clears owner, next and previous pointers. A previously unlinked node is a no-op, but a newly created, never-inserted node is not valid input: its owner field is already set although the list count does not include it.

Parameters:
  • node – [inout] Required inserted or normally unlinked node; clears membership without freeing it. Never-inserted nodes are invalid.

void Rbc_ListDeleteNode(Rbc_ListNode node)

Unlink and free an inserted or previously unlinked node.

Copied key storage is freed with the record; external clientData and one-word key targets are not freed. Never pass a newly created, never-inserted node.

Parameters:
  • node – [inout] Required inserted or normally unlinked node to consume; never pass a newly created, never-inserted node.

Rbc_ListNode Rbc_ListGetNode(Rbc_List list, const char *key)

Return the borrowed first node matching a key, or NULL.

Searches linearly in list order; duplicate keys are not rejected. A NULL list returns NULL. The node remains owned by its container/caller.

Parameters:
  • list – [in] Initialized list, or NULL for no match; membership is unchanged.

  • key – [in] Key matching the list type: readable NUL-terminated string, pointer-sized identity, or readable native int array; only identity keys may be NULL.

void Rbc_ListSort(Rbc_List list, Rbc_ListCompareProc *proc)

Reorder existing nodes with qsort without moving their allocations.

The comparator receives pointers to node pointers. It must not mutate the list, delete nodes or reenter code that does so. Equal-key ordering is not stable. NULL/short lists are unchanged; scratch-allocation failure silently leaves the list unchanged. Payload ownership is unaffected.

Parameters:
  • list – [inout] Initialized list to reorder, or NULL; NULL and lists shorter than two nodes are unchanged.

  • proc – [in] Comparator receiving pointers to node pointers; required for a nontrivial sort and must not mutate or destroy list state.

Implementation helpers

group Keyed-list search and reclamation

Private helpers; callers retain storage and lifetime responsibilities.

Functions

static struct Rbc_ListNodeStruct *FindString(struct Rbc_ListStruct *listPtr, const char *key)

Find the first node with equal string-key contents.

Requires a valid string-key list and non-NULL NUL-terminated key. Checks the first byte before strcmp while traversing head to tail. Returns a borrowed node or NULL without mutation, allocation or retention.

Parameters:
  • listPtr – [in] Borrowed live list with key representation matching this lookup helper; membership is not changed.

  • key – [in] Borrowed non-NULL NUL-terminated string whose contents are compared.

static Rbc_ListNode FindOneWord(struct Rbc_ListStruct *listPtr, const char *key)

Find the first node with the same pointer-sized key value.

Requires a valid one-word-key list. Compares identity, not pointed-to contents; NULL is a valid key value. Returns a borrowed first match or NULL. Does not dereference keys or change membership/payload ownership.

Parameters:
  • listPtr – [in] Borrowed live list with key representation matching this lookup helper; membership is not changed.

  • key – [in] Pointer-sized identity key; NULL is valid and pointed-to memory is never read.

static Rbc_ListNode FindArray(struct Rbc_ListStruct *listPtr, const char *key)

Find the first node with equal integer-array key bytes.

Requires a valid list whose type is the key’s int count and a readable key buffer of that size. Invalid count or byte-size overflow panics. Uses memcmp on copied native int bytes, not text or portable serialization. Returns a borrowed first match or NULL without mutation or allocation.

Parameters:
  • listPtr – [in] Borrowed live list with key representation matching this lookup helper; membership is not changed.

  • key – [in] Borrowed readable bytes for listPtr->type native ints, compared without alignment-dependent dereferencing.

static void FreeNode(struct Rbc_ListNodeStruct *nodePtr)

Free a node allocation and its inline copied key.

Caller must already have removed the node from membership, or be disposing of a never-inserted record. Does not unlink, adjust list count or free payloads or one-word key targets. All pointers into the node become invalid.

Parameters:
  • nodePtr – [inout] Owned detached node allocation; freed without unlinking or releasing its borrowed payload.

Creation, insertion and lookup

Rbc_Chain *Rbc_ChainCreate()

Allocate an initialized empty chain.

Uses Tcl allocation; allocation exhaustion is not a recoverable Tcl error. The caller owns the container and eventually uses Rbc_ChainDestroy. No payload or link is created.

Allocate a detached link with NULL neighbors and payload.

Caller owns the Tcl-allocated record until insertion. Link it once into a chain, or release the detached allocation with ckfree. No external payload is allocated or retained; allocation exhaustion follows Tcl’s allocation policy.

Rbc_ChainLink *Rbc_ChainAppend(Rbc_Chain *chainPtr, ClientData clientData)

Allocate a link and append a borrowed payload pointer.

Requires an initialized non-NULL chain. Returns the newly linked record, owned by the chain. Does not copy, retain or release clientData. Insertion increments the count and panics on count overflow.

Parameters:
  • chainPtr – [inout] Required initialized destination chain; takes ownership of the newly allocated link.

  • clientData – [in] Borrowed payload pointer, possibly NULL; no copy, retention or destructor is applied.

Rbc_ChainLink *Rbc_ChainPrepend(Rbc_Chain *chainPtr, ClientData clientData)

Allocate a link and prepend a borrowed payload pointer.

Requires an initialized non-NULL chain. Returns the newly linked record, owned by the chain. clientData remains independently owned. Allocation/count failure is not reported through an interpreter.

Parameters:
  • chainPtr – [inout] Required initialized destination chain; takes ownership of the newly allocated link.

  • clientData – [in] Borrowed payload pointer, possibly NULL; no copy, retention or destructor is applied.

void Rbc_ChainLinkAfter(Rbc_Chain *chainPtr, Rbc_ChainLink *linkPtr, Rbc_ChainLink *afterLinkPtr)

Insert a detached link after a neighbor, or prepend for NULL.

Requires a valid chain, a detached link with NULL neighbor pointers, and a non-NULL neighbor belonging to that chain. Does not validate membership or unlink an already inserted link. Updates endpoints, neighbors and count without allocation or callbacks; count overflow panics. Payload ownership is unchanged.

Parameters:
  • chainPtr – [inout] Required initialized destination chain; count and neighbors are updated.

  • linkPtr – [inout] Detached link with NULL neighbors; ownership of the record transfers to the chain.

  • afterLinkPtr – [in] Borrowed neighbor in this chain, or NULL to prepend.

void Rbc_ChainLinkBefore(Rbc_Chain *chainPtr, Rbc_ChainLink *linkPtr, Rbc_ChainLink *beforeLinkPtr)

Insert a detached link before a neighbor, or append for NULL.

Requires a valid chain, a detached link with NULL neighbor pointers, and a non-NULL neighbor belonging to that chain. No membership validation or automatic unlinking occurs. Updates endpoints, neighbors and count without allocation; count overflow panics. The chain owns the inserted record, not its payload.

Parameters:
  • chainPtr – [inout] Required initialized destination chain; count and neighbors are updated.

  • linkPtr – [inout] Detached link with NULL neighbors; ownership of the record transfers to the chain.

  • beforeLinkPtr – [in] Borrowed neighbor in this chain, or NULL to append.

void Rbc_ListInit(Rbc_List list, int type)

Initialize caller-owned list storage with a key representation.

Requires a non-NULL record. Stores type and clears endpoints/count; does not free prior nodes or validate type. Use TCL_STRING_KEYS, TCL_ONE_WORD_KEYS or an integer-array word count greater than TCL_ONE_WORD_KEYS. Reset a populated list before reinitializing it.

Parameters:
  • list – [inout] Required caller-owned record; initialization does not release existing nodes.

  • type – [in] TCL_STRING_KEYS, TCL_ONE_WORD_KEYS, or an int-array word count greater than TCL_ONE_WORD_KEYS; not validated here.

Rbc_List Rbc_ListCreate(int type)

Allocate and initialize an empty keyed list.

Returns caller-owned Tcl-allocated storage, eventually released through Rbc_ListDestroy. Type has the same preconditions as Rbc_ListInit and is not validated here. Allocation exhaustion is not an interpreter error.

Parameters:
  • type – [in] TCL_STRING_KEYS, TCL_ONE_WORD_KEYS, or an int-array word count greater than TCL_ONE_WORD_KEYS; not validated here.

void Rbc_ListDestroy(Rbc_List list)

Reset and free a heap-allocated keyed list.

Accepts NULL. Releases linked nodes and copied keys, then the list itself. Does not free external payloads or one-word key targets. Do not pass stack or embedded storage; use Rbc_ListReset for those records.

Parameters:
  • list – [inout] Heap-allocated list to consume, or NULL; linked nodes and container storage become invalid.

Rbc_ListNode Rbc_ListAppend(Rbc_List list, const char *key, ClientData clientData)

Create a keyed node and insert it at the tail.

Requires a valid initialized list and a key matching its representation. Copies string/array keys and stores one-word keys by value. Duplicate keys are allowed. Returns the list-owned node; clientData is borrowed and unchanged. Allocation, invalid key type and count overflow use fatal allocation/panic paths.

Parameters:
  • list – [inout] Required initialized destination list; owns the new node on return.

  • key – [in] Key matching the list type: readable NUL-terminated string, pointer-sized identity, or readable native int array; only identity keys may be NULL.

  • clientData – [in] Borrowed payload pointer, possibly NULL; no retention or destructor is installed.

Rbc_ListNode Rbc_ListPrepend(Rbc_List list, const char *key, ClientData clientData)

Create a keyed node and insert it at the head.

Uses the same key-copy and payload-ownership rules as Rbc_ListAppend. Duplicate keys are allowed and the new node becomes the first matching node for lookup. Requires a valid list/key; returns a list-owned record.

Parameters:
  • list – [inout] Required initialized destination list; owns the new node on return.

  • key – [in] Key matching the list type: readable NUL-terminated string, pointer-sized identity, or readable native int array; only identity keys may be NULL.

  • clientData – [in] Borrowed payload pointer, possibly NULL; no retention or destructor is installed.

void Rbc_ListLinkAfter(Rbc_List list, Rbc_ListNode node, Rbc_ListNode afterNode)

Insert a node after a neighbor, or prepend for NULL.

Accepts a newly created node or a normally unlinked node with NULL neighbors. Its key representation must match the destination list. Any non-NULL neighbor must belong to that list; an already inserted node must first be unlinked. Sets the node owner, neighbors, endpoints and count without allocation or callbacks. Count overflow panics; no membership or key-type check is performed.

Parameters:
  • list – [inout] Required initialized destination with a key type matching the node allocation.

  • node – [inout] Newly created or normally unlinked node with NULL neighbors; destination takes ownership.

  • afterNode – [in] Borrowed neighbor in the destination list, or NULL to prepend.

void Rbc_ListLinkBefore(Rbc_List list, Rbc_ListNode node, Rbc_ListNode beforeNode)

Insert a node before a neighbor, or append for NULL.

Requires the same detached/construction state and compatible key representation as Rbc_ListLinkAfter. Does not unlink prior membership or validate the neighbor. Sets owner and links, increments count, and panics on count overflow. Node payload and copied-key storage remain unchanged.

Parameters:
  • list – [inout] Required initialized destination with a key type matching the node allocation.

  • node – [inout] Newly created or normally unlinked node with NULL neighbors; destination takes ownership.

  • beforeNode – [in] Borrowed neighbor in the destination list, or NULL to append.

void Rbc_ListDeleteNodeByKey(Rbc_List list, const char *key)

Delete only the first matching node in current list order.

A NULL list or absent key is a no-op. Otherwise unlinks and frees the node and copied key, leaving clientData and one-word key targets owned by the caller. Uses the historical Rb_ spelling. Does not call a payload destructor.

Parameters:
  • list – [inout] Initialized list, or NULL for no match; the first matching node is removed and freed.

  • key – [in] Key matching the list type: readable NUL-terminated string, pointer-sized identity, or readable native int array; only identity keys may be NULL.

Rbc_ListNode Rbc_ListGetNthNode(Rbc_List list, Tcl_Size position, int direction)

Return a borrowed node at a zero-based position.

Traverses from head when direction is positive, from tail otherwise. Returns NULL for a NULL list, negative position or position at/above length. Linear traversal does not mutate the list or retain the returned record.

Parameters:
  • list – [in] Borrowed initialized list, or NULL to return NULL.

  • position – [in] Zero-based traversal position; negative or out-of-range values return NULL.

  • direction – [in] Positive starts at the head; zero or negative starts at the tail.

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 Rbc_Chain

Doubly linked chain container; links do not own client payloads.

Public Members

Rbc_ChainLink *headPtr

Pointer to first element in chain.

Rbc_ChainLink *tailPtr

Pointer to last element in chain.

Number of elements in chain.

struct Rbc_ChainLinkStruct

Chain linkage with borrowed caller payload.

Public Members

Rbc_ChainLink *prevPtr

Link to the previous link.

Rbc_ChainLink *nextPtr

Link to the next link.

ClientData clientData

Pointer to the data object.

union Rbc_ListKey
#include <rbcList.h>

Inline keyed-list storage selected by Rbc_ListStruct::type.

String and integer-array keys extend the node allocation beyond these placeholder arrays. One-word keys store only a borrowed pointer value. Keep the containing key member last in Rbc_ListNodeStruct.

Public Members

const char *oneWordValue

Borrowed one-word key; only the pointer value is stored.

int words[1]

Inline integer-array key; allocation extends to the list’s key word count.

char string[4]

Inline NUL-terminated string key; allocation extends to fit the copied key.

struct Rbc_ListNodeStruct

List link with inline or pointer key storage selected by the list key type.

Public Members

struct Rbc_ListNodeStruct *prevPtr

Link to the previous node.

struct Rbc_ListNodeStruct *nextPtr

Link to the next node.

ClientData clientData

Pointer to the data object.

struct Rbc_ListStruct *listPtr

List to eventually insert node.

union Rbc_ListKey key

Inline key storage; must remain last because allocation extends it for long keys.

struct Rbc_ListStruct

Owned list container; node payload ownership remains with the caller.

Public Members

struct Rbc_ListNodeStruct *headPtr

Pointer to first element in list.

struct Rbc_ListNodeStruct *tailPtr

Pointer to last element in list.

Tcl_Size nNodes

Number of node currently in the list.

int type

Type of keys in list.