Go to the first, previous, next, last section, table of contents.

# Predicates

This section describes functions for testing whether various facts are true or false.

- Type Predicates: `typep', `deftype', and `coerce'
- Equality Predicates: `eql' and `equalp'

## Type Predicates

The CL package defines a version of the Common Lisp `typep` predicate.

Function: typep object type
  Check if object is of type type, where type is a (quoted) type name of the sort used by Common Lisp. For example, `(typep foo 'integer)` is equivalent to `(integerp foo)`.

The type argument to the above function is either a symbol or a list beginning with a symbol.

- If the type name is a symbol, Emacs appends ``-p'` to the symbol name to form the name of a predicate function for testing the type. (Built-in predicates whose names end in ``p'` rather than ``-p'` are used when appropriate.)
- The type symbol `t` stands for the union of all types. `(typep object t)` is always true. Likewise, the type symbol `nil` stands for nothing at all, and `(typep object nil)` is always false.
- The type symbol `null` represents the symbol `nil`. Thus `(typep object 'null)` is equivalent to `(null object)`.
- The type symbol `real` is a synonym for `number`, and `fixnum` is a synonym for `integer`.
- The type symbols `character` and `string-char` match integers in the range from 0 to 255.
- The type symbol `float` uses the `floatp-safe` predicate defined by this package rather than `floatp`, so it will work correctly even in Emacs versions without floating-point support.
- The type list `(integer low high)` represents all integers between low and high, inclusive. Either bound may be a list of a single integer to specify an exclusive limit, or a `*` to specify no limit. The type `(integer * *)` is thus equivalent to `integer`.
- Likewise, lists beginning with `float`, `real`, or `number` represent numbers of that type falling in a particular range.
- Lists beginning with `and`, `or`, and `not` form combinations of types. For example, `(or integer (float 0 *))` represents all objects that are integers or non-negative floats.
- Lists beginning with `member` or `member*` represent objects `eql` to any of the following values. For example, `(member 1 2 3 4)` is equivalent to `(integer 1 4)`, and `(member nil)` is equivalent to `null`.
- Lists of the form `(satisfies predicate)` represent all objects for which predicate returns true when called with that object as an argument.

The following function and macro (not technically predicates) are related to `typep`.

Function: coerce object type
  This function attempts to convert object to the specified type. If object is already of that type as determined by `typep`, it is simply returned. Otherwise, certain types of conversions will be made: If type is any sequence type (`string`, `list`, etc.) then object will be converted to that type if possible. If type is `character`, then strings of length one and symbols with one-character names can be coerced. If type is `float`, then integers can be coerced in versions of Emacs that support floats. In all other circumstances, `coerce` signals an error.

Special Form: deftype name arglist forms...
  This macro defines a new type called name. It is similar to `defmacro` in many ways; when name is encountered as a type name, the body forms are evaluated and should return a type specifier that is equivalent to the type. The arglist is a Common Lisp argument list of the sort accepted by `defmacro*`. The type specifier ``(name args...)'` is expanded by calling the expander with those arguments; the type symbol ``name'` is expanded by calling the expander with no arguments. The arglist is processed the same as for `defmacro*` except that optional arguments without explicit defaults use `*` instead of `nil` as the "default" default. Some examples:

      (deftype null () '(satisfies null))    ; predefined
      (deftype list () '(or null cons))      ; predefined
      (deftype unsigned-byte (&optional bits)
        (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits)))))
      (unsigned-byte 8)  ==  (integer 0 255)
      (unsigned-byte)  ==  (integer 0 *)
      unsigned-byte  ==  (integer 0 *)

  The last example shows how the Common Lisp `unsigned-byte` type specifier could be implemented if desired; this package does not implement `unsigned-byte` by default.

The `typecase` and `check-type` macros also use type names. See section Conditionals. See section Assertions and Errors. The `map`, `concatenate`, and `merge` functions take type-name arguments to specify the type of sequence to return. See section Sequences.

## Equality Predicates

This package defines two Common Lisp predicates, `eql` and `equalp`.

Function: eql a b
  This function is almost the same as `eq`, except that if a and b are numbers of the same type, it compares them for numeric equality (as if by `equal` instead of `eq`). This makes a difference only for versions of Emacs that are compiled with floating-point support, such as Emacs 19. Emacs floats are allocated objects just like cons cells, which means that `(eq 3.0 3.0)` will not necessarily be true--if the two `3.0`s were allocated separately, the pointers will be different even though the numbers are the same. But `(eql 3.0 3.0)` will always be true.

  The types of the arguments must match, so `(eql 3 3.0)` is still false.

  Note that Emacs integers are "direct" rather than allocated, which basically means `(eq 3 3)` will always be true. Thus `eq` and `eql` behave differently only if floating-point numbers are involved, and are indistinguishable on Emacs versions that don't support floats.

  There is a slight inconsistency with Common Lisp in the treatment of positive and negative zeros. Some machines, notably those with IEEE standard arithmetic, represent `+0` and `-0` as distinct values. Normally this doesn't matter because the standard specifies that `(= 0.0 -0.0)` should always be true, and this is indeed what Emacs Lisp and Common Lisp do. But the Common Lisp standard states that `(eql 0.0 -0.0)` and `(equal 0.0 -0.0)` should be false on IEEE-like machines; Emacs Lisp does not do this, and in fact the only known way to distinguish between the two zeros in Emacs Lisp is to `format` them and check for a minus sign.

Function: equalp a b
  This function is a more flexible version of `equal`. In particular, it compares strings case-insensitively, and it compares numbers without regard to type (so that `(equalp 3 3.0)` is true). Vectors and conses are compared recursively. All other objects are compared as if by `equal`.

  This function differs from Common Lisp `equalp` in several respects. First, Common Lisp's `equalp` also compares characters case-insensitively, which would be impractical in this package since Emacs does not distinguish between integers and characters. In keeping with the idea that strings are less vector-like in Emacs Lisp, this package's `equalp` also will not compare strings against vectors of integers. Finally, Common Lisp's `equalp` compares hash tables without regard to ordering, whereas this package simply compares hash tables in terms of their underlying structure (which means vectors for Lucid Emacs 19 hash tables, or lists for other hash tables).

Also note that the Common Lisp functions `member` and `assoc` use `eql` to compare elements, whereas Emacs Lisp follows the MacLisp tradition and uses `equal` for these two functions. In Emacs, use `member*` and `assoc*` to get functions which use `eql` for comparisons.

Go to the first, previous, next, last section, table of contents.