Iteration

Modules
	Byte-at-a-time Access
	UTF-8 Code Point Access

Data Structures
struct	striter

Typedefs
typedef struct striter	striter

Enumerations
enum	STRI_SEEK_TYPE { }
	Iterator seek type - specifies what units to seek by. More...
enum	STRI_SEEK_WHENCE { }
	Iterator seek origin - specifies where to seek from. More...

Functions
void	striInit (striter *i, strref s)
void	striInitRev (striter *i, strref s)
bool	striNext (striter *i)
bool	striPrev (striter *i)
bool	striSeek (striter *i, int32 off, STRI_SEEK_TYPE type, STRI_SEEK_WHENCE whence)
void	striFinish (striter *i)
bool	striValid (striter *i)
void	striBorrow (striter *i, strref s)
void	striBorrowRev (striter *i, strref s)

Detailed Description

String iterators provide low-level access to string bytes for scanning and parsing operations. They are designed to efficiently handle both simple strings and ropes without exposing the internal representation.

Iterator Concept

An iterator represents a "run" of contiguous bytes within the string. For simple strings, the entire string is one run. For ropes (large strings built from concatenation), the string consists of multiple runs that must be traversed separately.

The iterator exposes the current run through public members:

• bytes: Pointer to the current run of bytes
• off: Byte offset of this run from the start of the string
• len: Number of bytes in this run
• cursor: Current position within this run (for byte-at-a-time access)

Usage Patterns

Pattern 1 - Process runs directly (most efficient):

striter it;
striInit(&it, s);
while (it.len > 0) {
    for (uint32 i = 0; i < it.len; i++) {
        // Process it.bytes[i]
    }
    striNext(&it);
}
striFinish(&it);

Pattern 2 - Byte-at-a-time access (simpler but slower):

striter it;
striInit(&it, s);
uint8 ch;
while (striChar(&it, &ch)) {
    // Process ch
}
striFinish(&it);

Pattern 3 - UTF-8 code point access:

striter it;
striInit(&it, s);
int32 codepoint;
while (striU8Char(&it, &codepoint)) {
    // Process codepoint
}
striFinish(&it);

Borrowed Iterators

For maximum performance in controlled situations, borrowed iterators don't hold a reference to the string. They can be discarded without calling striFinish(), but the source string must remain valid for the iterator's lifetime. Use striBorrow() instead of striInit().

Typedef Documentation

striter

typedef struct striter striter

String iterator structure

Represents a position within a string and the current run of contiguous bytes. Users should access the public members (bytes, off, len, cursor) but not modify them directly - use the iterator functions instead.

Enumeration Type Documentation

STRI_SEEK_TYPE

enum STRI_SEEK_TYPE

Iterator seek type - specifies what units to seek by.

Enumerator
STRI_U8CHAR	Seek by byte offset. Seek by UTF-8 code points (slower)

Definition at line 93 of file striter.h.

STRI_SEEK_WHENCE

enum STRI_SEEK_WHENCE

Iterator seek origin - specifies where to seek from.

Enumerator
STRI_CUR	Seek from beginning of string.
STRI_END	Seek from current position. Seek from end of string

Definition at line 99 of file striter.h.

Function Documentation

striBorrow()

void striBorrow	(	striter *	i,
		strref	s
	)

Initializes a borrowed iterator at the beginning (forward)

Creates an iterator without holding a reference to the string. This is more efficient but requires the source string to remain valid for the iterator's lifetime. The iterator can be discarded without calling striFinish().

Use this for performance-critical code with well-controlled lifetimes.

Parameters

i	Iterator structure to initialize
s	String to iterate over (must remain valid)

Example:

striter it;
striBorrow(&it, s);
// ... use iterator ...
// No striFinish() needed, but s must stay valid

striBorrowRev()

void striBorrowRev	(	striter *	i,
		strref	s
	)

Initializes a borrowed iterator at the end (reverse)

Like striBorrow(), but positioned at the end for reverse iteration with striPrev(). Does not hold a string reference and can be discarded without striFinish().

