diff options
Diffstat (limited to 'devdocs/elisp/equality-predicates.html')
| -rw-r--r-- | devdocs/elisp/equality-predicates.html | 110 |
1 files changed, 110 insertions, 0 deletions
diff --git a/devdocs/elisp/equality-predicates.html b/devdocs/elisp/equality-predicates.html new file mode 100644 index 00000000..3eb7a1ac --- /dev/null +++ b/devdocs/elisp/equality-predicates.html @@ -0,0 +1,110 @@ + <h3 class="section">Equality Predicates</h3> <p>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. </p> <dl> <dt id="eq">Function: <strong>eq</strong> <em>object1 object2</em> +</dt> <dd> +<p>This function returns <code>t</code> if <var>object1</var> and <var>object2</var> are the same object, and <code>nil</code> otherwise. </p> <p>If <var>object1</var> and <var>object2</var> are symbols with the same name, they are normally the same object—but see <a href="creating-symbols">Creating Symbols</a> for exceptions. For other non-numeric types (e.g., lists, vectors, strings), two arguments with the same contents or elements are not necessarily <code>eq</code> to each other: they are <code>eq</code> 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. </p> <p>If <var>object1</var> and <var>object2</var> are numbers with differing types or values, then they cannot be the same object and <code>eq</code> returns <code>nil</code>. If they are fixnums with the same value, then they are the same object and <code>eq</code> returns <code>t</code>. If they were computed separately but happen to have the same value and the same non-fixnum numeric type, then they might or might not be the same object, and <code>eq</code> returns <code>t</code> or <code>nil</code> depending on whether the Lisp interpreter created one object or two. </p> <div class="example"> <pre class="example">(eq 'foo 'foo) + ⇒ t +</pre> + +<pre class="example">(eq ?A ?A) + ⇒ t +</pre> + +<pre class="example">(eq 3.0 3.0) + ⇒ t <span class="roman">or</span> nil +;; <span class="roman">Equal floats may or may not be the same object.</span> +</pre> + +<pre class="example">(eq (make-string 3 ?A) (make-string 3 ?A)) + ⇒ nil +</pre> + +<pre class="example">(eq "asdf" "asdf") + ⇒ t <span class="roman">or</span> nil +;; <span class="roman">Equal string constants or may not be the same object.</span> +</pre> + +<pre class="example">(eq '(1 (2 (3))) '(1 (2 (3)))) + ⇒ nil +</pre> + +<pre class="example">(setq foo '(1 (2 (3)))) + ⇒ (1 (2 (3))) +(eq foo foo) + ⇒ t +(eq foo '(1 (2 (3)))) + ⇒ nil +</pre> + +<pre class="example">(eq [(1 2) 3] [(1 2) 3]) + ⇒ nil +</pre> + +<pre class="example">(eq (point-marker) (point-marker)) + ⇒ nil +</pre> +</div> <p>The <code>make-symbol</code> 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 <code>eq</code>. See <a href="creating-symbols">Creating Symbols</a>. </p> <div class="example"> <pre class="example">(eq (make-symbol "foo") 'foo) + ⇒ nil +</pre> +</div> <p> The Emacs Lisp byte compiler may collapse identical literal objects, such as literal strings, into references to the same object, with the effect that the byte-compiled code will compare such objects as <code>eq</code>, while the interpreted version of the same code will not. Therefore, your code should never rely on objects with the same literal contents being either <code>eq</code> or not <code>eq</code>, it should instead use functions that compare object contents such as <code>equal</code>, described below. Similarly, your code should not modify literal objects (e.g., put text properties on literal strings), since doing that might affect other literal objects of the same contents, if the byte compiler collapses them. </p> +</dd> +</dl> <dl> <dt id="equal">Function: <strong>equal</strong> <em>object1 object2</em> +</dt> <dd> +<p>This function returns <code>t</code> if <var>object1</var> and <var>object2</var> have equal components, and <code>nil</code> otherwise. Whereas <code>eq</code> tests if its arguments are the same object, <code>equal</code> looks inside nonidentical arguments to see if their elements or contents are the same. So, if two objects are <code>eq</code>, they are <code>equal</code>, but the converse is not always true. </p> <div class="example"> <pre class="example">(equal 'foo 'foo) + ⇒ t +</pre> + +<pre class="example">(equal 456 456) + ⇒ t +</pre> + +<pre class="example">(equal "asdf" "asdf") + ⇒ t +</pre> +<pre class="example">(eq "asdf" "asdf") + ⇒ nil +</pre> + +<pre class="example">(equal '(1 (2 (3))) '(1 (2 (3)))) + ⇒ t +</pre> +<pre class="example">(eq '(1 (2 (3))) '(1 (2 (3)))) + ⇒ nil +</pre> + +<pre class="example">(equal [(1 2) 3] [(1 2) 3]) + ⇒ t +</pre> +<pre class="example">(eq [(1 2) 3] [(1 2) 3]) + ⇒ nil +</pre> + +<pre class="example">(equal (point-marker) (point-marker)) + ⇒ t +</pre> + +<pre class="example">(eq (point-marker) (point-marker)) + ⇒ nil +</pre> +</div> <p>Comparison of strings is case-sensitive, but does not take account of text properties—it compares only the characters in the strings. See <a href="text-properties">Text Properties</a>. Use <code>equal-including-properties</code> to also compare text properties. For technical reasons, a unibyte string and a multibyte string are <code>equal</code> if and only if they contain the same sequence of character codes and all these codes are in the range 0 through 127 (<acronym>ASCII</acronym>). </p> <div class="example"> <pre class="example">(equal "asdf" "ASDF") + ⇒ nil +</pre> +</div> <p>The <code>equal</code> function recursively compares the contents of objects if they are integers, strings, markers, vectors, bool-vectors, byte-code function objects, char-tables, records, or font objects. Other objects are considered <code>equal</code> only if they are <code>eq</code>. For example, two distinct buffers are never considered <code>equal</code>, even if their textual contents are the same. </p> +</dd> +</dl> <p>For <code>equal</code>, equality is defined recursively; for example, given two cons cells <var>x</var> and <var>y</var>, <code>(equal <var>x</var> <var>y</var>)</code> returns <code>t</code> if and only if both the expressions below return <code>t</code>: </p> <div class="example"> <pre class="example">(equal (car <var>x</var>) (car <var>y</var>)) +(equal (cdr <var>x</var>) (cdr <var>y</var>)) +</pre> +</div> <p>Comparing circular lists may therefore cause deep recursion that leads to an error, and this may result in counterintuitive behavior such as <code>(equal a b)</code> returning <code>t</code> whereas <code>(equal b a)</code> signals an error. </p> <dl> <dt id="equal-including-properties">Function: <strong>equal-including-properties</strong> <em>object1 object2</em> +</dt> <dd> +<p>This function behaves like <code>equal</code> in all cases but also requires that for two strings to be equal, they have the same text properties. </p> <div class="example"> <pre class="example">(equal "asdf" (propertize "asdf" 'asdf t)) + ⇒ t +</pre> +<pre class="example">(equal-including-properties "asdf" + (propertize "asdf" 'asdf t)) + ⇒ nil +</pre> +</div> </dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Equality-Predicates.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Equality-Predicates.html</a> + </p> +</div> |