Update of /project/cl-utilities/cvsroot/cl-utilities/doc In directory common-lisp.net:/tmp/cvs-serv23548/doc
Modified Files: collecting.html extremum.html read-delimited.html split-sequence.html Added Files: compose.html copy-array.html expt-mod.html index.html once-only.html rotate-byte.html style.css with-unique-names.html Log Message: Big improvement to the documentation. I actually added a manual instead of simply telling people to look at the Cliki pages.
Also added a little more argument checking to N-MOST-EXTREME function.
Date: Wed Dec 14 22:15:19 2005 Author: pscott
Index: cl-utilities/doc/collecting.html diff -u cl-utilities/doc/collecting.html:1.1 cl-utilities/doc/collecting.html:1.2 --- cl-utilities/doc/collecting.html:1.1 Mon Aug 29 22:18:18 2005 +++ cl-utilities/doc/collecting.html Wed Dec 14 22:15:16 2005 @@ -43,6 +43,19 @@ <p>If the <i>collector</i> names are not all symbols, a <b>type-error</b> will be signalled.
+<p><b>Examples:</b> + +<pre> +(collecting (dotimes (x 10) (collect x))) => (0 1 2 3 4 5 6 7 8 9) + +(multiple-value-bind (a b) + (with-collectors (x y) + (x 1) + (y 2) + (x 3)) + (append a b)) => (1 2 3) +</pre> + <p><p><b>Implementation notes:</b></p>
<p>Opinions differ on how a collection macro should work. There are @@ -59,5 +72,7 @@ and you can't nest them to get the same effect as multiple collection since it always uses the <b>collect</b> function. If you want to collect into multiple lists, use the <b>with-collect</b> macro.</p> + +<p class="footer"><hr><a href="index.html">Manual Index</a></p>
</body></html>
Index: cl-utilities/doc/extremum.html diff -u cl-utilities/doc/extremum.html:1.1 cl-utilities/doc/extremum.html:1.2 --- cl-utilities/doc/extremum.html:1.1 Mon Aug 29 22:18:18 2005 +++ cl-utilities/doc/extremum.html Wed Dec 14 22:15:18 2005 @@ -1,17 +1,19 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <HTML> <HEAD> - <TITLE>Function EXTREMUM</TITLE> + <TITLE>Function EXTREMUM, EXTREMA, N-MOST-EXTREME</TITLE> <LINK REL="stylesheet" HREF="style.css" type="text/css"> </HEAD> <BODY>
-<p><p><i>Function</i> <b>EXTREMUM</b></a></a> <p> +<p><p><i>Function</i> <b>EXTREMUM, EXTREMA, N-MOST-EXTREME</b></a></a> <p> <p><b>Syntax:</b><p>
<p>
<p><b>extremum</b> <i>sequence predicate <tt>&key</tt> key (start 0) end</i> => <i>morally-smallest-element</i><p> +<p><b>extrema</b> <i>sequence predicate <tt>&key</tt> key (start 0) end</i> => <i>morally-smallest-elements</i><p> +<p><b>n-most-extreme</b> <i>n sequence predicate <tt>&key</tt> key (start 0) end</i> => <i>n-smallest-elements</i><p> <p> <p><b>Arguments and Values:</b><p> <p> @@ -32,6 +34,22 @@ http://www.lisp.org/HyperSpec/Body/fun_sortcm_stable-sort.html%22%3E<b>sort</b></a> using <i>predicate</i> and <i>key</i>
+<p><i>morally-smallest-elements</i>---the identical elements of +<i>sequence</i> that would appear first if the sequence were ordered +according to <a class="hyperspec" href =" +http://www.lisp.org/HyperSpec/Body/fun_sortcm_stable-sort.html"><b>sort</b></a> +using <i>predicate</i> and <i>key</i>. If <i>predicate</i> states that +neither of two objects is before the other, they are considered +identical. + +<i>n</i>---a positive integer<p> + +<i>n-smallest-elements</i>---the <i>n</i> elements of <i>sequence</i> that +would appear first if the sequence were ordered according to <a +class="hyperspec" href =" +http://www.lisp.org/HyperSpec/Body/fun_sortcm_stable-sort.html%22%3E<b>sort</b></a> +using <i>predicate</i> and <i>key</i> + <p> <p><b>Description:</b><p> <p> @@ -82,6 +100,18 @@ predicate (subseq sequence start end) :key key) 0)</tt> except when <i>sequence</i> is empty (see Exceptional Situations), but may use faster (less asymptotically complex) algorithms to find this answer. + +<p><b>extrema</b> is similar to <b>extremum</b>, but it returns a list +of values. There can be more than one extremum, as determined by +<i>predicate</i>, and with <b>extremum</b> the choice of which +extremum to return is arbitrary. <b>extrema</b> returns all the +possible values which <i>predicate</i> determines to be equal. + +<p><b>n-most-extreme</b> returns a list of <i>n</i> values without +testing for equality. It orders <i>sequence</i> in the same way as +<b>extremum</b> and <b>extrema</b>, then returns the first <i>n</i> +elements of the sorted sequence. + <p> <p><b>Exceptional situations:</b><p> <p> @@ -94,6 +124,14 @@ <p>Should be prepared to signal an error of type <b>type-error</b> if <i>sequence</i> is not a proper sequence.
+<p>If there are fewer than <i>n</i> values in the part of +<i>sequence</i> that <b>n-most-extreme</b> may operate on, it returns +all the values it can in sorted order and signals the warning +<b>n-most-extreme-not-enough-elements</b>. This warning stores the +given values for <i>n</i> and the relevant subsequence, and they may +be accessed with <b>n-most-extreme-not-enough-elements-n</b> and +<b>n-most-extreme-not-enough-elements-subsequence</b>, respectively. + <p><p><b>Implementation notes:</b></p>
<p>There are two implementations of this function included in @@ -111,5 +149,7 @@
<p>Don't worry about the performance of passing <tt>#'identity</tt> as <i>key</i>. This is optimized by a compiler macro.</p> + +<p class="footer"><hr><a href="index.html">Manual Index</a></p>
</body></html>
Index: cl-utilities/doc/read-delimited.html diff -u cl-utilities/doc/read-delimited.html:1.1 cl-utilities/doc/read-delimited.html:1.2 --- cl-utilities/doc/read-delimited.html:1.1 Mon Aug 29 22:18:18 2005 +++ cl-utilities/doc/read-delimited.html Wed Dec 14 22:15:18 2005 @@ -83,4 +83,6 @@ it is more efficient. If you need something more high-level, this could be built on top of <b>read-delimited</b> fairly easily.</p>
+<p class="footer"><hr><a href="index.html">Manual Index</a></p> + </body></html>
Index: cl-utilities/doc/split-sequence.html diff -u cl-utilities/doc/split-sequence.html:1.1 cl-utilities/doc/split-sequence.html:1.2 --- cl-utilities/doc/split-sequence.html:1.1 Mon Aug 29 22:18:18 2005 +++ cl-utilities/doc/split-sequence.html Wed Dec 14 22:15:18 2005 @@ -84,4 +84,6 @@ it, or even just complain about it on the mailing list---something might get done.</p>
+<p class="footer"><hr><a href="index.html">Manual Index</a></p> + </body></html>