Determining the equality of two values in Common Lisp is not as straightforward as it might seem, and there are a few parts of the specification that seems inconsistent, especially to those coming from other high level languages.
Overview
Common Lisp provides a long list of equality functions to choose from, depending on what you want to accomplish:
(= a b)
(eq a b)
(eql a b)
(equal a b)
(equalp a b)
(string= a b)
(string-equal a b)
(char= a b)
(char-equal a b)
I’m not going to go through all of them, but I do want to highlight gotchas I’ve run into.
Case sensitivity
You may have noticed that Common Lisp likes the SHIFT key. For reasons certainly not lost to history, symbols in Common Lisp are by default NOT case sensitive. There is some internal chickanery available to make the Common Lisp reader case sensitive, but I gather from my own research that this is considered a bit risky. So let’s not go there.
So for example, with symbols:
CL-USER> (eq 'a 'A)
T
CL-USER> (eql 'a 'A)
T
CL-USER> (equal 'a 'A)
T
CL-USER> (equalp 'a 'A)
T
CL-USER>
This is fine, because if you have an itchy pinky, Common Lisp will forgive you if you upper-case your symbols, function calls, etc.
Equality tower?
Does it seem like these particular equality functions are designed to get more and more general?
eq < eql < equal < equalp
eq tests for identity, as in the same pointer value. eql checks
if the values pointed to by different pointers are equal, like two
variables with the same number assigned to them. equal extends the
comparisons to recursively check lists and arrays. Finally, equalp
extends the comparison to structures and hash tables.
So you might be forgiven to assume (like I did) that equalp is a
good general choice if you’re not overly concerned about performance
and don’t mind letting the runtime pick the most type-appropriate
equality test. That’s where the problem begins.
Strings
So, back to Common Lisp’s love of the SHIFT key. It turns out this love extends to strings, as well:
CL-USER> (equalp "hello" "HELLO")
T
That’s the first gotcha. equalp seems good for a general-purpose
equality test, especially because it understands lists, arrays and
structures, but it apparently doesn’t understand the difference
between whispering and shouting.
Instead, you need one of these two functions if you want to compare strings the way most people do:
CL-USER> (equal "hello" "HELLO")
NIL
CL-USER> (string= "hello" "HELLO")
NIL
Watch out for the misleadingly named string-equal, however. It
sounds like it should be a string version of equal, but it gives a
different result:
CL-USER> (equal "hello" "HELLO")
NIL
CL-USER> (string-equal "hello" "HELLO")
T
I’m going to let the experts explain that naming choice, because I’m stumped.
Unicode
I haven’t tested the string equality functions on unicode strings
yet. The luxury of being an English-native speaker means I put
unicode off until later. But who knows if string=, string-equal,
and equal will work consistently with Unicode strings?
Structures
Even if equalp isn’t the right choice for strings, don’t write it
off just yet. It’s very useful for user-defined structures:
CL-USER> (defstruct foo-struct x)
FOO-STRUCT
CL-USER> (equalp (make-foo-struct :x 1) (make-foo-struct :x 1))
T
CL-USER> (equal (make-foo-struct :x 1) (make-foo-struct :x 1))
NIL
Two structures with different identities, but the same slot values,
are considered equal by equalp. This is generally what I want when
I define structures to hold data.
But hold on, if the data in the structures are strings, we’re in a bit of a pickle.
CL-USER> (equalp (make-foo-struct :x "hello") (make-foo-struct :x "HELLO"))
T
CL-USER> (equal (make-foo-struct :x "hello") (make-foo-struct :x "HELLO"))
NIL
CL-USER> (equal (make-foo-struct :x "hello") (make-foo-struct :x "hello"))
NIL
equalp of course decides that the two strings in the structure are
equal even if they’re different case. But our case-sensitive friend
equal fails us hard in the third test, because it’s not even
looking at the strings. (It’s not allowed to look into structures,
which is why we wanted to use equalp.
Unfortunately, the only way around this is to define a user function that walks through structure slots, checks the type of the value stored there, and uses the appropriate equality function.
Hash tables
With hash tables, equalp is your friend. Anything less doesn’t
have permission to look at keys and values. So for simple hash
tables that don’t use string keys or values, try this:
CL-USER> (defvar a (make-hash-table :test 'equalp))
A
CL-USER> (defvar b (make-hash-table :test 'equalp))
B
CL-USER> (setf (gethash :a a) 1)
1
CL-USER> (setf (gethash :a b) 1)
1
CL-USER> (equalp a b)
T
CL-USER> (equal a b)
NIL
With string values:
CL-USER> (setf (gethash :b a) "hello")
"hello"
CL-USER> (setf (gethash :b b) "hello")
"hello"
CL-USER> (equalp a b)
T
But watch out for equalp’s case-blindness:
CL-USER> (setf (gethash :c a) "hello")
"hello"
CL-USER> (setf (gethash :c b) "HELLO")
"HELLO"
CL-USER> (equalp a b)
T
And this case-blindness applies to keys as well, when the hash table
is set to use equalp as its test function (when we created it):
CL-USER> (setf (gethash "hello" a) "world")
"world"
CL-USER> (setf (gethash "HELLO" a) "WORLD")
"WORLD"
CL-USER> (gethash "hello" a)
"WORLD"
T
CL-USER>
For completeness, two identical hash tables with different test functions are not considered equal:
CL-USER> (equalp (make-hash-table :test 'eql) (make-hash-table :test 'equalp))
NIL
Classes
CLOS is amazing. Unfortunately, they forgot to introduce it to
equalp:
(defclass foo-class () ((x :initarg :x)))
#<STANDARD-CLASS COMMON-LISP-USER::FOO-CLASS>
CL-USER> (equalp (make-instance 'foo-class :x 1) (make-instance 'foo-class :x 1))
NIL
CL-USER> (equal (make-instance 'foo-class :x 1) (make-instance 'foo-class :x 1))
NIL
This foo-class is basically the same data layout as the
foo-struct I showed above,
but equalp fails even in the simplest non-string case. That’s because
equalp is not allowed to walk into a class instance. You might say
it’s in detention.
Now what?
So, the moral of the story is you can’t take equality for granted.
Common Lisp provides nearly a dozen equality functions for different
purposes, with some unfortunate inconsistencies in naming. In my own
code, I define a generic equal? function and specialize it for
various structures and classes. I default to using equalp unless I
know or suspect strings might appear, in which case I use equal.
There’s also something called CDR-8 that aims to specify higher-level generic equality and comparison, but there are some issues with the spec and no fully-functional implementations available as of this date.
Here’s hoping and working toward a more equal world for all of us.
As always comments are invited and appreciated, and are on reddit.