Function equal

Syntax:

Arguments and Values:

x—an object.

y—an object.

generalized-boolean—a generalized boolean.

Description:

6.3.0 12Returns true if x and y are structurally similar (isomorphic) objects. Objects are treated as follows by equal.

• Symbols, Numbers, and Characters

  6.3.0 13equal is true of two objects if they are symbols that are eq, if they are numbers that are eql, or if they are characters that are eql.

• Conses

  6.3.0 15For conses, equal is defined recursively as the two cars being equal and the two cdrs being equal.

• Arrays

  6.3.0 16Two arrays are equal only if they are eq, with one exception: strings and bit vectors are compared element-by-element (using eql). If either x or y has a fill pointer, the fill pointer limits the number of elements examined by equal. Uppercase and lowercase letters in strings are considered by equal to be different.

• Pathnames

  6.3.0 18Two pathnames are equal if and only if all the corresponding components (host, device, and so on) are !!! Barmar: "equivalent" ???equivalent. Whether or not uppercase and lowercase letters are considered equivalent in strings appearing in components is implementation-dependent. pathnames that are equal should be functionally equivalent.

  Barmar didn't think this belonged here. I agree. 23.1.1 19 For \term{pathnames}, \funref{eql} is the same as \funref{eq}.

• Other (Structures, hash-tables, instances, $\dots$)

  Two other objects are equal only if they are eq.

  Barmar: "EQUAL" or "EQUALP" in this next ??? Moon: Delete this. This is EQUAL, not EQUALP The following was added at the June 1989 meeting A structure defined by \macref{defstruct} without an explicit \kwd{type} option is called non-typed; otherwise it is typed. The definition of \funref{equalp} on \macref{defstruct} instances is as follows: \funref{equalp} on two \macref{defstruct} instances \f{s1} and \f{s2}, where both are non-typed structures, is \term{true} if and only if: \beginlist \itemitem{1.} The \term{type} of \f{s1} is the same as the type of \f{s2}. \itemitem{2.} The value of each \term{slot} of \f{s1} is \funref{equalp} to the value of the same \term{slot} of \f{s2}. \endlist

equal does not descend any objects other than the ones explicitly specified above. The next figure summarizes the information given in the previous list. !!! Moon: Strange way to phrase it.In addition, the figure specifies the priority of the behavior of equal, with upper entries taking priority over lower ones.

Any two objects that are eql are also equal.

equal may fail to terminate if x or y is circular.

Examples:

 (equal 'a 'b) → false
 (equal 'a 'a) → true
 (equal 3 3) → true
 (equal 3 3.0) → false
 (equal 3.0 3.0) → true
 (equal #c(3 -4) #c(3 -4)) → true
 (equal #c(3 -4.0) #c(3 -4)) → false
 (equal (cons 'a 'b) (cons 'a 'c)) → false
 (equal (cons 'a 'b) (cons 'a 'b)) → true
 (equal #\A #\A) → true
 (equal #\A #\a) → false
 (equal "Foo" "Foo") → true
 (equal "Foo" (copy-seq "Foo")) → true
 (equal "FOO" "foo") → false
 (equal "This-string" "This-string") → true
 (equal "This-string" "this-string") → false

Side Effects:

None.

Affected By:

None.

Exceptional Situations:

None.

See Also:

eq, eql, equalp, =, string=, string-equal, char=, char-equal, tree-equal

Notes:

Object equality is not a concept for which there is a uniquely determined correct algorithm. The appropriateness of an equality predicate can be judged only in the context of the needs of some particular program. Although these functions take any type of argument and their names sound very generic, equal and equalp are not appropriate for every application.

A rough rule of thumb is that two objects are equal if and only if their printed representations are the same.