Search

( alist-delete key [ list? alist ] ) list? ( alist-delete key [ list? alist ] [ procedure? = ] ) list?
= ( λ a b ) *
alist-delete, alist-delete! alist-delete deletes all associations from alist with the given key, using key-comparison procedure =, which defaults to equal?. The dynamic order in which the various applications of = are made is not specified. Return values may share common tails with the alist argument. The alist is not disordered -- elements that appear in the result alist occur in the same order as they occur in the argument alist. The comparison procedure is used to compare the element keys ki of alist's entries to the key parameter in this way: (= key ki). Thus, one can reliably remove all entries of alist whose key is greater than five with (alist-delete 5 alist <). alist-delete! is the linear-update variant of alist-delete. It is allowed, but not required, to alter cons cells from the alist parameter to construct the result.
( alist-delete! key [ list? alist ] ) list? ( alist-delete! key [ list? alist ] [ procedure? = ] ) list?
= ( λ a b ) *
alist-delete, alist-delete! alist-delete deletes all associations from alist with the given key, using key-comparison procedure =, which defaults to equal?. The dynamic order in which the various applications of = are made is not specified. Return values may share common tails with the alist argument. The alist is not disordered -- elements that appear in the result alist occur in the same order as they occur in the argument alist. The comparison procedure is used to compare the element keys ki of alist's entries to the key parameter in this way: (= key ki). Thus, one can reliably remove all entries of alist whose key is greater than five with (alist-delete 5 alist <). alist-delete! is the linear-update variant of alist-delete. It is allowed, but not required, to alter cons cells from the alist parameter to construct the result.
( any [ procedure? pred ] [ list? clist1 ] [ list? clist2 ] ... ) *
pred ( λ obj1 obj2 ... ) *
Applies the predicate across the lists, returning true if the predicate returns true on any application. If there are n list arguments clist1 ... clistn, then pred must be a procedure taking n arguments and returning a single value, interpreted as a boolean (that is, #f means false, and any other value means true). any applies pred to the first elements of the clisti parameters. If this application returns a true value, any immediately returns that value. Otherwise, it iterates, applying pred to the second elements of the clisti 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, any returns #f. The application of pred to the last element of the lists is a tail call. Note the difference between find and any -- find returns the element that satisfied the predicate; any returns the true value that the predicate produced. Like every, any's name does not end with a question mark -- this is to indicate that it does not return a simple boolean (#t or #f), but a general value.
( append-map [ procedure? proc ] [ list? list1 ] [ list? list2 ] ... ) list?
proc ( λ obj1 obj2 ... ) list?
append-map, append-map! Equivalent to (apply append (map f clist1 clist2 ...)) and (apply append! (map f clist1 clist2 ...)). Map f over the elements of the lists, just as in the map function. However, the results of the applications are appended together to make the final result. append-map uses append to append the results together; append-map! uses append!. The dynamic order in which the various applications of f are made is not specified.
( append-map! [ procedure? proc ] [ list? list1 ] [ list? list2 ] ... ) list?
proc ( λ obj1 objs2 ... ) list?
append-map, append-map! Equivalent to (apply append (map f clist1 clist2 ...)) and (apply append! (map f clist1 clist2 ...)). Map f over the elements of the lists, just as in the map function. However, the results of the applications are appended together to make the final result. append-map uses append to append the results together; append-map! uses append!. The dynamic order in which the various applications of f are made is not specified.
( args-fold [ list? args ] [ list? options ] [ procedure? unrecognized-option-proc ] [ procedure? operand-proc ] seed ... ) ( values * ... )
unrecognized-option-proc ( λ [ option option ] [ string? / char? name ] [ string? arg ] seed ... ) ( values * ... )
operand-proc ( λ [ string? operand ] seed ... ) ( values * ... )
( assoc obj [ list? alist ] ) ( or pair? #f ) ( assoc obj [ list? alist ] [ procedure? = ] ) ( or pair? #f )
= ( λ a b ) *
assq, assv, assoc It is an error if alist (for "association list") is not a list of pairs. These procedures find the first pair in alist whose car field is obj , and returns that pair. If no pair in alist has obj as its car, then #f (not the empty list) is returned. The assq procedure uses eq? to compare obj with the car fields of the pairs in alist , while assv uses eqv? and assoc uses compare if given and equal? otherwise. Rationale: Although they are often used as predicates, memq, memv, member, assq, assv, and assoc do not have question marks in their names because they return potentially useful values rather than just #t or #f.
( assoc obj [ list? alist ] ) ( or list? #f ) ( assoc obj [ list? alist ] [ procedure? = ] ) ( or pair? #f )
= ( λ a b ) *
assoc, assq, assv alist must be an association list -- a list of pairs. These procedures find the first pair in alist whose car field is key, and returns that pair. If no pair in alist has key as its car, then #f is returned. assq uses eq? to compare key with the car fields of the pairs in alist, while assv uses eqv? and assoc uses equal?. assoc is extended from its R5RS definition to allow the client to pass in an optional equality procedure = used to compare keys. The comparison procedure is used to compare the elements ei of list to the key parameter in this way: (= key (car ei)) ; list is (E1 ... En). That is, the first argument is always key, and the second argument is one of the list elements. Thus one can reliably find the first entry of alist whose key is greater than five with (assoc 5 alist <). Note that fully general alist searching may be performed with the find-tail and find procedures
( break [ procedure? pred ] [ list? list ] ) ( values list? list? ) ( break [ procedure? pred ] [ circular-list? list ] ) ( values list? circular-list? )
pred ( λ obj ) *
span, span!, break, break! Span splits the list into the longest initial prefix whose elements all satisfy pred, and the remaining tail. Break inverts the sense of the predicate: the tail commences with the first element of the input list that satisfies the predicate. In other words: span finds the intial span of elements satisfying pred, and break breaks the list at the first element satisfying pred. Span is equivalent to (values (take-while pred clist) (drop-while pred clist)). Span! and break! are the linear-update variants. They are allowed, but not required, to alter the argument list to produce the result.
( break! [ procedure? pred ] [ list? list ] ) ( values list? list? )
pred ( λ obj ) *
span, span!, break, break! Span splits the list into the longest initial prefix whose elements all satisfy pred, and the remaining tail. Break inverts the sense of the predicate: the tail commences with the first element of the input list that satisfies the predicate. In other words: span finds the intial span of elements satisfying pred, and break breaks the list at the first element satisfying pred. Span is equivalent to (values (take-while pred clist) (drop-while pred clist)). Span! and break! are the linear-update variants. They are allowed, but not required, to alter the argument list to produce the result.
( call-with-current-continuation [ procedure? proc ] ) *
proc ( λ [ procedure? k ] ) *
It is an error if proc does not accept one argument. The procedure call-with-current-continuation (or its equivalent abbreviation call/cc) packages the current continuation (see the rationale below) as an "escape procedure" and passes it as an argument to proc. The escape procedure is a Scheme procedure that, if it is later called, will abandon whatever continuation is in ect at that later time and will instead use the continuation that was in effect when the escape procedure was created. Calling the escape procedure will cause the invocation of before and after thunks installed using dynamic-wind. The escape procedure accepts the same number of arguments as the continuation to the original call to call-with-current-continuation. Most continuations take only one value. Continuations created by the call-with-values procedure (including the initialization expressions of define-values, let-values, and let*-values expressions), take the number of values that the consumer expects. The continuations of all non-final expressions within a sequence of expressions, such as in lambda, case-lambda, begin, let, let*, letrec, letrec*, let-values, let*-values, let-syntax, letrec-syntax, parameterize, guard, case, cond, when, and unless expressions, take an arbitrary number of values because they discard the values passed to them in any event. The ect of passing no values or more than one value to continuations that were not created in one of these ways is unspecified. The escape procedure that is passed to proc has unlimited extent just like any other procedure in Scheme. It can be stored in variables or data structures and can be called as many times as desired. However, like the raise and error procedures, it never returns to its caller. Rationale: A common use of call-with-current-continuation is for structured, non-local exits from loops or procedure bodies, but in fact call-with-current-continuation is useful for implementing a wide variety of advanced control structures. In fact, raise and guard provide a more structured mechanism for nonlocal exits. Whenever a Scheme expression is evaluated there is a continuation wanting the result of the expression. The continuation represents an entire (default) future for the computation. If the expression is evaluated at the REPL, for example, then the continuation might take the result, print it on the screen, prompt for the next input, evaluate it, and so on forever. Most of the time the continuation includes actions specified by user code, as in a continuation that will take the result, multiply it by the value stored in a local variable, add seven, and give the answer to the REPL's continuation to be printed. Normally these ubiquitous continuations are hidden behind the scenes and programmers do not think much about them. On rare occasions, however, a programmer needs to deal with continuations explicitly. The call-with-current-continuation procedure allows Scheme programmers to do that by creating a procedure that acts just like the current continuation.
( call-with-input-file [ string? string ] [ procedure? proc ] ) *
proc ( λ [ input-port? port ] ) *
call-with-input-file, call-with-output-file It is an error if proc does not accept one argument. These procedures obtain a textual port obtained by opening the named file for input or output as if by open-input-file or open-output-file. The port and proc are then passed to a procedure equivalent to call-with-port.
( call-with-output-file [ string? string ] [ procedure? proc ] ) *
proc ( λ [ output-port? port ] ) *
call-with-input-file, call-with-output-file It is an error if proc does not accept one argument. These procedures obtain a textual port obtained by opening the named file for input or output as if by open-input-file or open-output-file. The port and proc are then passed to a procedure equivalent to call-with-port.
( call-with-port [ port? port ] [ procedure? proc ] ) *
proc ( λ [ port? port ] ) *
It is an error if proc does not accept one argument. The call-with-port procedure calls proc with port as an argument. If proc returns, then the port is closed automatically and the values yielded by the proc are returned. If proc does not return, then the port must not be closed automatically unless it is possible to prove that the port will never again be used for a read or write operation. Rationale: Because Scheme’s escape procedures have unlimited extent, it is possible to escape from the current continuation but later to resume it. If implementations were permitted to close the port on any escape from the current continuation, then it would be impossible to write portable code using both call-with-current-continuation and call-with-port.
( call-with-values [ procedure? producer ] [ procedure? consumer ] ) *
producer ( λ ) *
consumer ( λ obj ... ) *
Calls its producer argument with no arguments and a continuation that, when passed some values, calls the consumer procedure with those values as arguments. The continuation for the call to consumer is the continuation of the call to call-with-values.
( call/cc [ procedure? proc ] ) *
proc ( λ [ procedure? k ] ) *
It is an error if proc does not accept one argument. The procedure call-with-current-continuation (or its equivalent abbreviation call/cc) packages the current continuation (see the rationale below) as an "escape procedure" and passes it as an argument to proc. The escape procedure is a Scheme procedure that, if it is later called, will abandon whatever continuation is in ect at that later time and will instead use the continuation that was in effect when the escape procedure was created. Calling the escape procedure will cause the invocation of before and after thunks installed using dynamic-wind. The escape procedure accepts the same number of arguments as the continuation to the original call to call-with-current-continuation. Most continuations take only one value. Continuations created by the call-with-values procedure (including the initialization expressions of define-values, let-values, and let*-values expressions), take the number of values that the consumer expects. The continuations of all non-final expressions within a sequence of expressions, such as in lambda, case-lambda, begin, let, let*, letrec, letrec*, let-values, let*-values, let-syntax, letrec-syntax, parameterize, guard, case, cond, when, and unless expressions, take an arbitrary number of values because they discard the values passed to them in any event. The ect of passing no values or more than one value to continuations that were not created in one of these ways is unspecified. The escape procedure that is passed to proc has unlimited extent just like any other procedure in Scheme. It can be stored in variables or data structures and can be called as many times as desired. However, like the raise and error procedures, it never returns to its caller. Rationale: A common use of call-with-current-continuation is for structured, non-local exits from loops or procedure bodies, but in fact call-with-current-continuation is useful for implementing a wide variety of advanced control structures. In fact, raise and guard provide a more structured mechanism for nonlocal exits. Whenever a Scheme expression is evaluated there is a continuation wanting the result of the expression. The continuation represents an entire (default) future for the computation. If the expression is evaluated at the REPL, for example, then the continuation might take the result, print it on the screen, prompt for the next input, evaluate it, and so on forever. Most of the time the continuation includes actions specified by user code, as in a continuation that will take the result, multiply it by the value stored in a local variable, add seven, and give the answer to the REPL's continuation to be printed. Normally these ubiquitous continuations are hidden behind the scenes and programmers do not think much about them. On rare occasions, however, a programmer needs to deal with continuations explicitly. The call-with-current-continuation procedure allows Scheme programmers to do that by creating a procedure that acts just like the current continuation.