elisp: Equality Predicates
2.7 Equality Predicates
=======================
Here we describe functions that test for equality between two objects.
Other functions test equality of contents 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, and ‘nil’ otherwise.
If OBJECT1 and OBJECT2 are integers with the same value, they are
considered to be the same object (i.e., ‘eq’ returns ‘t’). If
OBJECT1 and OBJECT2 are symbols with the same name, they are
normally the same object—but see 
Creating Symbols for
exceptions. 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,
meaning that a change in the contents of one will be reflected by
the same change in the contents of the other.
(eq 'foo 'foo)
⇒ t
(eq 456 456)
⇒ t
(eq "asdf" "asdf")
⇒ nil
(eq "" "")
⇒ t
;; This exception occurs because Emacs Lisp
;; makes just one multibyte empty string, to save space.
(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
The ‘make-symbol’ function returns an uninterned symbol, distinct
from the symbol that is used if you write the name in a Lisp
expression. Distinct symbols with the same name are not ‘eq’.
Creating Symbols.
(eq (make-symbol "foo") 'foo)
⇒ nil
-- Function: equal object1 object2
This function returns ‘t’ if OBJECT1 and OBJECT2 have equal
components, and ‘nil’ otherwise. Whereas ‘eq’ tests if its
arguments are the same object, ‘equal’ looks inside nonidentical
arguments to see if their elements or contents 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, but does not take account
of text properties—it compares only the characters in the strings.
Text Properties. Use ‘equal-including-properties’ to also
compare text properties. For technical reasons, a unibyte string
and a multibyte string are ‘equal’ if and only if they contain the
same sequence of character codes and all these codes are either in
the range 0 through 127 (ASCII) or 160 through 255
(‘eight-bit-graphic’). (Text Representations).
(equal "asdf" "ASDF")
⇒ nil
However, two distinct buffers are never considered ‘equal’, even if
their textual contents are the same.
The test for equality is implemented recursively; for example, given
two cons cells X and Y, ‘(equal X Y)’ returns ‘t’ if and only if both
the expressions below return ‘t’:
(equal (car X) (car Y))
(equal (cdr X) (cdr Y))
Because of this recursive method, circular lists may therefore cause
infinite recursion (leading to an error).
-- Function: equal-including-properties object1 object2
This function behaves like ‘equal’ in all cases but also requires
that for two strings to be equal, they have the same text
properties.
(equal "asdf" (propertize "asdf" 'asdf t))
⇒ t
(equal-including-properties "asdf"
(propertize "asdf" 'asdf t))
⇒ nil
Info Catalog
elisp: Type Predicates
elisp: Lisp Data Types