Add diagrams from Vincent's PADL paper to TR docs

pkgs/typed-racket-pkgs/typed-racket-doc/typed-racket/scribblings/reference/numeric-tower-pict.rkt

@@ -0,0 +1,121 @@
+#lang racket/base
+
+;; This module provides a pict version of the Typed Racket numeric type
+;; hierarchy diagram from "Typing the Numeric Tower" (pg 5) from PADL 2012
+
+(require pict)
+
+(provide numeric-tower-pict
+         integer-pict)
+
+;; large type category heading
+(define (text/1 str)
+  (text str null 20))
+
+;; small type category
+(define (text/2 str)
+  (text str null 15))
+
+(define base-complex
+  (linewidth
+   2
+   (cc-superimpose
+    (colorize (filled-rectangle 560 350) "white")
+    (rectangle 560 350)
+    (ellipse 510 280)
+    (vline 1 350))))
+
+(define left-side
+  (ct-superimpose
+   (cc-superimpose
+    (ghost (rectangle 270 350))
+    (hc-append (blank 30 1)
+               (cb-superimpose (linewidth 2 (ellipse 140 110))
+                               (vc-append (text/1 "Integer")
+                                          (blank 1 10))))
+    (hc-append (blank 25 1)
+               (linewidth 2 (linestyle 'dot (hline 250 2))))
+    (hc-append (blank 30 1)
+               (cc-superimpose (colorize (filled-ellipse 50 35) "white")
+                               (linewidth 2 (linestyle 'dot (ellipse 50 35)))
+                               (text/2 "Zero"))))
+   (vc-append (blank 1 7) (text/1 "Exact-Number"))
+   (vr-append (blank 265 70)
+              ;; this doesn't line up without the blank for
+              ;; some reason (due to text formatting)
+              ;(hc-append (text/1 "Exact-Rational") (blank 7 1))
+              (text/1 "Exact-Rational")
+              (text/2 "Positive-Exact-Rational")
+              (blank 1 130)
+              (text/2 "Negative-Exact-Rational"))))
+
+(define right-side
+  (ct-superimpose
+   (cc-superimpose
+    (ghost (rectangle 270 350))
+    (hc-append (linewidth 2 (linestyle 'dot (hline 260 2)))
+               (blank 25 1))
+    (hc-append (cc-superimpose (colorize (filled-ellipse 100 35) "white")
+                               (linewidth 2 (linestyle 'dot (ellipse 100 35)))
+                               (text/2 "Float-Zero"))
+               (blank 30 1)))
+   (vc-append (blank 1 7) (text/1 "Float-Complex"))
+   (vl-append (blank 245 70)
+              (text/1 "Float")
+              (text/2 "Positive-Float")
+              (blank 1 130)
+              (text/2 "Negative-Float"))))
+
+(define *integer-pict
+  (ct-superimpose
+   (linewidth
+    2
+    (cc-superimpose
+     (cc-superimpose
+      (colorize (filled-rectangle 200 350) "white")
+      (rectangle 200 350))
+     (rectangle 170 280)
+     (ct-superimpose (ghost (rectangle 140 210))
+                     (inset/clip (linewidth 3 (rectangle 140 210)) 0 0 0 -105))
+     (ct-superimpose (ghost (rectangle 110 140))
+                     (inset/clip (linewidth 3 (rectangle 110 140)) 0 0 0 -70))
+     (hline 200 2)
+     (cc-superimpose
+      (colorize (filled-ellipse 50 30) "white")
+      (ellipse 50 30)
+      (text/2 "Zero"))))
+   (vc-append (blank 1 7)
+              (text/2 "Positive-Integer")
+              (blank 1 20)
+              (text/2 "Positive-Fixnum")
+              (blank 1 20)
+              (text/2 "Positive-Index")
+              (blank 1 20)
+              (text/2 "Positive-Byte")
+              (blank 1 100)
+              (text/2 "Negative-Fixnum")
+              (blank 1 70)
+              (text/2 "Negative-Integer"))))
+
+(define complex-pict
+  (rc-superimpose
+   (lc-superimpose
+    base-complex
+    left-side)
+   right-side))
+
+(define numeric-tower-pict
+  ;; inset to avoid clipping a border
+  (inset (ht-append
+          30
+          (vc-append
+           10
+           (vl-append
+            10
+            (text/1 "Complex / Number")
+            complex-pict)
+           (text/1 "Exact-Rational ∪ Float = Real")))
+         1))
+
+(define integer-pict
+  (inset (vl-append 10 (text/1 "Integer") *integer-pict) 1))

pkgs/typed-racket-pkgs/typed-racket-doc/typed-racket/scribblings/reference/types.scrbl

@@ -1,6 +1,9 @@
 #lang scribble/manual
 
-@begin[(require "../utils.rkt" scribble/eval racket/sandbox)
+@begin[(require "../utils.rkt"
+                "numeric-tower-pict.rkt"
+                scribble/eval
+                racket/sandbox)
        (require (for-label (only-meta-in 0 [except-in typed/racket for])))]
 
 @(define the-eval (make-base-eval))
@@ -28,7 +31,19 @@ any expression of this type will not evaluate to a value.}
 
 @subsection{Numeric Types}
 
-These types represent the hierarchy of @rtech{numbers} of Racket.
+These types represent the hierarchy of @rtech{numbers} of Racket. The
+diagram below shows the relationships between the types in the hierarchy.
+
+@centered[@numeric-tower-pict]
+
+The regions with a solid border are @emph{layers} of the numeric hierarchy
+corresponding to sets of numbers such as integers or rationals. Layers
+contained within another are subtypes of the layer containing them. For
+example, @racket[Exact-Rational] is a subtype of @racket[Exact-Number].
+
+The @racket[Real] layer is also divided into positive and negative types
+(shown with a dotted line). The @racket[Integer] layer is subdivided into
+several fixed-width integers types, detailed later in this section.
 
 @defnums[(Number Complex)]
 @racket[Number] and @racket[Complex] are synonyms. This is the most general
@@ -136,7 +151,14 @@ sign. However, programs using them may require additional dynamic checks when
 the type-checker cannot guarantee that the sign constraints will be respected.
 
 In addition to being divided by sign, integers are further subdivided into
-range-bounded types.
+range-bounded types. The relationships between most of the range-bounded types
+are shown in this diagram:
+
+@centered[@integer-pict]
+
+Like the previous diagram, types nested inside of another in the
+diagram are subtypes of its containing types.
+
 @defnums[(
 One
 Byte