lispref.info: Equality Predicates

Lisp Data Types

Type Predicates

Back to Software Index

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

     NOTE: Under XEmacs 19, characters are really just integers, and
     thus characters and integers are `eq'.  Under XEmacs 20, it was
     necessary to preserve remants 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 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 OBJ1 OBJ2
     This function exists under 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 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 XEmacs; `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).