 ;;;; ___________________________________________________________________________
 ;;;; ---- Terminology ----
 
-;;; The phrase "equivalent value" is used when two numbers, possibly of
-;;; different types, are the same value as seen from the point of view of
-;;; mathematics. So, for example, 2 and 2.0 are equivalent values.
+;; The phrase "equivalent value" is used when two numbers, possibly of
+;; different types, are the same value as seen from the point of view of
+;; mathematics. So, for example, 2 and 2.0 are equivalent values.
 
 ;;;; ___________________________________________________________________________
 ;;;; ---- Clojure's numeric types ----

;;;;   Returns non-nil if nums all have the equivalent value (type-independent),
;;;;   otherwise false.

;;; The doc string uses the phrase "type-independent" in a way that is (to me)
;;; intuitive, but which has a different meaning to that in the doc string for
;;; `=`.

;;; From /Clojure Programming/:
;;;   Clojure opts to provide a third notion of equality, specifically to
;;;   address the need for type-insensitive equivalence tests.

(fact "Numbers with an equivalent value are equal using `==`"
  (== (Byte. (byte 2))

  (fact (= 2N 2M)    => false)
  (fact (= 1.25 5/4) => false))

;; From /Clojure Programming/:
;;   Clojure’s `=` could obviate these type differences (as Ruby and Python
;;   do), but doing so would impose some runtime cost that would be
;;   unappreciated by those who need to maximize the performance of programs
;;   that work with homogeneous numeric data.

;;;; ---------------------------------------------------------------------------
;;;; ---- My playing ----

;; Shows that "same category" is A Thing, as /Clojure Programming/ says. Shows
;; that the doc string's "type-independent manner" is wrong (according to what
;; I think that should mean).

;; Summary, showing the equivalence classes apart from Ratios:
;;;
;;   Key to the table entries:
;;;
;;         =   means   (= x y) is true
;;         .   means   (= x y) is false
;;             where x is the row value and y is the column value
;;;
;;       F2.0  means   (Float. 2.0)
;;;
;; 
;;              --------------------------------------
;;        =     |   2  2N   |  2M 2.0M  |  2.0  F2.0 |
;;     -----------------------------------------------
;;     |        |           |           |            |
;;     |  2     |   =   =   |   .   .   |   .   .    |
;;     |        |           |           |            |
;;     |  2N    |   =   =   |   .   .   |   .   .    |
;;     |        |           |           |            |
;;     -----------------------------------------------
;;     |        |           |           |            |
;;     |  2M    |   .   .   |   =   =   |   .   .    |
;;     |        |           |           |            |
;;     |  2.0M  |   .   .   |   =   =   |   .   .    |
;;     |        |           |           |            |
;;     -----------------------------------------------
;;     |        |           |           |            |
;;     |  2.0   |   .   .   |   .   .   |   =   =    |
;;     |        |           |           |            |
;;     |  F2.0  |   .   .   |   .   .   |   =   =    |
;;     |        |           |           |            |
;;     -----------------------------------------------


(fact "Two numbers of the same type and with equivalent value are equal using `=`"
