Previous: Memory Ports in Guile, Up: Guile API

##### 23.4.3.25 Iterators In Guile

A simple iterator facility is provided to allow, for example, iterating over the set of program symbols without having to first construct a list of all of them. A useful contribution would be to add support for SRFI 41 and SRFI 45.

— Scheme Procedure: make-iterator object progress next!

> A `<gdb:iterator>` object is constructed with the `make-iterator` procedure. It takes three arguments: the object to be iterated over, an object to record the progress of the iteration, and a procedure to return the next element in the iteration, or an implementation chosen value to denote the end of iteration.

> By convention, end of iteration is marked with `(end-of-iteration)`, and may be tested with the `end-of-iteration?` predicate. The result of `(end-of-iteration)` is chosen so that it is not otherwise used by the `(gdb)` module. If you are using `<gdb:iterator>` in your own code it is your responsibility to maintain this invariant.

> A trivial example for illustration's sake:

>               (use-modules (gdb iterator))
>               (define my-list (list 1 2 3))
>               (define iter
>                 (make-iterator my-list my-list
>                                (lambda (iter)
>                                  (let ((l (iterator-progress iter)))
>                                    (if (eq? l '())
>                                        (end-of-iteration)
>                                        (begin
>                                          (set-iterator-progress! iter (cdr l))
>                                          (car l)))))))

> Here is a slightly more realistic example, which computes a list of all the functions in `my-global-block`.

>               (use-modules (gdb iterator))
>               (define this-sal (find-pc-line (frame-pc (selected-frame))))
>               (define this-symtab (sal-symtab this-sal))
>               (define this-global-block (symtab-global-block this-symtab))
>               (define syms-iter (make-block-symbols-iterator this-global-block))
>               (define functions (iterator-filter symbol-function? syms-iter))

— Scheme Procedure: iterator? object

> Return `#t` if object is a `<gdb:iterator>` object. Otherwise return `#f`.

— Scheme Procedure: iterator-object iterator

> Return the first argument that was passed to `make-iterator`. This is the object being iterated over.

— Scheme Procedure: iterator-progress iterator

> Return the object tracking iteration progress.

— Scheme Procedure: set-iterator-progress! iterator new-value

> Set the object tracking iteration progress.

— Scheme Procedure: iterator-next! iterator

> Invoke the procedure that was the third argument to `make-iterator`, passing it one argument, the `<gdb:iterator>` object. The result is either the next element in the iteration, or an end marker as implemented by the `next!` procedure. By convention the end marker is the result of `(end-of-iteration)`.

— Scheme Procedure: end-of-iteration

> Return the Scheme object that denotes end of iteration.

— Scheme Procedure: end-of-iteration? object

> Return `#t` if object is the end of iteration marker. Otherwise return `#f`.

These functions are provided by the `(gdb iterator)` module to assist in using iterators.

— Scheme Procedure: make-list-iterator list

> Return a `<gdb:iterator>` object that will iterate over list.

— Scheme Procedure: iterator->list iterator

> Return the elements pointed to by iterator as a list.

— Scheme Procedure: iterator-map proc iterator

> Return the list of objects obtained by applying proc to the object pointed to by iterator and to each subsequent object.

— Scheme Procedure: iterator-for-each proc iterator

> Apply proc to each element pointed to by iterator. The result is unspecified.

— Scheme Procedure: iterator-filter pred iterator

> Return the list of elements pointed to by iterator that satisfy pred.

— Scheme Procedure: iterator-until pred iterator

> Run iterator until the result of `(pred element)` is true and return that as the result. Otherwise return `#f`.