From 8f904480c02a28b966ef8827d71bae534778995f Mon Sep 17 00:00:00 2001
From: Keyan Zhang <kz5@indiana.edu>
Date: Fri, 13 Mar 2015 14:04:20 -0400
Subject: [PATCH] detailed explanation of eq?, eqv?, and equal?

References:
1. http://docs.racket-lang.org/reference/booleans.html
2. http://docs.racket-lang.org/reference/eval-model.html
3. https://groups.google.com/forum/#!topic/plt-scheme/T1k49HMl450
4. http://stackoverflow.com/questions/16299246/what-is-the-difference-between-eq-eqv-equal-and-in-scheme
5. http://www.r6rs.org/final/html/r6rs/r6rs-Z-H-14.html
---
 racket.html.markdown | 48 +++++++++++++++++++++++++++++++++++++-------
 1 file changed, 41 insertions(+), 7 deletions(-)

diff --git a/racket.html.markdown b/racket.html.markdown
index 6abc8759..e345db8b 100644
--- a/racket.html.markdown
+++ b/racket.html.markdown
@@ -7,6 +7,7 @@ contributors:
   - ["Eli Barzilay", "https://github.com/elibarzilay"]
   - ["Gustavo Schmidt", "https://github.com/gustavoschmidt"]
   - ["Duong H. Nguyen", "https://github.com/cmpitg"]
+  - ["Keyan Zhang", "https://github.com/keyanzhang"]
 ---
 
 Racket is a general purpose, multi-paradigm programming language in the Lisp/Scheme family.
@@ -282,16 +283,49 @@ m ; => '#hash((b . 2) (a . 1) (c . 3))  <-- no `d'
 
 ;; for numbers use `='
 (= 3 3.0) ; => #t
-(= 2 1) ; => #f
+(= 2 1)   ; => #f
+
+;; `eq?' returns #t if 2 arguments refer to the same object (in memory), 
+;; #f otherwise.
+;; In other words, it's a simple pointer comparison.
+(eq? '() '()) ; => #t, since there exists only one empty list in memory
+(let ([x '()] [y '()])
+  (eq? x y))  ; => #t, same as above
 
-;; for object identity use `eq?'
-(eq? 3 3) ; => #t
-(eq? 3 3.0) ; => #f
 (eq? (list 3) (list 3)) ; => #f
+(let ([x (list 3)] [y (list 3)])
+  (eq? x y))            ; => #f — not the same list in memory!
 
-;; for collections use `equal?'
-(equal? (list 'a 'b) (list 'a 'b)) ; => #t
-(equal? (list 'a 'b) (list 'b 'a)) ; => #f
+(let* ([x (list 3)] [y x])
+  (eq? x y)) ; => #t, since x and y now point to the same stuff
+
+(eq? 'yes 'yes) ; => #t
+(eq? 'yes 'no)  ; => #f
+
+(eq? 3 3)   ; => #t — be careful here
+            ; It’s better to use `=' for number comparisons.
+(eq? 3 3.0) ; => #f
+
+(eq? (expt 2 100) (expt 2 100))               ; => #f
+(eq? (integer->char 955) (integer->char 955)) ; => #f
+
+(eq? (string-append "foo" "bar") (string-append "foo" "bar")) ; => #f
+
+;; `eqv?' supports the comparison of number and character datatypes.
+;; for other datatypes, `eqv?' and `eq?' return the same result.
+(eqv? 3 3.0)                                   ; => #f
+(eqv? (expt 2 100) (expt 2 100))               ; => #t
+(eqv? (integer->char 955) (integer->char 955)) ; => #t
+
+(eqv? (string-append "foo" "bar") (string-append "foo" "bar"))   ; => #f
+
+;; `equal?' supports the comparison of the following datatypes:
+;; strings, byte strings, pairs, mutable pairs, vectors, boxes, 
+;; hash tables, and inspectable structures.
+;; for other datatypes, `equal?' and `eqv?' return the same result.
+(equal? 3 3.0)                                                   ; => #f
+(equal? (string-append "foo" "bar") (string-append "foo" "bar")) ; => #t
+(equal? (list 3) (list 3))                                       ; => #t
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; 5. Control Flow