@c -*-texinfo-*-
@setfilename ../info/objects
@node Types of Lisp Object, Numbers, Introduction, Top
@chapter Lisp Data Types
@cindex object
@cindex Lisp object
@cindex type
@cindex data type

  A Lisp @dfn{object} is a piece of data used and manipulated by Lisp
programs.  For our purposes, a @dfn{type} or @dfn{data type} is a set of
possible objects.

  Every object belongs to at least one type.  Objects of the same type
have similar structures and may usually be used in the same contexts.
Types can overlap, and objects can belong to two or more types.
Consequently, we can ask whether an object belongs to a particular type,
but not for ``the'' type of an object.

@cindex primitive type
  A few fundamental object types are built into Emacs.  These, from
which all other types are constructed, are called @dfn{primitive types}.
They include @dfn{integer}, @dfn{cons}, @dfn{symbol}, @dfn{string},
@dfn{vector}, @dfn{subr} and several special types, such as
@dfn{buffer}, that are related to editing.  (@xref{Editing Types}.)

  While an object may be a member of more than one type, every object is
a member of exactly one primitive type.  The primitive type of an object
is stored with the object's data.  A Lisp function is provided for each
primitive type to check whether an object is a member of that type.

  Note that Lisp is unlike many other languages in that Lisp objects are
``self-typing'': the primitive type of the object is implicit in the
object itself.  For example, if an object is a vector, it cannot be
treated as a number because Lisp knows it is a vector, not a number.  In
most languages, the programmer must declare the data type of each
variable, and the type is known by the compiler but not represented in
the data.  Such type declarations do not exist in Emacs Lisp.

  This chapter describes the purpose, printed representation, and read
syntax of each of the standard types in GNU Emacs Lisp.  Details on how
to use these types can be found in later chapters.

@menu
* Printed Representation::      How Lisp objects are represented as text.
* Comments::                    Comments and their formatting conventions.
* Programming Types::           Types found in all Lisp systems.
* Editing Types::               Types specific to Emacs.
* Type Predicates::             Tests related to types.
* Equality Predicates::         Tests of equality between any two objects.
@end menu

@node Printed Representation, Comments, Types of Lisp Object, Types of Lisp Object
@comment  node-name,  next,  previous,  up
@section Printed Representation and Read Syntax
@cindex printed representation
@cindex read syntax

  The @dfn{printed representation} of an object is the format of the
output generated by the Lisp printer (the function @code{print}) for
that object.  The @dfn{read syntax} of an object is the format of the
input accepted by the Lisp reader (the function @code{read}) for that
object.  Most objects have more than one possible read syntax.  Some
types of object have no read syntax; except in these cases, the printed
representation of an object is also a read syntax for it.

  In other languages, an expression is text; it has no other form.  In
Lisp, an expression is primarily a Lisp object and only secondarily the
text that is the object's read syntax.  Often there is no need to
emphasize this distinction, but you must keep it in the back of your
mind, or you will occasionally be very confused.

@cindex hash notation
  Every type has a printed representation.  Some types have no read
syntax, since it may not make sense to enter objects of these types
directly in a Lisp program.  For example, the buffer type does not have
a read syntax.  Objects of these types are printed in @dfn{hash
notation}: the characters @samp{#<} followed by a descriptive string
(typically the type name followed by the name of the object), and closed
with a matching @samp{>}.  Hash notation cannot be read at all, so the
Lisp reader signals the error @code{invalid-read-syntax} whenever a
@samp{#} is encountered.
@kindex invalid-read-syntax

@example
(current-buffer)
     @result{} #<buffer objects.texi>
@end example

  When you evaluate an expression interactively, the Lisp interpreter
first reads the textual representation of it, producing a Lisp object,
and then evaluates that object (@pxref{Evaluation}).  However,
evaluation and reading are separate activities.  Reading returns the
Lisp object represented by the text that is read; the object may or may
not be evaluated later.  @xref{Input Functions}, for a description of
@code{read}, the basic function for reading objects.

@node Comments, Programming Types, Printed Representation, Types of Lisp Object
@comment  node-name,  next,  previous,  up
@section Comments
@cindex comments
@cindex @samp{;} in comment

  A @dfn{comment} is text that is written in a program only for the sake
of humans that read the program, and that has no effect on the meaning
of the program.  In Lisp, a comment starts with a semicolon (@samp{;})
and continues to the end of line.  Comments are discarded by the Lisp
reader, and do not become part of the Lisp objects which represent the
program within the Lisp system.

  We recommend these conventions for where to put comments and how to
indent them:

@table @samp
@item ;
Comments that start with a single semicolon, @samp{;}, should all be
aligned to the same column on the right of the source code.  Such
comments usually explain how the code on the same line does its job.  In
Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment})
command automatically inserts such a @samp{;} in the right place, or
aligns such a comment if it is already inserted.

(The following examples are taken from the Emacs sources.)

@group
@example
(setq base-version-list                 ; there was a base
      (assoc (substring fn 0 start-vn)  ; version to which
             file-version-assoc-list))  ; this looks like
                                        ; a subversion
@end example
@end group

@item ;;
Comments that start with two semicolons, @samp{;;}, should be aligned to
the same level of indentation as the code.  Such comments are used to
describe the purpose of the following lines or the state of the program
at that point.  For example:

@group
@example
  (prog1 (setq auto-fill-hook
               @dots{}
               @dots{}
    ;; update mode-line
    (set-buffer-modified-p (buffer-modified-p))))
@end example
@end group

These comments are also written before a function definition to explain
what the function does and how to call it properly.

@item ;;;
Comments that start with three semicolons, @samp{;;;}, should start at
the left margin.  Such comments are not used within function
definitions, but are used to make more general comments.  For example:

