User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

cl:functions:equalp [2019/06/15 02:00]
cl:functions:equalp [2019/11/19 12:00] (current)
Line 1: Line 1:
 +====== Function EQUALP ======
 +
 +====Syntax====
 +  * **equalp** //x y// → //​generalized-boolean//​
 +
 +====Arguments and Values====
 +  * //x// - an //​[[CL:​Glossary:​object]]//​.
 +  * //y// - an //​[[CL:​Glossary:​object]]//​.
 +  * //​generalized-boolean//​ - a //​[[CL:​Glossary:​generalized boolean]]//​.
 +
 +====Description====
 +Returns //​[[CL:​Glossary:​true]]//​ if //x// and //y// are **[[CL:​Functions:​equal]]**,​ or if they have components that are of the same //​[[CL:​Glossary:​type]]//​ as each other and if those components are **equalp**; specifically,​ **equalp** returns //​[[CL:​Glossary:​true]]//​ in the following cases: ​
 +
 +===Characters===
 +If two //​[[CL:​Glossary:​characters]]//​ are **[[CL:​Functions:​char-equal]]**.
 +
 +===Numbers===
 +If two //​[[CL:​Glossary:​numbers]]//​ are the //​[[CL:​Glossary:​same]]//​ under **[[CL:​Functions:​=]]**.
 +
 +===Conses===
 +If the two //​[[CL:​Glossary:​cars]]//​ in the //​[[CL:​Glossary:​conses]]//​ are **equalp** and the two //​[[CL:​Glossary:​cdrs]]//​ in the //​[[CL:​Glossary:​conses]]//​ are **equalp**.
 +
 +===Arrays===
 +If two //​[[CL:​Glossary:​array|arrays]]//​ have the same number of dimensions, the dimensions match, and the corresponding //​[[CL:​Glossary:​active elements]]//​ are **equalp**. The //​[[CL:​Glossary:​types]]//​ for which the //​[[CL:​Glossary:​array|arrays]]//​ are //​[[CL:​Glossary:​specialized]]//​ need not match; for example, a //​[[CL:​Glossary:​string]]//​ and a general //​[[CL:​Glossary:​array]]//​ that happens to contain the same //​[[CL:​Glossary:​characters]]//​ are **equalp**.
 +
 +Because **equalp** performs //​[[CL:​Glossary:​element]]//​-by-//​[[CL:​Glossary:​element]]//​ comparisons of //​[[CL:​Glossary:​strings]]//​ and ignores the //​[[CL:​Glossary:​case]]//​ of //​[[CL:​Glossary:​characters]]//,​ //​[[CL:​Glossary:​case]]//​ distinctions are ignored when **equalp** compares //​[[CL:​Glossary:​strings]]//​.
 +
 +===Structures===
 +If two //​[[CL:​Glossary:​structures]]//​ ''​S<​sub>​1</​sub>''​ and ''​S<​sub>​2</​sub>''​ have the same //​[[CL:​Glossary:​class]]//​ and the value of each //​[[CL:​Glossary:​slot]]//​ in ''​S<​sub>​1</​sub>''​ is the //​[[CL:​Glossary:​same]]//​ under **equalp** as the value of the corresponding //​[[CL:​Glossary:​slot]]//​ in ''​S<​sub>​2</​sub>''​.
 +
 +===Hash tables===
 +**equalp** descends //​[[CL:​Glossary:​hash-tables]]//​ by first comparing the count of entries and the **'':​test''​** function; if those are the same, it compares the keys of the tables using the **'':​test''​** function and then the values of the matching keys using **equalp** recursively.
 +
 +**equalp** does not descend any //​[[CL:​Glossary:​object|objects]]//​ other than the ones explicitly specified above. The below table summarizes the information given in the previous list. In addition, the table specifies the priority of the behavior of **equalp**, with upper entries taking priority over lower ones.
 +
 +^ Type                             ^ Behavior ​                            ^
 +| //​[[CL:​Glossary:​number]]// ​      | uses **[[CL:​Functions:​=]]** ​         |
 +| //​[[CL:​Glossary:​character]]// ​   | uses **[[CL:​Functions:​char-equal]]** |
 +| //​[[CL:​Glossary:​cons]]// ​        | descends ​                            |
 +| //​[[CL:​Glossary:​bit vector]]// ​  | descends ​                            |
 +| //​[[CL:​Glossary:​string]]// ​      | descends ​                            |
 +| //​[[CL:​Glossary:​pathname]]// ​    | same as **[[CL:​Functions:​equal]]** ​  |
 +| //​[[CL:​Glossary:​structure]]// ​   | descends, as described above         |
 +| Other //​[[CL:​Glossary:​array]]// ​ | descends ​                            |
 +| //​[[CL:​Glossary:​hash table]]// ​  | descends, as described above         |
 +| Other //​[[CL:​Glossary:​object]]//​ | uses **[[CL:​Functions:​eq]]** ​        |
 +
 +====Examples====
 +<​blockquote> ​
 +(equalp 'a 'b) <​r>//​[[CL:​Glossary:​false]]//​ </r>
 +(equalp 'a 'a) <​r>//​[[CL:​Glossary:​true]]//​ </r>
 +(equalp 3 3) <​r>//​[[CL:​Glossary:​true]]//​ </r>
 +(equalp 3 3.0) <​r>//​[[CL:​Glossary:​true]]//​ </r>
 +(equalp 3.0 3.0) <​r>//​[[CL:​Glossary:​true]]//​ </r>
 +(equalp #c(3 -4) #c(3 -4)) <​r>//​[[CL:​Glossary:​true]]//​ </r>
 +(equalp #c(3 -4.0) #c(3 -4)) <​r>//​[[CL:​Glossary:​true]]//​ </r>
 +(equalp ([[CL:​Functions:​cons]] 'a 'b) ([[CL:​Functions:​cons]] 'a 'c)) <​r>//​[[CL:​Glossary:​false]]//​ </r>
 +(equalp ([[CL:​Functions:​cons]] 'a 'b) ([[CL:​Functions:​cons]] 'a 'b)) <​r>//​[[CL:​Glossary:​true]]//​ </r>
 +(equalp #\\A #\\A) <​r>//​[[CL:​Glossary:​true]]//​ </r>
 +(equalp #\\A #\\a) <​r>//​[[CL:​Glossary:​true]]//​ </r>
 +(equalp "​Foo"​ "​Foo"​) <​r>//​[[CL:​Glossary:​true]]//​ </r>
 +(equalp "​Foo"​ (copy-seq "​Foo"​)) <​r>//​[[CL:​Glossary:​true]]//​ </r>
 +(equalp "​FOO"​ "​foo"​) <​r>//​[[CL:​Glossary:​true]]//​ </r>
 +([[CL:​Macros:​defparameter]] *array1*
 +  ([[CL:​Functions:​make-array]] 6 :​element-type '​[[CL:​Types:​integer]] :​initial-contents '(1 1 1 3 5 7))) <​r>​*ARRAY1*</​r>​
 +([[CL:​Macros:​defparameter]] *array2*
 +  ([[CL:​Functions:​make-array]] 8 :​element-type '​[[CL:​Types:​integer]] :​initial-contents '(1 1 1 3 5 7 2 6) :​fill-pointer 6)) <​r>​*ARRAY2*</​r>​
 +(equalp *array1* *array2*) <​r>//​[[CL:​Glossary:​true]]//​ </r>
 +([[CL:​Macros:​defparameter]] *vector1* ​
 +  ([[CL:​Functions:​vector]] 1 1 1 3 5 7)) <​r>​*VECTOR1*</​r>​
 +(equalp *array1* *vector1*) <​r>//​[[CL:​Glossary:​true]]//​ </r>
 +</​blockquote>​
 +
 +====Side Effects====
 +None.
 +
 +====Affected By====
 +None.
 +
 +====Exceptional Situations====
 +None.
 +
 +====See Also====
 +  * **[[CL:​Functions:​eq|Function EQ]]**
 +  * **[[CL:​Functions:​eql|Function EQL]]**
 +  * **[[CL:​Functions:​equalp|Function EQUAL]]**
 +  * **[[CL:​Functions:​math-equal|Function =]]**
 +  * **[[CL:​Functions:​string-equal|Function STRING=]]**
 +  * **[[CL:​Functions:​string-equal|Function STRING-EQUAL]]**
 +  * **[[CL:​Functions:​char-equal|Function CHAR=]]**
 +  * **[[CL:​Functions:​char-equal|Function CHAR-EQUAL]]**
 +
 +====Notes====
 +//​[[CL:​Glossary:​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, **[[CL:​Functions:​equal]]** and **equalp** are not appropriate for every application.
 +
 +\issue{EQUAL-STRUCTURE:​MAYBE-STATUS-QUO} \issue{EQUAL-STRUCTURE:​MAYBE-STATUS-QUO} \issue{EQUAL-STRUCTURE:​MAYBE-STATUS-QUO}