181 lines
11 KiB
HTML
181 lines
11 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3O//DTD W3 HTML 2.0//EN">
|
|
<!Converted with LaTeX2HTML 0.6.5 (Tue Nov 15 1994) by Nikos Drakos (nikos@cbl.leeds.ac.uk), CBLU, University of Leeds >
|
|
<HEAD>
|
|
<TITLE>A.2.5. Collectors</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<meta name="description" value=" Collectors">
|
|
<meta name="keywords" value="clm">
|
|
<meta name="resource-type" value="document">
|
|
<meta name="distribution" value="global">
|
|
<P>
|
|
<b>Common Lisp the Language, 2nd Edition</b>
|
|
<BR> <HR><A NAME=tex2html6128 HREF="node355.html"><IMG ALIGN=BOTTOM ALT="next" SRC="icons/next_motif.gif"></A> <A NAME=tex2html6126 HREF="node349.html"><IMG ALIGN=BOTTOM ALT="up" SRC="icons/up_motif.gif"></A> <A NAME=tex2html6120 HREF="node353.html"><IMG ALIGN=BOTTOM ALT="previous" SRC="icons/previous_motif.gif"></A> <A NAME=tex2html6130 HREF="node1.html"><IMG ALIGN=BOTTOM ALT="contents" SRC="icons/contents_motif.gif"></A> <A NAME=tex2html6131 HREF="index.html"><IMG ALIGN=BOTTOM ALT="index" SRC="icons/index_motif.gif"></A> <BR>
|
|
<B> Next:</B> <A NAME=tex2html6129 HREF="node355.html"> Alteration of Series</A>
|
|
<B>Up:</B> <A NAME=tex2html6127 HREF="node349.html"> Series Functions</A>
|
|
<B> Previous:</B> <A NAME=tex2html6121 HREF="node353.html"> Conditional and Other </A>
|
|
<HR> <P>
|
|
<H2><A NAME=SECTION003425000000000000000>A.2.5. Collectors</A></H2>
|
|
<P>
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
|
Collectors produce non-series outputs based on series inputs. They either
|
|
create a summary value based on some formula (the sum, for example) or collect the
|
|
elements of a series in an aggregate data structure (such as a list).
|
|
<P>
|
|
<BR><b>[Function]</b><BR>
|
|
<tt>collect-first <i>items</i> &optional (<i>default</i> nil) <BR></tt><tt>collect-last <i>items</i> &optional (<i>default</i> nil) <BR></tt><tt>collect-nth <i>n</i> <i>items</i> &optional (<i>default</i> nil)</tt><P>Given a series <i>items</i>, these functions return the first element, the
|
|
last element, and the <i>n</i>th element, respectively. If <i>items</i> has
|
|
no elements (or no <i>n</i>th element), <i>default</i> is returned.
|
|
If <i>default</i> is not specified, then <tt>nil</tt> is used for <i>default</i>.
|
|
<P><pre>
|
|
(collect-first #Z() 'z) => z
|
|
(collect-last #Z(a b c)) => c
|
|
(collect-nth 1 #Z(a b c)) => b
|
|
</pre><P>
|
|
<P>
|
|
<BR><b>[Function]</b><BR>
|
|
<tt>collect-length <i>items</i></tt><P><tt>collect-length</tt> returns the number of elements in a series.
|
|
<P><pre>
|
|
(collect-length #Z(a b c)) => 3
|
|
</pre><P>
|
|
<P>
|
|
<BR><b>[Function]</b><BR>
|
|
<tt>collect-sum <i>numbers</i> &optional (<i>type</i> 'number)</tt><P><tt>collect-sum</tt> returns the sum of the elements in a series of numbers.
|
|
The <i>type</i> is a type specifier that indicates the type of sum
|
|
to be created. If <i>type</i> is not specified, then <tt>number</tt> is used for
|
|
the <i>type</i>.
|
|
If there are no elements in the input, a zero (of the
|
|
appropriate type) is returned.
|
|
<P><pre>
|
|
(collect-sum #Z(1.1 1.2 1.3)) => 3.6
|
|
(collect-sum #Z() 'complex) => #C(0 0)
|
|
</pre><P>
|
|
<P>
|
|
<BR><b>[Function]</b><BR>
|
|
<tt>collect-max <i>numbers</i> <BR></tt><tt>collect-min <i>numbers</i> </tt><P>Given a series of non-complex numbers, these functions compute the maximum
|
|
element and the minimum element, respectively. If there are no elements in
|
|
the input, <tt>nil</tt> is returned.
|
|
<P><pre>
|
|
(collect-max #Z(2 1 4 3)) => 4
|
|
(collect-min #Z(1.2 1.1 1.4 1.3)) => 1.1
|
|
(collect-min #Z()) => nil
|
|
</pre><P>
|
|
<P>
|
|
<BR><b>[Function]</b><BR>
|
|
<tt>collect-and <i>bools</i></tt><P><tt>collect-and</tt> returns the <tt>and</tt> of the elements in a series. As
|
|
with the macro <tt>and</tt>, <tt>nil</tt> is returned if any element of <i>bools</i> is <tt>nil</tt>. Otherwise, the last element of <i>bools</i> is
|
|
returned. The value <tt>t</tt> is returned if there are no elements in <i>bools</i>.
|
|
<P><pre>
|
|
(collect-and #Z(a b c)) => c
|
|
(collect-and #Z(a nil c)) => nil
|
|
</pre><P>
|
|
<P>
|
|
<BR><b>[Function]</b><BR>
|
|
<tt>collect-or <i>bools</i></tt><P><tt>collect-or</tt> returns the <tt>or</tt> of the elements in a series. As with
|
|
the macro <tt>or</tt>, <tt>nil</tt> is returned if every element of <i>bools</i> is <tt>nil</tt>. Otherwise, the first non-null element of <i>bools</i>
|
|
is returned. The value <tt>nil</tt> is returned if there are no elements in
|
|
<i>bools</i>.
|
|
<P><pre>
|
|
(collect-or #Z(nil b c)) => b
|
|
(collect-or #Z()) => nil
|
|
</pre><P>
|
|
<P>
|
|
<BR><b>[Function]</b><BR>
|
|
<tt>collect <i>items</i> <BR></tt><tt>collect <i>type</i> <i>items</i></tt><P><tt>collect</tt> returns a sequence containing the elements of the series <i>items</i>. The <i>type</i> is a type specifier indicating the type of sequence
|
|
to be created. It must be either a proper subtype of <tt>sequence</tt> or the
|
|
symbol <tt>bag</tt>. If <i>type</i> is omitted, it defaults to <tt>list</tt>.
|
|
(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 <tt>&optional</tt>. It
|
|
is indicated above by two definition lines, showing the two possible
|
|
argument patterns.)
|
|
<P>
|
|
If the <i>type</i> is <tt>bag</tt>, 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 <i>items</i>. If
|
|
<i>type</i> specifies a length (that is, of a vector) this length must be
|
|
greater than or equal to the length of <i>items</i>.
|
|
<P>
|
|
The <i>n</i>th element of <i>items</i> is
|
|
placed in the <i>n</i>th 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 <i>type</i> is a subtype of
|
|
<tt>list</tt> or <tt>vector</tt> and for vectors what the length of the vector is.
|
|
<P><pre>
|
|
(collect #Z(a b c)) => (a b c)
|
|
(collect 'bag #Z(a b c)) => (c a b) or (b a c) or <b>...</b>
|
|
(collect '(vector integer 3) #Z(1 2 3)) => #(1 2 3)
|
|
</pre><P>
|
|
<P>
|
|
<BR><b>[Function]</b><BR>
|
|
<tt>collect-append <i>sequences</i> <BR></tt><tt>collect-append <i>type</i> <i>sequences</i></tt><P>Given a series of sequences, <tt>collect-append</tt> returns a new sequence by
|
|
concatenating these sequences together in order. The <i>type</i> is a type
|
|
specifier indicating the type of sequence created and must be a proper
|
|
subtype of <tt>sequence</tt>. If <i>type</i> is omitted, it defaults to
|
|
<tt>list</tt>. (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 <tt>&optional</tt>. It
|
|
is indicated above by two definition lines, showing the two possible
|
|
argument patterns.)
|
|
<P>
|
|
It must be possible for every element of every sequence in the input series
|
|
to be an element of a sequence of type <i>type</i>. The result does not
|
|
share any structure with the sequences in the input.
|
|
<P><pre>
|
|
(collect-append #Z((a b) nil (c d))) => (a b c d)
|
|
(collect-append 'string #Z("a " "big " "cat")) => "a big cat"
|
|
</pre><P>
|
|
<P>
|
|
<BR><b>[Function]</b><BR>
|
|
<tt>collect-nconc <i>lists</i></tt><P><tt>collect-nconc nconc</tt>s the elements of the series <i>lists</i> together in order and returns the result. This is the same as
|
|
<tt>collect-append</tt> except that the input must be a series of lists,
|
|
the output is always a list, the concatenation is done rapidly by
|
|
destructively modifying the input elements, and therefore the output
|
|
shares all of its structure with the input elements.
|
|
<P>
|
|
<BR><b>[Function]</b><BR>
|
|
<tt>collect-alist <i>keys</i> <i>values</i> <BR></tt><tt>collect-plist <i>keys</i> <i>values</i> <BR></tt><tt>collect-hash <i>keys</i> <i>values</i> &key :test :size :rehash-size :rehash-threshold</tt><P>Given a series of keys and a series of corresponding values, these
|
|
functions return an association list, a property list, and a hash table,
|
|
respectively. Following the order of the input, each <i>keys</i><IMG ALIGN=BOTTOM ALT="" SRC="_24769_tex2html_wrap44030.gif">-<i>values</i><IMG ALIGN=BOTTOM ALT="" SRC="_24769_tex2html_wrap44030.gif"> pair is entered into the output so that it overrides all
|
|
earlier associations. If one of the input series is longer than the other,
|
|
the extra elements are ignored. The keyword arguments of
|
|
<tt>collect-hash</tt> specify attributes of the hash table produced and have the
|
|
same meanings as the arguments to <tt>make-hash-table</tt>.
|
|
<P><pre>
|
|
(collect-alist #Z(a b c) #Z(1 2)) => ((b . 2) (a . 1))
|
|
(collect-plist #Z(a b c) #Z(1 2)) => (b 2 a 1)
|
|
(collect-hash #Z() #Z(1 2) :test #'eq) => <b></b>an empty hash table<b></b>
|
|
</pre><P>
|
|
<P>
|
|
<BR><b>[Function]</b><BR>
|
|
<tt>collect-file <i>file-name</i> <i>items</i> &optional (<i>printer</i> #'print)</tt><P>This creates a file named <i>file-name</i> and writes the
|
|
elements of the series <i>items</i> into it using the function <i>printer</i>. <i>Printer</i> must accept two inputs: an object
|
|
and an output stream. (For instance, <i>printer</i> can be <tt>print</tt>,
|
|
<tt>prin1</tt>, <tt>princ</tt>, <tt>pprint</tt>, <tt>write-char</tt>,
|
|
<tt>write-string</tt>, or <tt>write-line</tt>.)
|
|
If omitted, <i>printer</i> defaults to <tt>print</tt>. The value <tt>t</tt> is
|
|
returned. The file is correctly closed, even if an abort occurs.
|
|
<P>
|
|
<BR><b>[Function]</b><BR>
|
|
<tt>collect-fn <i>type</i> <i>init</i> <i>function</i> &rest <i>series-inputs</i></tt><P>The higher-order function <tt>collect-fn</tt> supports the general concept of
|
|
collecting. It is identical to <tt>collecting-fn</tt> except that it
|
|
returns only the last element of each series computed. If there are no elements
|
|
in these series, the values returned by <i>init</i> are passed on directly
|
|
as the output of <tt>collect-fn</tt>.
|
|
<P><pre>
|
|
(collect-fn 'integer #'(lambda () 0) #'+ #Z(1 2 3)) => 6
|
|
(collect-fn 'integer #'(lambda () 0) #'+ #Z()) => 0
|
|
(collect-fn 'integer #'(lambda () 1) #'* #Z(1 2 3 4 5)) => 120
|
|
</pre><P>
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
|
<P>
|
|
<BR> <HR><A NAME=tex2html6128 HREF="node355.html"><IMG ALIGN=BOTTOM ALT="next" SRC="icons/next_motif.gif"></A> <A NAME=tex2html6126 HREF="node349.html"><IMG ALIGN=BOTTOM ALT="up" SRC="icons/up_motif.gif"></A> <A NAME=tex2html6120 HREF="node353.html"><IMG ALIGN=BOTTOM ALT="previous" SRC="icons/previous_motif.gif"></A> <A NAME=tex2html6130 HREF="node1.html"><IMG ALIGN=BOTTOM ALT="contents" SRC="icons/contents_motif.gif"></A> <A NAME=tex2html6131 HREF="index.html"><IMG ALIGN=BOTTOM ALT="index" SRC="icons/index_motif.gif"></A> <BR>
|
|
<B> Next:</B> <A NAME=tex2html6129 HREF="node355.html"> Alteration of Series</A>
|
|
<B>Up:</B> <A NAME=tex2html6127 HREF="node349.html"> Series Functions</A>
|
|
<B> Previous:</B> <A NAME=tex2html6121 HREF="node353.html"> Conditional and Other </A>
|
|
<HR> <P>
|
|
<HR>
|
|
<P><ADDRESS>
|
|
AI.Repository@cs.cmu.edu
|
|
</ADDRESS>
|
|
</BODY>
|