[cl-utilities-cvs] CVS update: cl-utilities/doc/compose.html cl-utilities/doc/copy-array.html cl-utilities/doc/expt-mod.html cl-utilities/doc/index.html cl-utilities/doc/once-only.html cl-utilities/doc/rotate-byte.html cl-utilities/doc/style.css cl-utilities/doc/with-unique-names.html cl-utilities/doc/collecting.html cl-utilities/doc/extremum.html cl-utilities/doc/read-delimited.html cl-utilities/doc/split-sequence.html - cl-utilities-cvs@common-lisp.net - mailman3.common-lisp.net

14 Dec 2005

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>

    