Parameters

i	Iterator structure to initialize
s	String to iterate over (must remain valid)

Example:

striter it;
striBorrowRev(&it, s);
while (it.len > 0) {
    // Process run
    striPrev(&it);
}

striFinish()

void striFinish

(

striter *

i

)

Finishes with an iterator and releases resources

Releases the string reference held by the iterator. Must be called for every iterator created with striInit() or striInitRev() to prevent memory leaks. Not required for borrowed iterators (striBorrow).

Parameters

i	Iterator to finish

Example:

striter it;
striInit(&it, s);
// ... use iterator ...
striFinish(&it);

striInit()

void striInit	(	striter *	i,
		strref	s
	)

Initializes an iterator at the beginning of a string (forward iteration)

Creates an iterator positioned at the start of the string, set up to iterate forward. The iterator holds a reference to the string, so it must be cleaned up with striFinish() when done.

Parameters

i	Iterator structure to initialize
s	String to iterate over

Example:

striter it;
striInit(&it, s);
// ... use iterator ...
striFinish(&it);

striInitRev()

void striInitRev	(	striter *	i,
		strref	s
	)

Initializes an iterator at the end of a string (reverse iteration)

Creates an iterator positioned at the end of the string, set up to iterate backward using striPrev(). The iterator holds a reference to the string.

Parameters

i	Iterator structure to initialize
s	String to iterate over

Example:

striter it;
striInitRev(&it, s);
while (it.len > 0) {
    // Process run backward
    striPrev(&it);
}
striFinish(&it);

striNext()

bool striNext

(

striter *

i

)

Advances to the next run of bytes

Moves the iterator forward to the next contiguous run of bytes in the string. For simple strings, this will reach the end immediately. For rope strings, this advances to the next segment.

If cursor was in the middle of the previous run, the cursor position carries over (becomes negative) into the new run.

Parameters

i	Iterator to advance

Returns

true if advanced to next run, false if reached end of string

Example:

striter it;
striInit(&it, s);
do {
    // Process it.bytes[0..it.len-1]
} while (striNext(&it));
striFinish(&it);

Referenced by striAdvance(), striChar(), and striPeekChar().

striPrev()

bool striPrev

(

striter *

i

)

Moves to the previous run of bytes

Moves the iterator backward to the previous contiguous run of bytes. Used for reverse iteration, typically after striInitRev().

Parameters

i	Iterator to move backward

Returns

true if moved to previous run, false if reached beginning of string

Example:

striter it;
striInitRev(&it, s);
do {
    // Process run
} while (striPrev(&it));
striFinish(&it);

striSeek()

bool striSeek	(	striter *	i,
		int32	off,
		STRI_SEEK_TYPE	type,
		STRI_SEEK_WHENCE	whence
	)

Seeks to a specific position in the string

Repositions the iterator to a new location specified by offset, type, and origin. Can seek by byte offset or UTF-8 code points (slower). After seeking, the iterator is positioned at the start of a run containing the target position.

Parameters

i	Iterator to reposition
off	Offset to seek to
type	STRI_BYTE (byte offset) or STRI_U8CHAR (UTF-8 code points)
whence	STRI_SET (from start), STRI_CUR (from current), STRI_END (from end)

Returns

true if seek succeeded, false if position is out of bounds

Example:

striSeek(&it, 0, STRI_BYTE, STRI_SET);     // Seek to beginning
striSeek(&it, 10, STRI_BYTE, STRI_CUR);    // Advance 10 bytes
striSeek(&it, 5, STRI_U8CHAR, STRI_SET);   // Seek to 5th code point

striValid()

bool striValid ( striter *  i )

inline

bool striValid(striter *i)

Tests if an iterator has data available

Returns true if the iterator is positioned at a valid run with data, false if it has reached the end of the string or is invalid.

Parameters

i	Iterator to test

Returns

true if i->len > 0, false otherwise

Definition at line 231 of file striter.h.