@c This file is part of the MIT/GNU Scheme Reference Manual.
-@c $Id: lists.texi,v 1.6 2008/01/30 20:06:11 cph Exp $
+@c $Id: lists.texi,v 1.7 2008/01/31 00:54:36 cph Exp $
@c Copyright (C) 1986, 1987, 1988, 1989, 1990, 1991, 1992, 1993, 1994,
@c 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,
@cindex filtering, of list
@cindex deletion, of list element
-@deffn procedure keep-matching-items list predicate
-@deffnx procedure delete-matching-items list predicate
-These procedures return a newly allocated copy of @var{list} containing
-only the elements for which @var{predicate} is (respectively) true or
-false. @var{Predicate} must be a procedure of one argument.
+@deffn procedure filter predicate list
+(@acronym{SRFI} 1) Returns a newly allocated copy of @var{list}
+containing only the elements satisfying @var{predicate}.
+@var{Predicate} must be a procedure of one argument.
@example
-@group
-(keep-matching-items '(1 2 3 4 5) odd?) @result{} (1 3 5)
-(delete-matching-items '(1 2 3 4 5) odd?) @result{} (2 4)
-@end group
+(filter odd? '(1 2 3 4 5)) @result{} (1 3 5)
@end example
+@findex keep-matching-items
@findex list-transform-positive
+The non-standard procedure @code{keep-matching-items} (and its alias
+@code{list-transform-positive}) are the same except that its arguments
+are reversed.
+@end deffn
+
+@deffn procedure remove predicate list
+(@acronym{SRFI} 1) Like @code{filter}, except that the returned list
+contains only those elements @emph{not} satisfying @var{predicate}.
+
+@example
+(remove odd? '(1 2 3 4 5)) @result{} (2 4)
+@end example
+
+@findex delete-matching-items
@findex list-transform-negative
-For compatibility, the procedure @code{list-transform-positive} is an
-alias for @code{keep-matching-items}, and @code{list-transform-negative}
-is an alias for @code{delete-matching-items}.
+The non-standard procedure @code{delete-matching-items} (and its alias
+@code{list-transform-negative}) are the same except that its arguments
+are reversed.
@end deffn
-@deffn procedure keep-matching-items! list predicate
-@deffnx procedure delete-matching-items! list predicate
-These procedures are exactly like @code{keep-matching-items} and
-@code{delete-matching-items}, respectively, except that they
-destructively modify the @var{list} argument rather than allocating a
-new result.
+@deffn procedure partition predicate list
+(@acronym{SRFI} 1) Partitions the elements of @var{list} with
+@var{predicate}, and returns two values: the list of in-elements and
+the list of out-elements. The @var{list} is not disordered---elements
+occur in the result lists in the same order as they occur in the
+argument @var{list}. The dynamic order in which the various
+applications of @code{predicate} are made is not specified. One of
+the returned lists may share a common tail with the argument
+@var{list}.
+
+@example
+@group
+(partition symbol? '(one 2 3 four five 6)) =>
+ (one four five)
+ (2 3 6)
+@end group
+@end example
+@end deffn
+
+@deffn procedure filter! predicate list
+@deffnx procedure remove! predicate list
+@deffnx procedure partition! predicate list
+(@acronym{SRFI} 1) Linear-update variants of @code{filter},
+@code{remove} and @code{partition}. These procedures are allowed, but
+not required, to alter the cons cells in the argument @code{list} to
+construct the result lists.
+
+@findex keep-matching-items!
+@findex delete-matching-items!
+The non-standard procedures @code{keep-matching-items!} and
+@code{delete-matching-items!} bear a similar relationship to
+@code{keep-matching-items} and @code{delete-matching-items},
+respectively.
@end deffn
@deffn procedure delq element list
@section Searching Lists
@cindex searching, of list
-@deffn procedure find-matching-item list predicate
-Returns the first element in @var{list} for which @var{predicate} is
-true; returns @code{#f} if it doesn't find such an element. (This means
-that if @var{predicate} is true for @code{#f}, it may be impossible to
-distinguish a successful result from an unsuccessful one.)
-@var{Predicate} must be a procedure of one argument.
+@deffn procedure find predicate list
+(@acronym{SRFI} 1) Returns the first element in @var{list} for which
+@var{predicate} is true; returns @code{#f} if it doesn't find such an
+element. @var{Predicate} must be a procedure of one argument.
+@example
+(find even? '(3 1 4 1 5 9)) => 4
+@end example
+
+Note that @code{find} has an ambiguity in its lookup semantics---if
+@code{find} returns @code{#f}, you cannot tell (in general) if it
+found a @code{#f} element that satisfied @var{predicate}, or if it did
+not find any element at all. In many situations, this ambiguity
+cannot arise---either the list being searched is known not to contain
+any @code{#f} elements, or the list is guaranteed to have an element
+satisfying @var{predicate}. However, in cases where this ambiguity
+can arise, you should use @code{find-tail} instead of
+@code{find}---@code{find-tail} has no such ambiguity:
+
+@example
+@group
+(cond ((find-tail pred lis)
+ => (lambda (pair) @dots{})) ; Handle (CAR PAIR)
+ (else @dots{})) ; Search failed.
+@end group
+@end example
+
+@findex find-matching-item
@findex list-search-positive
@findex list-search-negative
-For compatibility, @code{list-search-positive} is an alias for
-@code{find-matching-item}. @code{list-search-negative} is similar but
-the sense of the predicate is reversed.
+The non-standard @code{find-matching-item} procedure (and its alias
+@code{list-search-positive}) works identically except that its
+argument order is reversed. @code{list-search-negative} is similar to
+@code{list-search-positive} but the sense of the predicate is
+reversed.
+@end deffn
+
+@deffn procedure find-tail predicate list
+(@acronym{SRFI} 1) Returns the first pair of @var{list} whose car
+satisfies @var{predicate}; returns @code{#f} if there's no such pair.
+@code{find-tail} can be viewed as a general-predicate variant of
+@var{memv}.
@end deffn
@deffn procedure memq object list
@end example
@end deffn
-@deffn procedure there-exists? list predicate
-@var{Predicate} must be a procedure of one argument. Applies
-@var{predicate} to each element of @var{list}, in order from left to
-right. If @var{predicate} is true for any element of @var{list}, the
-value yielded by @var{predicate} is immediately returned as the value of
-@code{there-exists?}; @var{predicate} will not be applied to the
-remaining elements of @var{list}. If @var{predicate} returns @code{#f}
-for all of the elements of @var{list}, then @code{#f} is returned.
+@deffn procedure any predicate list list @dots{}
+(@acronym{SRFI} 1) Applies @var{predicate} across the @var{list}s,
+returning true if @var{predicate} returns true on any application.
+
+If there are @math{n} list arguments @var{list1} @dots{} @var{listn},
+then @var{predicate} must be a procedure taking @math{n} arguments and
+returning a boolean result.
+
+@code{any} applies @var{predicate} to the first elements of the
+@var{list} parameters. If this application returns a true value,
+@code{any} immediately returns that value. Otherwise, it iterates,
+applying @var{predicate} to the second elements of the @var{list}
+parameters, then the third, and so forth. The iteration stops when a
+true value is produced or one of the lists runs out of values; in the
+latter case, @code{any} returns @code{#f}. The application of
+@var{predicate} to the last element of the @var{list}s is a tail call.
+
+Note the difference between @code{find} and @code{any}---@code{find}
+returns the element that satisfied the predicate; @code{any} returns
+the true value that the @var{predicate} produced.
+
+Like @code{every}, @code{any}'s name does not end with a question
+mark---this is to indicate that it does not return a simple boolean
+(@code{#t} or @code{#f}), but a general value.
+
+@example
+@group
+(any integer? '(a 3 b 2.7)) => #t
+(any integer? '(a 3.1 b 2.7)) => #f
+(any < '(3 1 4 1 5)
+ '(2 7 1 8 2)) => #t
+@end group
+@end example
+
+@findex there-exists?
+The non-standard procedure @code{there-exists?} is similar, except
+that it takes a single list and a predicate argument, in that order.
@end deffn
-@deffn procedure for-all? list predicate
-@var{Predicate} must be a procedure of one argument. Applies
-@var{predicate} to each element of @var{list}, in order from left to
-right. If @var{predicate} returns @code{#f} for any element of
-@var{list}, @code{#f} is immediately returned as the value of
-@code{for-all?}; @var{predicate} will not be applied to the remaining
-elements of @var{list}. If @var{predicate} is true for all of the
-elements of @var{list}, then @code{#t} is returned.
+@deffn procedure every predicate list list @dots{}
+(@acronym{SRFI} 1) Applies @var{predicate} across the @var{list}s,
+returning true if @var{predicate} returns true on every application.
+
+If there are @math{n} list arguments @var{list1} @dots{} @var{listn},
+then @var{predicate} must be a procedure taking @math{n} arguments and
+returning a boolean result.
+
+@code{every} applies @var{predicate} to the first elements of the
+@var{list} parameters. If this application returns false,
+@code{every} immediately returns false. Otherwise, it iterates,
+applying @var{predicate} to the second elements of the @var{list}
+parameters, then the third, and so forth. The iteration stops when a
+false value is produced or one of the @var{list}s runs out of values.
+In the latter case, @code{every} returns the true value produced by
+its final application of @var{predicate}. The application of
+@var{predicate} to the last element of the @var{list}s is a tail call.
+
+If one of the clisti has no elements, @code{every} simply returns @code{#t}.
+
+Like @code{any}, @code{every}'s name does not end with a question
+mark---this is to indicate that it does not return a simple boolean
+(@code{#t} or @code{#f}), but a general value.
+
+
+@findex for-all?
+The non-standard procedure @code{for-all?} is similar, except
+that it takes a single list and a predicate argument, in that order.
@end deffn
@node Miscellaneous List Operations, , Reduction of Lists, Lists
projects / mit-scheme.git / commitdiff