8.8 Equality Predicates

Here we describe two functions that test for equality between any two objects. Other functions test equality between objects of specific types, e.g., strings. For these predicates, see the appropriate chapter describing the data type.

Function: eq object1 object2

This function returns t if object1 and object2 are the same object, nil otherwise. The “same object” means that a change in one will be reflected by the same change in the other.

eq returns t if object1 and object2 are integers with the same value. Also, since symbol names are normally unique, if the arguments are symbols with the same name, they are eq. For other types (e.g., lists, vectors, strings), two arguments with the same contents or elements are not necessarily eq to each other: they are eq only if they are the same object.

(The make-symbol function returns an uninterned symbol that is not interned in the standard obarray. When uninterned symbols are in use, symbol names are no longer unique. Distinct symbols with the same name are not eq. See Creating Symbols.)

NOTE: Under XEmacs 19, characters are really just integers, and thus characters and integers are eq. Under SXEmacs and XEmacs 20+, it was necessary to preserve remnants of this in function such as old-eq in order to maintain byte-code compatibility. Byte code compiled under any Emacs 19 will automatically have calls to eq mapped to old-eq when executed under SXEmacs or XEmacs 20+.

(eq 'foo 'foo)
     ⇒ t

(eq 456 456)
     ⇒ t

(eq "asdf" "asdf")
     ⇒ nil

(eq '(1 (2 (3))) '(1 (2 (3))))
     ⇒ nil

(setq foo '(1 (2 (3))))
     ⇒ (1 (2 (3)))
(eq foo foo)
     ⇒ t
(eq foo '(1 (2 (3))))
     ⇒ nil

(eq [(1 2) 3] [(1 2) 3])
     ⇒ nil

(eq (point-marker) (point-marker))
     ⇒ nil

Function: old-eq object1 object2

This function exists under SXEmacs and XEmacs 20+ and is exactly like eq except that it suffers from the char-int confoundance disease. In other words, it returns t if given a character and the equivalent integer, even though the objects are of different types! You should not ever call this function explicitly in your code. However, be aware that all calls to eq in byte code compiled under version 19 map to old-eq in SXEmacs or XEmacs 20+.

Likewise for old-equal, old-memq, old-member, old-assq and old-assoc.

;; Remember, this does not apply under XEmacs 19.
?A
     ⇒ ?A
(char-int ?A)
     ⇒ 65
(old-eq ?A 65)
     ⇒ t               ; Eek, we’ve been infected.
(eq ?A 65)
     ⇒ nil             ; We are still healthy.

Function: equal object1 object2

This function returns t if object1 and object2 have equal components, nil otherwise. Whereas eq tests if its arguments are the same object, equal looks inside nonidentical arguments to see if their elements are the same. So, if two objects are eq, they are equal, but the converse is not always true.

(equal 'foo 'foo)
     ⇒ t

(equal 456 456)
     ⇒ t

(equal "asdf" "asdf")
     ⇒ t

(eq "asdf" "asdf")
     ⇒ nil

(equal '(1 (2 (3))) '(1 (2 (3))))
     ⇒ t

(eq '(1 (2 (3))) '(1 (2 (3))))
     ⇒ nil

(equal [(1 2) 3] [(1 2) 3])
     ⇒ t

(eq [(1 2) 3] [(1 2) 3])
     ⇒ nil

(equal (point-marker) (point-marker))
     ⇒ t

(eq (point-marker) (point-marker))
     ⇒ nil

Comparison of strings is case-sensitive.

Note that in FSF GNU Emacs, comparison of strings takes into account their text properties, and you have to use string-equal if you want only the strings themselves compared. This difference does not exist in SXEmacs; equal and string-equal always return the same value on the same strings.

(equal "asdf" "ASDF")
     ⇒ nil

Two distinct buffers are never equal, even if their contents are the same.

The test for equality is implemented recursively, and circular lists may therefore cause infinite recursion (leading to an error).