2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/objects
6 @node Lisp Data Types, Numbers, Introduction, Top
7 @chapter Lisp Data Types
13 A Lisp @dfn{object} is a piece of data used and manipulated by Lisp
14 programs. For our purposes, a @dfn{type} or @dfn{data type} is a set of
17 Every object belongs to at least one type. Objects of the same type
18 have similar structures and may usually be used in the same contexts.
19 Types can overlap, and objects can belong to two or more types.
20 Consequently, we can ask whether an object belongs to a particular type,
21 but not for ``the'' type of an object.
23 @cindex primitive type
24 A few fundamental object types are built into Emacs. These, from
25 which all other types are constructed, are called @dfn{primitive
26 types}. Each object belongs to one and only one primitive type. These
27 types include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol},
28 @dfn{string}, @dfn{vector}, @dfn{subr}, @dfn{byte-code function}, plus
29 several special types, such as @dfn{buffer}, that are related to
30 editing. (@xref{Editing Types}.)
32 Each primitive type has a corresponding Lisp function that checks
33 whether an object is a member of that type.
35 Note that Lisp is unlike many other languages in that Lisp objects are
36 @dfn{self-typing}: the primitive type of the object is implicit in the
37 object itself. For example, if an object is a vector, nothing can treat
38 it as a number; Lisp knows it is a vector, not a number.
40 In most languages, the programmer must declare the data type of each
41 variable, and the type is known by the compiler but not represented in
42 the data. Such type declarations do not exist in Emacs Lisp. A Lisp
43 variable can have any type of value, and it remembers whatever value
44 you store in it, type and all.
46 This chapter describes the purpose, printed representation, and read
47 syntax of each of the standard types in GNU Emacs Lisp. Details on how
48 to use these types can be found in later chapters.
51 * Printed Representation:: How Lisp objects are represented as text.
52 * Comments:: Comments and their formatting conventions.
53 * Programming Types:: Types found in all Lisp systems.
54 * Editing Types:: Types specific to Emacs.
55 * Type Predicates:: Tests related to types.
56 * Equality Predicates:: Tests of equality between any two objects.
59 @node Printed Representation
60 @comment node-name, next, previous, up
61 @section Printed Representation and Read Syntax
62 @cindex printed representation
65 The @dfn{printed representation} of an object is the format of the
66 output generated by the Lisp printer (the function @code{prin1}) for
67 that object. The @dfn{read syntax} of an object is the format of the
68 input accepted by the Lisp reader (the function @code{read}) for that
69 object. @xref{Read and Print}.
71 Most objects have more than one possible read syntax. Some types of
72 object have no read syntax, since it may not make sense to enter objects
73 of these types directly in a Lisp program. Except for these cases, the
74 printed representation of an object is also a read syntax for it.
76 In other languages, an expression is text; it has no other form. In
77 Lisp, an expression is primarily a Lisp object and only secondarily the
78 text that is the object's read syntax. Often there is no need to
79 emphasize this distinction, but you must keep it in the back of your
80 mind, or you will occasionally be very confused.
83 Every type has a printed representation. Some types have no read
84 syntax---for example, the buffer type has none. Objects of these types
85 are printed in @dfn{hash notation}: the characters @samp{#<} followed by
86 a descriptive string (typically the type name followed by the name of
87 the object), and closed with a matching @samp{>}. Hash notation cannot
88 be read at all, so the Lisp reader signals the error
89 @code{invalid-read-syntax} whenever it encounters @samp{#<}.
90 @kindex invalid-read-syntax
94 @result{} #<buffer objects.texi>
97 When you evaluate an expression interactively, the Lisp interpreter
98 first reads the textual representation of it, producing a Lisp object,
99 and then evaluates that object (@pxref{Evaluation}). However,
100 evaluation and reading are separate activities. Reading returns the
101 Lisp object represented by the text that is read; the object may or may
102 not be evaluated later. @xref{Input Functions}, for a description of
103 @code{read}, the basic function for reading objects.
106 @comment node-name, next, previous, up
109 @cindex @samp{;} in comment
111 A @dfn{comment} is text that is written in a program only for the sake
112 of humans that read the program, and that has no effect on the meaning
113 of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it
114 is not within a string or character constant. The comment continues to
115 the end of line. The Lisp reader discards comments; they do not become
116 part of the Lisp objects which represent the program within the Lisp
119 The @samp{#@@@var{count}} construct, which skips the next @var{count}
120 characters, is useful for program-generated comments containing binary
121 data. The Emacs Lisp byte compiler uses this in its output files
122 (@pxref{Byte Compilation}). It isn't meant for source files, however.
124 @xref{Comment Tips}, for conventions for formatting comments.
126 @node Programming Types
127 @section Programming Types
128 @cindex programming types
130 There are two general categories of types in Emacs Lisp: those having
131 to do with Lisp programming, and those having to do with editing. The
132 former exist in many Lisp implementations, in one form or another. The
133 latter are unique to Emacs Lisp.
136 * Integer Type:: Numbers without fractional parts.
137 * Floating Point Type:: Numbers with fractional parts and with a large range.
138 * Character Type:: The representation of letters, numbers and
140 * Symbol Type:: A multi-use object that refers to a function,
141 variable, or property list, and has a unique identity.
142 * Sequence Type:: Both lists and arrays are classified as sequences.
143 * Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
144 * Array Type:: Arrays include strings and vectors.
145 * String Type:: An (efficient) array of characters.
146 * Vector Type:: One-dimensional arrays.
147 * Char-Table Type:: One-dimensional sparse arrays indexed by characters.
148 * Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}.
149 * Function Type:: A piece of executable code you can call from elsewhere.
150 * Macro Type:: A method of expanding an expression into another
151 expression, more fundamental but less pretty.
152 * Primitive Function Type:: A function written in C, callable from Lisp.
153 * Byte-Code Type:: A function written in Lisp, then compiled.
154 * Autoload Type:: A type used for automatically loading seldom-used
159 @subsection Integer Type
161 The range of values for integers in Emacs Lisp is @minus{}134217728 to
162 134217727 (28 bits; i.e.,
176 on most machines. (Some machines may provide a wider range.) It is
177 important to note that the Emacs Lisp arithmetic functions do not check
178 for overflow. Thus @code{(1+ 134217727)} is @minus{}134217728 on most
181 The read syntax for integers is a sequence of (base ten) digits with an
182 optional sign at the beginning and an optional period at the end. The
183 printed representation produced by the Lisp interpreter never has a
184 leading @samp{+} or a final @samp{.}.
188 -1 ; @r{The integer -1.}
189 1 ; @r{The integer 1.}
190 1. ; @r{Also The integer 1.}
191 +1 ; @r{Also the integer 1.}
192 268435457 ; @r{Also the integer 1 on a 28-bit implementation.}
196 @xref{Numbers}, for more information.
198 @node Floating Point Type
199 @subsection Floating Point Type
201 Emacs supports floating point numbers (though there is a compilation
202 option to disable them). The precise range of floating point numbers is
205 The printed representation for floating point numbers requires either
206 a decimal point (with at least one digit following), an exponent, or
207 both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
208 @samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
209 number whose value is 1500. They are all equivalent.
211 @xref{Numbers}, for more information.
214 @subsection Character Type
215 @cindex @sc{ASCII} character codes
217 A @dfn{character} in Emacs Lisp is nothing more than an integer. In
218 other words, characters are represented by their character codes. For
219 example, the character @kbd{A} is represented as the @w{integer 65}.
221 Individual characters are not often used in programs. It is far more
222 common to work with @emph{strings}, which are sequences composed of
223 characters. @xref{String Type}.
225 Characters in strings, buffers, and files are currently limited to the
226 range of 0 to 524287---nineteen bits. But not all values in that range
227 are valid character codes. Codes 0 through 127 are ASCII codes; the
228 rest are non-ASCII (@pxref{Non-ASCII Characters}). Characters that represent
229 keyboard input have a much wider range, to encode modifier keys such as
230 Control, Meta and Shift.
232 @cindex read syntax for characters
233 @cindex printed representation for characters
234 @cindex syntax for characters
235 Since characters are really integers, the printed representation of a
236 character is a decimal number. This is also a possible read syntax for
237 a character, but writing characters that way in Lisp programs is a very
238 bad idea. You should @emph{always} use the special read syntax formats
239 that Emacs Lisp provides for characters. These syntax formats start
240 with a question mark.
242 The usual read syntax for alphanumeric characters is a question mark
243 followed by the character; thus, @samp{?A} for the character
244 @kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the
250 ?Q @result{} 81 ?q @result{} 113
253 You can use the same syntax for punctuation characters, but it is
254 often a good idea to add a @samp{\} so that the Emacs commands for
255 editing Lisp code don't get confused. For example, @samp{?\ } is the
256 way to write the space character. If the character is @samp{\}, you
257 @emph{must} use a second @samp{\} to quote it: @samp{?\\}.
260 @cindex bell character
276 You can express the characters Control-g, backspace, tab, newline,
277 vertical tab, formfeed, return, and escape as @samp{?\a}, @samp{?\b},
278 @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f}, @samp{?\r}, @samp{?\e},
282 ?\a @result{} 7 ; @r{@kbd{C-g}}
283 ?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}}
284 ?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}}
285 ?\n @result{} 10 ; @r{newline, @kbd{C-j}}
286 ?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}}
287 ?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}}
288 ?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}}
289 ?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}}
290 ?\\ @result{} 92 ; @r{backslash character, @kbd{\}}
293 @cindex escape sequence
294 These sequences which start with backslash are also known as
295 @dfn{escape sequences}, because backslash plays the role of an escape
296 character; this usage has nothing to do with the character @key{ESC}.
298 @cindex control characters
299 Control characters may be represented using yet another read syntax.
300 This consists of a question mark followed by a backslash, caret, and the
301 corresponding non-control character, in either upper or lower case. For
302 example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the
303 character @kbd{C-i}, the character whose value is 9.
305 Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is
306 equivalent to @samp{?\^I} and to @samp{?\^i}:
309 ?\^I @result{} 9 ?\C-I @result{} 9
312 In strings and buffers, the only control characters allowed are those
313 that exist in @sc{ASCII}; but for keyboard input purposes, you can turn
314 any character into a control character with @samp{C-}. The character
315 codes for these non-@sc{ASCII} control characters include the
322 bit as well as the code for the corresponding non-control
323 character. Ordinary terminals have no way of generating non-@sc{ASCII}
324 control characters, but you can generate them straightforwardly using an
327 For historical reasons, Emacs treats the @key{DEL} character as
328 the control equivalent of @kbd{?}:
331 ?\^? @result{} 127 ?\C-? @result{} 127
335 As a result, it is currently not possible to represent the character
336 @kbd{Control-?}, which is a meaningful input character under X, using
337 @samp{\C-}. It is not easy to change this, as various Lisp files refer
338 to @key{DEL} in this way.
340 For representing control characters to be found in files or strings,
341 we recommend the @samp{^} syntax; for control characters in keyboard
342 input, we prefer the @samp{C-} syntax. Which one you use does not
343 affect the meaning of the program, but may guide the understanding of
346 @cindex meta characters
347 A @dfn{meta character} is a character typed with the @key{META}
348 modifier key. The integer that represents such a character has the
355 bit set (which on most machines makes it a negative number). We
356 use high bits for this and other modifiers to make possible a wide range
357 of basic character codes.
366 bit attached to an ASCII character indicates a meta character; thus, the
367 meta characters that can fit in a string have codes in the range from
368 128 to 255, and are the meta versions of the ordinary @sc{ASCII}
369 characters. (In Emacs versions 18 and older, this convention was used
370 for characters outside of strings as well.)
372 The read syntax for meta characters uses @samp{\M-}. For example,
373 @samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with
374 octal character codes (see below), with @samp{\C-}, or with any other
375 syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A},
376 or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as
377 @samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
379 The case of a graphic character is indicated by its character code;
380 for example, @sc{ASCII} distinguishes between the characters @samp{a}
381 and @samp{A}. But @sc{ASCII} has no way to represent whether a control
382 character is upper case or lower case. Emacs uses the
389 bit to indicate that the shift key was used in typing a control
390 character. This distinction is possible only when you use X terminals
391 or other special terminals; ordinary terminals do not report the
392 distinction to the computer in any way.
394 @cindex hyper characters
395 @cindex super characters
396 @cindex alt characters
397 The X Window System defines three other modifier bits that can be set
398 in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
399 for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. Thus,
400 @samp{?\H-\M-\A-x} represents @kbd{Alt-Hyper-Meta-x}.
403 bit values are $2^{22}$ for alt, $2^{23}$ for super and $2^{24}$ for hyper.
407 bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
410 @cindex @samp{?} in character constant
411 @cindex question mark in character constant
412 @cindex @samp{\} in character constant
413 @cindex backslash in character constant
414 @cindex octal character code
415 Finally, the most general read syntax for a character represents the
416 character code in either octal or hex. To use octal, write a question
417 mark followed by a backslash and the octal character code (up to three
418 octal digits); thus, @samp{?\101} for the character @kbd{A},
419 @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
420 character @kbd{C-b}. Although this syntax can represent any @sc{ASCII}
421 character, it is preferred only when the precise octal value is more
422 important than the @sc{ASCII} representation.
426 ?\012 @result{} 10 ?\n @result{} 10 ?\C-j @result{} 10
427 ?\101 @result{} 65 ?A @result{} 65
431 To use hex, write a question mark followed by a backslash, @samp{x},
432 and the hexadecimal character code. You can use any number of hex
433 digits, so you can represent any character code in this way.
434 Thus, @samp{?\x41} for the character @kbd{A}, @samp{?\x1} for the
435 character @kbd{C-a}, and @code{?\x8c0} for the character
440 @samp{a} with grave accent.
443 A backslash is allowed, and harmless, preceding any character without
444 a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}.
445 There is no reason to add a backslash before most characters. However,
446 you should add a backslash before any of the characters
447 @samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing
448 Lisp code. Also add a backslash before whitespace characters such as
449 space, tab, newline and formfeed. However, it is cleaner to use one of
450 the easily readable escape sequences, such as @samp{\t}, instead of an
451 actual whitespace character such as a tab.
454 @subsection Symbol Type
456 A @dfn{symbol} in GNU Emacs Lisp is an object with a name. The symbol
457 name serves as the printed representation of the symbol. In ordinary
458 use, the name is unique---no two symbols have the same name.
460 A symbol can serve as a variable, as a function name, or to hold a
461 property list. Or it may serve only to be distinct from all other Lisp
462 objects, so that its presence in a data structure may be recognized
463 reliably. In a given context, usually only one of these uses is
464 intended. But you can use one symbol in all of these ways,
467 @cindex @samp{\} in symbols
468 @cindex backslash in symbols
469 A symbol name can contain any characters whatever. Most symbol names
470 are written with letters, digits, and the punctuation characters
471 @samp{-+=*/}. Such names require no special punctuation; the characters
472 of the name suffice as long as the name does not look like a number.
473 (If it does, write a @samp{\} at the beginning of the name to force
474 interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}} are
475 less often used but also require no special punctuation. Any other
476 characters may be included in a symbol's name by escaping them with a
477 backslash. In contrast to its use in strings, however, a backslash in
478 the name of a symbol simply quotes the single character that follows the
479 backslash. For example, in a string, @samp{\t} represents a tab
480 character; in the name of a symbol, however, @samp{\t} merely quotes the
481 letter @samp{t}. To have a symbol with a tab character in its name, you
482 must actually use a tab (preceded with a backslash). But it's rare to
485 @cindex CL note---case of letters
487 @b{Common Lisp note:} In Common Lisp, lower case letters are always
488 ``folded'' to upper case, unless they are explicitly escaped. In Emacs
489 Lisp, upper case and lower case letters are distinct.
492 Here are several examples of symbol names. Note that the @samp{+} in
493 the fifth example is escaped to prevent it from being read as a number.
494 This is not necessary in the sixth example because the rest of the name
495 makes it invalid as a number.
499 foo ; @r{A symbol named @samp{foo}.}
500 FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
501 char-to-string ; @r{A symbol named @samp{char-to-string}.}
504 1+ ; @r{A symbol named @samp{1+}}
505 ; @r{(not @samp{+1}, which is an integer).}
508 \+1 ; @r{A symbol named @samp{+1}}
509 ; @r{(not a very readable name).}
512 \(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
513 @c the @'s in this next line use up three characters, hence the
514 @c apparent misalignment of the comment.
515 +-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
516 ; @r{These characters need not be escaped.}
521 @subsection Sequence Types
523 A @dfn{sequence} is a Lisp object that represents an ordered set of
524 elements. There are two kinds of sequence in Emacs Lisp, lists and
525 arrays. Thus, an object of type list or of type array is also
526 considered a sequence.
528 Arrays are further subdivided into strings, vectors, char-tables and
529 bool-vectors. Vectors can hold elements of any type, but string
530 elements must be characters, and bool-vector elements must be @code{t}
531 or @code{nil}. The characters in a string can have text properties like
532 characters in a buffer (@pxref{Text Properties}); vectors and
533 bool-vectors do not support text properties even when their elements
534 happen to be characters. Char-tables are like vectors except that they
535 are indexed by any valid character code.
537 Lists, strings and the other array types are different, but they have
538 important similarities. For example, all have a length @var{l}, and all
539 have elements which can be indexed from zero to @var{l} minus one.
540 Several functions, called sequence functions, accept any kind of
541 sequence. For example, the function @code{elt} can be used to extract
542 an element of a sequence, given its index. @xref{Sequences Arrays
545 It is generally impossible to read the same sequence twice, since
546 sequences are always created anew upon reading. If you read the read
547 syntax for a sequence twice, you get two sequences with equal contents.
548 There is one exception: the empty list @code{()} always stands for the
549 same object, @code{nil}.
552 @subsection Cons Cell and List Types
553 @cindex address field of register
554 @cindex decrement field of register
556 A @dfn{cons cell} is an object comprising two pointers named the
557 @sc{car} and the @sc{cdr}. Each of them can point to any Lisp object.
559 A @dfn{list} is a series of cons cells, linked together so that the
560 @sc{cdr} of each cons cell points either to another cons cell or to the
561 empty list. @xref{Lists}, for functions that work on lists. Because
562 most cons cells are used as part of lists, the phrase @dfn{list
563 structure} has come to refer to any structure made out of cons cells.
565 The names @sc{car} and @sc{cdr} have only historical meaning now. The
566 original Lisp implementation ran on an @w{IBM 704} computer which
567 divided words into two parts, called the ``address'' part and the
568 ``decrement''; @sc{car} was an instruction to extract the contents of
569 the address part of a register, and @sc{cdr} an instruction to extract
570 the contents of the decrement. By contrast, ``cons cells'' are named
571 for the function @code{cons} that creates them, which in turn is named
572 for its purpose, the construction of cells.
575 Because cons cells are so central to Lisp, we also have a word for
576 ``an object which is not a cons cell''. These objects are called
580 The read syntax and printed representation for lists are identical, and
581 consist of a left parenthesis, an arbitrary number of elements, and a
584 Upon reading, each object inside the parentheses becomes an element
585 of the list. That is, a cons cell is made for each element. The
586 @sc{car} of the cons cell points to the element, and its @sc{cdr} points
587 to the next cons cell of the list, which holds the next element in the
588 list. The @sc{cdr} of the last cons cell is set to point to @code{nil}.
590 @cindex box diagrams, for lists
591 @cindex diagrams, boxed, for lists
592 A list can be illustrated by a diagram in which the cons cells are
593 shown as pairs of boxes. (The Lisp reader cannot read such an
594 illustration; unlike the textual notation, which can be understood by
595 both humans and computers, the box illustrations can be understood only
596 by humans.) The following represents the three-element list @code{(rose
601 --- --- --- --- --- ---
602 | | |--> | | |--> | | |--> nil
603 --- --- --- --- --- ---
606 --> rose --> violet --> buttercup
610 In this diagram, each box represents a slot that can refer to any Lisp
611 object. Each pair of boxes represents a cons cell. Each arrow is a
612 reference to a Lisp object, either an atom or another cons cell.
614 In this example, the first box, the @sc{car} of the first cons cell,
615 refers to or ``contains'' @code{rose} (a symbol). The second box, the
616 @sc{cdr} of the first cons cell, refers to the next pair of boxes, the
617 second cons cell. The @sc{car} of the second cons cell refers to
618 @code{violet} and the @sc{cdr} refers to the third cons cell. The
619 @sc{cdr} of the third (and last) cons cell refers to @code{nil}.
621 Here is another diagram of the same list, @code{(rose violet
622 buttercup)}, sketched in a different manner:
626 --------------- ---------------- -------------------
627 | car | cdr | | car | cdr | | car | cdr |
628 | rose | o-------->| violet | o-------->| buttercup | nil |
630 --------------- ---------------- -------------------
634 @cindex @samp{(@dots{})} in lists
635 @cindex @code{nil} in lists
637 A list with no elements in it is the @dfn{empty list}; it is identical
638 to the symbol @code{nil}. In other words, @code{nil} is both a symbol
641 Here are examples of lists written in Lisp syntax:
644 (A 2 "A") ; @r{A list of three elements.}
645 () ; @r{A list of no elements (the empty list).}
646 nil ; @r{A list of no elements (the empty list).}
647 ("A ()") ; @r{A list of one element: the string @code{"A ()"}.}
648 (A ()) ; @r{A list of two elements: @code{A} and the empty list.}
649 (A nil) ; @r{Equivalent to the previous.}
650 ((A B C)) ; @r{A list of one element}
651 ; @r{(which is a list of three elements).}
654 Here is the list @code{(A ())}, or equivalently @code{(A nil)},
655 depicted with boxes and arrows:
660 | | |--> | | |--> nil
669 * Dotted Pair Notation:: An alternative syntax for lists.
670 * Association List Type:: A specially constructed list.
673 @node Dotted Pair Notation
674 @comment node-name, next, previous, up
675 @subsubsection Dotted Pair Notation
676 @cindex dotted pair notation
677 @cindex @samp{.} in lists
679 @dfn{Dotted pair notation} is an alternative syntax for cons cells
680 that represents the @sc{car} and @sc{cdr} explicitly. In this syntax,
681 @code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
682 the object @var{a}, and whose @sc{cdr} is the object @var{b}. Dotted
683 pair notation is therefore more general than list syntax. In the dotted
684 pair notation, the list @samp{(1 2 3)} is written as @samp{(1 . (2 . (3
685 . nil)))}. For @code{nil}-terminated lists, the two notations produce
686 the same result, but list notation is usually clearer and more
687 convenient when it is applicable. When printing a list, the dotted pair
688 notation is only used if the @sc{cdr} of a cell is not a list.
690 Here's how box notation can illustrate dotted pairs. This example
691 shows the pair @code{(rose . violet)}:
704 Dotted pair notation can be combined with list notation to represent a
705 chain of cons cells with a non-@code{nil} final @sc{cdr}. For example,
706 @code{(rose violet . buttercup)} is equivalent to @code{(rose . (violet
707 . buttercup))}. The object looks like this:
712 | | |--> | | |--> buttercup
720 These diagrams make it evident why @w{@code{(rose .@: violet .@:
721 buttercup)}} is invalid syntax; it would require a cons cell that has
722 three parts rather than two.
724 The list @code{(rose violet)} is equivalent to @code{(rose . (violet))}
730 | | |--> | | |--> nil
738 Similarly, the three-element list @code{(rose violet buttercup)}
739 is equivalent to @code{(rose . (violet . (buttercup)))}.
745 --- --- --- --- --- ---
746 | | |--> | | |--> | | |--> nil
747 --- --- --- --- --- ---
750 --> rose --> violet --> buttercup
755 @node Association List Type
756 @comment node-name, next, previous, up
757 @subsubsection Association List Type
759 An @dfn{association list} or @dfn{alist} is a specially-constructed
760 list whose elements are cons cells. In each element, the @sc{car} is
761 considered a @dfn{key}, and the @sc{cdr} is considered an
762 @dfn{associated value}. (In some cases, the associated value is stored
763 in the @sc{car} of the @sc{cdr}.) Association lists are often used as
764 stacks, since it is easy to add or remove associations at the front of
770 (setq alist-of-colors
771 '((rose . red) (lily . white) (buttercup . yellow)))
775 sets the variable @code{alist-of-colors} to an alist of three elements. In the
776 first element, @code{rose} is the key and @code{red} is the value.
778 @xref{Association Lists}, for a further explanation of alists and for
779 functions that work on alists.
782 @subsection Array Type
784 An @dfn{array} is composed of an arbitrary number of slots for
785 referring to other Lisp objects, arranged in a contiguous block of
786 memory. Accessing any element of an array takes approximately the same
787 amount of time. In contrast, accessing an element of a list requires
788 time proportional to the position of the element in the list. (Elements
789 at the end of a list take longer to access than elements at the
790 beginning of a list.)
792 Emacs defines four types of array: strings, vectors, bool-vectors, and
795 A string is an array of characters and a vector is an array of
796 arbitrary objects. A bool-vector can hold only @code{t} or @code{nil}.
797 These kinds of array may have any length up to the largest integer.
798 Char-tables are sparse arrays indexed by any valid character code; they
799 can hold arbitrary objects.
801 The first element of an array has index zero, the second element has
802 index 1, and so on. This is called @dfn{zero-origin} indexing. For
803 example, an array of four elements has indices 0, 1, 2, @w{and 3}. The
804 largest possible index value is one less than the length of the array.
805 Once an array is created, its length is fixed.
807 All Emacs Lisp arrays are one-dimensional. (Most other programming
808 languages support multidimensional arrays, but they are not essential;
809 you can get the same effect with an array of arrays.) Each type of
810 array has its own read syntax; see the following sections for details.
812 The array type is contained in the sequence type and
813 contains the string type, the vector type, the bool-vector type, and the
817 @subsection String Type
819 A @dfn{string} is an array of characters. Strings are used for many
820 purposes in Emacs, as can be expected in a text editor; for example, as
821 the names of Lisp symbols, as messages for the user, and to represent
822 text extracted from buffers. Strings in Lisp are constants: evaluation
823 of a string returns the same string.
825 @xref{Strings and Characters}, for functions that operate on strings.
828 * Syntax for Strings::
829 * Non-ASCII in Strings::
830 * Nonprinting Characters::
831 * Text Props and Strings::
834 @node Syntax for Strings
835 @subsubsection Syntax for Strings
837 @cindex @samp{"} in strings
838 @cindex double-quote in strings
839 @cindex @samp{\} in strings
840 @cindex backslash in strings
841 The read syntax for strings is a double-quote, an arbitrary number of
842 characters, and another double-quote, @code{"like this"}. To include a
843 double-quote in a string, precede it with a backslash; thus, @code{"\""}
844 is a string containing just a single double-quote character. Likewise,
845 you can include a backslash by preceding it with another backslash, like
846 this: @code{"this \\ is a single embedded backslash"}.
848 @cindex newline in strings
849 The newline character is not special in the read syntax for strings;
850 if you write a new line between the double-quotes, it becomes a
851 character in the string. But an escaped newline---one that is preceded
852 by @samp{\}---does not become part of the string; i.e., the Lisp reader
853 ignores an escaped newline while reading a string. An escaped space
854 @w{@samp{\ }} is likewise ignored.
857 "It is useful to include newlines
858 in documentation strings,
861 @result{} "It is useful to include newlines
862 in documentation strings,
863 but the newline is ignored if escaped."
866 @node Non-ASCII in Strings
867 @subsubsection Non-ASCII Characters in Strings
869 You can include a non-@sc{ASCII} international character in a string
870 constant by writing it literally. There are two text representations
871 for non-@sc{ASCII} characters in Emacs strings (and in buffers): unibyte
872 and multibyte. If the string constant is read from a multibyte source,
873 such as a multibyte buffer or string, or a file that would be visited as
874 multibyte, then the character is read as a multibyte character, and that
875 makes the string multibyte. If the string constant is read from a
876 unibyte source, then the character is read as unibyte and that makes the
880 You can also represent a multibyte non-@sc{ASCII} character with its
881 character code, using a hex escape, @samp{\x@var{nnnnnnn}}, with as many
882 digits as necessary. (Multibyte non-@sc{ASCII} character codes are all
883 greater than 256.) Any character which is not a valid hex digit
884 terminates this construct. If the character that would follow is a hex
885 digit, write @samp{\ } to terminate the hex escape---for example,
886 @samp{\x8c0\ } represents one character, @samp{a} with grave accent.
887 @samp{\ } in a string constant is just like backslash-newline; it does
888 not contribute any character to the string, but it does terminate the
889 preceding hex escape.
891 Using a multibyte hex escape forces the string to multibyte. You can
892 represent a unibyte non-@sc{ASCII} character with its character code,
893 which must be in the range from 128 (0200 octal) to 255 (0377 octal).
894 This forces a unibyte string.
896 @xref{Text Representations}, for more information about the two
897 text representations.
899 @node Nonprinting Characters
900 @subsubsection Nonprinting Characters in Strings
902 Strings cannot hold characters that have the hyper, super, or alt
903 modifiers; the only control or meta characters they can hold are the
904 @sc{ASCII} control characters. Strings do not distinguish case in
905 @sc{ASCII} control characters.
907 You can use the same backslash escape-sequences in a string constant
908 as in character literals (but do not use the question mark that begins a
909 character constant). For example, you can write a string containing the
910 nonprinting characters tab, @kbd{C-a} and @kbd{M-C-a}, with commas and
911 spaces between them, like this: @code{"\t, \C-a, \M-\C-a"}.
912 @xref{Character Type}, for a description of the read syntax for
915 If you use the @samp{\M-} syntax to indicate a meta character in a
916 string constant, this sets the
923 bit of the character in the string. This construct works only with
924 ASCII characters. Note that the same meta characters have a different
925 representation when not in a string. @xref{Character Type}.
927 @node Text Props and Strings
928 @subsubsection Text Properties in Strings
930 A string can hold properties for the characters it contains, in
931 addition to the characters themselves. This enables programs that copy
932 text between strings and buffers to copy the text's properties with no
933 special effort. @xref{Text Properties}, for an explanation of what text
934 properties mean. Strings with text properties use a special read and
938 #("@var{characters}" @var{property-data}...)
942 where @var{property-data} consists of zero or more elements, in groups
946 @var{beg} @var{end} @var{plist}
950 The elements @var{beg} and @var{end} are integers, and together specify
951 a range of indices in the string; @var{plist} is the property list for
952 that range. For example,
955 #("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic))
959 represents a string whose textual contents are @samp{foo bar}, in which
960 the first three characters have a @code{face} property with value
961 @code{bold}, and the last three have a @code{face} property with value
962 @code{italic}. (The fourth character has no text properties so its
963 property list is @code{nil}.)
966 @subsection Vector Type
968 A @dfn{vector} is a one-dimensional array of elements of any type. It
969 takes a constant amount of time to access any element of a vector. (In
970 a list, the access time of an element is proportional to the distance of
971 the element from the beginning of the list.)
973 The printed representation of a vector consists of a left square
974 bracket, the elements, and a right square bracket. This is also the
975 read syntax. Like numbers and strings, vectors are considered constants
979 [1 "two" (three)] ; @r{A vector of three elements.}
980 @result{} [1 "two" (three)]
983 @xref{Vectors}, for functions that work with vectors.
985 @node Char-Table Type
986 @subsection Char-Table Type
988 A @dfn{char-table} is a one-dimensional array of elements of any type,
989 indexed by character codes. Char-tables have certain extra features to
990 make them more useful for many jobs that involve assigning information
991 to character codes---for example, a char-table can have a parent to
992 inherit from, a default value, and a small number of extra slots to use for
993 special purposes. A char-table can also specify a single value for
994 a whole character set.
996 The printed representation of a char-table is like a vector
997 except that there is an extra @samp{#^} at the beginning.
999 @xref{Char-Tables}, for special functions to operate on char-tables.
1000 Uses of char-tables include:
1004 Case tables (@pxref{Case Tables}).
1007 Character category tables (@pxref{Categories}).
1010 Display Tables (@pxref{Display Tables}).
1013 Syntax tables (@pxref{Syntax Tables}).
1016 @node Bool-Vector Type
1017 @subsection Bool-Vector Type
1019 A @dfn{bool-vector} is a one-dimensional array of elements that
1020 must be @code{t} or @code{nil}.
1022 The printed representation of a Bool-vector is like a string, except
1023 that it begins with @samp{#&} followed by the length. The string
1024 constant that follows actually specifies the contents of the bool-vector
1025 as a bitmap---each ``character'' in the string contains 8 bits, which
1026 specify the next 8 elements of the bool-vector (1 stands for @code{t},
1027 and 0 for @code{nil}). If the length is not a multiple of 8, the
1028 printed representation describes extra elements, but these really
1032 (make-bool-vector 3 t)
1034 (make-bool-vector 3 nil)
1036 ;; @r{These are equal since only the first 3 bits are used.}
1037 (equal #&3"\377" #&3"\340")
1042 @subsection Function Type
1044 Just as functions in other programming languages are executable,
1045 @dfn{Lisp function} objects are pieces of executable code. However,
1046 functions in Lisp are primarily Lisp objects, and only secondarily the
1047 text which represents them. These Lisp objects are lambda expressions:
1048 lists whose first element is the symbol @code{lambda} (@pxref{Lambda
1051 In most programming languages, it is impossible to have a function
1052 without a name. In Lisp, a function has no intrinsic name. A lambda
1053 expression is also called an @dfn{anonymous function} (@pxref{Anonymous
1054 Functions}). A named function in Lisp is actually a symbol with a valid
1055 function in its function cell (@pxref{Defining Functions}).
1057 Most of the time, functions are called when their names are written in
1058 Lisp expressions in Lisp programs. However, you can construct or obtain
1059 a function object at run time and then call it with the primitive
1060 functions @code{funcall} and @code{apply}. @xref{Calling Functions}.
1063 @subsection Macro Type
1065 A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
1066 language. It is represented as an object much like a function, but with
1067 different argument-passing semantics. A Lisp macro has the form of a
1068 list whose first element is the symbol @code{macro} and whose @sc{cdr}
1069 is a Lisp function object, including the @code{lambda} symbol.
1071 Lisp macro objects are usually defined with the built-in
1072 @code{defmacro} function, but any list that begins with @code{macro} is
1073 a macro as far as Emacs is concerned. @xref{Macros}, for an explanation
1074 of how to write a macro.
1076 @strong{Warning}: Lisp macros and keyboard macros (@pxref{Keyboard
1077 Macros}) are entirely different things. When we use the word ``macro''
1078 without qualification, we mean a Lisp macro, not a keyboard macro.
1080 @node Primitive Function Type
1081 @subsection Primitive Function Type
1082 @cindex special forms
1084 A @dfn{primitive function} is a function callable from Lisp but
1085 written in the C programming language. Primitive functions are also
1086 called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is
1087 derived from ``subroutine''.) Most primitive functions evaluate all
1088 their arguments when they are called. A primitive function that does
1089 not evaluate all its arguments is called a @dfn{special form}
1090 (@pxref{Special Forms}).@refill
1092 It does not matter to the caller of a function whether the function is
1093 primitive. However, this does matter if you try to redefine a primitive
1094 with a function written in Lisp. The reason is that the primitive
1095 function may be called directly from C code. Calls to the redefined
1096 function from Lisp will use the new definition, but calls from C code
1097 may still use the built-in definition. Therefore, @strong{we discourage
1098 redefinition of primitive functions}.
1100 The term @dfn{function} refers to all Emacs functions, whether written
1101 in Lisp or C. @xref{Function Type}, for information about the
1102 functions written in Lisp.
1104 Primitive functions have no read syntax and print in hash notation
1105 with the name of the subroutine.
1109 (symbol-function 'car) ; @r{Access the function cell}
1110 ; @r{of the symbol.}
1111 @result{} #<subr car>
1112 (subrp (symbol-function 'car)) ; @r{Is this a primitive function?}
1113 @result{} t ; @r{Yes.}
1117 @node Byte-Code Type
1118 @subsection Byte-Code Function Type
1120 The byte compiler produces @dfn{byte-code function objects}.
1121 Internally, a byte-code function object is much like a vector; however,
1122 the evaluator handles this data type specially when it appears as a
1123 function to be called. @xref{Byte Compilation}, for information about
1126 The printed representation and read syntax for a byte-code function
1127 object is like that for a vector, with an additional @samp{#} before the
1131 @subsection Autoload Type
1133 An @dfn{autoload object} is a list whose first element is the symbol
1134 @code{autoload}. It is stored as the function definition of a symbol as
1135 a placeholder for the real definition; it says that the real definition
1136 is found in a file of Lisp code that should be loaded when necessary.
1137 The autoload object contains the name of the file, plus some other
1138 information about the real definition.
1140 After the file has been loaded, the symbol should have a new function
1141 definition that is not an autoload object. The new definition is then
1142 called as if it had been there to begin with. From the user's point of
1143 view, the function call works as expected, using the function definition
1146 An autoload object is usually created with the function
1147 @code{autoload}, which stores the object in the function cell of a
1148 symbol. @xref{Autoload}, for more details.
1151 @section Editing Types
1152 @cindex editing types
1154 The types in the previous section used for general programming
1155 purposes, and most of them are common to most Lisp dialects. Emacs Lisp
1156 provides several additional data types for purposes connected with
1160 * Buffer Type:: The basic object of editing.
1161 * Marker Type:: A position in a buffer.
1162 * Window Type:: Buffers are displayed in windows.
1163 * Frame Type:: Windows subdivide frames.
1164 * Window Configuration Type:: Recording the way a frame is subdivided.
1165 * Frame Configuration Type:: Recording the status of all frames.
1166 * Process Type:: A process running on the underlying OS.
1167 * Stream Type:: Receive or send characters.
1168 * Keymap Type:: What function a keystroke invokes.
1169 * Overlay Type:: How an overlay is represented.
1173 @subsection Buffer Type
1175 A @dfn{buffer} is an object that holds text that can be edited
1176 (@pxref{Buffers}). Most buffers hold the contents of a disk file
1177 (@pxref{Files}) so they can be edited, but some are used for other
1178 purposes. Most buffers are also meant to be seen by the user, and
1179 therefore displayed, at some time, in a window (@pxref{Windows}). But a
1180 buffer need not be displayed in any window.
1182 The contents of a buffer are much like a string, but buffers are not
1183 used like strings in Emacs Lisp, and the available operations are
1184 different. For example, you can insert text efficiently into an
1185 existing buffer, whereas ``inserting'' text into a string requires
1186 concatenating substrings, and the result is an entirely new string
1189 Each buffer has a designated position called @dfn{point}
1190 (@pxref{Positions}). At any time, one buffer is the @dfn{current
1191 buffer}. Most editing commands act on the contents of the current
1192 buffer in the neighborhood of point. Many of the standard Emacs
1193 functions manipulate or test the characters in the current buffer; a
1194 whole chapter in this manual is devoted to describing these functions
1197 Several other data structures are associated with each buffer:
1201 a local syntax table (@pxref{Syntax Tables});
1204 a local keymap (@pxref{Keymaps}); and,
1207 a list of buffer-local variable bindings (@pxref{Buffer-Local Variables}).
1210 overlays (@pxref{Overlays}).
1213 text properties for the text in the buffer (@pxref{Text Properties}).
1217 The local keymap and variable list contain entries that individually
1218 override global bindings or values. These are used to customize the
1219 behavior of programs in different buffers, without actually changing the
1222 A buffer may be @dfn{indirect}, which means it shares the text
1223 of another buffer, but presents it differently. @xref{Indirect Buffers}.
1225 Buffers have no read syntax. They print in hash notation, showing the
1231 @result{} #<buffer objects.texi>
1236 @subsection Marker Type
1238 A @dfn{marker} denotes a position in a specific buffer. Markers
1239 therefore have two components: one for the buffer, and one for the
1240 position. Changes in the buffer's text automatically relocate the
1241 position value as necessary to ensure that the marker always points
1242 between the same two characters in the buffer.
1244 Markers have no read syntax. They print in hash notation, giving the
1245 current character position and the name of the buffer.
1250 @result{} #<marker at 10779 in objects.texi>
1254 @xref{Markers}, for information on how to test, create, copy, and move
1258 @subsection Window Type
1260 A @dfn{window} describes the portion of the terminal screen that Emacs
1261 uses to display a buffer. Every window has one associated buffer, whose
1262 contents appear in the window. By contrast, a given buffer may appear
1263 in one window, no window, or several windows.
1265 Though many windows may exist simultaneously, at any time one window
1266 is designated the @dfn{selected window}. This is the window where the
1267 cursor is (usually) displayed when Emacs is ready for a command. The
1268 selected window usually displays the current buffer, but this is not
1269 necessarily the case.
1271 Windows are grouped on the screen into frames; each window belongs to
1272 one and only one frame. @xref{Frame Type}.
1274 Windows have no read syntax. They print in hash notation, giving the
1275 window number and the name of the buffer being displayed. The window
1276 numbers exist to identify windows uniquely, since the buffer displayed
1277 in any given window can change frequently.
1282 @result{} #<window 1 on objects.texi>
1286 @xref{Windows}, for a description of the functions that work on windows.
1289 @subsection Frame Type
1291 A @var{frame} is a rectangle on the screen that contains one or more
1292 Emacs windows. A frame initially contains a single main window (plus
1293 perhaps a minibuffer window) which you can subdivide vertically or
1294 horizontally into smaller windows.
1296 Frames have no read syntax. They print in hash notation, giving the
1297 frame's title, plus its address in core (useful to identify the frame
1303 @result{} #<frame emacs@@mole.gnu.ai.mit.edu 0xdac80>
1307 @xref{Frames}, for a description of the functions that work on frames.
1309 @node Window Configuration Type
1310 @subsection Window Configuration Type
1311 @cindex screen layout
1313 A @dfn{window configuration} stores information about the positions,
1314 sizes, and contents of the windows in a frame, so you can recreate the
1315 same arrangement of windows later.
1317 Window configurations do not have a read syntax; their print syntax
1318 looks like @samp{#<window-configuration>}. @xref{Window
1319 Configurations}, for a description of several functions related to
1320 window configurations.
1322 @node Frame Configuration Type
1323 @subsection Frame Configuration Type
1324 @cindex screen layout
1326 A @dfn{frame configuration} stores information about the positions,
1327 sizes, and contents of the windows in all frames. It is actually
1328 a list whose @sc{car} is @code{frame-configuration} and whose
1329 @sc{cdr} is an alist. Each alist element describes one frame,
1330 which appears as the @sc{car} of that element.
1332 @xref{Frame Configurations}, for a description of several functions
1333 related to frame configurations.
1336 @subsection Process Type
1338 The word @dfn{process} usually means a running program. Emacs itself
1339 runs in a process of this sort. However, in Emacs Lisp, a process is a
1340 Lisp object that designates a subprocess created by the Emacs process.
1341 Programs such as shells, GDB, ftp, and compilers, running in
1342 subprocesses of Emacs, extend the capabilities of Emacs.
1344 An Emacs subprocess takes textual input from Emacs and returns textual
1345 output to Emacs for further manipulation. Emacs can also send signals
1348 Process objects have no read syntax. They print in hash notation,
1349 giving the name of the process:
1354 @result{} (#<process shell>)
1358 @xref{Processes}, for information about functions that create, delete,
1359 return information about, send input or signals to, and receive output
1363 @subsection Stream Type
1365 A @dfn{stream} is an object that can be used as a source or sink for
1366 characters---either to supply characters for input or to accept them as
1367 output. Many different types can be used this way: markers, buffers,
1368 strings, and functions. Most often, input streams (character sources)
1369 obtain characters from the keyboard, a buffer, or a file, and output
1370 streams (character sinks) send characters to a buffer, such as a
1371 @file{*Help*} buffer, or to the echo area.
1373 The object @code{nil}, in addition to its other meanings, may be used
1374 as a stream. It stands for the value of the variable
1375 @code{standard-input} or @code{standard-output}. Also, the object
1376 @code{t} as a stream specifies input using the minibuffer
1377 (@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo
1380 Streams have no special printed representation or read syntax, and
1381 print as whatever primitive type they are.
1383 @xref{Read and Print}, for a description of functions
1384 related to streams, including parsing and printing functions.
1387 @subsection Keymap Type
1389 A @dfn{keymap} maps keys typed by the user to commands. This mapping
1390 controls how the user's command input is executed. A keymap is actually
1391 a list whose @sc{car} is the symbol @code{keymap}.
1393 @xref{Keymaps}, for information about creating keymaps, handling prefix
1394 keys, local as well as global keymaps, and changing key bindings.
1397 @subsection Overlay Type
1399 An @dfn{overlay} specifies properties that apply to a part of a
1400 buffer. Each overlay applies to a specified range of the buffer, and
1401 contains a property list (a list whose elements are alternating property
1402 names and values). Overlay properties are used to present parts of the
1403 buffer temporarily in a different display style. Overlays have no read
1404 syntax, and print in hash notation, giving the buffer name and range of
1407 @xref{Overlays}, for how to create and use overlays.
1409 @node Type Predicates
1410 @section Type Predicates
1412 @cindex type checking
1413 @kindex wrong-type-argument
1415 The Emacs Lisp interpreter itself does not perform type checking on
1416 the actual arguments passed to functions when they are called. It could
1417 not do so, since function arguments in Lisp do not have declared data
1418 types, as they do in other programming languages. It is therefore up to
1419 the individual function to test whether each actual argument belongs to
1420 a type that the function can use.
1422 All built-in functions do check the types of their actual arguments
1423 when appropriate, and signal a @code{wrong-type-argument} error if an
1424 argument is of the wrong type. For example, here is what happens if you
1425 pass an argument to @code{+} that it cannot handle:
1430 @error{} Wrong type argument: number-or-marker-p, a
1434 @cindex type predicates
1435 @cindex testing types
1436 If you want your program to handle different types differently, you
1437 must do explicit type checking. The most common way to check the type
1438 of an object is to call a @dfn{type predicate} function. Emacs has a
1439 type predicate for each type, as well as some predicates for
1440 combinations of types.
1442 A type predicate function takes one argument; it returns @code{t} if
1443 the argument belongs to the appropriate type, and @code{nil} otherwise.
1444 Following a general Lisp convention for predicate functions, most type
1445 predicates' names end with @samp{p}.
1447 Here is an example which uses the predicates @code{listp} to check for
1448 a list and @code{symbolp} to check for a symbol.
1453 ;; If X is a symbol, put it on LIST.
1454 (setq list (cons x list)))
1456 ;; If X is a list, add its elements to LIST.
1457 (setq list (append x list)))
1460 ;; We handle only symbols and lists.
1461 (error "Invalid argument %s in add-on" x))))
1464 Here is a table of predefined type predicates, in alphabetical order,
1465 with references to further information.
1469 @xref{List-related Predicates, atom}.
1472 @xref{Array Functions, arrayp}.
1475 @xref{Bool-Vectors, bool-vector-p}.
1478 @xref{Buffer Basics, bufferp}.
1480 @item byte-code-function-p
1481 @xref{Byte-Code Type, byte-code-function-p}.
1484 @xref{Case Tables, case-table-p}.
1486 @item char-or-string-p
1487 @xref{Predicates for Strings, char-or-string-p}.
1490 @xref{Char-Tables, char-table-p}.
1493 @xref{Interactive Call, commandp}.
1496 @xref{List-related Predicates, consp}.
1498 @item display-table-p
1499 @xref{Display Tables, display-table-p}.
1502 @xref{Predicates on Numbers, floatp}.
1504 @item frame-configuration-p
1505 @xref{Frame Configurations, frame-configuration-p}.
1508 @xref{Deleting Frames, frame-live-p}.
1511 @xref{Frames, framep}.
1514 @xref{Functions, functionp}.
1516 @item integer-or-marker-p
1517 @xref{Predicates on Markers, integer-or-marker-p}.
1520 @xref{Predicates on Numbers, integerp}.
1523 @xref{Creating Keymaps, keymapp}.
1526 @xref{List-related Predicates, listp}.
1529 @xref{Predicates on Markers, markerp}.
1532 @xref{Predicates on Numbers, wholenump}.
1535 @xref{List-related Predicates, nlistp}.
1538 @xref{Predicates on Numbers, numberp}.
1540 @item number-or-marker-p
1541 @xref{Predicates on Markers, number-or-marker-p}.
1544 @xref{Overlays, overlayp}.
1547 @xref{Processes, processp}.
1550 @xref{Sequence Functions, sequencep}.
1553 @xref{Predicates for Strings, stringp}.
1556 @xref{Function Cells, subrp}.
1559 @xref{Symbols, symbolp}.
1561 @item syntax-table-p
1562 @xref{Syntax Tables, syntax-table-p}.
1564 @item user-variable-p
1565 @xref{Defining Variables, user-variable-p}.
1568 @xref{Vectors, vectorp}.
1570 @item window-configuration-p
1571 @xref{Window Configurations, window-configuration-p}.
1574 @xref{Deleting Windows, window-live-p}.
1577 @xref{Basic Windows, windowp}.
1580 The most general way to check the type of an object is to call the
1581 function @code{type-of}. Recall that each object belongs to one and
1582 only one primitive type; @code{type-of} tells you which one (@pxref{Lisp
1583 Data Types}). But @code{type-of} knows nothing about non-primitive
1584 types. In most cases, it is more convenient to use type predicates than
1587 @defun type-of object
1588 This function returns a symbol naming the primitive type of
1589 @var{object}. The value is one of the symbols @code{symbol},
1590 @code{integer}, @code{float}, @code{string}, @code{cons}, @code{vector},
1591 @code{char-table}, @code{bool-vector}, @code{subr},
1592 @code{compiled-function}, @code{marker}, @code{overlay}, @code{window},
1593 @code{buffer}, @code{frame}, @code{process}, or
1594 @code{window-configuration}.
1601 (type-of '()) ; @r{@code{()} is @code{nil}.}
1608 @node Equality Predicates
1609 @section Equality Predicates
1612 Here we describe two functions that test for equality between any two
1613 objects. Other functions test equality between objects of specific
1614 types, e.g., strings. For these predicates, see the appropriate chapter
1615 describing the data type.
1617 @defun eq object1 object2
1618 This function returns @code{t} if @var{object1} and @var{object2} are
1619 the same object, @code{nil} otherwise. The ``same object'' means that a
1620 change in one will be reflected by the same change in the other.
1622 @code{eq} returns @code{t} if @var{object1} and @var{object2} are
1623 integers with the same value. Also, since symbol names are normally
1624 unique, if the arguments are symbols with the same name, they are
1625 @code{eq}. For other types (e.g., lists, vectors, strings), two
1626 arguments with the same contents or elements are not necessarily
1627 @code{eq} to each other: they are @code{eq} only if they are the same
1647 (eq '(1 (2 (3))) '(1 (2 (3))))
1652 (setq foo '(1 (2 (3))))
1653 @result{} (1 (2 (3)))
1656 (eq foo '(1 (2 (3))))
1661 (eq [(1 2) 3] [(1 2) 3])
1666 (eq (point-marker) (point-marker))
1671 (The @code{make-symbol} function returns an uninterned symbol that is
1672 not interned in the standard @code{obarray}. When uninterned symbols
1673 are in use, symbol names are no longer unique. Distinct symbols with
1674 the same name are not @code{eq}. @xref{Creating Symbols}.)
1678 (eq (make-symbol "foo") 'foo)
1684 @defun equal object1 object2
1685 This function returns @code{t} if @var{object1} and @var{object2} have
1686 equal components, @code{nil} otherwise. Whereas @code{eq} tests if its
1687 arguments are the same object, @code{equal} looks inside nonidentical
1688 arguments to see if their elements are the same. So, if two objects are
1689 @code{eq}, they are @code{equal}, but the converse is not always true.
1703 (equal "asdf" "asdf")
1712 (equal '(1 (2 (3))) '(1 (2 (3))))
1716 (eq '(1 (2 (3))) '(1 (2 (3))))
1721 (equal [(1 2) 3] [(1 2) 3])
1725 (eq [(1 2) 3] [(1 2) 3])
1730 (equal (point-marker) (point-marker))
1735 (eq (point-marker) (point-marker))
1740 Comparison of strings is case-sensitive, but does not take account of
1741 text properties---it compares only the characters in the strings.
1742 A unibyte string never equals a multibyte string unless the
1743 contents are entirely @sc{ASCII} (@pxref{Text Representations}).
1747 (equal "asdf" "ASDF")
1752 Two distinct buffers are never @code{equal}, even if their contents
1756 The test for equality is implemented recursively, and circular lists may
1757 therefore cause infinite recursion (leading to an error).