@group
@example
;;; This Lisp code is run in Emacs when it is to operate as
;;; a server for other processes.
@end example
@end group

@item ;;;;
Comments that start with four semicolons, @samp{;;;;}, should be aligned
to the left margin and are used for headings of major sections of a
program.  For example:

@group
@example
;;;; The kill ring
@end example
@end group
@end table

@noindent
The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;}
(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line})
automatically indent comments according to these conventions,
depending on the the number of semicolons.  @xref{Comments,,
Manipulating Comments, emacs, The GNU Emacs Manual}.

  Any character may be included in a comment, but it is advisable to
precede a character with syntactic significance in Lisp (such as
@samp{\} or unpaired @samp{(} or @samp{)}) with a @samp{\}, to prevent
it from confusing the Emacs commands for editing Lisp.

@node Programming Types, Editing Types, Comments, Types of Lisp Object
@section Programming Types
@cindex programming types

  There are two general categories of types in Emacs Lisp: those having
to do with Lisp programming, and those having to do with editing.  The
former are provided in many Lisp implementations, in one form or
another.  The latter are unique to Emacs Lisp.

@menu
* Number Type::         Primarily integers.
* Character Type::      The representation of letters, numbers and
                        control characters.
* Sequence Type::       Both lists and arrays are classified as sequences.
* List Type::           Lists gave Lisp its name (not to mention reputation).
* Array Type::          Arrays include strings and vectors.
* String Type::         An (efficient) array of characters.
* Vector Type::         One-dimensional arrays.
* Symbol Type::         A multi-use object that refers to a function,
                        variable, property list, or itself.
* Lisp Function Type::  A piece of executable code you can call from elsewhere.
* Lisp Macro Type::     A method of expanding an expression into another
                          expression, more fundamental but less pretty.
* Primitive Function Type::     A function written in C, callable from Lisp.
* Autoload Type::       A type used for automatically loading seldom-used
                        functions.
@end menu

@node Number Type, Character Type, Programming Types, Programming Types
@subsection Number Type

  Integers are the only kind of number in GNU Emacs Lisp, version 18.
The range of values for integers is @minus{}8388608 to
8388607 (24 bits; i.e.,
@ifinfo
-2**23
@end ifinfo
@tex
$-2^{23}$
@end tex
to
@ifinfo
2**23 - 1)
@end ifinfo
@tex
$2^{23}-1$)
@end tex
on most machines, but is 25 or 26 bits on some systems.  It is important
to note that the Emacs Lisp arithmetic functions do not check for
overflow.  Thus @code{(1+ 8388607)} is @minus{}8388608 on 24-bit
implementations.@refill

@cindex floating point
@cindex reals
Version 19 supports floating point numbers.

  The read syntax for numbers is a sequence of (base ten) digits with an
optional sign.  The printed representation produced by the Lisp interpreter
never has a leading @samp{+}.

@example
-1               ; @r{The integer -1.}
1                ; @r{The integer 1.}
+1               ; @r{Also the integer 1.}
16777217         ; @r{Also the integer 1! (on a 24-bit or 25-bit implementation)}
@end example

  @xref{Numbers}, for more information.

@node Character Type, Sequence Type, Number Type, Programming Types
@subsection Character Type
@cindex ASCII character codes

  A @dfn{character} in Emacs Lisp is nothing more than an integer.  In
other words, characters are represented by their eight-bit @sc{ASCII}
values.  For example, the character @kbd{A} is represented as the
@w{integer 65}.  If an arbitrary integer is used as a character, only
the lower eight bits are significant.

  Individual characters are not often used in programs.  It is far more
common to work with @emph{strings}, which are sequences composed of
characters.  @xref{String Type}.

@cindex read syntax for characters
@cindex printed representation for characters
@cindex syntax for characters
  Since characters are really integers, the printed representation of a
character is a decimal number.  This is also a possible read syntax for
a character, but it is not convenient for that purpose.  Therefore,
Emacs Lisp provides a variety of read syntax formats, such as @samp{?A}
and @samp{?\101}, for entering characters.  They all start with a
question mark.

  The usual read syntax for alphanumeric characters is a question mark
followed by the character; thus, @samp{?A} for the character
@kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the
character @kbd{a}.  For example:

@group
@example
?Q @result{} 81

?q @result{} 113
@end example
@end group

@cindex whitespace
@cindex backspace
@cindex @samp{\b}
@cindex tab
@cindex @samp{\t}
@cindex vertical tab
@cindex @samp{\v}
@cindex formfeed
@cindex @samp{\f}
@cindex newline
@cindex @samp{\n}
@cindex return
@cindex @samp{\r}
@cindex escape
@cindex @samp{\e}
  The characters backspace, tab, newline, vertical tab, formfeed,
return, and escape may be represented as @samp{?\b}, @samp{?\t},
@samp{?\n}, @samp{?\v}, @samp{?\f}, @samp{?\r}, @samp{?\e},
respectively.  Those values are 8, 9, 10, 11, 12, 13, and 27 in decimal.
Thus,@refill

