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}, and
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; except for these cases, the printed
73 representation of an object is also a read syntax for it.
75 In other languages, an expression is text; it has no other form. In
76 Lisp, an expression is primarily a Lisp object and only secondarily the
77 text that is the object's read syntax. Often there is no need to
78 emphasize this distinction, but you must keep it in the back of your
79 mind, or you will occasionally be very confused.
82 Every type has a printed representation. Some types have no read
83 syntax, since it may not make sense to enter objects of these types
84 directly in a Lisp program. For example, the buffer type does not have
85 a read syntax. Objects of these types are printed in @dfn{hash
86 notation}: the characters @samp{#<} followed by a descriptive string
87 (typically the type name followed by the name of the object), and closed
88 with a matching @samp{>}. Hash notation cannot be read at all, so the
89 Lisp reader signals the error @code{invalid-read-syntax} whenever it
91 @kindex invalid-read-syntax
95 @result{} #<buffer objects.texi>
98 When you evaluate an expression interactively, the Lisp interpreter
99 first reads the textual representation of it, producing a Lisp object,
100 and then evaluates that object (@pxref{Evaluation}). However,
101 evaluation and reading are separate activities. Reading returns the
102 Lisp object represented by the text that is read; the object may or may
103 not be evaluated later. @xref{Input Functions}, for a description of
104 @code{read}, the basic function for reading objects.
107 @comment node-name, next, previous, up
110 @cindex @samp{;} in comment
112 A @dfn{comment} is text that is written in a program only for the sake
113 of humans that read the program, and that has no effect on the meaning
114 of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it
115 is not within a string or character constant. The comment continues to
116 the end of line. The Lisp reader discards comments; they do not become
117 part of the Lisp objects which represent the program within the Lisp
120 The @samp{#@@@var{count}} construct, which skips the next @var{count}
121 characters, is useful for program-generated comments containing binary
122 data. The Emacs Lisp byte compiler uses this in its output files
123 (@pxref{Byte Compilation}). It isn't meant for source files, however.
125 @xref{Comment Tips}, for conventions for formatting comments.
127 @node Programming Types
128 @section Programming Types
129 @cindex programming types
131 There are two general categories of types in Emacs Lisp: those having
132 to do with Lisp programming, and those having to do with editing. The
133 former exist in many Lisp implementations, in one form or another. The
134 latter are unique to Emacs Lisp.
137 * Integer Type:: Numbers without fractional parts.
138 * Floating Point Type:: Numbers with fractional parts and with a large range.
139 * Character Type:: The representation of letters, numbers and
141 * Symbol Type:: A multi-use object that refers to a function,
142 variable, or property list, and has a unique identity.
143 * Sequence Type:: Both lists and arrays are classified as sequences.
144 * Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
145 * Array Type:: Arrays include strings and vectors.
146 * String Type:: An (efficient) array of characters.
147 * Vector Type:: One-dimensional arrays.
148 * Char-Table Type:: One-dimensional sparse arrays indexed by characters.
149 * Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}.
150 * Function Type:: A piece of executable code you can call from elsewhere.
151 * Macro Type:: A method of expanding an expression into another
152 expression, more fundamental but less pretty.
153 * Primitive Function Type:: A function written in C, callable from Lisp.
154 * Byte-Code Type:: A function written in Lisp, then compiled.
155 * Autoload Type:: A type used for automatically loading seldom-used
160 @subsection Integer Type
162 The range of values for integers in Emacs Lisp is @minus{}134217728 to
163 134217727 (28 bits; i.e.,
177 on most machines. (Some machines may provide a wider range.) It is
178 important to note that the Emacs Lisp arithmetic functions do not check
179 for overflow. Thus @code{(1+ 134217727)} is @minus{}134217728 on most
182 The read syntax for integers is a sequence of (base ten) digits with an
183 optional sign at the beginning and an optional period at the end. The
184 printed representation produced by the Lisp interpreter never has a
185 leading @samp{+} or a final @samp{.}.
189 -1 ; @r{The integer -1.}
190 1 ; @r{The integer 1.}
191 1. ; @r{Also The integer 1.}
192 +1 ; @r{Also the integer 1.}
193 268435457 ; @r{Also the integer 1!}
194 ; @r{ (on a 28-bit implementation)}
198 @xref{Numbers}, for more information.
200 @node Floating Point Type
201 @subsection Floating Point Type
203 Emacs supports floating point numbers (though there is a compilation
204 option to disable them). The precise range of floating point numbers is
207 The printed representation for floating point numbers requires either
208 a decimal point (with at least one digit following), an exponent, or
209 both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
210 @samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
211 number whose value is 1500. They are all equivalent.
213 @xref{Numbers}, for more information.
216 @subsection Character Type
217 @cindex @sc{ASCII} character codes
219 A @dfn{character} in Emacs Lisp is nothing more than an integer. In
220 other words, characters are represented by their character codes. For
221 example, the character @kbd{A} is represented as the @w{integer 65}.
223 Individual characters are not often used in programs. It is far more
224 common to work with @emph{strings}, which are sequences composed of
225 characters. @xref{String Type}.
227 Characters in strings, buffers, and files are currently limited to the
228 range of 0 to 524287---nineteen bits. But not all values in that range
229 are valid character codes. Characters that represent keyboard input
230 have a much wider range, so they can modifier keys such as Control, Meta
233 @cindex read syntax for characters
234 @cindex printed representation for characters
235 @cindex syntax for characters
236 Since characters are really integers, the printed representation of a
237 character is a decimal number. This is also a possible read syntax for
238 a character, but writing characters that way in Lisp programs is a very
239 bad idea. You should @emph{always} use the special read syntax formats
240 that Emacs Lisp provides for characters. These syntax formats start
241 with a question mark.
243 The usual read syntax for alphanumeric characters is a question mark
244 followed by the character; thus, @samp{?A} for the character
245 @kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the
251 ?Q @result{} 81 ?q @result{} 113
254 You can use the same syntax for punctuation characters, but it is
255 often a good idea to add a @samp{\} so that the Emacs commands for
256 editing Lisp code don't get confused. For example, @samp{?\ } is the
257 way to write the space character. If the character is @samp{\}, you
258 @emph{must} use a second @samp{\} to quote it: @samp{?\\}.
261 @cindex bell character
277 You can express the characters Control-g, backspace, tab, newline,
278 vertical tab, formfeed, return, and escape as @samp{?\a}, @samp{?\b},
279 @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f}, @samp{?\r}, @samp{?\e},
283 ?\a @result{} 7 ; @r{@kbd{C-g}}
284 ?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}}
285 ?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}}
286 ?\n @result{} 10 ; @r{newline, @key{LFD}, @kbd{C-j}}
287 ?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}}
288 ?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}}
289 ?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}}
290 ?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}}
291 ?\\ @result{} 92 ; @r{backslash character, @kbd{\}}
294 @cindex escape sequence
295 These sequences which start with backslash are also known as
296 @dfn{escape sequences}, because backslash plays the role of an escape
297 character; this usage has nothing to do with the character @key{ESC}.
299 @cindex control characters
300 Control characters may be represented using yet another read syntax.
301 This consists of a question mark followed by a backslash, caret, and the
302 corresponding non-control character, in either upper or lower case. For
303 example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the
304 character @kbd{C-i}, the character whose value is 9.
306 Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is
307 equivalent to @samp{?\^I} and to @samp{?\^i}:
310 ?\^I @result{} 9 ?\C-I @result{} 9
313 In strings and buffers, the only control characters allowed are those
314 that exist in @sc{ASCII}; but for keyboard input purposes, you can turn
315 any character into a control character with @samp{C-}. The character
316 codes for these non-@sc{ASCII} control characters include the
323 bit as well as the code for the corresponding non-control
324 character. Ordinary terminals have no way of generating non-@sc{ASCII}
325 control characters, but you can generate them straightforwardly using an
328 For historical reasons, Emacs treats the @key{DEL} character as
329 the control equivalent of @kbd{?}:
332 ?\^? @result{} 127 ?\C-? @result{} 127
336 As a result, it is currently not possible to represent the character
337 @kbd{Control-?}, which is a meaningful input character under X. It is
338 not easy to change this as various Lisp files refer to @key{DEL} in this
341 For representing control characters to be found in files or strings,
342 we recommend the @samp{^} syntax; for control characters in keyboard
343 input, we prefer the @samp{C-} syntax. This does not affect the meaning
344 of the program, but may guide the understanding of people who read it.
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 for typing a control
390 character. This distinction is possible only when you use X terminals
391 or other special terminals; ordinary terminals do not indicate 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 @kbd{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 and vectors. Vectors can
529 hold elements of any type, but string elements must be characters in the
530 range from 0 to 255. However, the characters in a string can have text
531 properties like characters in a buffer (@pxref{Text Properties});
532 vectors do not support text properties even when their elements happen
535 Lists, strings and vectors are different, but they have important
536 similarities. For example, all have a length @var{l}, and all have
537 elements which can be indexed from zero to @var{l} minus one. Also,
538 several functions, called sequence functions, accept any kind of
539 sequence. For example, the function @code{elt} can be used to extract
540 an element of a sequence, given its index. @xref{Sequences Arrays
543 It is impossible to read the same sequence twice, since sequences are
544 always created anew upon reading. If you read the read syntax for a
545 sequence twice, you get two sequences with equal contents. There is one
546 exception: the empty list @code{()} always stands for the same object,
550 @subsection Cons Cell and List Types
551 @cindex address field of register
552 @cindex decrement field of register
554 A @dfn{cons cell} is an object comprising two pointers named the
555 @sc{car} and the @sc{cdr}. Each of them can point to any Lisp object.
557 A @dfn{list} is a series of cons cells, linked together so that the
558 @sc{cdr} of each cons cell points either to another cons cell or to the
559 empty list. @xref{Lists}, for functions that work on lists. Because
560 most cons cells are used as part of lists, the phrase @dfn{list
561 structure} has come to refer to any structure made out of cons cells.
563 The names @sc{car} and @sc{cdr} have only historical meaning now. The
564 original Lisp implementation ran on an @w{IBM 704} computer which
565 divided words into two parts, called the ``address'' part and the
566 ``decrement''; @sc{car} was an instruction to extract the contents of
567 the address part of a register, and @sc{cdr} an instruction to extract
568 the contents of the decrement. By contrast, ``cons cells'' are named
569 for the function @code{cons} that creates them, which in turn is named
570 for its purpose, the construction of cells.
573 Because cons cells are so central to Lisp, we also have a word for
574 ``an object which is not a cons cell''. These objects are called
578 The read syntax and printed representation for lists are identical, and
579 consist of a left parenthesis, an arbitrary number of elements, and a
582 Upon reading, each object inside the parentheses becomes an element
583 of the list. That is, a cons cell is made for each element. The
584 @sc{car} of the cons cell points to the element, and its @sc{cdr} points
585 to the next cons cell of the list, which holds the next element in the
586 list. The @sc{cdr} of the last cons cell is set to point to @code{nil}.
588 @cindex box diagrams, for lists
589 @cindex diagrams, boxed, for lists
590 A list can be illustrated by a diagram in which the cons cells are
591 shown as pairs of boxes. (The Lisp reader cannot read such an
592 illustration; unlike the textual notation, which can be understood by
593 both humans and computers, the box illustrations can be understood only
594 by humans.) The following represents the three-element list @code{(rose
599 ___ ___ ___ ___ ___ ___
600 |___|___|--> |___|___|--> |___|___|--> nil
603 --> rose --> violet --> buttercup
607 In this diagram, each box represents a slot that can refer to any Lisp
608 object. Each pair of boxes represents a cons cell. Each arrow is a
609 reference to a Lisp object, either an atom or another cons cell.
611 In this example, the first box, the @sc{car} of the first cons cell,
612 refers to or ``contains'' @code{rose} (a symbol). The second box, the
613 @sc{cdr} of the first cons cell, refers to the next pair of boxes, the
614 second cons cell. The @sc{car} of the second cons cell refers to
615 @code{violet} and the @sc{cdr} refers to the third cons cell. The
616 @sc{cdr} of the third (and last) cons cell refers to @code{nil}.
618 Here is another diagram of the same list, @code{(rose violet
619 buttercup)}, sketched in a different manner:
623 --------------- ---------------- -------------------
624 | car | cdr | | car | cdr | | car | cdr |
625 | rose | o-------->| violet | o-------->| buttercup | nil |
627 --------------- ---------------- -------------------
631 @cindex @samp{(@dots{})} in lists
632 @cindex @code{nil} in lists
634 A list with no elements in it is the @dfn{empty list}; it is identical
635 to the symbol @code{nil}. In other words, @code{nil} is both a symbol
638 Here are examples of lists written in Lisp syntax:
641 (A 2 "A") ; @r{A list of three elements.}
642 () ; @r{A list of no elements (the empty list).}
643 nil ; @r{A list of no elements (the empty list).}
644 ("A ()") ; @r{A list of one element: the string @code{"A ()"}.}
645 (A ()) ; @r{A list of two elements: @code{A} and the empty list.}
646 (A nil) ; @r{Equivalent to the previous.}
647 ((A B C)) ; @r{A list of one element}
648 ; @r{(which is a list of three elements).}
651 Here is the list @code{(A ())}, or equivalently @code{(A nil)},
652 depicted with boxes and arrows:
657 |___|___|--> |___|___|--> nil
665 * Dotted Pair Notation:: An alternative syntax for lists.
666 * Association List Type:: A specially constructed list.
669 @node Dotted Pair Notation
670 @comment node-name, next, previous, up
671 @subsubsection Dotted Pair Notation
672 @cindex dotted pair notation
673 @cindex @samp{.} in lists
675 @dfn{Dotted pair notation} is an alternative syntax for cons cells
676 that represents the @sc{car} and @sc{cdr} explicitly. In this syntax,
677 @code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
678 the object @var{a}, and whose @sc{cdr} is the object @var{b}. Dotted
679 pair notation is therefore more general than list syntax. In the dotted
680 pair notation, the list @samp{(1 2 3)} is written as @samp{(1 . (2 . (3
681 . nil)))}. For @code{nil}-terminated lists, the two notations produce
682 the same result, but list notation is usually clearer and more
683 convenient when it is applicable. When printing a list, the dotted pair
684 notation is only used if the @sc{cdr} of a cell is not a list.
686 Here's how box notation can illustrate dotted pairs. This example
687 shows the pair @code{(rose . violet)}:
699 Dotted pair notation can be combined with list notation to represent a
700 chain of cons cells with a non-@code{nil} final @sc{cdr}. For example,
701 @code{(rose violet . buttercup)} is equivalent to @code{(rose . (violet
702 . buttercup))}. The object looks like this:
707 |___|___|--> |___|___|--> buttercup
714 These diagrams make it evident why @w{@code{(rose .@: violet .@:
715 buttercup)}} is invalid syntax; it would require a cons cell that has
716 three parts rather than two.
718 The list @code{(rose violet)} is equivalent to @code{(rose . (violet))}
724 |___|___|--> |___|___|--> nil
731 Similarly, the three-element list @code{(rose violet buttercup)}
732 is equivalent to @code{(rose . (violet . (buttercup)))}.
738 ___ ___ ___ ___ ___ ___
739 |___|___|--> |___|___|--> |___|___|--> nil
742 --> rose --> violet --> buttercup
747 @node Association List Type
748 @comment node-name, next, previous, up
749 @subsubsection Association List Type
751 An @dfn{association list} or @dfn{alist} is a specially-constructed
752 list whose elements are cons cells. In each element, the @sc{car} is
753 considered a @dfn{key}, and the @sc{cdr} is considered an
754 @dfn{associated value}. (In some cases, the associated value is stored
755 in the @sc{car} of the @sc{cdr}.) Association lists are often used as
756 stacks, since it is easy to add or remove associations at the front of
762 (setq alist-of-colors
763 '((rose . red) (lily . white) (buttercup . yellow)))
767 sets the variable @code{alist-of-colors} to an alist of three elements. In the
768 first element, @code{rose} is the key and @code{red} is the value.
770 @xref{Association Lists}, for a further explanation of alists and for
771 functions that work on alists.
774 @subsection Array Type
776 An @dfn{array} is composed of an arbitrary number of slots for
777 referring to other Lisp objects, arranged in a contiguous block of
778 memory. Accessing any element of an array takes the same amount of
779 time. In contrast, accessing an element of a list requires time
780 proportional to the position of the element in the list. (Elements at
781 the end of a list take longer to access than elements at the beginning
784 Emacs defines two types of array, strings and vectors. A string is an
785 array of characters and a vector is an array of arbitrary objects. Both
786 are one-dimensional. (Most other programming languages support
787 multidimensional arrays, but they are not essential; you can get the
788 same effect with an array of arrays.) Each type of array has its own
789 read syntax; see @ref{String Type}, and @ref{Vector Type}.
791 An array may have any length up to the largest integer; but once
792 created, it has a fixed size. The first element of an array has index
793 zero, the second element has index 1, and so on. This is called
794 @dfn{zero-origin} indexing. For example, an array of four elements has
795 indices 0, 1, 2, @w{and 3}.
797 The array type is contained in the sequence type and contains both the
798 string type and the vector type.
801 @subsection String Type
803 A @dfn{string} is an array of characters. Strings are used for many
804 purposes in Emacs, as can be expected in a text editor; for example, as
805 the names of Lisp symbols, as messages for the user, and to represent
806 text extracted from buffers. Strings in Lisp are constants: evaluation
807 of a string returns the same string.
809 @xref{Strings and Characters}, for functions that operate on strings.
812 * Syntax for Strings::
813 * Non-ASCII in Strings::
814 * Nonprinting Characters::
815 * Text Props and Strings::
818 @node Syntax for Strings
819 @subsubsection Syntax for Strings
821 @cindex @samp{"} in strings
822 @cindex double-quote in strings
823 @cindex @samp{\} in strings
824 @cindex backslash in strings
825 The read syntax for strings is a double-quote, an arbitrary number of
826 characters, and another double-quote, @code{"like this"}. To include a
827 double-quote in a string, precede it with a backslash; thus, @code{"\""}
828 is a string containing just a single double-quote character. Likewise,
829 you can include a backslash by preceding it with another backslash, like
830 this: @code{"this \\ is a single embedded backslash"}.
832 @cindex newline in strings
833 The newline character is not special in the read syntax for strings;
834 if you write a new line between the double-quotes, it becomes a
835 character in the string. But an escaped newline---one that is preceded
836 by @samp{\}---does not become part of the string; i.e., the Lisp reader
837 ignores an escaped newline while reading a string. An escaped space
838 @w{@samp{\ }} is likewise ignored.
841 "It is useful to include newlines
842 in documentation strings,
845 @result{} "It is useful to include newlines
846 in documentation strings,
847 but the newline is ignored if escaped."
850 @node Non-ASCII in Strings
851 @subsubsection Non-ASCII Characters in Strings
853 You can include a non-@sc{ASCII} international character in a string
854 constant by writing it literally. There are two text representations
855 for non-@sc{ASCII} characters in Emacs strings (and in buffers): unibyte
856 and multibyte. If the string constant is read from a multibyte source,
857 then the character is read as a multibyte character, and that makes the
858 string multibyte. If the string constant is read from a unibyte source,
859 then the character is read as unibyte and that makes the string unibyte.
861 You can also represent a multibyte non-@sc{ASCII} character with its
862 character code, using a hex escape, @samp{\x@var{nnnnnnn}}, with as many
863 digits as necessary. (Multibyte non-@sc{ASCII} character codes are all
864 greater than 256.) Any character which is not a valid hex digit
865 terminates this construct. If the character that would follow is a hex
866 digit, write @samp{\ } to terminate the hex escape---for example,
867 @samp{\x8c0\ } represents one character, @samp{a} with grave accent.
868 @samp{\ } in a string constant is just like backslash-newline; it does
869 not contribute any character to the string, but it does terminate the
870 preceding hex escape.
872 Using a multibyte hex escape forces the string to multibyte. You can
873 represent a unibyte non-@sc{ASCII} character with its character code,
874 which must be in the range from 128 (0200 octal) to 255 (0377 octal).
875 This forces a unibyte string.
877 @xref{Text Representations}, for more information about the two
878 text representations.
880 @node Nonprinting Characters
881 @subsubsection Nonprinting Characters in Strings
883 Strings cannot hold characters that have the hyper, super, or alt
884 modifiers; the only control or meta characters they can hold are the
885 @sc{ASCII} control characters. Strings do not distinguish case in
886 @sc{ASCII} control characters.
888 You can use the same backslash escape-sequences in a string constant
889 as in character literals (but do not use the question mark that begins a
890 character constant). For example, you can write a string containing the
891 nonprinting characters tab, @kbd{C-a} and @kbd{M-C-a}, with commas and
892 spaces between them, like this: @code{"\t, \C-a, \M-\C-a"}.
893 @xref{Character Type}, for a description of the read syntax for
896 If you use the @samp{\M-} syntax to indicate a meta character in a
897 string constant, this sets the
904 bit of the character in the string. This construct works only with
905 ASCII characters. Note that the same meta characters have a different
906 representation when not in a string. @xref{Character Type}.
908 @node Text Props and Strings
909 @subsubsection Text Properties in Strings
911 A string can hold properties for the characters it contains, in
912 addition to the characters themselves. This enables programs that copy
913 text between strings and buffers to copy the text's properties with no
914 special effort. @xref{Text Properties}, for an explanation of what text
915 properties mean. Strings with text properties use a special read and
919 #("@var{characters}" @var{property-data}...)
923 where @var{property-data} consists of zero or more elements, in groups
927 @var{beg} @var{end} @var{plist}
931 The elements @var{beg} and @var{end} are integers, and together specify
932 a range of indices in the string; @var{plist} is the property list for
933 that range. For example,
936 #("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic))
940 represents a string whose textual contents are @samp{foo bar}, in which
941 the first three characters have a @code{face} property with value
942 @code{bold}, and the last three have a @code{face} property with value
943 @code{italic}. (The fourth character has no text properties so its
944 property list is @code{nil}.)
947 @subsection Vector Type
949 A @dfn{vector} is a one-dimensional array of elements of any type. It
950 takes a constant amount of time to access any element of a vector. (In
951 a list, the access time of an element is proportional to the distance of
952 the element from the beginning of the list.)
954 The printed representation of a vector consists of a left square
955 bracket, the elements, and a right square bracket. This is also the
956 read syntax. Like numbers and strings, vectors are considered constants
960 [1 "two" (three)] ; @r{A vector of three elements.}
961 @result{} [1 "two" (three)]
964 @xref{Vectors}, for functions that work with vectors.
966 @node Char-Table Type
967 @subsection Char-Table Type
969 A @dfn{char-table} is a one-dimensional array of elements of any type,
970 indexed by character codes. Char-tables have certain extra features to
971 make them more useful for many jobs that involve assigning information
972 to character codes---for example, a char-table can have a parent to
973 inherit from, a default value, and a small number of extra slots to use for
974 special purposes. A char-table can also specify a single value for
975 a whole character set.
977 The printed representation of a char-table is like a vector
978 except that there is an extra @samp{#} at the beginning.
980 @xref{Char-Tables}, for special functions to operate on char-tables.
982 @node Bool-Vector Type
983 @subsection Bool-Vector Type
985 A @dfn{bool-vector} is a one-dimensional array of elements that
986 must be @code{t} or @code{nil}.
988 The printed representation of a Bool-vector is like a string, except
989 that it begins with @samp{#&} followed by the length. The string
990 constant that follows actually specifies the contents of the bool-vector
991 as a bitmap---each ``character'' in the string contains 8 bits, which
992 specify the next 8 elements of the bool-vector (1 stands for @code{t},
993 and 0 for @code{nil}). If the length is not a multiple of 8, the
994 printed representation describes extra elements, but these really
998 (make-bool-vector 3 t)
1000 (make-bool-vector 3 nil)
1005 @subsection Function Type
1007 Just as functions in other programming languages are executable,
1008 @dfn{Lisp function} objects are pieces of executable code. However,
1009 functions in Lisp are primarily Lisp objects, and only secondarily the
1010 text which represents them. These Lisp objects are lambda expressions:
1011 lists whose first element is the symbol @code{lambda} (@pxref{Lambda
1014 In most programming languages, it is impossible to have a function
1015 without a name. In Lisp, a function has no intrinsic name. A lambda
1016 expression is also called an @dfn{anonymous function} (@pxref{Anonymous
1017 Functions}). A named function in Lisp is actually a symbol with a valid
1018 function in its function cell (@pxref{Defining Functions}).
1020 Most of the time, functions are called when their names are written in
1021 Lisp expressions in Lisp programs. However, you can construct or obtain
1022 a function object at run time and then call it with the primitive
1023 functions @code{funcall} and @code{apply}. @xref{Calling Functions}.
1026 @subsection Macro Type
1028 A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
1029 language. It is represented as an object much like a function, but with
1030 different parameter-passing semantics. A Lisp macro has the form of a
1031 list whose first element is the symbol @code{macro} and whose @sc{cdr}
1032 is a Lisp function object, including the @code{lambda} symbol.
1034 Lisp macro objects are usually defined with the built-in
1035 @code{defmacro} function, but any list that begins with @code{macro} is
1036 a macro as far as Emacs is concerned. @xref{Macros}, for an explanation
1037 of how to write a macro.
1039 @strong{Warning}: Lisp macros and keyboard macros (@pxref{Keyboard
1040 Macros}) are entirely different things. When we use the word ``macro''
1041 without qualification, we mean a Lisp macro, not a keyboard macro.
1043 @node Primitive Function Type
1044 @subsection Primitive Function Type
1045 @cindex special forms
1047 A @dfn{primitive function} is a function callable from Lisp but
1048 written in the C programming language. Primitive functions are also
1049 called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is
1050 derived from ``subroutine''.) Most primitive functions evaluate all
1051 their arguments when they are called. A primitive function that does
1052 not evaluate all its arguments is called a @dfn{special form}
1053 (@pxref{Special Forms}).@refill
1055 It does not matter to the caller of a function whether the function is
1056 primitive. However, this does matter if you try to substitute a
1057 function written in Lisp for a primitive of the same name. The reason
1058 is that the primitive function may be called directly from C code.
1059 Calls to the redefined function from Lisp will use the new definition,
1060 but calls from C code may still use the built-in definition. Therefore,
1061 @strong{we discourage redefinition of primitive functions}.
1063 The term @dfn{function} refers to all Emacs functions, whether written
1064 in Lisp or C. @xref{Function Type}, for information about the
1065 functions written in Lisp.
1067 Primitive functions have no read syntax and print in hash notation
1068 with the name of the subroutine.
1072 (symbol-function 'car) ; @r{Access the function cell}
1073 ; @r{of the symbol.}
1074 @result{} #<subr car>
1075 (subrp (symbol-function 'car)) ; @r{Is this a primitive function?}
1076 @result{} t ; @r{Yes.}
1080 @node Byte-Code Type
1081 @subsection Byte-Code Function Type
1083 The byte compiler produces @dfn{byte-code function objects}.
1084 Internally, a byte-code function object is much like a vector; however,
1085 the evaluator handles this data type specially when it appears as a
1086 function to be called. @xref{Byte Compilation}, for information about
1089 The printed representation and read syntax for a byte-code function
1090 object is like that for a vector, with an additional @samp{#} before the
1094 @subsection Autoload Type
1096 An @dfn{autoload object} is a list whose first element is the symbol
1097 @code{autoload}. It is stored as the function definition of a symbol as
1098 a placeholder for the real definition; it says that the real definition
1099 is found in a file of Lisp code that should be loaded when necessary.
1100 The autoload object contains the name of the file, plus some other
1101 information about the real definition.
1103 After the file has been loaded, the symbol should have a new function
1104 definition that is not an autoload object. The new definition is then
1105 called as if it had been there to begin with. From the user's point of
1106 view, the function call works as expected, using the function definition
1109 An autoload object is usually created with the function
1110 @code{autoload}, which stores the object in the function cell of a
1111 symbol. @xref{Autoload}, for more details.
1114 @section Editing Types
1115 @cindex editing types
1117 The types in the previous section are common to many Lisp dialects.
1118 Emacs Lisp provides several additional data types for purposes connected
1122 * Buffer Type:: The basic object of editing.
1123 * Marker Type:: A position in a buffer.
1124 * Window Type:: Buffers are displayed in windows.
1125 * Frame Type:: Windows subdivide frames.
1126 * Window Configuration Type:: Recording the way a frame is subdivided.
1127 * Process Type:: A process running on the underlying OS.
1128 * Stream Type:: Receive or send characters.
1129 * Keymap Type:: What function a keystroke invokes.
1130 * Syntax Table Type:: What a character means.
1131 * Display Table Type:: How display tables are represented.
1132 * Overlay Type:: How an overlay is represented.
1136 @subsection Buffer Type
1138 A @dfn{buffer} is an object that holds text that can be edited
1139 (@pxref{Buffers}). Most buffers hold the contents of a disk file
1140 (@pxref{Files}) so they can be edited, but some are used for other
1141 purposes. Most buffers are also meant to be seen by the user, and
1142 therefore displayed, at some time, in a window (@pxref{Windows}). But a
1143 buffer need not be displayed in any window.
1145 The contents of a buffer are much like a string, but buffers are not
1146 used like strings in Emacs Lisp, and the available operations are
1147 different. For example, insertion of text into a buffer is very
1148 efficient, whereas ``inserting'' text into a string requires
1149 concatenating substrings, and the result is an entirely new string
1152 Each buffer has a designated position called @dfn{point}
1153 (@pxref{Positions}). At any time, one buffer is the @dfn{current
1154 buffer}. Most editing commands act on the contents of the current
1155 buffer in the neighborhood of point. Many of the standard Emacs
1156 functions manipulate or test the characters in the current buffer; a
1157 whole chapter in this manual is devoted to describing these functions
1160 Several other data structures are associated with each buffer:
1164 a local syntax table (@pxref{Syntax Tables});
1167 a local keymap (@pxref{Keymaps}); and,
1170 a local variable binding list (@pxref{Buffer-Local Variables}).
1173 a list of overlays (@pxref{Overlays}).
1176 text properties for the text in the buffer (@pxref{Text Properties}).
1180 The local keymap and variable list contain entries that individually
1181 override global bindings or values. These are used to customize the
1182 behavior of programs in different buffers, without actually changing the
1185 A buffer may be @dfn{indirect}, which means it shares the text
1186 of another buffer. @xref{Indirect Buffers}.
1188 Buffers have no read syntax. They print in hash notation, showing the
1194 @result{} #<buffer objects.texi>
1199 @subsection Marker Type
1201 A @dfn{marker} denotes a position in a specific buffer. Markers
1202 therefore have two components: one for the buffer, and one for the
1203 position. Changes in the buffer's text automatically relocate the
1204 position value as necessary to ensure that the marker always points
1205 between the same two characters in the buffer.
1207 Markers have no read syntax. They print in hash notation, giving the
1208 current character position and the name of the buffer.
1213 @result{} #<marker at 10779 in objects.texi>
1217 @xref{Markers}, for information on how to test, create, copy, and move
1221 @subsection Window Type
1223 A @dfn{window} describes the portion of the terminal screen that Emacs
1224 uses to display a buffer. Every window has one associated buffer, whose
1225 contents appear in the window. By contrast, a given buffer may appear
1226 in one window, no window, or several windows.
1228 Though many windows may exist simultaneously, at any time one window
1229 is designated the @dfn{selected window}. This is the window where the
1230 cursor is (usually) displayed when Emacs is ready for a command. The
1231 selected window usually displays the current buffer, but this is not
1232 necessarily the case.
1234 Windows are grouped on the screen into frames; each window belongs to
1235 one and only one frame. @xref{Frame Type}.
1237 Windows have no read syntax. They print in hash notation, giving the
1238 window number and the name of the buffer being displayed. The window
1239 numbers exist to identify windows uniquely, since the buffer displayed
1240 in any given window can change frequently.
1245 @result{} #<window 1 on objects.texi>
1249 @xref{Windows}, for a description of the functions that work on windows.
1252 @subsection Frame Type
1254 A @var{frame} is a rectangle on the screen that contains one or more
1255 Emacs windows. A frame initially contains a single main window (plus
1256 perhaps a minibuffer window) which you can subdivide vertically or
1257 horizontally into smaller windows.
1259 Frames have no read syntax. They print in hash notation, giving the
1260 frame's title, plus its address in core (useful to identify the frame
1266 @result{} #<frame xemacs@@mole.gnu.ai.mit.edu 0xdac80>
1270 @xref{Frames}, for a description of the functions that work on frames.
1272 @node Window Configuration Type
1273 @subsection Window Configuration Type
1274 @cindex screen layout
1276 A @dfn{window configuration} stores information about the positions,
1277 sizes, and contents of the windows in a frame, so you can recreate the
1278 same arrangement of windows later.
1280 Window configurations do not have a read syntax; their print syntax
1281 looks like @samp{#<window-configuration>}. @xref{Window
1282 Configurations}, for a description of several functions related to
1283 window configurations.
1286 @subsection Process Type
1288 The word @dfn{process} usually means a running program. Emacs itself
1289 runs in a process of this sort. However, in Emacs Lisp, a process is a
1290 Lisp object that designates a subprocess created by the Emacs process.
1291 Programs such as shells, GDB, ftp, and compilers, running in
1292 subprocesses of Emacs, extend the capabilities of Emacs.
1294 An Emacs subprocess takes textual input from Emacs and returns textual
1295 output to Emacs for further manipulation. Emacs can also send signals
1298 Process objects have no read syntax. They print in hash notation,
1299 giving the name of the process:
1304 @result{} (#<process shell>)
1308 @xref{Processes}, for information about functions that create, delete,
1309 return information about, send input or signals to, and receive output
1313 @subsection Stream Type
1315 A @dfn{stream} is an object that can be used as a source or sink for
1316 characters---either to supply characters for input or to accept them as
1317 output. Many different types can be used this way: markers, buffers,
1318 strings, and functions. Most often, input streams (character sources)
1319 obtain characters from the keyboard, a buffer, or a file, and output
1320 streams (character sinks) send characters to a buffer, such as a
1321 @file{*Help*} buffer, or to the echo area.
1323 The object @code{nil}, in addition to its other meanings, may be used
1324 as a stream. It stands for the value of the variable
1325 @code{standard-input} or @code{standard-output}. Also, the object
1326 @code{t} as a stream specifies input using the minibuffer
1327 (@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo
1330 Streams have no special printed representation or read syntax, and
1331 print as whatever primitive type they are.
1333 @xref{Read and Print}, for a description of functions
1334 related to streams, including parsing and printing functions.
1337 @subsection Keymap Type
1339 A @dfn{keymap} maps keys typed by the user to commands. This mapping
1340 controls how the user's command input is executed. A keymap is actually
1341 a list whose @sc{car} is the symbol @code{keymap}.
1343 @xref{Keymaps}, for information about creating keymaps, handling prefix
1344 keys, local as well as global keymaps, and changing key bindings.
1346 @node Syntax Table Type
1347 @subsection Syntax Table Type
1349 A @dfn{syntax table} is a char-table which specifies the syntax of
1350 each character, for word and list parsing. Each element of the syntax
1351 table defines how one character is interpreted when it appears in a
1352 buffer. For example, in C mode (@pxref{Major Modes}), the @samp{+}
1353 character is punctuation, but in Lisp mode it is a valid character in a
1354 symbol. These modes specify different interpretations by changing the
1355 syntax table entry for @samp{+}, at index 43 in the syntax table.
1357 Syntax tables are used only to control primitives that scan text in
1358 buffers, not for reading Lisp expressions. The syntax that the Lisp
1359 interpreter uses to read expressions is built into the Emacs source code
1360 and cannot be changed; thus, to change the list delimiters to be
1361 @samp{@{} and @samp{@}} instead of @samp{(} and @samp{)} would be
1362 impossible. (Some Lisp systems provide ways to redefine the read
1363 syntax, but we decided to leave this feature out of Emacs Lisp for
1366 @xref{Syntax Tables}, for details about syntax classes and how to make
1367 and modify syntax tables.
1369 @node Display Table Type
1370 @subsection Display Table Type
1372 A @dfn{display table} specifies how to display each character code.
1373 Each buffer and each window can have its own display table. A display
1374 table is actually a char-table. @xref{Display Tables}.
1377 @subsection Overlay Type
1379 An @dfn{overlay} specifies properties that apply to a part of a
1380 buffer. Each overlay applies to a specified range of the buffer, and
1381 contains a property list (a list whose elements are alternating property
1382 names and values). Overlay properties are used to present parts of the
1383 buffer temporarily in a different display style. Overlays have no read
1384 syntax, and print in hash notation, giving the buffer name and range of
1387 @xref{Overlays}, for how to create and use overlays.
1389 @node Type Predicates
1390 @section Type Predicates
1392 @cindex type checking
1393 @kindex wrong-type-argument
1395 The Emacs Lisp interpreter itself does not perform type checking on
1396 the actual arguments passed to functions when they are called. It could
1397 not do so, since function arguments in Lisp do not have declared data
1398 types, as they do in other programming languages. It is therefore up to
1399 the individual function to test whether each actual argument belongs to
1400 a type that the function can use.
1402 All built-in functions do check the types of their actual arguments
1403 when appropriate, and signal a @code{wrong-type-argument} error if an
1404 argument is of the wrong type. For example, here is what happens if you
1405 pass an argument to @code{+} that it cannot handle:
1410 @error{} Wrong type argument: number-or-marker-p, a
1414 @cindex type predicates
1415 @cindex testing types
1416 If you want your program to handle different types differently, you
1417 must do explicit type checking. The most common way to check the type
1418 of an object is to call a @dfn{type predicate} function. Emacs has a
1419 type predicate for each type, as well as some predicates for
1420 combinations of types.
1422 A type predicate function takes one argument; it returns @code{t} if
1423 the argument belongs to the appropriate type, and @code{nil} otherwise.
1424 Following a general Lisp convention for predicate functions, most type
1425 predicates' names end with @samp{p}.
1427 Here is an example which uses the predicates @code{listp} to check for
1428 a list and @code{symbolp} to check for a symbol.
1433 ;; If X is a symbol, put it on LIST.
1434 (setq list (cons x list)))
1436 ;; If X is a list, add its elements to LIST.
1437 (setq list (append x list)))
1440 ;; We only handle symbols and lists.
1441 (error "Invalid argument %s in add-on" x))))
1444 Here is a table of predefined type predicates, in alphabetical order,
1445 with references to further information.
1449 @xref{List-related Predicates, atom}.
1452 @xref{Array Functions, arrayp}.
1455 @xref{Buffer Basics, bufferp}.
1457 @item byte-code-function-p
1458 @xref{Byte-Code Type, byte-code-function-p}.
1461 @xref{Case Table, case-table-p}.
1463 @item char-or-string-p
1464 @xref{Predicates for Strings, char-or-string-p}.
1467 @xref{Interactive Call, commandp}.
1470 @xref{List-related Predicates, consp}.
1473 @xref{Predicates on Numbers, floatp}.
1476 @xref{Deleting Frames, frame-live-p}.
1479 @xref{Frames, framep}.
1482 @xref{Functions, functionp}.
1484 @item integer-or-marker-p
1485 @xref{Predicates on Markers, integer-or-marker-p}.
1488 @xref{Predicates on Numbers, integerp}.
1491 @xref{Creating Keymaps, keymapp}.
1494 @xref{List-related Predicates, listp}.
1497 @xref{Predicates on Markers, markerp}.
1500 @xref{Predicates on Numbers, wholenump}.
1503 @xref{List-related Predicates, nlistp}.
1506 @xref{Predicates on Numbers, numberp}.
1508 @item number-or-marker-p
1509 @xref{Predicates on Markers, number-or-marker-p}.
1512 @xref{Overlays, overlayp}.
1515 @xref{Processes, processp}.
1518 @xref{Sequence Functions, sequencep}.
1521 @xref{Predicates for Strings, stringp}.
1524 @xref{Function Cells, subrp}.
1527 @xref{Symbols, symbolp}.
1529 @item syntax-table-p
1530 @xref{Syntax Tables, syntax-table-p}.
1532 @item user-variable-p
1533 @xref{Defining Variables, user-variable-p}.
1536 @xref{Vectors, vectorp}.
1538 @item window-configuration-p
1539 @xref{Window Configurations, window-configuration-p}.
1542 @xref{Deleting Windows, window-live-p}.
1545 @xref{Basic Windows, windowp}.
1548 The most general way to check the type of an object is to call the
1549 function @code{type-of}. Recall that each object belongs to one and
1550 only one primitive type; @code{type-of} tells you which one (@pxref{Lisp
1551 Data Types}). But @code{type-of} knows nothing about non-primitive
1552 types. In most cases, it is more convenient to use type predicates than
1555 @defun type-of object
1556 This function returns a symbol naming the primitive type of
1557 @var{object}. The value is one of the symbols @code{symbol},
1558 @code{integer}, @code{float}, @code{string}, @code{cons}, @code{vector},
1559 @code{marker}, @code{overlay}, @code{window}, @code{buffer},
1560 @code{subr}, @code{compiled-function}, @code{process}, or
1561 @code{window-configuration}.
1568 (type-of '()) ; @r{@code{()} is @code{nil}.}
1575 @node Equality Predicates
1576 @section Equality Predicates
1579 Here we describe two functions that test for equality between any two
1580 objects. Other functions test equality between objects of specific
1581 types, e.g., strings. For these predicates, see the appropriate chapter
1582 describing the data type.
1584 @defun eq object1 object2
1585 This function returns @code{t} if @var{object1} and @var{object2} are
1586 the same object, @code{nil} otherwise. The ``same object'' means that a
1587 change in one will be reflected by the same change in the other.
1589 @code{eq} returns @code{t} if @var{object1} and @var{object2} are
1590 integers with the same value. Also, since symbol names are normally
1591 unique, if the arguments are symbols with the same name, they are
1592 @code{eq}. For other types (e.g., lists, vectors, strings), two
1593 arguments with the same contents or elements are not necessarily
1594 @code{eq} to each other: they are @code{eq} only if they are the same
1597 (The @code{make-symbol} function returns an uninterned symbol that is
1598 not interned in the standard @code{obarray}. When uninterned symbols
1599 are in use, symbol names are no longer unique. Distinct symbols with
1600 the same name are not @code{eq}. @xref{Creating Symbols}.)
1619 (eq '(1 (2 (3))) '(1 (2 (3))))
1624 (setq foo '(1 (2 (3))))
1625 @result{} (1 (2 (3)))
1628 (eq foo '(1 (2 (3))))
1633 (eq [(1 2) 3] [(1 2) 3])
1638 (eq (point-marker) (point-marker))
1645 @defun equal object1 object2
1646 This function returns @code{t} if @var{object1} and @var{object2} have
1647 equal components, @code{nil} otherwise. Whereas @code{eq} tests if its
1648 arguments are the same object, @code{equal} looks inside nonidentical
1649 arguments to see if their elements are the same. So, if two objects are
1650 @code{eq}, they are @code{equal}, but the converse is not always true.
1664 (equal "asdf" "asdf")
1673 (equal '(1 (2 (3))) '(1 (2 (3))))
1677 (eq '(1 (2 (3))) '(1 (2 (3))))
1682 (equal [(1 2) 3] [(1 2) 3])
1686 (eq [(1 2) 3] [(1 2) 3])
1691 (equal (point-marker) (point-marker))
1696 (eq (point-marker) (point-marker))
1701 Comparison of strings is case-sensitive, but does not take account of
1702 text properties---it compares only the characters in the strings.
1703 A unibyte string never equals a multibyte string unless the
1704 contents are entirely @sc{ASCII} (@pxref{Text Representations}).
1708 (equal "asdf" "ASDF")
1713 Two distinct buffers are never @code{equal}, even if their contents
1717 The test for equality is implemented recursively, and circular lists may
1718 therefore cause infinite recursion (leading to an error).