

                                                                collecting-fn

    FUNCTION
COLLECTING-FN TYPE INIT FUNCTION &rest SERIES-INPUTS             [Function]

    Package
    series

    DESCRIPTION

The higher-order function COLLECTING-FN supports the general concept of a
simple transducer with internal state.  The TYPE argument is a type
specifier, which specifies the type of values returned by FUNCTION.  The
VALUES construct can be used to indicate multiple types; however, TYPE
cannot indicate zero values.  If TYPE indicates M types t1, ..., tm, then
COLLECTING-FN returns M series T1, ..., TM where TI has the type (SERIES
ti).  The arguments INIT and FUNCTION are functions.  The remaining
arguments (if any) are all series.  Let these series be S1, ..., SN and
suppose that SI has the type (SERIES si).

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

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

The length of each output is the same as the length of the shortest input.
If there are no bounded series inputs, the outputs are unbounded.  The
elements of the TI are computed as follows:

(VALUES T1[0] ... TM[0]) =
  (MULTIPLE-VALUE-CALL FUNCTION (FUNCALL  INIT) S1[0] ... SN[0]) 

(VALUES T1[j] ... TM[j]) = 
  (FUNCALL FUNCTION T1[j-1] ... TM[j-1] S1[j] ... SN[j]) 

If INIT and/or FUNCTION have side effects, they can count on being called
in the order indicated by the equations above.  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 computes a series of partial sums of the numbers in an input series.
The second example computes two output series: the partial sums of its
first input and the partial products of its second input.

(COLLECTING-FN 'INTEGER #'(LAMBDA () 0) #'+ #Z(1 2 3)) => #Z(1 3 6) 
(COLLECTING-FN '(VALUES INTEGER INTEGER) 
               #'(LAMBDA () (VALUES 0 1)) 
               #'(LAMBDA (SUM PROD X Y) 
                   (VALUES (+ SUM X) (* PROD Y))) 
               #Z(4 6 8)  
               #Z(1 2 3)) 
 => #Z(4 10 18) AND #Z(1 2 6)



     SEE ALSO
     about-series
     about-generators

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



