Previous: Memory Ports in Guile, Up: Guile API


23.3.3.22 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.