iter.c File Reference

Iterator type implementation (lazy traversal of sequences). More...

#include "x-type/iter.h"
#include "x-obj.h"
#include "x-eval.h"
#include "x-type/prim.h"

Functions
x_obj_t *	x_make_iter (x_obj_t *p_base, x_obj_flag_t flags, void *p1, void *p2)
x_obj_t *	x_type_iter_struct (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_iter_register (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_iter_make (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_iter_next (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_iter_step (x_obj_t *p_base, x_obj_t *p_args)

Variables
x_satom_t	x_type_iter_name = x_obj_set(x_type_atom_obj, X_OBJ_FLAG_NONE, { .s = (x_char_t *)X_TYPE_ITER_NAME })
x_satom_t	x_type_iter_make_prim = x_obj_set(x_type_atom_obj, X_OBJ_FLAG_NONE, { (x_obj_t *)&x_type_iter_make })
x_satom_t	x_type_iter_struct_prim = x_obj_set(x_type_atom_obj, X_OBJ_FLAG_NONE, { (x_obj_t *)&x_type_iter_struct })

Detailed Description

Iterator type implementation (lazy traversal of sequences).

Author

Jon Ruttan (jonru.nosp@m.ttan.nosp@m.@gmai.nosp@m.l.co.nosp@m.m)

Copyright

2024 Jon Ruttan @license MIT No Attribution (MIT-0)

Function Documentation

x_make_iter()

x_obj_t * x_make_iter	(	x_obj_t *	p_base,
		x_obj_flag_t	flags,
		void *	p1,
		void *	p2
	)

Allocate a new iterator object on the heap.

The iterator stores a step function (p1) and a current value (p2) in the standard pair layout.

Parameters

p_base	x_obj_t* – Base (execution context)
flags	x_obj_flag_t – Object flags
p1	void* – Step function (callable)
p2	void* – Initial value (nil when exhausted)

Returns

Heap-allocated iterator object

x_type_iter_make()

x_obj_t * x_type_iter_make	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Type-dispatch make callback: construct an iterator from x-lang args.

Expects args: ((step-fn . value) [flags]).

Parameters

p_base	x_obj_t* – Base (execution context)
p_args	x_obj_t* – Construction arguments

Returns

New iterator object

x_type_iter_next()

x_obj_t * x_type_iter_next	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Advance an iterator by one step.

The iterator is a boxed GENERATOR: (step . state). Steps are pure – they never mutate the box; this driver owns the single write-back. Two step ABIs, discriminated exactly as x_callable_call does:

• SATOM step (raw C fn): pure cell ABI. Called with a caller-owned stack cell (state . nil); the step returns the value and writes the successor state into the cell's first slot. Zero heap allocation, so the tokenizer's stack iterators stay GC-silent.
• Any other callable (x-lang fn, heap prim): functional ABI. Called as (step state) via the apply path (state is data, never re-evaluated) and must return (value . next-state), or nil when exhausted. This is the Gen / Seq step contract.

Parameters

p_base	x_obj_t* – Base (execution context)
p_args	x_obj_t* – (iterator)

Returns

The yielded element, or NULL when exhausted

x_type_iter_register()

x_obj_t * x_type_iter_register	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Register (or retrieve) the ITER type struct on p_base.

Parameters

p_base	x_obj_t* – Base (execution context)
p_args	x_obj_t* – Unused

Returns

The registered type struct object

x_type_iter_step()

x_obj_t * x_type_iter_step	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Step an iterator FUNCTIONALLY – no mutation, generator view.

The persistent complement of x_type_iter_next: yields (value . next-iterator) as a fresh pair (the Seq step shape), leaving the given iterator untouched, or nil when it is exhausted. This is the X-boundary door that lets Gen pipelines run on C steps; the two allocations happen here, where allocation is legal.

Parameters

p_base	x_obj_t* – Base (execution context)
p_args	x_obj_t* – (iterator)

Returns

(value . next-iterator) pair, or NULL when exhausted

x_type_iter_struct()

x_obj_t * x_type_iter_struct	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Build the ITER type struct descriptor.

Parameters

p_base	x_obj_t* – Base (execution context)
p_args	x_obj_t* – Unused

Returns

Type struct pair list

Variable Documentation

x_type_iter_make_prim

x_satom_t x_type_iter_make_prim = x_obj_set(x_type_atom_obj, X_OBJ_FLAG_NONE, { (x_obj_t *)&x_type_iter_make })

x_type_iter_name

x_satom_t x_type_iter_name = x_obj_set(x_type_atom_obj, X_OBJ_FLAG_NONE, { .s = (x_char_t *)X_TYPE_ITER_NAME })

x_type_iter_struct_prim

x_satom_t x_type_iter_struct_prim = x_obj_set(x_type_atom_obj, X_OBJ_FLAG_NONE, { (x_obj_t *)&x_type_iter_struct })