#### 23.3.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`.