From: Chris Hanson Date: Thu, 31 Jan 2008 00:54:36 +0000 (+0000) Subject: Update for some of the srfi-1 procedures. X-Git-Tag: 20090517-FFI~369 X-Git-Url: https://birchwood-abbey.net/git?a=commitdiff_plain;h=435984eb43e0edb6f834fddffbd8623b60efa602;p=mit-scheme.git Update for some of the srfi-1 procedures. --- diff --git a/v7/doc/ref-manual/lists.texi b/v7/doc/ref-manual/lists.texi index caedc14a1..48096a717 100644 --- a/v7/doc/ref-manual/lists.texi +++ b/v7/doc/ref-manual/lists.texi @@ -1,5 +1,5 @@ @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, @@ -753,32 +753,70 @@ procedure. @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 @@ -877,18 +915,48 @@ with the appropriate elements removed. The procedure returned by @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 @@ -1119,24 +1187,73 @@ is iterative in nature, combining the elements as the list is traversed. @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