Welcome! Please see the About page for a little more info on how this works.

+5 votes
in Docs by

The current docstring of = says:
> compares numbers and collections in a type-independent manner

Which makes it sound like it compares numbers by value, checking whether dots on a number line coincide.

Whereas in reality:

user=> (= 1. 1)

The page at https://clojure.org/guides/equality#_summary explains why, but it would be nice to have that information in the docstring as well.

2 Answers

+4 votes

Following the same docstring I saw some confusions with:
> Same as Java x.equals(y) except it also works for nil

and people expecting this to mean the same thing:

(defrecord Foo [a])

(= (Foo. 1)
   {:a 1})
;; => false

(.equals (Foo. 1)
         {:a 1})
;; => true
I also notice that `=` thinks `(long 1)` and `(short 1)` are equal but not `1` and `1.0`.  So it does *some* case independent comparison, but exactly what is unclear.
Another weird example:
    user=> (= 1/1 (clojure.lang.Ratio. (biginteger 1) (biginteger 1)))
    user=> (= 1/2 (clojure.lang.Ratio. (biginteger 1) (biginteger 2)))
I am not an authority on this matter, but my educated guess is that Clojure's implementation never intended to support direct calls to the clojure.lang.Ratio constructor.  There is code outside of that constructor when doing math on ratio types that explicitly reduces numerator and denominator to lowest common terms, and returns an integer object, not a ratio object, when the result is an integer.  Thus it seems like your constructor calls are intentionally trying to sidestep that by digging into calls intended to remain part of Clojure's internal implementation, not its supported API.
0 votes

I do not know the Clojure maintainer's views on this idea, but an approach that would make the details easier to find for many people, without significantly increasing the length of the compiled-into-the-Clojure-image doc string, would be to add a sentence like "For additional details, see https://clojure.org/guides/equality" in the doc string.