Skip to main content

eq

eq Function

Syntax:

eq x y → generalized-boolean

Arguments and Values:

x—an object.

y—an object.

generalized-boolean—a generalized boolean.

Description:

Returns true if its arguments are the same, identical object; otherwise, returns false.

Examples:

(eq ’a ’b) → false 
(eq ’a ’a) → true 
(eq 3 3) 
→ true 
<i><sup>or</sup>→ false</i> 
(eq 3 3.0) → false 
(eq 3.0 3.0) 
→ true 
<i><sup>or</sup>→ false</i> 

**eq** 
(eq #c(3 -4) #c(3 -4)) 
→ true 
<i><sup>or</sup>→ false</i> 
(eq #c(3 -4.0) #c(3 -4)) → false 
(eq (cons ’a ’b) (cons ’a ’c)) → false 
(eq (cons ’a ’b) (cons ’a ’b)) → false 
(eq ’(a . b) ’(a . b)) 
→ true 
<i><sup>or</sup>→ false</i> 
(progn (setq x (cons ’a ’b)) (eq x x)) → true 
(progn (setq x ’(a . b)) (eq x x)) → true 
(eq #\A #\A) 
→ true 
<i><sup>or</sup>→ false</i> 
(let ((x "Foo")) (eq x x)) → true 
(eq "Foo" "Foo") 
→ true 
<i><sup>or</sup>→ false</i> 
(eq "Foo" (copy-seq "Foo")) → false 
(eq "FOO" "foo") → false 
(eq "string-seq" (copy-seq "string-seq")) → false 
(let ((x 5)) (eq x x)) 
→ true 
<i><sup>or</sup>→ false</i>

See Also:

eql, equal, equalp, =, Section 3.2 (Compilation)

Notes:

Objects that appear the same when printed are not necessarily eq to each other. Symbols that print the same usually are eq to each other because of the use of the intern function. However, numbers with the same value need not be eq, and two similar lists are usually not identical.

An implementation is permitted to make “copies” of characters and numbers at any time. The effect is that Common Lisp makes no guarantee that eq is true even when both its arguments are “the same thing” if that thing is a character or number .

Most Common Lisp operators use eql rather than eq to compare objects, or else they default to eql and only use eq if specifically requested to do so. However, the following operators are defined to use eq rather than eql in a way that cannot be overridden by the code which employs them:

Data and Control

|

catch getf throw

get remf

get-properties remprop

|

| :- |

Figure 5–11. Operators that always prefer EQ over EQL

Expanded Reference: eq​

Basic identity comparison with symbols​

eq tests whether two objects are the exact same object in memory. Symbols with the same name are always eq because the reader interns them to the same object.

(eq 'hello 'hello) → T
(eq 'a 'b) → NIL

Cons cells are never eq unless they are the same object​

Two separately constructed cons cells are never eq, even if they contain the same elements. Only the exact same cons cell is eq to itself.

(eq (cons 1 2) (cons 1 2)) → NIL

(let ((x (cons 1 2)))
  (eq x x)) → T

Numbers and characters are unreliable with eq​

The standard does not guarantee that eq returns true for numbers or characters, even when they have the same value. Implementations may or may not cache these objects. Use eql instead for reliable number and character comparison.

;; Symbols are always reliably eq
(eq 'foo 'foo) → T

;; Numbers may or may not be eq -- implementation-dependent
(eq 3 3) → T ; or NIL -- unspecified

;; Different numeric types are never eq
(eq 3 3.0) → NIL

;; Characters may or may not be eq -- implementation-dependent
(eq #\A #\A) → T ; or NIL -- unspecified

Strings are only eq when they are the same object​

Strings that look the same are not necessarily the same object. Use equal or string= for string comparison.

(let ((s "hello"))
  (eq s s)) → T

(eq "hello" (copy-seq "hello")) → NIL

Practical use: checking for specific sentinel objects​

eq is commonly used to check for sentinel values like NIL, or when you need to know if two variables reference the exact same mutable object.

(let ((sentinel (list 'unique)))
  (eq sentinel sentinel)) → T

(eq nil '()) → T
(eq t 't) → T