From 82d45bc644ca1d2d1c30d8098ab32d317097c15f Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Mon, 3 Sep 2007 17:06:54 +0000
Subject: [PATCH] doc procedure-reduce-arity

svn: r7269
---
 .../scribblings/reference/procedures.scrbl    | 33 +++++++++++++++----
 collects/scribblings/reference/to-do.ss       |  2 ++
 2 files changed, 28 insertions(+), 7 deletions(-)

diff --git a/collects/scribblings/reference/procedures.scrbl b/collects/scribblings/reference/procedures.scrbl
index b7d7905598..9b103c4bed 100644
--- a/collects/scribblings/reference/procedures.scrbl
+++ b/collects/scribblings/reference/procedures.scrbl
@@ -54,14 +54,14 @@ and @scheme[lst]; otherwise, the @exnraise[exn:fail:contract].
 ]}
 
 @defproc[(procedure-arity [proc procedure?])
-         (or/c exact-nonnegative-integer?
-               arity-at-least?
-               (listof
-                (or/c exact-nonnegative-integer?
-                      arity-at-least?)))]{
+         arity?]{
 
 Returns information about the number of by-position arguments accepted
-by @scheme[proc]. The result @scheme[_a] is one of the following:
+by @scheme[proc]. See also @scheme[arity?].}
+
+@defproc[(arity? [v any/c]) boolean?]{
+
+A valid arity is one of the following:
 
 @itemize{
 
@@ -89,6 +89,7 @@ by @scheme[proc]. The result @scheme[_a] is one of the following:
 
 @defproc[(procedure-arity-includes? [proc procedure?] [k exact-nonnegative-integer?])
          boolean?]{
+
 Returns @scheme[#t] if the procedure can accept @scheme[k] arguments
 when no keyword arguments are supplied, @scheme[#f] otherwise.
 
@@ -97,6 +98,20 @@ when no keyword arguments are supplied, @scheme[#f] otherwise.
 (procedure-arity-includes? display 3)
 ]}
 
+@defproc[(procedure-reduce-arity [proc procedure?]
+                                 [arity arity?])
+         procedure?]{
+
+Returns a procedure that is the same as @scheme[proc] (including
+the same name returned by @scheme[object-name]), but that accepts
+only arguments consistent with @scheme[arity]. In particular,
+when @scheme[procedure-arity] is applied to the generated
+procedure, it returns a value that is @scheme[equal?] to
+@scheme[arity].
+
+If the @scheme[arity] specification allows arguments that are not
+in @scheme[(procedure-arity proc)], the @exnraise[exn:fail:contract].}
+
 @defproc[(procedure-keywords [proc procedure?])
          (values
           (listof keyword?)
@@ -144,8 +159,12 @@ obtains its result frmo @scheme[plain-proc].
 (show #:init 0 1 2 3 #:extra 4)
 ]}
 
+
 @defstruct[arity-at-least ([value nonnegative-exact-integer?])]{
-This structure type is used for the result of @scheme[procedure-arity].}
+
+This structure type is used for the result of @scheme[procedure-arity].
+See also @scheme[arity?].}
+
 
 @defthing[prop:procedure struct-type-property?]{
 
diff --git a/collects/scribblings/reference/to-do.ss b/collects/scribblings/reference/to-do.ss
index fb5ccad64b..4cf99be5af 100644
--- a/collects/scribblings/reference/to-do.ss
+++ b/collects/scribblings/reference/to-do.ss
@@ -29,4 +29,6 @@
   (define empty? #f)
   (define empty #f)
 
+  (define arity? #f)
+
   (provide (all-defined)))