iter.h File Reference

Iterator type for x-lang (lazy traversal of sequences). More...

#include "x-type.h"

Go to the source code of this file.

Macros
#define	X_TYPE_ITER_NAME   "ITER"
Type predicates
#define	x_obj_type_isiter(B, X)   x_obj_is_type((B), (X), X_TYPE_ITER_NAME)
Field accessors
Iterator layout: (step-fn . current-value) – a boxed GENERATOR. Steps are PURE (they never touch the box); x_type_iter_next owns the write-back. Step ABIs: a SATOM step is a raw C fn over a caller-owned state cell (zero-alloc); any other callable is functional, (step state) -> (value . next-state) | nil – the Gen/Seq contract.
#define	x_iterprim(X)   x_firstobj((X))
#define	x_iterval(X)   x_restobj((X))
#define	x_iterempty(B, X)   x_obj_isnil((B), x_iterval(X))
Convenience constructors
#define	x_mkiter(B, FN, L)   x_make_iter((B), X_OBJ_FLAG_NONE, (FN), (L))
#define	x_mkfiter(B, F, FN, L)   x_make_iter((B), (F), (FN), (L))

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_register (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_iter_struct (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)

Detailed Description

Iterator type for x-lang (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)

Macro Definition Documentation

x_iterempty

#define x_iterempty	(		B,
			X
	)		x_obj_isnil((B), x_iterval(X))

True when iterator is exhausted.

x_iterprim

#define x_iterprim

(

X

)

x_firstobj((X))

Step function (callable).

x_iterval

#define x_iterval

(

X

)

x_restobj((X))

Current value (nil when exhausted).

x_mkfiter

#define x_mkfiter	(		B,
			F,
			FN,
			L
	)		x_make_iter((B), (F), (FN), (L))

Make iterator with explicit flags.

x_mkiter

#define x_mkiter	(		B,
			FN,
			L
	)		x_make_iter((B), X_OBJ_FLAG_NONE, (FN), (L))

Make iterator with default flags.

x_obj_type_isiter

#define x_obj_type_isiter	(		B,
			X
	)		x_obj_is_type((B), (X), X_TYPE_ITER_NAME)

Test if object is an iterator.

X_TYPE_ITER_NAME

#define X_TYPE_ITER_NAME   "ITER"

Type name string (overridable).

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.

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 for ITER.

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, returning the current element.

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.

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: (value . next-iterator) pair, or NULL.

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.

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