Skip to main content

eql

eql Function

Syntax:

eql x y → generalized-boolean

Arguments and Values:

x—an object.

y—an object.

generalized-boolean—a generalized boolean.

Description:

The value of eql is true of two objects, x and y, in the folowing cases:

1. If x and y are eq.

2. If x and y are both numbers of the same type and the same value.

3. If they are both characters that represent the same character.

Otherwise the value of eql is false.

If an implementation supports positive and negative zeros as distinct values, then (eql 0.0 -0.0) returns false. Otherwise, when the syntax -0.0 is read it is interpreted as the value 0.0, and so (eql 0.0 -0.0) returns true.

Examples:

(eql ’a ’b) → false 
(eql ’a ’a) → true 
(eql 3 3) → true 
(eql 3 3.0) → false 
(eql 3.0 3.0) → true 
(eql #c(3 -4) #c(3 -4)) → true 
(eql #c(3 -4.0) #c(3 -4)) → false 
(eql (cons ’a ’b) (cons ’a ’c)) → false 

(eql (cons ’a ’b) (cons ’a ’b)) → false 
(eql ’(a . b) ’(a . b)) 
→ true 
<i><sup>or</sup>→ false</i> 
(progn (setq x (cons ’a ’b)) (eql x x)) → true 
(progn (setq x ’(a . b)) (eql x x)) → true 
(eql #\A #\A) → true 
(eql "Foo" "Foo") 
→ true 
<i><sup>or</sup>→ false</i> 
(eql "Foo" (copy-seq "Foo")) → false 
(eql "FOO" "foo") → false 
Normally (eql 1.0s0 1.0d0) is false, under the assumption that 1.0s0 and 1.0d0 are of distinct data types. However, implementations that do not provide four distinct floating-point formats are permitted to “collapse” the four formats into some smaller number of them; in such an implementation (eql 1.0s0 1.0d0) might be true.

See Also:

eq, equal, equalp, =, char=

Notes:

eql is the same as eq, except that if the arguments are characters or numbers of the same type then their values are compared. Thus eql tells whether two objects are conceptually the same, whereas eq tells whether two objects are implementationally identical. It is for this reason that eql, not eq, is the default comparison predicate for operators that take sequences as arguments.

eql may not be true of two floats even when they represent the same value. = is used to compare mathematical values.

Two complex numbers are considered to be eql if their real parts are eql and their imaginary parts are eql. For example, (eql #C(4 5) #C(4 5)) is true and (eql #C(4 5) #C(4.0 5.0)) is false. Note that while (eql #C(5.0 0.0) 5.0) is false, (eql #C(5 0) 5) is true. In the case of

(eql #C(5.0 0.0) 5.0) the two arguments are of different types, and so cannot satisfy eql. In the case of (eql #C(5 0) 5), #C(5 0) is not a complex number, but is automatically reduced to the integer 5.

Expanded Reference: eql​

Basic value comparison​

eql is the default comparison predicate in Common Lisp. It is like eq but additionally guarantees correct comparison for numbers of the same type and for characters.

(eql 'a 'a) → T
(eql 'a 'b) → NIL
(eql 3 3) → T
(eql #\A #\A) → T

Numbers must be the same type and value​

eql only considers numbers equal when they are of the same type and have the same value. It does not perform numeric type coercion.

(eql 3 3) → T
(eql 3 3.0) → NIL
(eql 3.0 3.0) → T
(eql #c(3 -4) #c(3 -4)) → T
(eql #c(3 -4.0) #c(3 -4)) → NIL

Lists and other compound objects​

Like eq, eql does not descend into compound structures. Two separately constructed lists are not eql.

(eql (cons 'a 'b) (cons 'a 'b)) → NIL

(let ((x (list 1 2 3)))
  (eql x x)) → T

Strings are not compared by content​

eql does not compare string contents. Use equal or string= for that.

(eql "Foo" (copy-seq "Foo")) → NIL
(eql "FOO" "foo") → NIL

eql as the default test in standard functions​

Many standard functions like member, assoc, and find use eql as their default :test. This is why they work naturally with numbers and characters.

(member 3 '(1 2 3 4 5)) → (3 4 5)
(assoc 2 '((1 . a) (2 . b) (3 . c))) → (2 . B)
(find #\a "banana") → #\a