69 lines
12 KiB
HTML
69 lines
12 KiB
HTML
<!-- Common Lisp HyperSpec (TM), version 7.0 generated by Kent M. Pitman on Mon, 11-Apr-2005 2:31am EDT -->
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>CLHS: Section 6.1.3</TITLE>
|
|
<LINK HREF="../Data/clhs.css" REL="stylesheet" TYPE="text/css" />
|
|
<META HTTP-EQUIV="Author" CONTENT="Kent M. Pitman">
|
|
<META HTTP-EQUIV="Organization" CONTENT="LispWorks Ltd.">
|
|
<LINK REL=TOP HREF="../Front/index.htm">
|
|
<LINK REL=COPYRIGHT HREF="../Front/Help.htm#Legal">
|
|
<LINK REL=DISCLAIMER HREF="../Front/Help.htm#Disclaimer">
|
|
<LINK REL=PREV HREF="06_abba.htm">
|
|
<LINK REL=UP HREF="06_a.htm">
|
|
<LINK REL=NEXT HREF="06_aca.htm">
|
|
</HEAD>
|
|
<BODY>
|
|
<H1><A REV=MADE HREF="http://www.lispworks.com/"><IMG WIDTH=80 HEIGHT=65 ALT="[LISPWORKS]" SRC="../Graphics/LWSmall.gif" ALIGN=Bottom></A><A REL=TOP HREF="../Front/index.htm"><IMG WIDTH=237 HEIGHT=65 ALT="[Common Lisp HyperSpec (TM)]" SRC="../Graphics/CLHS_Sm.gif" ALIGN=Bottom></A> <A REL=PREV HREF="06_abba.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Previous]" SRC="../Graphics/Prev.gif" ALIGN=Bottom></A><A REL=UP HREF="06_a.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Up]" SRC="../Graphics/Up.gif" ALIGN=Bottom></A><A REL=NEXT HREF="06_aca.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Next]" SRC="../Graphics/Next.gif" ALIGN=Bottom></A></H1>
|
|
|
|
<HR>
|
|
|
|
<H2>
|
|
6.1.3 Value Accumulation Clauses</H2> <P>
|
|
The constructs <TT>collect</TT>, <TT>collecting</TT>, <TT>append</TT>, <TT>appending</TT>, <TT>nconc</TT>, <TT>nconcing</TT>, <TT>count</TT>, <TT>counting</TT>, <TT>maximize</TT>, <TT>maximizing</TT>, <TT>minimize</TT>, <TT>minimizing</TT>, <TT>sum</TT>, and <TT>summing</TT>, allow values to be accumulated in a <A REL=DEFINITION HREF="m_loop.htm#loop"><B>loop</B></A>. <P>
|
|
The constructs <TT>collect</TT>, <TT>collecting</TT>, <TT>append</TT>, <TT>appending</TT>, <TT>nconc</TT>, and <TT>nconcing</TT>, designate clauses that accumulate values in <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>lists</I></A> and return them. The constructs <TT>count</TT>, <TT>counting</TT>, <TT>maximize</TT>, <TT>maximizing</TT>, <TT>minimize</TT>, <TT>minimizing</TT>, <TT>sum</TT>, and <TT>summing</TT> designate clauses that accumulate and return numerical values. <P>
|
|
During each iteration, the constructs <TT>collect</TT> and <TT>collecting</TT> collect the value of the supplied <I>form</I> into a <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A>. When iteration terminates, the <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A> is returned. The argument <I>var</I> is set to the <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A> of collected values; if <I>var</I> is supplied, the <A REL=DEFINITION HREF="m_loop.htm#loop"><B>loop</B></A> does not return the final <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A> automatically. If <I>var</I> is not supplied, it is equivalent to supplying an internal name for <I>var</I> and returning its value in a <TT>finally</TT> clause. The <I>var</I> argument is bound as if by the construct <TT>with</TT>. No mechanism is provided for declaring the <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> of <I>var</I>; it must be of <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> <A REL=DEFINITION HREF="t_list.htm#list"><B>list</B></A>. <P>
|
|
The constructs <TT>append</TT>, <TT>appending</TT>, <TT>nconc</TT>, and <TT>nconcing</TT> are similar to <TT>collect</TT> except that the values of the supplied <I>form</I> must be <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>lists</I></A>. <P>
|
|
<P><DL><DT>* The <TT>append</TT> keyword causes its <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A> values to be concatenated into a single <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A>, as if they were arguments to the <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> <A REL=DEFINITION HREF="f_append.htm#append"><B>append</B></A>. <P><DD>
|
|
<DT>* The <TT>nconc</TT> keyword causes its <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A> values to be concatenated into a single <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A>, as if they were arguments to the <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> <A REL=DEFINITION HREF="f_nconc.htm#nconc"><B>nconc</B></A>. <P><DD></DL><P>
|
|
The argument <I>var</I> is set to the <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A> of concatenated values; if <I>var</I> is supplied, <A REL=DEFINITION HREF="m_loop.htm#loop"><B>loop</B></A> does not return the final <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A> automatically. The <I>var</I> argument is bound as if by the construct <TT>with</TT>. A <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> cannot be supplied for <I>var</I>; it must be of <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> <A REL=DEFINITION HREF="t_list.htm#list"><B>list</B></A>. The construct <TT>nconc</TT> destructively modifies its argument <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>lists</I></A>. <P>
|
|
The <TT>count</TT> construct counts the number of times that the supplied <I>form</I> returns <A REL=DEFINITION HREF="26_glo_t.htm#true"><I>true</I></A>. The argument <I>var</I> accumulates the number of occurrences; if <I>var</I> is supplied, <A REL=DEFINITION HREF="m_loop.htm#loop"><B>loop</B></A> does not return the final count automatically. The <I>var</I> argument is bound as if by the construct <TT>with</TT> to a zero of the appropriate type. Subsequent values (including any necessary coercions) are computed as if by the function <A REL=DEFINITION HREF="f_1pl_1_.htm#1PL"><B>1+</B></A>. If <TT>into</TT> <I>var</I> is used, a <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> can be supplied for <I>var</I> with the <I>type-spec</I> argument; the consequences are unspecified if a nonnumeric <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> is supplied. If there is no <TT>into</TT> variable, the optional <I>type-spec</I> argument applies to the internal variable that is keeping the count. The default <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> is <A REL=DEFINITION HREF="26_glo_i.htm#implementation-dependent"><I>implementation-dependent</I></A>; but it must be a <A REL=DEFINITION HREF="26_glo_s.htm#supertype"><I>supertype</I></A> of <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> <A REL=DEFINITION HREF="t_fixnum.htm#fixnum"><B>fixnum</B></A>. <P>
|
|
The <TT>maximize</TT> and <TT>minimize</TT> constructs compare the value of the supplied <I>form</I> obtained during the first iteration with values obtained in successive iterations. The maximum (for <TT>maximize</TT>) or minimum (for <TT>minimize</TT>) value encountered is determined (as if by the <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> <A REL=DEFINITION HREF="f_max_m.htm#max"><B>max</B></A> for <TT>maximize</TT> and as if by the <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> <A REL=DEFINITION HREF="f_max_m.htm#min"><B>min</B></A> for <TT>minimize</TT>) and returned. If the <TT>maximize</TT> or <TT>minimize</TT> clause is never executed, the accumulated value is unspecified. The argument <I>var</I> accumulates the maximum or minimum value; if <I>var</I> is supplied, <A REL=DEFINITION HREF="m_loop.htm#loop"><B>loop</B></A> does not return the maximum or minimum automatically. The <I>var</I> argument is bound as if by the construct <TT>with</TT>. If <TT>into</TT> <I>var</I> is used, a <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> can be supplied for <I>var</I> with the <I>type-spec</I> argument; the consequences are unspecified if a nonnumeric <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> is supplied. If there is no <TT>into</TT> variable, the optional <I>type-spec</I> argument applies to the internal variable that is keeping the maximum or minimum value. The default <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> is <A REL=DEFINITION HREF="26_glo_i.htm#implementation-dependent"><I>implementation-dependent</I></A>; but it must be a <A REL=DEFINITION HREF="26_glo_s.htm#supertype"><I>supertype</I></A> of <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> <A REL=DEFINITION HREF="t_real.htm#real"><B>real</B></A>. <P>
|
|
The <TT>sum</TT> construct forms a cumulative sum of the successive <A REL=DEFINITION HREF="26_glo_p.htm#primary_value"><I>primary values</I></A> of the supplied <I>form</I> at each iteration. The argument <I>var</I> is used to accumulate the sum; if <I>var</I> is supplied, <A REL=DEFINITION HREF="m_loop.htm#loop"><B>loop</B></A> does not return the final sum automatically. The <I>var</I> argument is bound as if by the construct <TT>with</TT> to a zero of the appropriate type. Subsequent values (including any necessary coercions) are computed as if by the <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> <A REL=DEFINITION HREF="f_pl.htm#PL"><B>+</B></A>. If <TT>into</TT> <I>var</I> is used, a <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> can be supplied for <I>var</I> with the <I>type-spec</I> argument; the consequences are unspecified if a nonnumeric <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> is supplied. If there is no <TT>into</TT> variable, the optional <I>type-spec</I> argument applies to the internal variable that is keeping the sum. The default <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> is <A REL=DEFINITION HREF="26_glo_i.htm#implementation-dependent"><I>implementation-dependent</I></A>; but it must be a <A REL=DEFINITION HREF="26_glo_s.htm#supertype"><I>supertype</I></A> of <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> <A REL=DEFINITION HREF="t_number.htm#number"><B>number</B></A>. <P>
|
|
If <TT>into</TT> is used, the construct does not provide a default return value; however, the variable is available for use in any <TT>finally</TT> clause. <P>
|
|
Certain kinds of accumulation clauses can be combined in a <A REL=DEFINITION HREF="m_loop.htm#loop"><B>loop</B></A> if their destination is the same (the result of <A REL=DEFINITION HREF="m_loop.htm#loop"><B>loop</B></A> or an <TT>into</TT> <I>var</I>) because they are considered to accumulate conceptually compatible quantities. In particular, any elements of following sets of accumulation clauses can be mixed with other elements of the same set for the same destination in a <A REL=DEFINITION HREF="m_loop.htm#loop"><B>loop</B></A> <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>form</I></A>: <P>
|
|
<P><DL><DT>* <TT>collect</TT>, <TT>append</TT>, <TT>nconc</TT> <P><DD>
|
|
<DT>* <TT>sum</TT>, <TT>count</TT> <P><DD>
|
|
<DT>* <TT>maximize</TT>, <TT>minimize</TT> <P><DD></DL><P>
|
|
<PRE>
|
|
;; Collect every name and the kids in one list by using
|
|
;; COLLECT and APPEND.
|
|
(loop for name in '(fred sue alice joe june)
|
|
for kids in '((bob ken) () () (kris sunshine) ())
|
|
collect name
|
|
append kids)
|
|
=> (FRED BOB KEN SUE ALICE JOE KRIS SUNSHINE JUNE)
|
|
</PRE>
|
|
</TT> <P>
|
|
Any two clauses that do not accumulate the same <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> of <A REL=DEFINITION HREF="26_glo_o.htm#object"><I>object</I></A> can coexist in a <A REL=DEFINITION HREF="m_loop.htm#loop"><B>loop</B></A> only if each clause accumulates its values into a different <A REL=DEFINITION HREF="26_glo_v.htm#variable"><I>variable</I></A>. <P>
|
|
|
|
|
|
<A REL=CHILD HREF="06_aca.htm"><H2>
|
|
6.1.3.1 Examples of COLLECT clause</H2></A><P>
|
|
|
|
<A REL=CHILD HREF="06_acb.htm"><H2>
|
|
6.1.3.2 Examples of APPEND and NCONC clauses</H2></A><P>
|
|
|
|
<A REL=CHILD HREF="06_acc.htm"><H2>
|
|
6.1.3.3 Examples of COUNT clause</H2></A><P>
|
|
|
|
<A REL=CHILD HREF="06_acd.htm"><H2>
|
|
6.1.3.4 Examples of MAXIMIZE and MINIMIZE clauses</H2></A><P>
|
|
|
|
<A REL=CHILD HREF="06_ace.htm"><H2>
|
|
6.1.3.5 Examples of SUM clause</H2></A><P><HR>
|
|
|
|
<A REL=NAVIGATOR HREF="../Front/StartPts.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Starting Points]" SRC="../Graphics/StartPts.gif" ALIGN=Bottom></A><A REL=TOC HREF="../Front/Contents.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Contents]" SRC="../Graphics/Contents.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Master.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Index]" SRC="../Graphics/Index.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Symbol.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Symbols]" SRC="../Graphics/Symbols.gif" ALIGN=Bottom></A><A REL=GLOSSARY HREF="../Body/26_a.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Glossary]" SRC="../Graphics/Glossary.gif" ALIGN=Bottom></A><A HREF="../Front/X3J13Iss.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Issues]" SRC="../Graphics/Issues.gif" ALIGN=Bottom></A><BR>
|
|
|
|
<A REL=COPYRIGHT HREF="../Front/Help.htm#Legal"><I>Copyright 1996-2005, LispWorks Ltd. All rights reserved.</I></A><P>
|
|
</BODY>
|
|
</HTML>
|