65b1a569a0
Use the new functions in `syntax-case'; the benefit is small, and it's mostly useful as hint to the optimizer that the operation can be dropped if the result isn't used
1093 lines
32 KiB
Racket
1093 lines
32 KiB
Racket
#lang scribble/doc
|
|
@(require "mz.rkt" scribble/scheme racket/generator racket/list
|
|
(for-syntax racket/base))
|
|
|
|
@(define (generate-c_r-example proc)
|
|
(define (make-it start n)
|
|
(generator ()
|
|
(let loop ([start start]
|
|
[n n])
|
|
(yield (list* n start))
|
|
(yield (append start (list n)))
|
|
(when (< (length (flatten start)) 8)
|
|
(loop (list* n start) (add1 n))
|
|
(loop (list start n) (add1 n))
|
|
))))
|
|
(define (example proc)
|
|
(define maker (make-it '() 1))
|
|
(let loop ([value (maker)])
|
|
(with-handlers ([exn? (lambda (e) (loop (maker)))])
|
|
(proc value)
|
|
value)))
|
|
(example proc))
|
|
|
|
@(define-syntax (defc_r stx)
|
|
(syntax-case stx ()
|
|
[(_ x ... example-arg)
|
|
(let ([xs (map syntax-e (syntax->list #'(x ...)))])
|
|
(let ([name (string->symbol
|
|
(string-append
|
|
"c"
|
|
(apply string-append (map symbol->string xs))
|
|
"r"))]
|
|
[contract (let loop ([l (reverse xs)])
|
|
(cond
|
|
[(null? (cdr l)) 'pair?]
|
|
[(eq? (car l) 'a) `(cons/c ,(loop (cdr l)) any/c)]
|
|
[(eq? (car l) 'd) `(cons/c any/c ,(loop (cdr l)))]))]
|
|
[equiv (let loop ([l xs])
|
|
(cond
|
|
[(null? l) 'p]
|
|
[(eq? (car l) 'a) `(car ,(loop (cdr l)))]
|
|
[(eq? (car l) 'd) `(cdr ,(loop (cdr l)))]))])
|
|
(with-syntax ([name name]
|
|
[contract (let loop ([c contract] [pos 0])
|
|
(if (pair? c)
|
|
(let* ([a (loop (car c) (add1 pos))]
|
|
[b (loop (cdr c) (+ 1 pos (syntax-span a)))]
|
|
[span (+ 1 (syntax-span a) (syntax-span b))])
|
|
(datum->syntax #'here
|
|
(cons a b)
|
|
(list (syntax-source stx)
|
|
1
|
|
pos
|
|
(add1 pos)
|
|
span)))
|
|
(datum->syntax #'here c
|
|
(list (syntax-source stx) 1 pos (add1 pos) 1))))]
|
|
[example (let ([ex #'example-arg])
|
|
(datum->syntax #f
|
|
(list
|
|
(datum->syntax #f
|
|
name
|
|
(vector (syntax-source ex)
|
|
(syntax-line ex)
|
|
(- (syntax-column ex) 2)
|
|
(- (syntax-position ex) 2)
|
|
1))
|
|
ex)
|
|
(vector (syntax-source ex)
|
|
(syntax-line ex)
|
|
(- (syntax-column ex) 3)
|
|
(- (syntax-position ex) 3)
|
|
(+ (syntax-span ex) 4))))]
|
|
[equiv equiv])
|
|
#'(defproc (name [v contract]) any/c
|
|
"Returns " (to-element 'equiv) (mz-examples example)))))]))
|
|
|
|
|
|
@title[#:tag "pairs"]{Pairs and Lists}
|
|
|
|
@guideintro["pairs"]{pairs and lists}
|
|
|
|
A @deftech{pair} combines exactly two values. The first value is
|
|
accessed with the @racket[car] procedure, and the second value is
|
|
accessed with the @racket[cdr] procedure. Pairs are not mutable (but
|
|
see @secref["mpairs"]).
|
|
|
|
A @deftech{list} is recursively defined: it is either the constant
|
|
@racket[null], or it is a pair whose second value is a list.
|
|
|
|
A list can be used as a single-valued sequence (see
|
|
@secref["sequences"]). The elements of the list serve as elements
|
|
of the sequence. See also @racket[in-list].
|
|
|
|
Cyclic data structures can be created using only immutable pairs via
|
|
@racket[read] or @racket[make-reader-graph]. If starting with a pair
|
|
and using some number of @racket[cdr]s returns to the starting pair,
|
|
then the pair is not a list.
|
|
|
|
@; ----------------------------------------
|
|
@section{Pair Constructors and Selectors}
|
|
|
|
@defproc[(pair? [v any/c]) boolean?]{Returns @racket[#t] if @racket[v] is
|
|
a pair, @racket[#f] otherwise.
|
|
@mz-examples[
|
|
(pair? 1)
|
|
(pair? (cons 1 2))
|
|
(pair? (list 1 2))
|
|
(pair? '(1 2))
|
|
(pair? '())
|
|
]}
|
|
|
|
@defproc[(null? [v any/c]) boolean?]{Returns @racket[#t] if @racket[v] is
|
|
the empty list, @racket[#f] otherwise.
|
|
@mz-examples[
|
|
(null? 1)
|
|
(null? '(1 2))
|
|
(null? '())
|
|
(null? (cdr (list 1)))
|
|
]}
|
|
|
|
@defproc[(cons [a any/c] [d any/c]) pair?]{Returns a newly allocated pair whose first
|
|
element is @racket[a] and second element is @racket[d].
|
|
@mz-examples[
|
|
(cons 1 2)
|
|
(cons 1 '())
|
|
]}
|
|
|
|
@defproc[(car [p pair?]) any/c]{Returns the first element of the
|
|
pair @racket[p].
|
|
@mz-examples[
|
|
(car '(1 2))
|
|
(car (cons 2 3))
|
|
]}
|
|
|
|
@defproc[(cdr [p pair?]) any/c]{Returns the second element of the
|
|
pair @racket[p].
|
|
@mz-examples[
|
|
(cdr '(1 2))
|
|
(cdr '(1))
|
|
]}
|
|
|
|
@defthing[null null?]{The empty list.
|
|
@mz-examples[
|
|
null
|
|
'()
|
|
(eq? '() null)
|
|
]}
|
|
|
|
|
|
@defproc[(list? [v any/c]) boolean?]{Returns @racket[#t] if @racket[v]
|
|
is a list: either the empty list, or a pair whose second element is a
|
|
list. This procedure effectively takes constant time due to internal caching
|
|
(so that any necessary traversals of pairs can in principle count as an
|
|
extra cost of allocating the pairs).
|
|
|
|
@mz-examples[
|
|
(list? '(1 2))
|
|
(list? (cons 1 (cons 2 '())))
|
|
(list? (cons 1 2))
|
|
]}
|
|
|
|
@defproc[(list [v any/c] ...) list?]{Returns a newly allocated list
|
|
containing the @racket[v]s as its elements.
|
|
@mz-examples[
|
|
(list 1 2 3 4)
|
|
(list (list 1 2) (list 3 4))
|
|
]}
|
|
|
|
@defproc[(list* [v any/c] ... [tail any/c]) any/c]{
|
|
|
|
Like @racket[list], but the last argument is used as the tail of
|
|
the result, instead of the final element. The result is a list
|
|
only if the last argument is a list.
|
|
@mz-examples[
|
|
(list* 1 2)
|
|
(list* 1 2 (list 3 4))
|
|
]}
|
|
|
|
@defproc[(build-list [n exact-nonnegative-integer?]
|
|
[proc (exact-nonnegative-integer? . -> . any)])
|
|
list?]{
|
|
|
|
Creates a list of @racket[n] elements by applying @racket[proc] to the
|
|
integers from @racket[0] to @racket[(sub1 n)] in order. If
|
|
@racket[_lst] is the resulting list, then @racket[(list-ref _lst _i)]
|
|
is the value produced by @racket[(proc _i)].
|
|
|
|
@mz-examples[
|
|
(build-list 10 values)
|
|
(build-list 5 (lambda (x) (* x x)))
|
|
]}
|
|
|
|
@; ----------------------------------------
|
|
@section{List Operations}
|
|
|
|
@defproc[(length [lst list?])
|
|
exact-nonnegative-integer?]{
|
|
|
|
Returns the number of elements in @racket[lst].
|
|
@mz-examples[
|
|
(length (list 1 2 3 4))
|
|
(length '())
|
|
]}
|
|
|
|
|
|
@defproc[(list-ref [lst any/c] [pos exact-nonnegative-integer?])
|
|
any/c]{
|
|
|
|
Returns the element of @racket[lst] at position @racket[pos], where
|
|
the list's first element is position @racket[0]. If the list has
|
|
@racket[pos] or fewer elements, then the
|
|
@exnraise[exn:fail:contract].
|
|
|
|
The @racket[lst] argument need not actually be a list; @racket[lst]
|
|
must merely start with a chain of at least @racket[(add1 pos)] pairs.
|
|
|
|
@mz-examples[
|
|
(list-ref (list 'a 'b 'c) 0)
|
|
(list-ref (list 'a 'b 'c) 1)
|
|
(list-ref (list 'a 'b 'c) 2)
|
|
(list-ref (cons 1 2) 0)
|
|
]}
|
|
|
|
|
|
@defproc[(list-tail [lst any/c] [pos exact-nonnegative-integer?])
|
|
any/c]{
|
|
|
|
Returns the list after the first @racket[pos] elements of
|
|
@racket[lst]. If the list has fewer than @racket[pos] elements, then
|
|
the @exnraise[exn:fail:contract].
|
|
|
|
The @racket[lst] argument need not actually be a list; @racket[lst]
|
|
must merely start with a chain of at least @racket[pos] pairs.
|
|
@mz-examples[
|
|
(list-tail (list 1 2 3 4) 2)
|
|
(list-ref (cons 1 2) 1)
|
|
(list-ref 'not-a-pair 0)
|
|
]}
|
|
|
|
|
|
@defproc*[([(append [lst list?] ...) list?]
|
|
[(append [lst list?] ... [v any/c]) any/c])]{
|
|
|
|
When given all list arguments, the result is a list that contains all
|
|
of the elements of the given lists in order. The last argument is used
|
|
directly in the tail of the result.
|
|
|
|
The last argument need not be a list, in which case the result is an
|
|
``improper list.''
|
|
|
|
@mz-examples[
|
|
(append (list 1 2) (list 3 4))
|
|
(append (list 1 2) (list 3 4) (list 5 6) (list 7 8))
|
|
]}
|
|
|
|
@defproc[(reverse [lst list?]) list?]{
|
|
|
|
Returns a list that has the same elements as @racket[lst], but in
|
|
reverse order.
|
|
|
|
@mz-examples[
|
|
(reverse (list 1 2 3 4))
|
|
]}
|
|
|
|
|
|
@; ----------------------------------------
|
|
@section{List Iteration}
|
|
|
|
@defproc[(map [proc procedure?] [lst list?] ...+)
|
|
list?]{
|
|
|
|
Applies @racket[proc] to the elements of the @racket[lst]s from the
|
|
first elements to the last. The @racket[proc] argument must accept
|
|
the same number of arguments as the number of supplied @racket[lst]s,
|
|
and all @racket[lst]s must have the same number of elements. The
|
|
result is a list containing each result of @racket[proc] in order.
|
|
|
|
@mz-examples[
|
|
(map (lambda (number)
|
|
(+ 1 number))
|
|
'(1 2 3 4))
|
|
(map (lambda (number1 number2)
|
|
(+ number1 number2))
|
|
'(1 2 3 4)
|
|
'(10 100 1000 10000))
|
|
]}
|
|
|
|
@defproc[(andmap [proc procedure?] [lst list?] ...+)
|
|
any]{
|
|
|
|
Similar to @racket[map], except that
|
|
|
|
@itemize[
|
|
|
|
@item{the result is @racket[#f] if any application of @racket[proc] produces
|
|
@racket[#f], in which case @racket[proc] is not applied to later
|
|
elements of the @racket[lst]s; and}
|
|
|
|
@item{the result is that of @racket[proc] applied to the last elements
|
|
of the @racket[lst]s; more specifically, the application of
|
|
@racket[proc] to the last elements in the @racket[lst]s is in tail
|
|
position with respect to the @racket[andmap] call.}
|
|
|
|
]
|
|
|
|
If the @racket[lst]s are empty, then @racket[#t] is returned.}
|
|
|
|
@mz-examples[
|
|
(andmap positive? '(1 2 3))
|
|
(andmap positive? '(1 2 a))
|
|
(andmap positive? '(1 -2 a))
|
|
(andmap + '(1 2 3) '(4 5 6))
|
|
]
|
|
|
|
|
|
@defproc[(ormap [proc procedure?] [lst list?] ...+)
|
|
any]{
|
|
|
|
Similar to @racket[map], except that
|
|
|
|
@itemize[
|
|
|
|
@item{the result is @racket[#f] if every application of @racket[proc] produces
|
|
@racket[#f]; and}
|
|
|
|
@item{the result is that of the first application of @racket[proc] producing a
|
|
value other than @racket[#f], in which case @racket[proc] is not
|
|
applied to later elements of the @racket[lst]s;
|
|
the application of @racket[proc] to the last elements of the
|
|
@racket[lst]s is in tail position with respect to the
|
|
@racket[ormap] call.}
|
|
|
|
]
|
|
|
|
If the @racket[lst]s are empty, then @racket[#f] is returned.}
|
|
|
|
@mz-examples[
|
|
(ormap eq? '(a b c) '(a b c))
|
|
(ormap positive? '(1 2 a))
|
|
(ormap + '(1 2 3) '(4 5 6))
|
|
]
|
|
|
|
|
|
@defproc[(for-each [proc procedure?] [lst list?] ...+)
|
|
void?]{
|
|
|
|
Similar to @racket[map], but @racket[proc] is called only for its
|
|
effect, and its result (which can be any number of values) is
|
|
ignored.
|
|
|
|
@mz-examples[
|
|
(for-each (lambda (arg)
|
|
(printf "Got ~a\n" arg)
|
|
23)
|
|
'(1 2 3 4))
|
|
]}
|
|
|
|
|
|
@defproc[(foldl [proc procedure?] [init any/c] [lst list?] ...+)
|
|
any/c]{
|
|
|
|
Like @racket[map], @racket[foldl] applies a procedure to the
|
|
elements of one or more lists. Whereas @racket[map] combines the return
|
|
values into a list, @racket[foldl] combines the return values in an
|
|
arbitrary way that is determined by @racket[proc].
|
|
|
|
If @racket[foldl] is called with @math{n} lists, then @racket[proc]
|
|
must take @math{n+1} arguments. The extra argument is the combined
|
|
return values so far. The @racket[proc] is initially invoked with the
|
|
first item of each list, and the final argument is @racket[init]. In
|
|
subsequent invocations of @racket[proc], the last argument is the
|
|
return value from the previous invocation of @racket[proc]. The input
|
|
@racket[lst]s are traversed from left to right, and the result of the
|
|
whole @racket[foldl] application is the result of the last
|
|
application of @racket[proc]. If the @racket[lst]s are empty, the
|
|
result is @racket[init].
|
|
|
|
Unlike @racket[foldr], @racket[foldl] processes the @racket[lst]s in
|
|
constant space (plus the space for each call to @racket[proc]).
|
|
|
|
@mz-examples[
|
|
(foldl cons '() '(1 2 3 4))
|
|
(foldl + 0 '(1 2 3 4))
|
|
(foldl (lambda (a b result)
|
|
(* result (- a b)))
|
|
1
|
|
'(1 2 3)
|
|
'(4 5 6))
|
|
]}
|
|
|
|
@defproc[(foldr [proc procedure?] [init any/c] [lst list?] ...+)
|
|
any/c]{
|
|
|
|
Like @racket[foldl], but the lists are traversed from right to left.
|
|
Unlike @racket[foldl], @racket[foldr] processes the @racket[lst]s in
|
|
space proportional to the length of @racket[lst]s (plus the space for
|
|
each call to @racket[proc]).
|
|
|
|
@mz-examples[
|
|
(foldr cons '() '(1 2 3 4))
|
|
(foldr (lambda (v l) (cons (add1 v) l)) '() '(1 2 3 4))
|
|
]}
|
|
|
|
@; ----------------------------------------
|
|
@section{List Filtering}
|
|
|
|
@defproc[(filter [pred procedure?] [lst list?])
|
|
list?]{
|
|
|
|
Returns a list with the elements of @racket[lst] for which
|
|
@racket[pred] produces a true value. The @racket[pred] procedure is
|
|
applied to each element from first to last.
|
|
|
|
@mz-examples[
|
|
(filter positive? '(1 -2 3 4 -5))
|
|
]}
|
|
|
|
|
|
@defproc[(remove [v any/c] [lst list?] [proc procedure? equal?])
|
|
list?]{
|
|
|
|
Returns a list that is like @racket[lst], omitting the first element
|
|
of @racket[lst] that is equal to @racket[v] using the comparison
|
|
procedure @racket[proc] (which must accept two arguments).
|
|
|
|
@mz-examples[
|
|
(remove 2 (list 1 2 3 2 4))
|
|
(remove 2 (list 1 2 3 2 4) =)
|
|
(remove '(2) (list '(1) '(2) '(3)))
|
|
(remove "2" (list "1" "2" "3"))
|
|
(remove #\c (list #\a #\b #\c))
|
|
]}
|
|
|
|
|
|
@defproc[(remq [v any/c] [lst list?])
|
|
list?]{
|
|
|
|
Returns @racket[(remove v lst eq?)].
|
|
@mz-examples[
|
|
(remq 2 (list 1 2 3 4 5))
|
|
(remq '(2) (list '(1) '(2) '(3)))
|
|
(remq "2" (list "1" "2" "3"))
|
|
(remq #\c (list #\a #\b #\c))
|
|
]}
|
|
|
|
|
|
@defproc[(remv [v any/c] [lst list?])
|
|
list?]{
|
|
|
|
Returns @racket[(remove v lst eqv?)].
|
|
@mz-examples[
|
|
(remv 2 (list 1 2 3 4 5))
|
|
(remv '(2) (list '(1) '(2) '(3)))
|
|
(remv "2" (list "1" "2" "3"))
|
|
(remv #\c (list #\a #\b #\c))
|
|
]}
|
|
|
|
|
|
@defproc[(remove* [v-lst list?] [lst list?] [proc procedure? equal?])
|
|
list?]{
|
|
|
|
Like @racket[remove], but removes from @racket[lst] every instance of
|
|
every element of @racket[v-lst].
|
|
@mz-examples[
|
|
(remove* (list 1 2) (list 1 2 3 2 4 5 2))
|
|
]}
|
|
|
|
|
|
@defproc[(remq* [v-lst list?] [lst list?])
|
|
list?]{
|
|
|
|
Returns @racket[(remove* v-lst lst eq?)].
|
|
|
|
@mz-examples[
|
|
(remq* (list 1 2) (list 1 2 3 2 4 5 2))
|
|
]}
|
|
|
|
|
|
@defproc[(remv* [v-lst list?] [lst list?])
|
|
list?]{
|
|
|
|
Returns @racket[(remove* v-lst lst eqv?)].
|
|
@mz-examples[
|
|
(remv* (list 1 2) (list 1 2 3 2 4 5 2))
|
|
]}
|
|
|
|
|
|
@defproc[(sort [lst list?] [less-than? (any/c any/c . -> . any/c)]
|
|
[#:key extract-key (any/c . -> . any/c) (lambda (x) x)]
|
|
[#:cache-keys? cache-keys? boolean? #f])
|
|
list?]{
|
|
|
|
Returns a list sorted according to the @racket[less-than?] procedure,
|
|
which takes two elements of @racket[lst] and returns a true value if
|
|
the first is less (i.e., should be sorted earlier) than the
|
|
second.
|
|
|
|
The sort is stable; if two elements of @racket[lst] are ``equal''
|
|
(i.e., @racket[proc] does not return a true value when given the pair
|
|
in either order), then the elements preserve their relative order
|
|
from @racket[lst] in the output list. To preserve this guarantee,
|
|
use @racket[sort] with a strict comparison functions (e.g.,
|
|
@racket[<] or @racket[string<?]; not @racket[<=] or
|
|
@racket[string<=?]).
|
|
|
|
The @racket[#:key] argument @racket[extract-key] is used to extract a
|
|
key value for comparison from each list element. That is, the full
|
|
comparison procedure is essentially
|
|
|
|
@racketblock[
|
|
(lambda (x y)
|
|
(less-than? (extract-key x) (extract-key y)))
|
|
]
|
|
|
|
By default, @racket[extract-key] is applied to two list elements for
|
|
every comparison, but if @racket[cache-keys?] is true, then the
|
|
@racket[extract-key] function is used exactly once for each list
|
|
item. Supply a true value for @racket[cache-keys?] when
|
|
@racket[extract-key] is an expensive operation; for example, if
|
|
@racket[file-or-directory-modify-seconds] is used to extract a
|
|
timestamp for every file in a list, then @racket[cache-keys?] should
|
|
be @racket[#t] to minimize file-system calls, but if
|
|
@racket[extract-key] is @racket[car], then @racket[cache-keys?]
|
|
should be @racket[#f]. As another example, providing
|
|
@racket[extract-key] as @racket[(lambda (x) (random))] and
|
|
@racket[#t] for @racket[cache-keys?] effectively shuffles the list.}
|
|
|
|
@mz-examples[
|
|
(sort '(1 3 4 2) <)
|
|
(sort '("aardvark" "dingo" "cow" "bear") string<?)
|
|
(sort '(("aardvark") ("dingo") ("cow") ("bear"))
|
|
#:key car string<?)
|
|
]
|
|
|
|
@; ----------------------------------------
|
|
@section{List Searching}
|
|
|
|
@defproc[(member [v any/c] [lst list?])
|
|
(or/c list? #f)]{
|
|
|
|
Locates the first element of @racket[lst] that is @racket[equal?] to
|
|
@racket[v]. If such an element exists, the tail of @racket[lst]
|
|
starting with that element is returned. Otherwise, the result is
|
|
@racket[#f].
|
|
|
|
@mz-examples[
|
|
(member 2 (list 1 2 3 4))
|
|
(member 9 (list 1 2 3 4))
|
|
]}
|
|
|
|
|
|
@defproc[(memv [v any/c] [lst list?])
|
|
(or/c list? #f)]{
|
|
|
|
Like @racket[member], but finds an element using @racket[eqv?].
|
|
@mz-examples[
|
|
(memv 2 (list 1 2 3 4))
|
|
(memv 9 (list 1 2 3 4))
|
|
]}
|
|
|
|
|
|
@defproc[(memq [v any/c] [lst list?])
|
|
(or/c list? #f)]{
|
|
|
|
Like @racket[member], but finds an element using @racket[eq?].
|
|
|
|
@mz-examples[
|
|
(memq 2 (list 1 2 3 4))
|
|
(memq 9 (list 1 2 3 4))
|
|
]}
|
|
|
|
|
|
@defproc[(memf [proc procedure?] [lst list?])
|
|
(or/c list? #f)]{
|
|
|
|
Like @racket[member], but finds an element using the predicate
|
|
@racket[proc]; an element is found when @racket[proc] applied to the
|
|
element returns a true value.
|
|
|
|
@mz-examples[
|
|
(memf (lambda (arg)
|
|
(> arg 9))
|
|
'(7 8 9 10 11))
|
|
]}
|
|
|
|
|
|
@defproc[(findf [proc procedure?] [lst list?]) any/c]{
|
|
|
|
Like @racket[memf], but returns the element or @racket[#f]
|
|
instead of a tail of @racket[lst] or @racket[#f].
|
|
@mz-examples[
|
|
(findf (lambda (arg)
|
|
(> arg 9))
|
|
'(7 8 9 10 11))
|
|
]}
|
|
|
|
|
|
@defproc[(assoc [v any/c]
|
|
[lst (listof pair?)]
|
|
[is-equal? (any/c any/c -> any/c) equal?])
|
|
(or/c pair? #f)]{
|
|
|
|
Locates the first element of @racket[lst] whose @racket[car] is
|
|
equal to @racket[v] according to @racket[is-equal?]. If such an element exists, the pair
|
|
(i.e., an element of @racket[lst]) is returned. Otherwise, the result
|
|
is @racket[#f].
|
|
@mz-examples[
|
|
(assoc 3 (list (list 1 2) (list 3 4) (list 5 6)))
|
|
(assoc 9 (list (list 1 2) (list 3 4) (list 5 6)))
|
|
(assoc 3.5
|
|
(list (list 1 2) (list 3 4) (list 5 6))
|
|
(lambda (a b) (< (abs (- a b)) 1)))
|
|
]}
|
|
|
|
|
|
@defproc[(assv [v any/c] [lst (listof pair?)])
|
|
(or/c pair? #f)]{
|
|
|
|
Like @racket[assoc], but finds an element using @racket[eqv?].
|
|
@mz-examples[
|
|
(assv 3 (list (list 1 2) (list 3 4) (list 5 6)))
|
|
]}
|
|
|
|
|
|
@defproc[(assq [v any/c] [lst (listof pair?)])
|
|
(or/c pair? #f)]{
|
|
|
|
Like @racket[assoc], but finds an element using @racket[eq?].
|
|
@mz-examples[
|
|
(assq 3 (list (list 1 2) (list 3 4) (list 5 6)))
|
|
]}
|
|
|
|
|
|
@defproc[(assf [proc procedure?] [lst list?])
|
|
(or/c list? #f)]{
|
|
|
|
Like @racket[assoc], but finds an element using the predicate
|
|
@racket[proc]; an element is found when @racket[proc] applied to the
|
|
@racket[car] of an @racket[lst] element returns a true value.
|
|
@mz-examples[
|
|
(assf (lambda (arg)
|
|
(> arg 2))
|
|
(list (list 1 2) (list 3 4) (list 5 6)))
|
|
]}
|
|
|
|
|
|
|
|
@; ----------------------------------------
|
|
@section{Pair Accessor Shorthands}
|
|
|
|
@defc_r[a a '((1 2) 3 4)]
|
|
@defc_r[a d '((1 2) 3 4)]
|
|
@defc_r[d a '((7 6 5 4 3 2 1) 8 9)]
|
|
@defc_r[d d '(2 1)]
|
|
@defc_r[a a a '(((6 5 4 3 2 1) 7) 8 9)]
|
|
@defc_r[a a d '(9 (7 6 5 4 3 2 1) 8)]
|
|
@defc_r[a d a '((7 6 5 4 3 2 1) 8 9)]
|
|
@defc_r[a d d '(3 2 1)]
|
|
@defc_r[d a a '(((6 5 4 3 2 1) 7) 8 9)]
|
|
@defc_r[d a d '(9 (7 6 5 4 3 2 1) 8)]
|
|
@defc_r[d d a '((7 6 5 4 3 2 1) 8 9)]
|
|
@defc_r[d d d '(3 2 1)]
|
|
@defc_r[a a a a '((((5 4 3 2 1) 6) 7) 8 9)]
|
|
@defc_r[a a a d '(9 ((6 5 4 3 2 1) 7) 8)]
|
|
@defc_r[a a d a '((7 (5 4 3 2 1) 6) 8 9)]
|
|
@defc_r[a a d d '(9 8 (6 5 4 3 2 1) 7)]
|
|
@defc_r[a d a a '(((6 5 4 3 2 1) 7) 8 9)]
|
|
@defc_r[a d a d '(9 (7 6 5 4 3 2 1) 8)]
|
|
@defc_r[a d d a '((7 6 5 4 3 2 1) 8 9)]
|
|
@defc_r[a d d d '(4 3 2 1)]
|
|
@defc_r[d a a a '((((5 4 3 2 1) 6) 7) 8 9)]
|
|
@defc_r[d a a d '(9 ((6 5 4 3 2 1) 7) 8)]
|
|
@defc_r[d a d a '((7 (5 4 3 2 1) 6) 8 9)]
|
|
@defc_r[d a d d '(9 8 (6 5 4 3 2 1) 7)]
|
|
@defc_r[d d a a '(((6 5 4 3 2 1) 7) 8 9)]
|
|
@defc_r[d d a d '(9 (7 6 5 4 3 2 1) 8)]
|
|
@defc_r[d d d a '((7 6 5 4 3 2 1) 8 9)]
|
|
@defc_r[d d d d '(4 3 2 1)]
|
|
|
|
@; ----------------------------------------
|
|
@section{Additional List Functions and Synonyms}
|
|
|
|
@note-lib[racket/list]
|
|
@(define list-eval (make-base-eval))
|
|
@(interaction-eval #:eval list-eval
|
|
(require racket/list (only-in racket/function negate)))
|
|
|
|
@defthing[empty null?]{
|
|
The empty list.
|
|
@mz-examples[#:eval list-eval
|
|
empty
|
|
(eq? empty null)
|
|
]}
|
|
|
|
@defproc[(cons? [v any/c]) boolean?]{
|
|
The same as @racket[(pair? v)].
|
|
@mz-examples[#:eval list-eval
|
|
(cons? '(1 2))
|
|
]}
|
|
|
|
@defproc[(empty? [v any/c]) boolean?]{
|
|
The same as @racket[(null? v)].
|
|
@mz-examples[#:eval list-eval
|
|
(empty? '(1 2))
|
|
(empty? '())
|
|
]}
|
|
|
|
@defproc[(first [lst list?]) any/c]{
|
|
The same as @racket[(car lst)], but only for lists (that are not empty).
|
|
@mz-examples[#:eval list-eval
|
|
(first '(1 2 3 4 5 6 7 8 9 10))
|
|
]}
|
|
|
|
@defproc[(rest [lst list?]) list?]{
|
|
The same as @racket[(cdr lst)], but only for lists (that are not empty).
|
|
|
|
@mz-examples[#:eval list-eval
|
|
(rest '(1 2 3 4 5 6 7 8 9 10))
|
|
]}
|
|
|
|
@defproc[(second [lst list?]) any]{Returns the second element of the list.
|
|
@mz-examples[#:eval list-eval
|
|
(second '(1 2 3 4 5 6 7 8 9 10))
|
|
]}
|
|
|
|
@defproc[(third [lst list?]) any]{Returns the third element of the list.
|
|
@mz-examples[#:eval list-eval
|
|
(third '(1 2 3 4 5 6 7 8 9 10))
|
|
]}
|
|
|
|
@defproc[(fourth [lst list?]) any]{Returns the fourth element of the list.
|
|
@mz-examples[#:eval list-eval
|
|
(fourth '(1 2 3 4 5 6 7 8 9 10))
|
|
]}
|
|
|
|
@defproc[(fifth [lst list?]) any]{Returns the fifth element of the list.
|
|
@mz-examples[#:eval list-eval
|
|
(fifth '(1 2 3 4 5 6 7 8 9 10))
|
|
]}
|
|
|
|
@defproc[(sixth [lst list?]) any]{Returns the sixth element of the list.
|
|
@mz-examples[#:eval list-eval
|
|
(sixth '(1 2 3 4 5 6 7 8 9 10))
|
|
]}
|
|
|
|
@defproc[(seventh [lst list?]) any]{Returns the seventh element of the list.
|
|
@mz-examples[#:eval list-eval
|
|
(seventh '(1 2 3 4 5 6 7 8 9 10))
|
|
]}
|
|
|
|
@defproc[(eighth [lst list?]) any]{Returns the eighth element of the list.
|
|
@mz-examples[#:eval list-eval
|
|
(eighth '(1 2 3 4 5 6 7 8 9 10))
|
|
]}
|
|
|
|
@defproc[(ninth [lst list?]) any]{Returns the ninth element of the list.
|
|
@mz-examples[#:eval list-eval
|
|
(ninth '(1 2 3 4 5 6 7 8 9 10))
|
|
]}
|
|
|
|
@defproc[(tenth [lst list?]) any]{Returns the tenth element of the list.
|
|
@mz-examples[#:eval list-eval
|
|
(tenth '(1 2 3 4 5 6 7 8 9 10))
|
|
]}
|
|
|
|
@defproc[(last [lst list?]) any]{Returns the last element of the list.
|
|
@mz-examples[#:eval list-eval
|
|
(last '(1 2 3 4 5 6 7 8 9 10))
|
|
]}
|
|
|
|
@defproc[(last-pair [p pair?]) pair?]{
|
|
Returns the last pair of a (possibly improper) list.
|
|
@mz-examples[#:eval list-eval
|
|
(last-pair '(1 2 3 4))
|
|
]}
|
|
|
|
@defproc[(make-list [k exact-nonnegative-integer?] [v any?]) list?]{
|
|
Returns a newly constructed list of length @racket[k], holding
|
|
@racket[v] in all positions.
|
|
|
|
@mz-examples[#:eval list-eval
|
|
(make-list 7 'foo)]}
|
|
|
|
@defproc[(take [lst any/c] [pos exact-nonnegative-integer?]) list?]{
|
|
Returns a fresh list whose elements are the first @racket[pos] elements of
|
|
@racket[lst]. If @racket[lst] has fewer than
|
|
@racket[pos] elements, the @exnraise[exn:fail:contract].
|
|
|
|
The @racket[lst] argument need not actually be a list; @racket[lst]
|
|
must merely start with a chain of at least @racket[pos] pairs.
|
|
|
|
@mz-examples[#:eval list-eval
|
|
(take '(1 2 3 4) 2)
|
|
(take 'non-list 0)
|
|
]}
|
|
|
|
@defproc[(drop [lst any/c] [pos exact-nonnegative-integer?]) any/c]{
|
|
Just like @racket[list-tail].}
|
|
|
|
@defproc[(split-at [lst any/c] [pos exact-nonnegative-integer?])
|
|
(values list? any/c)]{
|
|
Returns the same result as
|
|
|
|
@racketblock[(values (take lst pos) (drop lst pos))]
|
|
|
|
except that it can be faster.}
|
|
|
|
@defproc[(take-right [lst any/c] [pos exact-nonnegative-integer?]) any/c]{
|
|
Returns the @racket[list]'s @racket[pos]-length tail. If @racket[lst]
|
|
has fewer than @racket[pos] elements, then the
|
|
@exnraise[exn:fail:contract].
|
|
|
|
The @racket[lst] argument need not actually be a list; @racket[lst]
|
|
must merely end with a chain of at least @racket[pos] pairs.
|
|
|
|
@mz-examples[#:eval list-eval
|
|
(take-right '(1 2 3 4) 2)
|
|
(take-right 'non-list 0)
|
|
]}
|
|
|
|
@defproc[(drop-right [lst any/c] [pos exact-nonnegative-integer?]) list?]{
|
|
Returns a fresh list whose elements are the prefix of @racket[lst],
|
|
dropping its @racket[pos]-length tail. If @racket[lst] has fewer than
|
|
@racket[pos] elements, then the @exnraise[exn:fail:contract].
|
|
|
|
The @racket[lst] argument need not actually be a list; @racket[lst]
|
|
must merely end with a chain of at least @racket[pos] pairs.
|
|
|
|
@mz-examples[#:eval list-eval
|
|
(drop-right '(1 2 3 4) 2)
|
|
(drop-right 'non-list 0)
|
|
]}
|
|
|
|
@defproc[(split-at-right [lst any/c] [pos exact-nonnegative-integer?])
|
|
(values list? any/c)]{
|
|
Returns the same result as
|
|
|
|
@racketblock[(values (drop-right lst pos) (take-right lst pos))]
|
|
|
|
except that it can be faster.
|
|
|
|
@mz-examples[#:eval list-eval
|
|
(split-at-right '(1 2 3 4 5 6) 3)
|
|
(split-at-right '(1 2 3 4 5 6) 4)
|
|
]}
|
|
|
|
@defproc[(add-between [lst list?] [v any/c]) list?]{
|
|
|
|
Returns a list with the same elements as @racket[lst], but with
|
|
@racket[v] between each pair of items in @racket[lst].
|
|
|
|
@mz-examples[#:eval list-eval
|
|
(add-between '(x y z) 'or)
|
|
(add-between '(x) 'or)
|
|
]}
|
|
|
|
@defproc*[([(append* [lst list?] ... [lsts (listof list?)]) list?]
|
|
[(append* [lst list?] ... [lsts list?]) any/c])]{
|
|
@; Note: this is exactly the same description as the one for string-append*
|
|
|
|
Like @racket[append], but the last argument is used as a list of
|
|
arguments for @racket[append], so @racket[(append* lst ... lsts)] is the
|
|
same as @racket[(apply append lst ... lsts)]. In other words, the
|
|
relationship between @racket[append] and @racket[append*] is similar
|
|
to the one between @racket[list] and @racket[list*].
|
|
|
|
@mz-examples[#:eval list-eval
|
|
(append* '(a) '(b) '((c) (d)))
|
|
(cdr (append* (map (lambda (x) (list ", " x))
|
|
'("Alpha" "Beta" "Gamma"))))
|
|
]}
|
|
|
|
@defproc[(flatten [v any/c])
|
|
list?]{
|
|
|
|
Flattens an arbitrary S-expression structure of pairs into a
|
|
list. More precisely, @racket[v] is treated as a binary tree where
|
|
pairs are interior nodes, and the resulting list contains all of the
|
|
non-@racket[null] leaves of the tree in the same order as an inorder
|
|
traversal.
|
|
|
|
@mz-examples[#:eval list-eval
|
|
(flatten '((a) b (c (d) . e) ()))
|
|
(flatten 'a)
|
|
]}
|
|
|
|
@defproc[(remove-duplicates [lst list?]
|
|
[same? (any/c any/c . -> . any/c) equal?]
|
|
[#:key extract-key (any/c . -> . any/c)
|
|
(lambda (x) x)])
|
|
list?]{
|
|
|
|
Returns a list that has all items in @racket[lst], but without
|
|
duplicate items, where @racket[same?] determines whether two elements
|
|
of the list are equivalent. The resulting list is in the same order
|
|
as @racket[lst], and for any item that occurs multiple times, the
|
|
first one is kept.
|
|
|
|
The @racket[#:key] argument @racket[extract-key] is used to extract a
|
|
key value from each list element, so two items are considered equal if
|
|
@racket[(same? (extract-key x) (extract-key y))] is true.
|
|
|
|
@mz-examples[#:eval list-eval
|
|
(remove-duplicates '(a b b a))
|
|
(remove-duplicates '(1 2 1.0 0))
|
|
(remove-duplicates '(1 2 1.0 0) =)
|
|
]}
|
|
|
|
@defproc[(filter-map [proc procedure?] [lst list?] ...+)
|
|
list?]{
|
|
|
|
Returns @racket[(filter (lambda (x) x) (map proc lst ...))], but
|
|
without building the intermediate list.
|
|
|
|
@mz-examples[#:eval list-eval
|
|
(filter-map (lambda (x) (and (positive? x) x)) '(1 2 3 -2 8))
|
|
]}
|
|
|
|
@defproc[(count [proc procedure?] [lst list?] ...+)
|
|
exact-nonnegative-integer?]{
|
|
|
|
Returns @racket[(length (filter proc lst ...))], but without building
|
|
the intermediate list.
|
|
|
|
@mz-examples[#:eval list-eval
|
|
(count positive? '(1 -1 2 3 -2 5))
|
|
]}
|
|
|
|
|
|
@defproc[(partition [pred procedure?] [lst list?])
|
|
(values list? list?)]{
|
|
|
|
Similar to @racket[filter], except that two values are returned: the
|
|
items for which @racket[pred] returns a true value, and the items for
|
|
which @racket[pred] returns @racket[#f].
|
|
|
|
The result is the same as
|
|
|
|
@racketblock[(values (filter pred lst) (filter (negate pred) lst))]
|
|
|
|
but @racket[pred] is applied to each item in @racket[lst] only once.
|
|
|
|
@mz-examples[#:eval list-eval
|
|
(partition even? '(1 2 3 4 5 6))
|
|
]}
|
|
|
|
|
|
@defproc[(append-map [proc procedure?] [lst list?] ...+)
|
|
list?]{
|
|
|
|
Returns @racket[(append* (map proc lst ...))].
|
|
|
|
@mz-examples[#:eval list-eval
|
|
(append-map vector->list '(#(1) #(2 3) #(4)))
|
|
]}
|
|
|
|
|
|
@defproc[(filter-not [pred (any/c . -> . any/c)] [lst list?])
|
|
list?]{
|
|
|
|
Like @racket[filter], but the meaning of the @racket[pred] predicate
|
|
is reversed: the result is a list of all items for which @racket[pred]
|
|
returns @racket[#f].
|
|
|
|
@mz-examples[#:eval list-eval
|
|
(filter-not even? '(1 2 3 4 5 6))
|
|
]}
|
|
|
|
|
|
@defproc[(shuffle [lst list?]) list?]{
|
|
|
|
Returns a list with all elements from @racket[lst], randomly shuffled.
|
|
|
|
@mz-examples[#:eval list-eval
|
|
(shuffle '(1 2 3 4 5 6))
|
|
]}
|
|
|
|
|
|
@defproc[(argmin [proc (-> any/c real?)] [lst (and/c pair? list?)]) any/c]{
|
|
|
|
Returns the first element in the list @racket[lst] that minimizes
|
|
the result of @racket[proc]. Signals an error on an empty list.
|
|
|
|
@mz-examples[#:eval list-eval
|
|
(argmin car '((3 pears) (1 banana) (2 apples)))
|
|
(argmin car '((1 banana) (1 orange)))
|
|
]}
|
|
|
|
@defproc[(argmax [proc (-> any/c real?)] [lst (and/c pair? list?)]) any/c]{
|
|
|
|
Returns the first element in the list @racket[lst] that maximizes
|
|
the result of @racket[proc]. Signals an error on an empty list.
|
|
|
|
@mz-examples[#:eval list-eval
|
|
(argmax car '((3 pears) (1 banana) (2 apples)))
|
|
(argmax car '((3 pears) (3 oranges)))
|
|
]}
|
|
|
|
@close-eval[list-eval]
|
|
|
|
@; ----------------------------------------
|
|
@section{Immutable Cyclic Data}
|
|
|
|
@defproc[(make-reader-graph [v any/c]) any/c]{
|
|
|
|
Returns a value like @racket[v], with placeholders created by
|
|
@racket[make-placeholder] replaced with the values that they contain,
|
|
and with placeholders created by @racket[make-hash-placeholder]
|
|
with an immutable hash table. No part of @racket[v] is mutated;
|
|
instead, parts of @racket[v] are copied as necessary to construct
|
|
the resulting graph, where at most one copy is created for any given
|
|
value.
|
|
|
|
Since the copied values can be immutable, and since the copy is also
|
|
immutable, @racket[make-reader-graph] can create cycles involving only
|
|
immutable pairs, vectors, boxes, and hash tables.
|
|
|
|
Only the following kinds of values are copied and traversed to detect
|
|
placeholders:
|
|
|
|
@itemize[
|
|
|
|
@item{pairs}
|
|
|
|
@item{vectors, both mutable and immutable}
|
|
|
|
@item{boxes, both mutable and immutable}
|
|
|
|
@item{hash tables, both mutable and immutable}
|
|
|
|
@item{instances of a @techlink{prefab} structure type}
|
|
|
|
@item{placeholders created by @racket[make-placeholder] and
|
|
@racket[make-hash-placeholder]}
|
|
|
|
]
|
|
|
|
Due to these restrictions, @racket[make-reader-graph] creates exactly
|
|
the same sort of cyclic values as @racket[read].
|
|
|
|
@mz-examples[
|
|
(let* ([ph (make-placeholder #f)]
|
|
[x (cons 1 ph)])
|
|
(placeholder-set! ph x)
|
|
(make-reader-graph x))
|
|
]}
|
|
|
|
@defproc[(placeholder? [v any/c]) boolean?]{
|
|
|
|
Returns @racket[#t] if @racket[v] is a placeholder created by
|
|
@racket[make-placeholder], @racket[#f] otherwise.}
|
|
|
|
|
|
@defproc[(make-placeholder [v any/c]) placeholder?]{
|
|
|
|
Returns a placeholder for use with @racket[placeholder-set!] and
|
|
@racket[make-reader-graph]. The @racket[v] argument supplies the
|
|
initial value for the placeholder.}
|
|
|
|
@defproc[(placeholder-set! [ph placeholder?] [datum any/c]) void?]{
|
|
|
|
Changes the value of @racket[ph] to @racket[v].}
|
|
|
|
@defproc[(placeholder-get [ph placeholder?]) any/c]{
|
|
|
|
Returns the value of @racket[ph].}
|
|
|
|
|
|
@defproc[(hash-placeholder? [v any/c]) boolean?]{
|
|
|
|
Returns @racket[#t] if @racket[v] is a placeholder created by
|
|
@racket[make-hash-placeholder], @racket[#f] otherwise.}
|
|
|
|
|
|
@defproc[(make-hash-placeholder [assocs (listof pair?)])
|
|
hash-placeholder?]{
|
|
|
|
Like @racket[make-immutable-hash], but produces a table placeholder
|
|
for use with @racket[make-reader-graph].}
|
|
|
|
@defproc[(make-hasheq-placeholder [assocs (listof pair?)])
|
|
hash-placeholder?]{
|
|
|
|
Like @racket[make-immutable-hasheq], but produces a table placeholder
|
|
for use with @racket[make-reader-graph].}
|
|
|
|
@defproc[(make-hasheqv-placeholder [assocs (listof pair?)])
|
|
hash-placeholder?]{
|
|
|
|
Like @racket[make-immutable-hasheqv], but produces a table placeholder
|
|
for use with @racket[make-reader-graph].}
|