

                                                                     map-fn

    FUNCTION
MAP-FN TYPE FUNCTION &rest SERIES-INPUTS                         [Function]

    Package
    series

    DESCRIPTION

The higher-order function MAP-FN supports the general concept of mapping.
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 MAP-FN returns M series T1, ..., TM
where TI has the type (SERIES ti).  The argument FUNCTION is a function.
The remaining arguments (if any) are all series.  Let these series be S1,
..., SN and suppose that SI has the type (SERIES si).

The FUNCTION must be of type (FUNCTION (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 the results of applying FUNCTION to the
corresponding elements of the series inputs.

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

If FUNCTION has side effects, it can count on being called first on the
SI[0], then on the SI[1], and so on.  However, due to the lazy evaluation
nature of series, FUNCTION will not be called on any group of input
elements until the result is actually used (if ever).  In addition, no
assumptions can be made about the relative order of evaluation of the calls
on FUNCTION with regard to execution in other parts of a given series
expression.

(MAP-FN 'INTEGER #'+ #Z(1 2 3) #Z(4 5)) => #Z(5 7) 
(MAP-FN T #'GENSYM) => #Z(#:G3 #:G4 #:G5 ...) 
(MAP-FN '(VALUES INTEGER RATIONAL) #'FLOOR #Z(1/4 9/5 12/3)) 
 => #Z(0 1 4) AND #Z(1/4 4/5 0)


The # macro character syntax #M makes it easy to specify uses of MAP-FN
where TYPE is T and the FUNCTION is a named function.  The notation
(#MFUNCTION ...) is an abbreviation for (MAP-FN T #'FUNCTION ...).  The
form FUNCTION can be the printed representation of any Lisp object.  The
notation #MFUNCTION can only appear in the function position of a list.

(COLLECT (#M1+ (SCAN '(1 2 3)))) => (2 3 4)



     SEE ALSO
     about-series
     about-generators
     mapping iterate

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