@example
?\b @result{} 8                 ; @r{backspace, @key{BS}, @kbd{C-h}}
?\t @result{} 9                 ; @r{tab, @key{TAB}, @kbd{C-i}}
?\n @result{} 10                ; @r{newline, @key{LFD}, @kbd{C-j}}
?\v @result{} 11                ; @r{vertical tab, @kbd{C-k}}
?\f @result{} 12                ; @r{formfeed character, @kbd{C-l}}
?\r @result{} 13                ; @r{carriage return, @key{RET}, @kbd{C-m}}
?\e @result{} 27                ; @r{escape character, @key{ESC}, @kbd{C-[}}
?\\ @result{} 92                ; @r{backslash character, @kbd{\}}
@end example

@cindex control characters
  Control characters may be represented using yet another read syntax.
This consists of a question mark followed by a backslash, caret, and the
corresponding non-control character, in either upper or lower case.  For
example, either @samp{?\^I} or @samp{?\^i} may be used as the read
syntax for the character @kbd{C-i}, the character whose value is 9.

  Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is
equivalent to @samp{?\^I}, and @samp{?\C-i} is equivalent to
@samp{?\^i}.  For example:

@group
@example
?\^I @result{} 9
     
?\C-I @result{} 9
@end example
@end group

  The @key{DEL} key can be considered and written as @kbd{Control-?}:

@group
@example
?\^? @result{} 127
     
?\C-? @result{} 127
@end example
@end group

  When you represent control characters to be found in files or strings,
we recommend the @samp{^} syntax; but when you refer to keyboard input,
we prefer the @samp{C-} syntax.  This does not affect the meaning of the
program, but may guide the understanding of people who read it.

@cindex meta characters
  A @dfn{meta character} is a character that has its eighth bit set.
The read syntax for these characters is question mark, backslash,
@samp{M-}, and the corresponding seven-bit character.  For example,
@samp{?\M-A} stands for @kbd{M-A}, the character with code 193 (301
octal).  The seven-bit character can be written directly or specified by
any of the @samp{\} escapes described above or below.  Thus, @kbd{M-A}
can be written as @samp{?\M-A}, or as @samp{?\M-\101}, or as
@samp{?\301}.  Likewise, the character whose decimal printed
representation is 130 (202 octal) can use any one of the following for
its read syntax: @samp{?\202}, @samp{?\M-\C-b}, @samp{?\C-\M-b}, or
@samp{?\M-\002}.  For example:

@group
@example
?\C-\M-b @result{} 130          ?\M-\C-b @result{} 130

?\^\M-b @result{} 130           ?\M-\002 @result{} 130
@end example
@end group

@cindex @samp{?} in character constant
@cindex question mark in character constant
@cindex @samp{\} in character constant
@cindex backslash in character constant
@cindex octal character code
@cindex escape sequence
  Finally, the most general read syntax consists of a question mark
followed by a backslash and the @sc{ASCII} code for the character in
octal (up to three octal digits); thus, @samp{?\101} for the character
@kbd{A}, @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for
the character @kbd{C-b}.  Although this syntax can represent any
character, it is preferred only when the precise octal value is more
important than the @sc{ASCII} representation.  (These sequences which
start with backslash are also known as @dfn{escape sequences}, because
backslash plays the role of an escape character, but they have nothing
to do with the character @key{ESC}.)@refill

@example
?\012 @result{} 10        ?\n @result{} 10         ?\C-j @result{} 10

?\101 @result{} 65        ?A @result{} 65           

?\301 @result{} 193       ?\M-A @result{} 193      ?\M-\101 @result{} 193
@end example

  A backslash is allowed, and harmless, preceding any character without
a special escape meaning; thus, @samp{?\A} is equivalent to @samp{?A}.
There is no reason to use a backslash before most such characters.
However, any of the characters @samp{()\|;'`"#.,} should be preceded by
a backslash to avoid confusing the Emacs commands for editing Lisp code.
Whitespace characters such as space, tab, newline and formfeed should
also be preceded by a backslash.  However, it is cleaner to use one of
the easily readable escape sequences, such as @samp{\t}, instead of an
actual control character such as a tab.

@node Sequence Type, List Type, Character Type, Programming Types
@subsection Sequence Types

  A @dfn{sequence} is a Lisp object that represents an ordered set of
elements.  There are two kinds of sequence in Emacs Lisp, lists and
arrays.  Thus, an object of type list or of type array is also
considered a sequence.

  Arrays are further subdivided into strings and vectors.  Vectors can
hold elements of any type, but string elements must be
characters---integers from 0 to 255.

  Lists, strings and vectors are different, but they have important
similarities.  For example, all have a length @var{l}, and all have
elements which can be indexed from zero to @var{l} minus one.  Also,
several functions, called sequence functions, accept any kind of
sequence.  For example, the function @code{elt} can be used to extract
an element of a sequence, given its index.  @xref{Sequences Arrays
Vectors}.

  It is impossible to read the same sequence twice, in the sense of
@code{eq} (@pxref{Equality Predicates}), since sequences are always
created anew upon reading.  There is one exception: the empty list
@code{()} is always read as the same object, @code{nil}.

@node List Type, Array Type, Sequence Type, Programming Types
@subsection List Type
@cindex address field of register
@cindex decrement field of register

  A @dfn{list} is a series of cons cells, linked together.  A @dfn{cons
cell} is an object comprising two pointers named the @sc{car} and the
@sc{cdr}.  Each of them can point to any Lisp object, but when the cons
cell is part of a list, the @sc{cdr} points either to another cons cell
or to the empty list.  @xref{Lists}, for functions that work on lists.

  The names @sc{car} and @sc{cdr} have only historical meaning now.  The
original Lisp implementation ran on an @w{IBM 704} computer which
divided words into two parts, called the ``address'' part and the
``decrement''; @sc{car} was an instruction to extract the contents of
the address part of a register, and @sc{cdr} an instruction to extract
the contents of the decrement.  By contrast, ``cons cells'' are named
for the function @code{cons} that creates them, which in turn is named
for its purpose, the construction of cells.

@cindex atom
  Because cons cells are so central to Lisp, we also have a word for
``an object which is not a cons cell''.  These objects are called
@dfn{atoms}.

@cindex parenthesis
  The read syntax and printed representation for lists are identical, and
consist of a left parenthesis, an arbitrary number of elements, and a
right parenthesis.

   Upon reading, any object inside the parentheses is made into an
element of the list.  That is, a cons cell is made for each element.
The @sc{car} of the cons cell points to the element, and its @sc{cdr}
points to the next cons cell which holds the next element in the list.
The @sc{cdr} of the last cons cell is set to point to @code{nil}.

@cindex box diagrams, for lists
@cindex diagrams, boxed, for lists
  A list can be illustrated by a diagram in which the cons cells are
shown as pairs of boxes.  (The Lisp reader cannot read such an
illustration; unlike the textual notation, which can be understood both
humans and computers, the box illustrations can only be understood by
humans.)  The following represents the three-element list @code{(rose
violet buttercup)}:

@group
@example
    ___ ___      ___ ___      ___ ___
   |___|___|--> |___|___|--> |___|___|--> nil
     |            |            |
     |            |            |
      --> rose     --> violet   --> buttercup
@end example
@end group

  In the diagram, each box represents a slot that can refer to any Lisp
object.  Each pair of boxes represents a cons cell.  Each arrow is a
reference to a Lisp object, either an atom or another cons cell.

  In this example, the first box, the @sc{car} of the first cons cell,
refers to or ``contains'' @code{rose} (a symbol).  The second box, the
@sc{cdr} of the first cons cell, refers to the next pair of boxes, the
second cons cell.  The @sc{car} of the second cons cell refers to
@code{violet} and the @sc{cdr} refers to the third cons cell.  The
@sc{cdr} of the third (and last) cons cell refers to @code{nil}.

Here is another diagram of the same list, @code{(rose violet
buttercup)}, sketched in a different manner:

@group
@example
 ---------------         ----------------         -------------------
|car    |cdr    |       |car     |cdr    |       |car        |cdr    |
| rose  |   o---------->| violet |   o---------->| buttercup |  nil  |
|       |       |       |        |       |       |           |       |
 ---------------         ----------------         -------------------
@end example
@end group

@cindex @samp{(@dots{})} in lists
@cindex @code{nil} in lists
@cindex empty list
  A list with no elements in it is the @dfn{empty list}; it is identical
to the symbol @code{nil}.  In other words, @code{nil} is both a symbol
and a list.

  Here are examples of lists written in Lisp syntax:

@example
(A 2 "A")            ; @r{A list of three elements.}
()                   ; @r{A list of no elements (the empty list).}
nil                  ; @r{A list of no elements (the empty list).}
("A ()")             ; @r{A list of one element: the string @code{"A ()"}.}
(A ())               ; @r{A list of two elements: @code{A} and the empty list.}
(A nil)              ; @r{Equivalent to the previous.}
((A B C))            ; @r{A list of one element}
                     ; @r{(which is a list of three elements).}
@end example

  Here is the list @code{(A ())}, or equivalently @code{(A nil)},
depicted with boxes and arrows:

@group
@example
    ___ ___      ___ ___
   |___|___|--> |___|___|--> nil
     |            |
     |            |
      --> A        --> nil
@end example
@end group

@menu
* Dotted Pair Notation::        An alternative syntax for lists.
* Association List Type::       A specially constructed list.
@end menu

@node Dotted Pair Notation, Association List Type, List Type, List Type
@comment  node-name,  next,  previous,  up
@subsubsection Dotted Pair Notation
@cindex dotted pair notation
@cindex @samp{.} in lists

  @dfn{Dotted pair notation} is an alternative syntax for cons cells
that represents the @sc{car} and @sc{cdr} explicitly.  In this syntax,
@code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
the object @var{a}, and whose @sc{cdr} is the object @var{b}.  Dotted
pair notation is therefore more general than list syntax.  In the dotted
pair notation, the list @samp{(1 2 3)} is written as @samp{(1 .  (2 . (3
. nil)))}.  For @code{nil}-terminated lists, the two notations produce
the same result, but list notation is usually clearer and more
convenient when it is applicable.  When printing a list, the dotted pair
notation is only used if the @sc{cdr} of a cell is not a list.

  Box notation can also be used to illustrate what dotted pairs look
like.  For example, @code{(rose . violet)} is diagrammed as follows:

@group
@example
    ___ ___
   |___|___|--> violet
     |
     |
      --> rose
@end example
@end group

  Dotted pair notation can be combined with list notation to represent a
chain of cons cells with a non-@code{nil} final @sc{cdr}.  For example,
@code{(rose violet . buttercup)} is equivalent to @code{(rose . (violet
. buttercup))}.  The object looks like this:

@group
@example
    ___ ___      ___ ___
   |___|___|--> |___|___|--> buttercup
     |            |
     |            |
      --> rose     --> violet
@end example
@end group

  These diagrams make it evident that @w{@code{(rose .@: violet .@:
buttercup)}} must have an invalid syntax since it would require that a
cons cell have three parts rather than two.

  The list @code{(rose violet)} is equivalent to @code{(rose . (violet))}
and looks like this:

@group
@example
    ___ ___      ___ ___
   |___|___|--> |___|___|--> nil
     |            |
     |            |
      --> rose     --> violet
@end example
@end group

  Similarly, the three-element list @code{(rose violet buttercup)}
is equivalent to @code{(rose . (violet . (buttercup)))}.
@ifinfo
It looks like this:

@group
@example
    ___ ___      ___ ___      ___ ___
   |___|___|--> |___|___|--> |___|___|--> nil
     |            |            |
     |            |            |
      --> rose     --> violet   --> buttercup
@end example
@end group
@end ifinfo

@node Association List Type,  , Dotted Pair Notation, List Type
@comment  node-name,  next,  previous,  up
@subsubsection Association List Type

  An @dfn{association list} or @dfn{alist} is a specially-constructed
list whose elements are cons cells.  In each element, the @sc{car} is
considered a @dfn{key}, and the @sc{cdr} is considered an
@dfn{associated value}.  (In some cases, the associated value is stored
in the @sc{car} of the @sc{cdr}.)  Association lists are often used to
implement stacks, since new associations may easily be added to or
removed from the front of the list.

  For example,

@example
(setq alist-of-colors '((rose . red) (lily . white)  (buttercup . yellow)))
@end example

@noindent
sets the variable @code{alist-of-colors} to an alist of three elements.  In the
first element, @code{rose} is the key and @code{red} is the value.

  @xref{Association Lists}, for a further explanation of alists and for
functions that work on alists.

@node Array Type, String Type, List Type, Programming Types
@subsection Array Type

  An @dfn{array} is composed of an arbitrary number of other Lisp
objects, arranged in a contiguous block of memory.  Any element of an
array may be accessed in constant time.  In contrast, accessing an
element of a list requires time proportional to the position of the
element in the list.  (Elements at the end of a list take longer to
access than elements at the beginning of a list.)

  Emacs defines two types of array, strings and vectors.  A string is an
array of characters and a vector is an array of arbitrary objects.  Both
are one-dimensional.  (Most other programming languages support
multidimensional arrays, but we don't think they are essential in Emacs
Lisp.)  Each type of array has its own read syntax; see @ref{String
Type}, and @ref{Vector Type}.

  An array may have any length up to the largest integer; but once
created, it has a fixed size.  The first element of an array has index
zero, the second element has index 1, and so on.  This is called
@dfn{zero-origin} indexing.  For example, an array of four elements has
indices 0, 1, 2, @w{and 3}.

  The array type is contained in the sequence type and contains both
strings and vectors.

@node String Type, Vector Type, Array Type, Programming Types
@subsection String Type

  A @dfn{string} is an array of characters.  Strings are used for many
purposes in Emacs, as can be expected in a text editor; for example, as
the names of Lisp symbols, as messages for the user, and to represent
text extracted from buffers.  Strings in Lisp are constants; evaluation
of a string returns the same string.

@cindex @samp{"} in strings
@cindex double-quote in strings
@cindex @samp{\} in strings
@cindex backslash in strings
  The read syntax for strings is a double-quote, an arbitrary number of
characters, and another double-quote, @code{"like this"}.  The Lisp
reader accepts the same formats for reading the characters of a string
as it does for reading single characters (without the question mark that
begins a character literal).  You can enter a nonprinting character such
as tab, @kbd{C-a} or @kbd{M-C-A} using the convenient escape sequences,
like this: @code{"\t, \C-a, \M-\C-a"}.  You can include a double-quote
in a string by preceding it with a backslash; thus, @code{"\""} is a
string containing just a single double-quote character.
(@xref{Character Type}, for a description of the read syntax for
characters.)

  In contrast with the C programming language, newlines are allowed in
Emacs Lisp string literals.  But an escaped newline---one that is
preceded by @samp{\}---does not become part of the string; i.e., the
Lisp reader ignores an escaped newline in a string literal.
@cindex newline in strings

@example
"It is useful to include newlines in
documentation strings, but the newline is \
ignored if escaped."
     @result{} "It is useful to include newlines in
documentation strings, but the newline is ignored if escaped."
@end example

  The printed representation of a string consists of a double-quote, the
characters it contains, and another double-quote.  However, any
backslash or double-quote characters in the string are preceded with a
backslash like this: @code{"this \" is an embedded quote"}.

  @xref{Strings and Characters}, for functions that work on strings.

@node Vector Type, Symbol Type, String Type, Programming Types
@subsection Vector Type

  A @dfn{vector} is a one-dimensional array of elements of any type.  It
takes a constant amount of time to access any element of a vector.  (In
a list, the access time of an element is proportional to the distance of
the element from the beginning of the list.)

  The printed representation of a vector consists of a left square
bracket, the elements, and a right square bracket.  This is also the
read syntax.  Like numbers and strings, vectors are considered constants
for evaluation.

@example
[1 "two" (three)]      ; @r{A vector of three elements.}
     @result{} [1 "two" (three)]
@end example

  @xref{Vectors}, for functions that work with vectors.

@node Symbol Type, Lisp Function Type, Vector Type, Programming Types
@subsection Symbol Type

  A @dfn{symbol} in GNU Emacs Lisp is an object with a name.  The symbol
name is the printed representation of the symbol.  In ordinary use, the
name is unique---no two symbols have the same name.

  A symbol may be used in programs as a variable, as a function name, or
to hold a list of properties.  Or it may serve only to be distinct from
all other Lisp objects, so that its presence in a data structure may be
recognized reliably.  In a given context, usually only one of these uses
is intended.

@cindex @samp{\} in symbols
@cindex backslash in symbols
  A symbol name can contain any characters whatever.  Most symbol names
are written with letters, digits, and the punctuation characters
@samp{-+=*/}.  Such names require no special punctuation; the characters
of the name suffice as long as the name does not look like a number.
(If it does, write a @samp{\} at the beginning of the name to force
interpretation as a symbol.)  The characters @samp{_~!@@$%^&:<>@{@}} are
less often used but also require no special punctuation.  Any other
characters may be included in a symbol's name by escaping them with a
backslash.  In contrast to its use in strings, however, a backslash in
the name of a symbol quotes the single character that follows the
backslash, without conversion.  For example, in a string, @samp{\t}
represents a tab character; in the name of a symbol, however, @samp{\t}
merely quotes the letter @kbd{t}.  To have a symbol with a tab character
in its name, you must actually type an tab (preceded with a backslash).
But you would hardly ever do such a thing.@refill

@quotation
@b{Common Lisp note:} in Common Lisp, lower case letters are always
``folded'' to upper case, unless they are explicitly escaped.  This is
in contrast to Emacs Lisp, in which upper case and lower case letters
are distinct.
@end quotation

  Here are several examples of symbol names.  Note that the @samp{+} in
the fifth example is escaped to prevent it from being read as a number.
This is not necessary in the last example because the rest of the name
makes it invalid as a number.

@example
foo                 ; @r{A symbol named @samp{foo}.}
FOO                 ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
char-to-string      ; @r{A symbol named @samp{char-to-string}.}
1+                  ; @r{A symbol named @samp{1+}}
                    ;     @r{(not @samp{+1}, which is an integer).}
\+1                 ; @r{A symbol named @samp{+1} (not a very readable name).}
\(*\ 1\ 2\)         ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
@c the @'s in this next line use up three characters, hence the
@c apparent misalignment of the comment.
+-*/_~!@@$%^&=:<>@{@}  ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
                    ;     @r{These characters need not be escaped.}
@end example

@node Lisp Function Type, Lisp Macro Type, Symbol Type, Programming Types
@subsection Lisp Function Type

  Just as functions in other programming languages are executable, a
@dfn{Lisp function} object is a piece of executable code.  However, Lisp
functions are primarily Lisp objects, and only secondarily the text
which represents them.  These Lisp objects are lambda expressions: lists
whose first element is the symbol @code{lambda} (@pxref{Lambda
Expressions}).

  In most programming languages, it is impossible to have a function
without a name.  In Lisp, a function has no intrinsic name.  A lambda
expression is also called an @dfn{anonymous function} (@pxref{Anonymous
Functions}).  A named function in Lisp is actually a symbol with a valid
function in its function cell (@pxref{Defining Functions}).

  Most of the time, functions are called when their names are written in
Lisp expressions in Lisp programs.  However, a function object found or
constructed at run time can be called and passed arguments with the
primitive functions @code{funcall} and @code{apply}.  @xref{Calling
Functions}.

@node Lisp Macro Type, Primitive Function Type, Lisp Function Type, Programming Types
@subsection Lisp Macro Type

  A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
language.  It is represented as an object much like a function, but with
different parameter-passing semantics.  A Lisp macro has the form of a
list whose first element is the symbol @code{macro} and whose @sc{cdr}
is a Lisp function object, including the @code{lambda} symbol.

  Lisp macro objects are usually defined with the built-in function
@code{defmacro}, but any list that begins with @code{macro} is a macro
as far as Emacs is concerned.  @xref{Macros}, for an explanation of how
to write a macro.

@node Primitive Function Type, Autoload Type, Lisp Macro Type, Programming Types
@subsection Primitive Function Type
@cindex special forms

  A @dfn{primitive function} is a function callable from Lisp but
written in the C programming language.  Primitive functions are also
called @dfn{subrs} or @dfn{built-in functions}.  (The word ``subr'' is
derived from ``subroutine''.)  Most primitive functions evaluate all
their arguments when they are called.  A primitive function that does
not evaluate all its arguments is called a @dfn{special form}
(@pxref{Special Forms}).@refill

  It does not matter to the caller of a function whether the function is
primitive.  However, this does matter if you are trying to substitute a
function written in Lisp for a primitive of the same name.  The reason
is that the primitive function may be called directly from C code.  When
the redefined function is called from Lisp, the new definition will be
used; but calls from C code may still use the old definition.

  The term @dfn{function} is used to refer to all Emacs functions,
whether written in Lisp or C.  @xref{Lisp Function Type}, for information
about the functions written in Lisp.@refill

  Primitive functions have no read syntax and print in hash notation
with the name of the subroutine.

@example
(symbol-function 'car)          ; @r{Access the function cell of the symbol.}
     @result{} #<subr car>
(subrp (symbol-function 'car))  ; @r{Is this a primitive function?}
     @result{} t                       ; @r{Yes.}
@end example

@node Autoload Type,  , Primitive Function Type, Programming Types
@subsection Autoload Type

  An @dfn{autoload object} is a list whose first element is the symbol
@code{autoload}.  It is stored as the function definition of a symbol to
say that a file of Lisp code should be loaded when necessary to find the
true definition of that symbol.  The autoload object contains the name
of the file, plus some other information about the real definition.

  After the file has been loaded, the symbol should have a new function
definition that is not an autoload object.  The new definition is then
called as if it had been there to begin with.  From the user's point of
view, the function call works as expected, using the function definition
in the loaded file.

  An autoload object is usually created with the function
@code{autoload}, which stores the object in the function cell of a
symbol.  @xref{Autoload}, for more details.

@node Editing Types, Type Predicates, Programming Types, Types of Lisp Object
@section Editing Types
@cindex editing types

  The types in the previous section are common to many Lisp-like
languages.  But Emacs Lisp provides several additional data types for
purposes connected with editing.

@menu
* Buffer Type::         The basic object of editing.
* Window Type::         What makes buffers visible.
* Window Configuration Type::   Save what the screen looks like.
* Marker Type::         A position in a buffer.
* Process Type::        A process running on the underlying OS.
* Stream Type::         Receive or send characters.
* Keymap Type::         What function a keystroke invokes.
* Syntax Table Type::   What a character means.
@end menu

@node Buffer Type, Window Type, Editing Types, Editing Types
@subsection Buffer Type

  A @dfn{buffer} is an object that holds text that can be edited
(@pxref{Buffers}).  Most buffers hold the contents of a disk file
(@pxref{Files}) so they can be edited, but some are used for other
purposes.  Most buffers are also meant to be seen by the user, and
therefore displayed, at some time, in a window (@pxref{Windows}).  But a
buffer need not be displayed in a window.

  The contents of a buffer are much like a string, but buffers are not
used like strings in Emacs Lisp, and the available operations are
different.  For example, text can be inserted into a buffer very
quickly, while ``inserting'' text into a string is accomplished by
concatenation and the result is an entirely new string object.

  Each buffer has a designated position called @dfn{point}
(@pxref{Positions}).  And one buffer is the @dfn{current buffer}.  Most
editing commands act on the contents of the current buffer in the
neighborhood of point.  Many other functions manipulate or test the
characters in the current buffer and much of this manual is devoted to
describing these functions (@pxref{Text}).

  Several other data structures are associated with each buffer:

@itemize @bullet
@item
a local syntax table (@pxref{Syntax Tables});

@item
a local keymap (@pxref{Keymaps}); and,

@item
a local variable binding list (@pxref{Variables}).
@end itemize

@noindent
The local keymap and variable list contain entries which individually
override global bindings or values.  These are used to customize the
behavior of programs in different buffers, without actually changing the
programs.

  Buffers have no read syntax.  They print in hash notation with the
buffer name.

@example
(current-buffer)
     @result{} #<buffer objects.texi>
@end example

@node Window Type, Window Configuration Type, Buffer Type, Editing Types
@subsection Window Type

  A @dfn{window} describes the portion of the terminal screen that Emacs
uses to display a buffer.  Every window has one associated buffer, whose
contents appear in the window.  By contrast, a given buffer may appear
in one window, no window, or several windows.

  Though many windows may exist simultaneously, one window is designated
the @dfn{selected window}.  This is the window where the cursor is
(usually) displayed when Emacs is ready for a command.  The selected window
usually displays the current buffer, but this is not necessarily the
case.

  Windows have no read syntax.  They print in hash notation, giving the
window number and the name of the buffer being displayed.  The window
numbers exist to identify windows uniquely, since the buffer displayed
in any given window can change frequently.

@example
(selected-window)
     @result{} #<window 1 on objects.texi>
@end example

  @xref{Windows}, for a description of the functions that work on windows.

@node Window Configuration Type, Marker Type, Window Type, Editing Types
@subsection Window Configuration Type
@cindex screen layout

  A @dfn{window configuration} stores information about the positions
and sizes of windows at the time the window configuration is created, so
that the screen layout may be recreated later.

  Window configurations have no read syntax.  They print as
@samp{#<window-configuration>}.  @xref{Window Configurations}, for a
description of several functions related to window configurations.

@node Marker Type, Process Type, Window Configuration Type, Editing Types
@subsection Marker Type

  A @dfn{marker} denotes a position in a specific buffer.  Markers
therefore have two components: one for the buffer, and one for the
position.  The position value is changed automatically as necessary as
text is inserted into or deleted from the buffer.  This is to ensure
that the marker always points between the same two characters in the
buffer.

  Markers have no read syntax.  They print in hash notation, giving the
current character position and the name of the buffer.

@example
(point-marker)
     @result{} #<marker at 10779 in objects.texi>
@end example

@xref{Markers}, for information on how to test, create, copy, and move
markers.

@node Process Type, Stream Type, Marker Type, Editing Types
@subsection Process Type

  The word @dfn{process} means a running program.  Emacs itself runs in
a process of this sort.  However, in Emacs Lisp, a process is a Lisp
object that designates a subprocess created by Emacs process.  External
subprocesses, such as shells, GDB, ftp, and compilers, may be used to
extend the processing capability of Emacs.

  A process takes input from Emacs and returns output to Emacs for
further manipulation.  Both text and signals can be communicated between
Emacs and a subprocess.

  Processes have no read syntax.  They print in hash notation, giving
the name of the process:

@example
(process-list)
     @result{} (#<process shell>)
@end example

@xref{Processes}, for information about functions that create, delete,
return information about, send input or signals to, and receive output
from processes.

@node Stream Type, Keymap Type, Process Type, Editing Types
@subsection Stream Type

  A @dfn{stream} is an object that can be used as a source or sink for
characters---either to supply characters for input or to accept them as
output.  Many different types can be used this way: markers, buffers,
strings, and functions.  Most often, input streams (character sources)
obtain characters from the keyboard, a buffer, or a file, and output
streams (character sinks) send characters to a buffer, such as a
@file{*Help*} buffer, or to the echo area.

  The object @code{nil}, in addition to its other meanings, may be used
as a stream.  It stands for the value of the variable
@code{standard-input} or @code{standard-output}.  Also, the object
@code{t} as a stream specifies input using the minibuffer
(@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo
Area}).

  Streams have no special printed representation or read syntax, and
print as whatever primitive type they are.

  @xref{Streams}, for a description of various functions related to
streams, including various parsing and printing functions.

@node Keymap Type, Syntax Table Type, Stream Type, Editing Types
@subsection Keymap Type

  A @dfn{keymap} maps keys typed by the user to functions.  This mapping
controls how the user's command input is executed.  Emacs defines two
kinds of keymaps: @dfn{full keymaps}, which are vectors of 128 elements,
and @dfn{sparse keymaps}, which are association lists whose first
element is the symbol @code{keymap}.

  @xref{Keymaps}, for information about creating keymaps, handling prefix
keys, local as well as global keymaps, and changing key bindings.

@node Syntax Table Type,  , Keymap Type, Editing Types
@subsection Syntax Table Type

  A @dfn{syntax table} is a vector of 256 integers.  Each element of the
vector defines how one character is interpreted when it appears in a
buffer.  For example, in C mode (@pxref{Major Modes}), the @samp{+}
character is punctuation, but in Lisp mode it is a valid character in a
symbol.  These different interpretations are effected by changing the
syntax table entry for @samp{+}, i.e., at @w{index 43}.@refill

  Syntax tables are only used for scanning text in buffers, not for
reading Lisp expressions.  The table the Lisp interpreter uses to read
expressions is built into the Emacs source code and cannot be changed;
thus, to change the list delimiters to be @samp{@{} and @samp{@}}
instead of @samp{(} and @samp{)} would be impossible.

  @xref{Syntax Tables}, for details about syntax classes and how to make
and modify syntax tables.

@node Type Predicates, Equality Predicates, Editing Types, Types of Lisp Object
@section Type Predicates
@cindex predicates
@cindex type checking
@kindex wrong-type-argument

  The Emacs Lisp interpreter itself does not perform type checking on
the actual arguments passed to functions when they are called.  It could
not do otherwise, since variables in Lisp are not declared to be of a
certain type, as they are in other programming languages.  It is
therefore up to the individual function to test whether each actual
argument belongs to a type that can be used by the function.

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

@group
@example
(+ 2 'a)
     @error{} Wrong type argument: integer-or-marker-p, a
@end example
@end group

@cindex type predicates
@cindex testing types
  Many functions, called @dfn{type predicates}, are provided to test
whether an object is a member of a given type.  (Following a convention
of long standing, the names of most Emacs Lisp predicates end in
@samp{p}.)

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

@table @code
@item atom
@pxref{List-related Predicates, atom}

@item arrayp
@pxref{Array Functions, arrayp}

@item bufferp
@pxref{Buffer Basics, bufferp}

@item char-or-string-p
@pxref{Predicates for Strings, char-or-string-p}

@item consp
@pxref{List-related Predicates, consp}

@item integer-or-marker-p
@pxref{Predicates on Markers, integer-or-marker-p}

@item integerp
@pxref{Predicates on Numbers, integerp}

@item keymapp
@pxref{Creating Keymaps, keymapp}

@item listp
@pxref{List-related Predicates, listp}

@item markerp
@pxref{Predicates on Markers, markerp}

@item natnump
@pxref{Predicates on Numbers, natnump}

@item nlistp
@pxref{List-related Predicates, nlistp}

@item processp
@pxref{Processes, processp}

@item sequencep
@pxref{Sequence Functions, sequencep}

@item stringp
@pxref{Predicates for Strings, stringp}

@item subrp
@pxref{Function Cells, subrp}

@item symbolp
@pxref{Symbols, symbolp}

@item syntax-table-p
@pxref{Syntax Tables, syntax-table-p}

@item user-variable-p
@pxref{Defining Variables, user-variable-p}

@item vectorp
@pxref{Vectors, vectorp}

@item windowp
@pxref{Basic Windows, windowp}
@end table

@node Equality Predicates,  , Type Predicates, Types of Lisp Object
@section Equality Predicates
@cindex equality

  Here we describe two functions that test for equality between any two
objects.  Other functions test equality between objects of specific
types, e.g., strings.  See the appropriate chapter describing the data
type for these predicates.

@defun eq object1 object2
  This function returns @code{t} if @var{object1} and @var{object2} are
the same object, @code{nil} otherwise.  The ``same object'' means that a
change in one will be reflected by the same change in the other.

  @code{eq} will be true if @var{object1} and @var{object2} are numbers
with the same value.  Also, since symbol names are normally unique, if
the arguments are symbols with the same name, they are @code{eq}.  For
other types (e.g., lists, vectors, strings), two arguments with the same
contents or elements are not necessarily @code{eq} to each other: they
are @code{eq} only if they are the same object.

  (The @code{make-symbol} function returns an uninterned symbol that is
not interned in the standard @code{obarray}.  When uninterned symbols
are in use, symbol names are no longer unique.  Distinct symbols with
the same name are not @code{eq}.  @xref{Creating Symbols}.)

@example
(eq 'foo 'foo)
     @result{} t

(eq 456 456)
     @result{} t

(eq "asdf" "asdf")
     @result{} nil

(eq '(1 (2 (3))) '(1 (2 (3))))
     @result{} nil

(eq [(1 2) 3] [(1 2) 3])
     @result{} nil

(eq (point-marker) (point-marker))
     @result{} nil
@end example

@end defun

@defun equal object1 object2
  This function returns @code{t} if @var{object1} and @var{object2} have
equal components, @code{nil} otherwise.  Whereas @code{eq} tests if its
arguments are the same object, @code{equal} looks inside nonidentical
arguments to see if their elements are the same.  So, if two objects are
@code{eq}, they are @code{equal}, but the converse is not always true.

@example
(equal 'foo 'foo)
     @result{} t

(equal 456 456)
     @result{} t

(equal "asdf" "asdf")
     @result{} t
(eq "asdf" "asdf")
     @result{} nil

(equal '(1 (2 (3))) '(1 (2 (3))))
     @result{} t
(eq '(1 (2 (3))) '(1 (2 (3))))
     @result{} nil

(equal [(1 2) 3] [(1 2) 3])
     @result{} t
(eq [(1 2) 3] [(1 2) 3])
     @result{} nil

(equal (point-marker) (point-marker))
     @result{} t
@group
(eq (point-marker) (point-marker))
     @result{} nil
@end group
@end example

Comparison of strings is case-sensitive.

@example
(equal "asdf" "ASDF")
     @result{} nil
@end example
@end defun

  The test for equality is implemented recursively, and circular lists may
therefore cause infinite recursion (leading to an error).
