From c991ada1e77b6a9235167f6a7173d2d71ae79aac Mon Sep 17 00:00:00 2001 From: Jon Rafkind Date: Mon, 16 Nov 2009 02:40:45 +0000 Subject: [PATCH] add examples for pairs svn: r16794 --- collects/scribblings/reference/pairs.scrbl | 215 ++++++++++++++++++--- 1 file changed, 183 insertions(+), 32 deletions(-) diff --git a/collects/scribblings/reference/pairs.scrbl b/collects/scribblings/reference/pairs.scrbl index 6b59f12b86..9043a85307 100644 --- a/collects/scribblings/reference/pairs.scrbl +++ b/collects/scribblings/reference/pairs.scrbl @@ -67,35 +67,78 @@ then the pair is not a list. @section{Pair Constructors and Selectors} @defproc[(pair? [v any/c]) boolean?]{Returns @scheme[#t] if @scheme[v] is -a pair, @scheme[#f] otherwise.} +a pair, @scheme[#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 @scheme[#t] if @scheme[v] is -the empty list, @scheme[#f] otherwise.} +the empty list, @scheme[#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 pair whose first -element is @scheme[a] and second element is @scheme[d].} +element is @scheme[a] and second element is @scheme[d]. +@mz-examples[ +(cons 1 2) +(cons 1 '()) +]} @defproc[(car [p pair?]) any/c]{Returns the first element of the -pair @scheme[p].} +pair @scheme[p]. +@mz-examples[ +(car '(1 2)) +(car (cons 2 3)) +]} @defproc[(cdr [p pair?]) any/c]{Returns the second element of the -pair @scheme[p].} +pair @scheme[p]. +@mz-examples[ +(cdr '(1 2)) +(cdr '(1)) +]} -@defthing[null null?]{The empty list.} +@defthing[null null?]{The empty list. +@mz-examples[ +null +'() +(eq? '() null) +]} @defproc[(list? [v any/c]) boolean?]{Returns @scheme[#t] if @scheme[v] is a list: either the empty list, or a pair whose second element is a - list. This procedure takes amortized constant time.} + list. This procedure takes amortized constant time. +@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 @scheme[v]s as its elements.} +containing the @scheme[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 @scheme[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.} +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)]) @@ -117,7 +160,11 @@ is the value produced by @scheme[(proc _i)]. @defproc[(length [lst list?]) exact-nonnegative-integer?]{ -Returns the number of elements in @scheme[lst].} +Returns the number of elements in @scheme[lst]. +@mz-examples[ +(length (list 1 2 3 4)) +(length '()) +]} @defproc[(list-ref [lst any/c] [pos exact-nonnegative-integer?]) @@ -129,7 +176,12 @@ the list's first element is position @scheme[0]. If the list has @exnraise[exn:fail:contract]. The @scheme[lst] argument need not actually be a list; @scheme[lst] -must merely start with a chain of at least @scheme[pos] pairs.} +must merely start with a chain of at least @scheme[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) +]} @defproc[(list-tail [lst any/c] [pos exact-nonnegative-integer?]) @@ -140,7 +192,10 @@ Returns the list after the first @scheme[pos] elements of the @exnraise[exn:fail:contract]. The @scheme[lst] argument need not actually be a list; @scheme[lst] -must merely start with a chain of at least @scheme[pos] pairs.} +must merely start with a chain of at least @scheme[pos] pairs. +@mz-examples[ +(list-tail (list 1 2 3 4) 2) +]} @defproc*[([(append [lst list?] ...) list?] @@ -151,12 +206,21 @@ 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.''} +``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 @scheme[lst], but in -reverse order.} +reverse order. + +@mz-examples[ +(reverse (list 1 2 3 4)) +]} @; ---------------------------------------- @@ -169,7 +233,17 @@ Applies @scheme[proc] to the elements of the @scheme[lst]s from the first elements to the last. The @scheme[proc] argument must accept the same number of arguments as the number of supplied @scheme[lst]s, and all @scheme[lst]s must have the same number of elements. The - result is a list containing each result of @scheme[proc] in order.} + result is a list containing each result of @scheme[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]{ @@ -232,7 +306,14 @@ If the @scheme[lst]s are empty, then @scheme[#f] is returned.} Similar to @scheme[map], but @scheme[proc] is called only for its effect, and its result (which can be any number of values) is - ignored.} + 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?] ...+) @@ -260,6 +341,11 @@ Unlike @scheme[foldr], @scheme[foldl] processes the @scheme[lst]s in @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?] ...+) @@ -283,7 +369,11 @@ Like @scheme[foldl], but the lists are traversed from right to left. Returns a list with the elements of @scheme[lst] for which @scheme[pred] produces a true value. The @scheme[pred] procedure is - applied to each element from first to last.} + 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?]) @@ -291,38 +381,58 @@ Returns a list with the elements of @scheme[lst] for which Returns a list that is like @scheme[lst], omitting the first element of @scheme[lst] that is equal to @scheme[v] using the comparison - procedure @scheme[proc] (which must accept two arguments).} + procedure @scheme[proc] (which must accept two arguments). + +@mz-examples[ +(remove 2 (list 1 2 3 2 4)) +]} @defproc[(remq [v any/c] [lst list?]) list?]{ -Returns @scheme[(remove v lst eq?)].} +Returns @scheme[(remove v lst eq?)]. +@mz-examples[ +(remq 2 (list 1 2 3 4 5)) +]} @defproc[(remv [v any/c] [lst list?]) list?]{ -Returns @scheme[(remove v lst eqv?)].} +Returns @scheme[(remove v lst eqv?)]. +@mz-examples[ +(remv 2 (list 1 2 3 4 5)) +]} @defproc[(remove* [v-lst list?] [lst list?] [proc procedure? equal?]) list?]{ Like @scheme[remove], but removes from @scheme[lst] every instance of -every element of @scheme[v-lst].} +every element of @scheme[v-lst]. +@mz-examples[ +(remove* 2 (list 1 2 3 2 4 5 2)) +]} @defproc[(remq* [v-lst list?] [lst list?]) list?]{ -Returns @scheme[(remove* v-lst lst eq?)].} +Returns @scheme[(remove* v-lst lst eq?)]. + +@mz-examples[ +(remq* 2 (list 1 2 3 2 4 5 2)) +]} @defproc[(remv* [v-lst list?] [lst list?]) list?]{ -Returns @scheme[(remove* v-lst lst eqv?)].} +Returns @scheme[(remove* v-lst lst eqv?)]. +@mz-examples[ +(remv* 2 (list 1 2 3 2 4 5 2)) +]} @defproc[(sort [lst list?] [less-than? (any/c any/c . -> . any/c)] @@ -381,19 +491,34 @@ By default, @scheme[extract-key] is applied to two list elements for Locates the first element of @scheme[lst] that is @scheme[equal?] to @scheme[v]. If such an element exists, the tail of @scheme[lst] starting with that element is returned. Otherwise, the result is - @scheme[#f].} + @scheme[#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 @scheme[member], but finds an element using @scheme[eqv?].} +Like @scheme[member], but finds an element using @scheme[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 @scheme[member], but finds an element using @scheme[eq?].} +Like @scheme[member], but finds an element using @scheme[eq?]. + +@mz-examples[ +(memq 2 (list 1 2 3 4)) +(memq 9 (list 1 2 3 4)) +]} +} @defproc[(memf [proc procedure?] [lst list?]) @@ -401,13 +526,24 @@ Like @scheme[member], but finds an element using @scheme[eq?].} Like @scheme[member], but finds an element using the predicate @scheme[proc]; an element is found when @scheme[proc] applied to the - element returns a true value.} + 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 @scheme[memf], but returns the element or @scheme[#f] - instead of a tail of @scheme[lst] or @scheme[#f].} + instead of a tail of @scheme[lst] or @scheme[#f]. +@mz-examples[ +(findf (lambda (arg) + (> arg 9)) + '(7 8 9 10 11)) +]} @defproc[(assoc [v any/c] [lst (listof pair?)]) @@ -416,19 +552,29 @@ Like @scheme[memf], but returns the element or @scheme[#f] Locates the first element of @scheme[lst] whose @scheme[car] is @scheme[equal?] to @scheme[v]. If such an element exists, the pair (i.e., an element of @scheme[lst]) is returned. Otherwise, the result - is @scheme[#f].} + is @scheme[#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))) +]} @defproc[(assv [v any/c] [lst (listof pair?)]) (or/c pair? #f)]{ -Like @scheme[assoc], but finds an element using @scheme[eqv?].} +Like @scheme[assoc], but finds an element using @scheme[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 @scheme[assoc], but finds an element using @scheme[eq?].} +Like @scheme[assoc], but finds an element using @scheme[eq?]. +@mz-examples[ +(assq 3 (list (list 1 2) (list 3 4) (list 5 6))) +]} @defproc[(assf [proc procedure?] [lst list?]) @@ -436,7 +582,12 @@ Like @scheme[assoc], but finds an element using @scheme[eq?].} Like @scheme[assoc], but finds an element using the predicate @scheme[proc]; an element is found when @scheme[proc] applied to the - @scheme[car] of an @scheme[lst] element returns a true value.} + @scheme[car] of an @scheme[lst] element returns a true value. +@mz-examples[ +(assf (lambda (arg) + (> arg 2)) + (list (list 1 2) (list 3 4) (list 5 6))) +]}