

                                                                   scan-fn

    FUNCTION
SCAN-FN TYPE INIT STEP &optional TEST                            [Function]

    Package
    series

    DESCRIPTION

The higher-order function SCAN-FN supports the general concept of scanning.
The TYPE argument is a type specifier, which specifies the type of values
returned by INIT and STEP.  The VALUES type specifier can be used for this
argument to indicate multiple types; however, TYPE cannot indicate zero
values.  If TYPE indicates M types t1, ..., tm, then SCAN-FN returns M
series T1, ..., TM where TI has the type (SERIES ti).  The arguments INIT,
STEP, and TEST are functions.

The INIT must be of type (FUNCTION () (VALUES t1 ... tm)).

The STEP must be of type (FUNCTION (t1 ... tm) (VALUES t1 ... tm)).

The TEST (if present) must be of type (FUNCTION (t1 ... tm) T).

The elements of the TI are computed as follows:

(VALUES T1[0] ... TM[0]) = (FUNCALL INIT) 
(VALUES T1[j] ... TM[j]) = (FUNCALL STEP T1[j-1] ... TM[j-1])


The outputs all have the same length.  If there is no TEST, the outputs
have unbounded length.  If there is a TEST, the outputs consist of the
elements up to, but not including, the first elements (with index J, say)
for which the following termination test is not NIL.

(FUNCALL TEST T1[j] ... TM[j])

It is guaranteed that STEP will not be applied to the elements that pass
this termination test.

If any of INIT, STEP, and TEST have side effects when invoked, they can
count on being called in the order indicated by the equations above, with
TEST called just before STEP on each cycle.  However, due to the lazy
evaluation nature of series, these functions will not be called until their
outputs are actually used (if ever).  In addition, no assumptions can be
made about the relative order of evaluation of these calls with regard to
execution in other parts of a given series expression.  The first example
below scans down a list stepping two elements at a time.  The second
example generates two unbounded series: the integers counting up from 1 and
the sequence of partial sums of the first I integers.

(SCAN-FN T #'(LAMBDA () '(A B C D)) #'CDDR #'NULL) => #Z((A B C D) (C D)) 
(SCAN-FN '(VALUES INTEGER INTEGER) 
         #'(LAMBDA () (VALUES 1 0)) 
         #'(LAMBDA (I SUM) (VALUES (+ I 1) (+ SUM I)))) 
 => #Z(1 2 3 4 ...) AND #Z(0 1 3 6 ...)


     SEE ALSO
     about-series
     about-generators
     scan-fn-inclusive

;Copyright 1989 by the Massachusetts Institute of Technology,
;Cambridge, Massachusetts.

;Permission to use, copy, modify, and distribute this software and its
;documentation for any purpose and without fee is hereby granted,
;provided that this copyright and permission notice appear in all
;copies and supporting documentation, and that the name of M.I.T. not
;be used in advertising or publicity pertaining to distribution of the
;software without specific, written prior permission. M.I.T. makes no
;representations about the suitability of this software for any
;purpose.  It is provided "as is" without express or implied warranty.

;    M.I.T. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
;    ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
;    M.I.T. BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
;    ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
;    WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
;    ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
;    SOFTWARE.



