GNU Info

(elisp)Equality Predicates

---

Prev: Type Predicates Up: Lisp Data Types

---

Enter node , (file) or (file)node

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.

          (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

     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'.
     Note: Creating Symbols.

          (eq (make-symbol "foo") 'foo)
               => nil

 - 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 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.
     A unibyte string never equals a multibyte string unless the
     contents are entirely ASCII (Note: 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).