X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=src%2Fcode%2Fseq.lisp;h=472b41b989214944be04f71b32ec434f0d502b16;hb=b6aa15328871678a3475e82c150b251dffb49ba1;hp=0b0e4bcfbc782cf9a5244bbae0b19061411aa435;hpb=d3862cc781cabf52f15c2d3a164f992dbbba84f4;p=sbcl.git diff --git a/src/code/seq.lisp b/src/code/seq.lisp index 0b0e4bc..472b41b 100644 --- a/src/code/seq.lisp +++ b/src/code/seq.lisp @@ -35,11 +35,11 @@ (sb!xc:defmacro make-sequence-like (sequence length) #!+sb-doc - "Returns a sequence of the same type as SEQUENCE and the given LENGTH." + "Return a sequence of the same type as SEQUENCE and the given LENGTH." `(make-sequence-of-type (type-of ,sequence) ,length)) (sb!xc:defmacro type-specifier-atom (type) - #!+sb-doc "Returns the broad class of which TYPE is a specific subclass." + #!+sb-doc "Return the broad class of which TYPE is a specific subclass." `(if (atom ,type) ,type (car ,type))) ) ; EVAL-WHEN @@ -107,7 +107,7 @@ '(integer (0) (0)))))) (defun make-sequence-of-type (type length) - #!+sb-doc "Returns a sequence of the given TYPE and LENGTH." + #!+sb-doc "Return a sequence of the given TYPE and LENGTH." (declare (fixnum length)) (case (type-specifier-atom type) (list (make-list length)) @@ -123,7 +123,7 @@ (make-sequence-of-type (result-type-or-lose type) length)))) (defun elt (sequence index) - #!+sb-doc "Returns the element of SEQUENCE specified by INDEX." + #!+sb-doc "Return the element of SEQUENCE specified by INDEX." (etypecase sequence (list (do ((count index (1- count)) @@ -246,7 +246,7 @@ ;;; routines for other reasons (see above). (defun subseq (sequence start &optional end) #!+sb-doc - "Returns a copy of a subsequence of SEQUENCE starting with element number + "Return a copy of a subsequence of SEQUENCE starting with element number START and continuing to the end of SEQUENCE or the optional END." (seq-dispatch sequence (list-subseq* sequence start end) @@ -278,7 +278,7 @@ ) ; EVAL-WHEN (defun copy-seq (sequence) - #!+sb-doc "Returns a copy of SEQUENCE which is EQUAL to SEQUENCE but not EQ." + #!+sb-doc "Return a copy of SEQUENCE which is EQUAL to SEQUENCE but not EQ." (seq-dispatch sequence (list-copy-seq* sequence) (vector-copy-seq* sequence))) @@ -487,7 +487,7 @@ (defun reverse (sequence) #!+sb-doc - "Returns a new sequence containing the same elements but in reverse order." + "Return a new sequence containing the same elements but in reverse order." (seq-dispatch sequence (list-reverse* sequence) (vector-reverse* sequence))) @@ -532,7 +532,7 @@ (defun nreverse (sequence) #!+sb-doc - "Returns a sequence of the same elements in reverse order; the argument + "Return a sequence of the same elements in reverse order; the argument is destroyed." (seq-dispatch sequence (list-nreverse* sequence) @@ -599,7 +599,7 @@ ;;; efficiency, but space efficiency..) (defun concatenate (output-type-spec &rest sequences) #!+sb-doc - "Returns a new sequence of all the argument sequences concatenated together + "Return a new sequence of all the argument sequences concatenated together which shares no structure with the original argument sequences of the specified OUTPUT-TYPE-SPEC." (case (type-specifier-atom output-type-spec) @@ -638,7 +638,7 @@ (vector (dovector (,i sequence) ,@body)))))) (defun %map-to-list-arity-1 (fun sequence) (let ((reversed-result nil) - (really-fun (%coerce-callable-to-function fun))) + (really-fun (%coerce-callable-to-fun fun))) (dosequence (element sequence) (push (funcall really-fun element) reversed-result)) @@ -646,7 +646,7 @@ (defun %map-to-simple-vector-arity-1 (fun sequence) (let ((result (make-array (length sequence))) (index 0) - (really-fun (%coerce-callable-to-function fun))) + (really-fun (%coerce-callable-to-fun fun))) (declare (type index index)) (dosequence (element sequence) (setf (aref result index) @@ -654,7 +654,7 @@ (incf index)) result)) (defun %map-for-effect-arity-1 (fun sequence) - (let ((really-fun (%coerce-callable-to-function fun))) + (let ((really-fun (%coerce-callable-to-fun fun))) (dosequence (element sequence) (funcall really-fun element))) nil)) @@ -760,7 +760,7 @@ ;;; length of the output sequence matches any length specified ;;; in RESULT-TYPE. (defun %map (result-type function first-sequence &rest more-sequences) - (let ((really-function (%coerce-callable-to-function function))) + (let ((really-function (%coerce-callable-to-fun function))) ;; Handle one-argument MAP NIL specially, using ETYPECASE to turn ;; it into something which can be DEFTRANSFORMed away. (It's ;; fairly important to handle this case efficiently, since @@ -826,7 +826,7 @@ (when fp-result (setf (fill-pointer result-sequence) len)) - (let ((really-fun (%coerce-callable-to-function function))) + (let ((really-fun (%coerce-callable-to-fun function))) (dotimes (index len) (setf (elt result-sequence index) (apply really-fun @@ -894,22 +894,22 @@ ,@more-seqs) ,',unfound-result))))))) (defquantifier some when pred-value :unfound-result nil :doc - "PREDICATE is applied to the elements with index 0 of the sequences, then - possibly to those with index 1, and so on. SOME returns the first - non-NIL value encountered, or NIL if the end of a sequence is reached.") + "Apply PREDICATE to the 0-indexed elements of the sequences, then + possibly to those with index 1, and so on. Return the first + non-NIL value encountered, or NIL if the end of any sequence is reached.") (defquantifier every unless nil :doc - "PREDICATE is applied to the elements with index 0 of the sequences, then - possibly to those with index 1, and so on. EVERY returns NIL as soon + "Apply PREDICATE to the 0-indexed elements of the sequences, then + possibly to those with index 1, and so on. Return NIL as soon as any invocation of PREDICATE returns NIL, or T if every invocation is non-NIL.") (defquantifier notany when nil :doc - "PREDICATE is applied to the elements with index 0 of the sequences, then - possibly to those with index 1, and so on. NOTANY returns NIL as soon + "Apply PREDICATE to the 0-indexed elements of the sequences, then + possibly to those with index 1, and so on. Return NIL as soon as any invocation of PREDICATE returns a non-NIL value, or T if the end - of a sequence is reached.") + of any sequence is reached.") (defquantifier notevery unless t :doc - "PREDICATE is applied to the elements with index 0 of the sequences, then - possibly to those with index 1, and so on. NOTEVERY returns T as soon + "Apply PREDICATE to 0-indexed elements of the sequences, then + possibly to those with index 1, and so on. Return T as soon as any invocation of PREDICATE returns NIL, or NIL if every invocation is non-NIL.")) @@ -1122,8 +1122,8 @@ (defun delete (item sequence &key from-end (test #'eql) test-not (start 0) end count key) #!+sb-doc - "Returns a sequence formed by destructively removing the specified Item from - the given Sequence." + "Return a sequence formed by destructively removing the specified ITEM from + the given SEQUENCE." (declare (fixnum start)) (let* ((length (length sequence)) (end (or end length)) @@ -1160,8 +1160,8 @@ (defun delete-if (predicate sequence &key from-end (start 0) key end count) #!+sb-doc - "Returns a sequence formed by destructively removing the elements satisfying - the specified Predicate from the given Sequence." + "Return a sequence formed by destructively removing the elements satisfying + the specified PREDICATE from the given SEQUENCE." (declare (fixnum start)) (let* ((length (length sequence)) (end (or end length)) @@ -1198,8 +1198,8 @@ (defun delete-if-not (predicate sequence &key from-end (start 0) end key count) #!+sb-doc - "Returns a sequence formed by destructively removing the elements not - satisfying the specified Predicate from the given Sequence." + "Return a sequence formed by destructively removing the elements not + satisfying the specified PREDICATE from the given SEQUENCE." (declare (fixnum start)) (let* ((length (length sequence)) (end (or end length)) @@ -1345,7 +1345,7 @@ (defun remove (item sequence &key from-end (test #'eql) test-not (start 0) end count key) #!+sb-doc - "Returns a copy of SEQUENCE with elements satisfying the test (default is + "Return a copy of SEQUENCE with elements satisfying the test (default is EQL) with ITEM removed." (declare (fixnum start)) (let* ((length (length sequence)) @@ -1363,8 +1363,8 @@ (defun remove-if (predicate sequence &key from-end (start 0) end count key) #!+sb-doc - "Returns a copy of sequence with elements such that predicate(element) - is non-null are removed" + "Return a copy of sequence with elements such that predicate(element) + is non-null removed" (declare (fixnum start)) (let* ((length (length sequence)) (end (or end length)) @@ -1381,8 +1381,8 @@ (defun remove-if-not (predicate sequence &key from-end (start 0) end count key) #!+sb-doc - "Returns a copy of sequence with elements such that predicate(element) - is null are removed" + "Return a copy of sequence with elements such that predicate(element) + is null removed" (declare (fixnum start)) (let* ((length (length sequence)) (end (or end length)) @@ -1668,8 +1668,8 @@ (defun substitute (new old sequence &key from-end (test #'eql) test-not (start 0) count end key) #!+sb-doc - "Returns a sequence of the same kind as Sequence with the same elements - except that all elements equal to Old are replaced with New. See manual + "Return a sequence of the same kind as SEQUENCE with the same elements, + except that all elements equal to OLD are replaced with NEW. See manual for details." (declare (fixnum start)) (let* ((length (length sequence)) @@ -1683,8 +1683,8 @@ (defun substitute-if (new test sequence &key from-end (start 0) end count key) #!+sb-doc - "Returns a sequence of the same kind as Sequence with the same elements - except that all elements satisfying the Test are replaced with New. See + "Return a sequence of the same kind as SEQUENCE with the same elements + except that all elements satisfying the TEST are replaced with NEW. See manual for details." (declare (fixnum start)) (let* ((length (length sequence)) @@ -1699,8 +1699,8 @@ (defun substitute-if-not (new test sequence &key from-end (start 0) end count key) #!+sb-doc - "Returns a sequence of the same kind as Sequence with the same elements - except that all elements not satisfying the Test are replaced with New. + "Return a sequence of the same kind as SEQUENCE with the same elements + except that all elements not satisfying the TEST are replaced with NEW. See manual for details." (declare (fixnum start)) (let* ((length (length sequence)) @@ -1717,9 +1717,9 @@ (defun nsubstitute (new old sequence &key from-end (test #'eql) test-not end count key (start 0)) #!+sb-doc - "Returns a sequence of the same kind as Sequence with the same elements - except that all elements equal to Old are replaced with New. The Sequence - may be destroyed. See manual for details." + "Return a sequence of the same kind as SEQUENCE with the same elements + except that all elements equal to OLD are replaced with NEW. The SEQUENCE + may be destructively modified. See manual for details." (declare (fixnum start)) (let ((end (or end (length sequence))) (count (or count most-positive-fixnum))) @@ -1767,9 +1767,9 @@ (defun nsubstitute-if (new test sequence &key from-end (start 0) end count key) #!+sb-doc - "Returns a sequence of the same kind as Sequence with the same elements - except that all elements satisfying the Test are replaced with New. The - Sequence may be destroyed. See manual for details." + "Return a sequence of the same kind as SEQUENCE with the same elements + except that all elements satisfying the TEST are replaced with NEW. + SEQUENCE may be destructively modified. See manual for details." (declare (fixnum start)) (let ((end (or end (length sequence))) (count (or count most-positive-fixnum))) @@ -1807,9 +1807,9 @@ (defun nsubstitute-if-not (new test sequence &key from-end (start 0) end count key) #!+sb-doc - "Returns a sequence of the same kind as Sequence with the same elements - except that all elements not satisfying the Test are replaced with New. - The Sequence may be destroyed. See manual for details." + "Return a sequence of the same kind as SEQUENCE with the same elements + except that all elements not satisfying the TEST are replaced with NEW. + SEQUENCE may be destructively modified. See manual for details." (declare (fixnum start)) (let ((end (or end (length sequence))) (count (or count most-positive-fixnum))) @@ -1852,16 +1852,16 @@ (defun effective-find-position-test (test test-not) (cond ((and test test-not) (error "can't specify both :TEST and :TEST-NOT")) - (test (%coerce-callable-to-function test)) + (test (%coerce-callable-to-fun test)) (test-not ;; (Without DYNAMIC-EXTENT, this is potentially horribly ;; inefficient, but since the TEST-NOT option is deprecated ;; anyway, we don't care.) - (complement (%coerce-callable-to-function test-not))) + (complement (%coerce-callable-to-fun test-not))) (t #'eql))) (defun effective-find-position-key (key) (if key - (%coerce-callable-to-function key) + (%coerce-callable-to-fun key) #'identity)) ;;; shared guts of out-of-line FIND, POSITION, FIND-IF, and POSITION-IF @@ -1936,7 +1936,7 @@ &key from-end (start 0) end key) (nth-value ,values-index - (%find-position-if (%coerce-callable-to-function predicate) + (%find-position-if (%coerce-callable-to-fun predicate) sequence from-end start @@ -1949,6 +1949,26 @@ ;;; the deprecated functions FIND-IF-NOT and POSITION-IF-NOT. We don't ;;; bother to worry about optimizing them. ;;; +;;; (Except note that on Sat, Oct 06, 2001 at 04:22:38PM +0100, +;;; Christophe Rhodes wrote on sbcl-devel +;;; +;;; My understanding is that while the :test-not argument is +;;; deprecated in favour of :test (complement #'foo) because of +;;; semantic difficulties (what happens if both :test and :test-not +;;; are supplied, etc) the -if-not variants, while officially +;;; deprecated, would be undeprecated were X3J13 actually to produce +;;; a revised standard, as there are perfectly legitimate idiomatic +;;; reasons for allowing the -if-not versions equal status, +;;; particularly remove-if-not (== filter). +;;; +;;; This is only an informal understanding, I grant you, but +;;; perhaps it's worth optimizing the -if-not versions in the same +;;; way as the others? +;;; +;;; That sounds reasonable, so if someone wants to submit patches to +;;; make the -IF-NOT functions compile as efficiently as the +;;; corresponding -IF variants do, go for it. -- WHN 2001-10-06) +;;; ;;; FIXME: Remove uses of these deprecated functions (and of :TEST-NOT ;;; too) within the implementation of SBCL. (macrolet ((def-find-position-if-not (fun-name values-index) @@ -1956,7 +1976,7 @@ &key from-end (start 0) end key) (nth-value ,values-index - (%find-position-if (complement (%coerce-callable-to-function + (%find-position-if (complement (%coerce-callable-to-fun predicate)) sequence from-end @@ -1999,7 +2019,7 @@ (defun count (item sequence &key from-end (test #'eql) test-not (start 0) end key) #!+sb-doc - "Returns the number of elements in SEQUENCE satisfying a test with ITEM, + "Return the number of elements in SEQUENCE satisfying a test with ITEM, which defaults to EQL." (declare (ignore from-end) (fixnum start)) (let ((end (or end (length sequence)))) @@ -2033,7 +2053,7 @@ (defun count-if (test sequence &key from-end (start 0) end key) #!+sb-doc - "Returns the number of elements in SEQUENCE satisfying TEST(el)." + "Return the number of elements in SEQUENCE satisfying TEST(el)." (declare (ignore from-end) (fixnum start)) (let ((end (or end (length sequence)))) (declare (type index end)) @@ -2064,7 +2084,7 @@ (defun count-if-not (test sequence &key from-end (start 0) end key) #!+sb-doc - "Returns the number of elements in SEQUENCE not satisfying TEST(el)." + "Return the number of elements in SEQUENCE not satisfying TEST(el)." (declare (ignore from-end) (fixnum start)) (let ((end (or end (length sequence)))) (declare (type index end))