flatten and docs

svn: r8926

collects/scheme/list.ss

@@ -7,7 +7,9 @@
 
          cons?
          empty
-         empty?)
+         empty?
+
+         flatten)
 
 (define (first x)
   (if (and (pair? x) (list? x))
@@ -51,3 +53,9 @@
 (define cons? (lambda (l) (pair? l)))
 (define empty? (lambda (l) (null? l)))
 (define empty '())
+
+(define (flatten orig-sexp)
+  (let loop ([sexp orig-sexp] [acc null])
+    (cond [(null? sexp) acc]
+          [(pair? sexp) (loop (car sexp) (loop (cdr sexp) acc))]
+          [else (cons sexp acc)])))

collects/scribblings/reference/pairs.scrbl

@@ -272,14 +272,13 @@ Like @scheme[foldl], but the lists are traversed from right to left.
 @defproc[(flatten [x any/c])
          list?]{
 
-Like @scheme[foldl], but the lists are traversed from right to left.
- Unlike @scheme[foldl], @scheme[foldr] processes the @scheme[lst]s in
- space proportional to the length of @scheme[lst]s (plus the space for
- each call to @scheme[proc]).
+Flattens an arbitrary S-expression structure of pairs to a list.  Note
+that this function never raises an error, since all values are valid
+S-expressions.
 
 @examples[
-(foldr cons '() '(1 2 3 4))
-(foldr (lambda (v l) (cons (add1 v) l)) '() '(1 2 3 4))
+(flatten '((x) x (x (x) x) ()))
+(flatten 'x)
 ]}
 
 @; ----------------------------------------