SXEmacs Lisp Reference Manual: Type Predicates

8.7 Type Predicates

The SXEmacs Lisp interpreter itself does not perform type checking on the actual arguments passed to functions when they are called. It could not do so, since function arguments in Lisp do not have declared data types, as they do in other programming languages. It is therefore up to the individual function to test whether each actual argument belongs to a type that the function can use.

All built-in functions do check the types of their actual arguments when appropriate, and signal a wrong-type-argument error if an argument is of the wrong type. For example, here is what happens if you pass an argument to + that it cannot handle:

(+ 2 'a)
     error→ Wrong type argument: integer-or-marker-p, a

If you want your program to handle different types differently, you must do explicit type checking. The most common way to check the type of an object is to call a type predicate function. SXEmacs has a type predicate for each type, as well as some predicates for combinations of types.

A type predicate function takes one argument; it returns t if the argument belongs to the appropriate type, and nil otherwise. Following a general Lisp convention for predicate functions, most type predicates’ names end with ‘p’.

Here is an example which uses the predicates listp to check for a list and symbolp to check for a symbol.

(defun add-on (x)
  (cond ((symbolp x)
         ;; If X is a symbol, put it on LIST.
         (setq list (cons x list)))
        ((listp x)
         ;; If X is a list, add its elements to LIST.
         (setq list (append x list)))
        (t
         ;; We only handle symbols and lists.
         (error "Invalid argument %s in add-on" x))))

Here is a table of predefined type predicates, in alphabetical order, with references to further information.

annotationp: See annotationp.
arrayp: See arrayp.
atom: See atom.
bit-vector-p: See bit-vector-p.
bitp: See bitp.
boolean-specifier-p: See boolean-specifier-p.
buffer-glyph-p: See buffer-glyph-p.
buffer-live-p: See buffer-live-p.
bufferp: See bufferp.
button-event-p: See button-event-p.
button-press-event-p: See button-press-event-p.
button-release-event-p: See button-release-event-p.
case-table-p: See case-table-p.
char-int-p: See char-int-p.
char-or-char-int-p: See char-or-char-int-p.
char-or-string-p: See char-or-string-p.
char-table-p: See char-table-p.
characterp: See characterp.
color-instance-p: See color-instance-p.
color-pixmap-image-instance-p: See color-pixmap-image-instance-p.
color-specifier-p: See color-specifier-p.
commandp: See commandp.
compiled-function-p: See compiled-function-p.
console-live-p: See console-live-p.
consolep: See consolep.
consp: See consp.
database-live-p: See database-live-p.
databasep: See databasep.
device-live-p: See device-live-p.
device-or-frame-p: See device-or-frame-p.
devicep: See devicep.
eval-event-p: See eval-event-p.
event-live-p: See event-live-p.
eventp: See eventp.
extent-live-p: See extent-live-p.
extentp: See extentp.
face-boolean-specifier-p: See face-boolean-specifier-p.
facep: See facep.
floatp: See floatp.
font-instance-p: See font-instance-p.
font-specifier-p: See font-specifier-p.
frame-live-p: See frame-live-p.
framep: See framep.
functionp: (not yet documented)
generic-specifier-p: See generic-specifier-p.
glyphp: See glyphp.
hash-table-p: See hash-table-p.
icon-glyph-p: See icon-glyph-p.
image-instance-p: See image-instance-p.
image-specifier-p: See image-specifier-p.
integer-char-or-marker-p: See integer-char-or-marker-p.
integer-or-char-p: See integer-or-char-p.
integer-or-marker-p: See integer-or-marker-p.
integer-specifier-p: See integer-specifier-p.
integerp: See integerp.
itimerp: (not yet documented)
key-press-event-p: See key-press-event-p.
keymapp: See keymapp.
keywordp: (not yet documented)
listp: See listp.
markerp: See markerp.
misc-user-event-p: See misc-user-event-p.
mono-pixmap-image-instance-p: See mono-pixmap-image-instance-p.
motion-event-p: See motion-event-p.
mouse-event-p: See mouse-event-p.
natnum-specifier-p: See natnum-specifier-p.
natnump: See natnump.
nlistp: See nlistp.
nothing-image-instance-p: See nothing-image-instance-p.
number-char-or-marker-p: See number-char-or-marker-p.
number-or-marker-p: See number-or-marker-p.
numberp: See numberp.
pointer-glyph-p: See pointer-glyph-p.
pointer-image-instance-p: See pointer-image-instance-p.
process-event-p: See process-event-p.
processp: See processp.
range-table-p: See range-table-p.
ringp: (not yet documented)
sequencep: See sequencep.
specifierp: See specifierp.
stringp: See stringp.
subrp: See subrp.
subwindow-image-instance-p: See subwindow-image-instance-p.
subwindowp: See subwindowp.
symbolp: See symbolp.
syntax-table-p: See syntax-table-p.
text-image-instance-p: See text-image-instance-p.
timeout-event-p: See timeout-event-p.
toolbar-button-p: See toolbar-button-p.
toolbar-specifier-p: See toolbar-specifier-p.
user-variable-p: See user-variable-p.
vectorp: See vectorp.
weak-list-p: See weak-list-p.
window-configuration-p: See window-configuration-p.
window-live-p: See window-live-p.
windowp: See windowp.

The most general way to check the type of an object is to call the function type-of. Recall that each object belongs to one and only one primitive type; type-of tells you which one (see Lisp Data Types). But type-of knows nothing about non-primitive types. In most cases, it is more convenient to use type predicates than type-of.

Function: type-of object

This function returns a symbol naming the primitive type of object. The value is one of bit-vector, buffer, char-table, character, charset, coding-system, cons, color-instance, compiled-function, console, database, device, event, extent, face, float, font-instance, frame, glyph, hash-table, image-instance, integer, keymap, marker, process, range-table, specifier, string, subr, subwindow, symbol, toolbar-button, vector, weak-list, window, window-configuration, or x-resource.

(type-of 1)
     ⇒ integer
(type-of 'nil)
     ⇒ symbol
(type-of '())    ; () is nil.
     ⇒ symbol
(type-of '(x))
     ⇒ cons