Generic Container Iteration

Provides a unified foreach macro for iterating over various container types and iterable objects. The macro expands to type-specific iteration code while presenting a consistent interface.

Overview

The foreach macro adapts to different container types, automatically handling iterator initialization, validity checking, advancement, and cleanup. The syntax varies by container type to accommodate different iteration patterns.

Supported Container Types

Dynamic Arrays (sarray)

Iterates over elements in a dynamic array with direct indexed access. Elements are copied by assignment (shallow copy), allowing iteration over value types without pointers.

Syntax:

foreach(sarray, index, ElementType, element, array)

Parameters:

• index - int32 iteration variable (0 to size-1)
• ElementType - Type of elements stored in the array (can be value or pointer type)
• element - Variable to receive each element (copied by assignment)
• array - The sarray to iterate (by value, not pointer)

Examples:

// Iterating over pointer types
sa_ObjIface impls = {0};
// ... populate array ...
foreach (sarray, i, ObjIface*, impl, impls) {
    if (!_objCheckIface(impl))
        return false;
}
 
// Iterating over value types (no pointer needed)
sa_int32 numbers = {0};
// ... populate array ...
foreach (sarray, i, int32, num, numbers) {
    total += num;
}

Hash Tables (hashtable)

Iterates over all entries in a hash table in insertion order. CX hashtables preserve the order in which entries were added.

Syntax:

foreach(hashtable, iterator, table)

Parameters:

• iterator - htiter variable for the iteration state
• table - The hashtable to iterate

Accessing Values: Use htiKey(type, iterator) and htiVal(type, iterator) to copy entries from the table, or use htiKeyPtr(type, iterator) and htiValPtr(type, iterator) to get direct pointers to the stored keys and values without copying:

// Copying values out of the table
hashtable deferred = {0};
// ... populate table ...
foreach (hashtable, it, deferred) {
    ComplexTask *task = htiKey(object, it);
    // process task...
}
 
// Direct access to stored values (no copy)
hashtable settings = {0};
// ... populate with string keys and int32 values ...
foreach (hashtable, it, settings) {
    string *key = htiKeyPtr(string, it);
    int32 *value = htiValPtr(int32, it);
    // Modify value in place: (*value)++
}

Strings (string)

Iterates over chunks (runs) of contiguous bytes in a string. This efficiently handles both simple strings (single chunk) and rope strings (multiple chunks).

Syntax:

foreach(string, iterator, str)

Parameters:

• iterator - striter variable for the iteration state
• str - The string to iterate

Iterator Fields:

• iterator.bytes - Pointer to current run of bytes
• iterator.len - Length of current run in bytes
• iterator.off - Byte offset from string start

Example:

foreach (string, it, str) {
    if (!sbufPWrite(sb, it.bytes, it.len))
        return false;
}

File System Search (vfssearch)

Iterates over directory entries in a VFS, optionally matching a search pattern.

Syntax:

foreach(vfssearch, iterator, vfs, path, pattern, typefilter, stat)

Parameters:

• iterator - FSSearchIter variable for the iteration state
• vfs - VFS instance to search within
• path - Directory path to search
• pattern - Wildcard pattern (e.g., "*.txt") or NULL for all entries
• typefilter - Entry type filter (FS_File, FS_Directory, or 0 for all)
• stat - bool indicating whether to populate stat information

Iterator Fields:

• iterator.name - Filename (string, valid until next iteration)
• iterator.type - Entry type (FS_File or FS_Directory)
• iterator.stat - File metadata (if stat parameter was true)

Example:

VFS *vfs = vfsCreate(0);
vfsMountFS(vfs, _S"/", _S"c:/data");
FSSearchIter iter;
foreach(vfssearch, iter, vfs, _S"/logs", _S"*.log", FS_File, false) {
    // Process iter.name (log files only)
}
objRelease(&vfs);

SSD Tree Nodes (ssd)

Iterates over key-value pairs in an SSDTree node with automatic locking. The iteration occurs within a locked transaction for thread safety.

Syntax:

foreach(ssd, iterator, index, key, value, node)

Parameters:

• iterator - SSDIterator* variable (managed internally)
• index - int32 variable to receive entry index
• key - strref variable to receive entry key
• value - stvar* variable to receive entry value
• node - The SSDNode to iterate

Example:

SSDNode *btree = ssdSubtreeB(tree, _S"config");
foreach(ssd, oiter, idx, name, val, btree) {
    if (strEq(name, _S"setting1") && stvarIs(val, int32)) {
        // Process val->data.st_int32
    }
}

Note: The node is automatically locked for the duration of the iteration.

Iterable Objects (object)

Iterates over objects implementing the Iterable interface, which provides an Iterator object for traversal.

Syntax:

foreach(object, iterator, IteratorType, obj)

Parameters:

• iterator - Iterator pointer variable
• IteratorType - Type of the iterator class
• obj - Object implementing the Iterable interface

Example:

MyIterable *collection = ...;
foreach(object, iter, MyIterator, collection) {
    stvar val;
    if (iter->_->get(iter, &val)) {
        // Process val
    }
}

Note: The iterator is automatically released when the loop exits.

Usage Guidelines

• All iterator variables are automatically initialized and cleaned up
• Breaking out of a foreach loop is safe - cleanup code always runs
• Iterator variables should not be modified manually
• Modifying the container during iteration may cause undefined behavior
• For hashtables and strings, use accessor functions to retrieve data