

                                                                    collect

    FUNCTION
COLLECT ITEMS                                                    [Function]
COLLECT TYPE ITEMS                                               [Function]

    Package
    series

    DESCRIPTION

COLLECT returns a sequence containing the elements of the series ITEMS.
The TYPE is a type specifier indicating the type of sequence to be created.
It must be either a proper subtype of SEQUENCE or the symbol BAG.  If TYPE
is omitted, it defaults to LIST.  (This function exhibits an argument
pattern that is unusual for Common Lisp:  an ``optional'' argument
preceding a required argument.  This pattern cannot be expressed in the
usual manner with &OPTIONAL.  It is indicated above by two definition
lines, showing the two possible argument patterns.)

If the TYPE is BAG, a list is created with the elements in whatever order
can be most efficiently obtained.  Otherwise, the order of the elements in
the sequence is the same as the order in ITEMS.  If TYPE specifies a length
(that is, of a vector) this length must be greater than or equal to the
length of ITEMS.

The nth element of ITEMS is placed in the nth slot of the sequence
produced.  Any unneeded slots are left in their initial state.  Collecting
is significantly more efficient if it can be determined at compile time
whether TYPE is a subtype of LIST or VECTOR and for vectors what the length
of the vector is.

(COLLECT #Z(A B C)) => (A B C) 
(COLLECT 'BAG #Z(A B C)) => (C A B) or (B A C) or ... 
(COLLECT '(VECTOR INTEGER 3) #Z(1 2 3)) => #(1 2 3)


     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.



