@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/objects
@node Lisp Data Types, Numbers, Introduction, Top
Each primitive type has a corresponding Lisp function that checks
whether an object is a member of that type.
- Note that Lisp is unlike many other languages in that Lisp objects are
-@dfn{self-typing}: the primitive type of the object is implicit in the
-object itself. For example, if an object is a vector, nothing can treat
-it as a number; Lisp knows it is a vector, not a number.
+ Lisp is unlike many other languages in that its objects are
+@dfn{self-typing}: the primitive type of each object is implicit in
+the object itself. For example, if an object is a vector, nothing can
+treat it as a number; 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
@node Integer Type
@subsection Integer Type
- The range of values for integers in Emacs Lisp is @minus{}268435456 to
-268435455 (29 bits; i.e.,
+ The range of values for integers in Emacs Lisp is @minus{}536870912 to
+536870911 (30 bits; i.e.,
@ifnottex
--2**28
+-2**29
@end ifnottex
@tex
-@math{-2^{28}}
+@math{-2^{29}}
@end tex
to
@ifnottex
-2**28 - 1)
+2**29 - 1)
@end ifnottex
@tex
-@math{2^{28}-1})
+@math{2^{29}-1})
@end tex
-on most machines. (Some machines may provide a wider range.) It is
-important to note that the Emacs Lisp arithmetic functions do not check
-for overflow. Thus @code{(1+ 268435455)} is @minus{}268435456 on most
-machines.
+on typical 32-bit machines. (Some machines provide a wider range.)
+Emacs Lisp arithmetic functions do not check for overflow. Thus
+@code{(1+ 536870911)} is @minus{}536870912 if Emacs integers are 30 bits.
The read syntax for integers is a sequence of (base ten) digits with an
optional sign at the beginning and an optional period at the end. The
1 ; @r{The integer 1.}
1. ; @r{Also the integer 1.}
+1 ; @r{Also the integer 1.}
-536870913 ; @r{Also the integer 1 on a 29-bit implementation.}
@end group
@end example
+@noindent
+As a special exception, if a sequence of digits specifies an integer
+too large or too small to be a valid integer object, the Lisp reader
+reads it as a floating-point number (@pxref{Floating Point Type}).
+For instance, if Emacs integers are 30 bits, @code{536870912} is read
+as the floating-point number @code{536870912.0}.
+
@xref{Numbers}, for more information.
@node Floating Point Type
more common to work with @emph{strings}, which are sequences composed
of characters. @xref{String Type}.
- Characters in strings, buffers, and files are currently limited to
-the range of 0 to 524287---nineteen bits. But not all values in that
-range are valid character codes. Codes 0 through 127 are
-@acronym{ASCII} codes; the rest are non-@acronym{ASCII}
-(@pxref{Non-ASCII Characters}). Characters that represent keyboard
-input have a much wider range, to encode modifier keys such as
-Control, Meta and Shift.
+ Characters in strings and buffers are currently limited to the range
+of 0 to 4194303---twenty two bits (@pxref{Character Codes}). Codes 0
+through 127 are @acronym{ASCII} codes; the rest are
+non-@acronym{ASCII} (@pxref{Non-ASCII Characters}). Characters that
+represent keyboard input have a much wider range, to encode modifier
+keys such as Control, Meta and Shift.
There are special functions for producing a human-readable textual
description of a character for the sake of messages. @xref{Describing
Characters}.
@menu
-* Basic Char Syntax::
-* General Escape Syntax::
-* Ctl-Char Syntax::
-* Meta-Char Syntax::
-* Other Char Bits::
+* Basic Char Syntax:: Syntax for regular characters.
+* General Escape Syntax:: How to specify characters by their codes.
+* Ctl-Char Syntax:: Syntax for control characters.
+* Meta-Char Syntax:: Syntax for meta-characters.
+* Other Char Bits:: Syntax for hyper-, super-, and alt-characters.
@end menu
@node Basic Char Syntax
@node General Escape Syntax
@subsubsection General Escape Syntax
- In addition to the specific excape sequences for special important
-control characters, Emacs provides general categories of escape syntax
-that you can use to specify non-ASCII text characters.
+ In addition to the specific escape sequences for special important
+control characters, Emacs provides several types of escape syntax that
+you can use to specify non-ASCII text characters.
@cindex unicode character escape
- For instance, you can specify characters by their Unicode values.
+ You can specify characters by their Unicode values.
@code{?\u@var{nnnn}} represents a character that maps to the Unicode
-code point @samp{U+@var{nnnn}}. There is a slightly different syntax
-for specifying characters with code points above @code{#xFFFF};
-@code{\U00@var{nnnnnn}} represents the character whose Unicode code
-point is @samp{U+@var{nnnnnn}}, if such a character is supported by
-Emacs. If the corresponding character is not supported, Emacs signals
-an error.
+code point @samp{U+@var{nnnn}} (by convention, Unicode code points are
+given in hexadecimal). There is a slightly different syntax for
+specifying characters with code points higher than
+@code{U+@var{ffff}}: @code{\U00@var{nnnnnn}} represents the character
+whose code point is @samp{U+@var{nnnnnn}}. The Unicode Standard only
+defines code points up to @samp{U+@var{10ffff}}, so if you specify a
+code point higher than that, Emacs signals an error.
This peculiar and inconvenient syntax was adopted for compatibility
with other programming languages. Unlike some other languages, Emacs
-Lisp supports this syntax in only character literals and strings.
+Lisp supports this syntax only in character literals and strings.
@cindex @samp{\} in character constant
-@cindex backslash in character constant
+@cindex backslash in character constants
@cindex octal character code
The most general read syntax for a character represents the
character code in either octal or hex. To use octal, write a question
and the hexadecimal character code. You can use any number of hex
digits, so you can represent any character code in this way.
Thus, @samp{?\x41} for the character @kbd{A}, @samp{?\x1} for the
-character @kbd{C-a}, and @code{?\x8e0} for the Latin-1 character
+character @kbd{C-a}, and @code{?\xe0} for the Latin-1 character
@iftex
@samp{@`a}.
@end iftex
@ifnottex
2**26
@end ifnottex
-bit as well as the code for the corresponding non-control
-character. Ordinary terminals have no way of generating non-@acronym{ASCII}
-control characters, but you can generate them straightforwardly using X
-and other window systems.
+bit as well as the code for the corresponding non-control character.
+Ordinary text terminals have no way of generating non-@acronym{ASCII}
+control characters, but you can generate them straightforwardly using
+X and other window systems.
For historical reasons, Emacs treats the @key{DEL} character as
the control equivalent of @kbd{?}:
bit attached to an @acronym{ASCII} character indicates a meta
character; thus, the meta characters that can fit in a string have
codes in the range from 128 to 255, and are the meta versions of the
-ordinary @acronym{ASCII} characters. (In Emacs versions 18 and older,
-this convention was used for characters outside of strings as well.)
+ordinary @acronym{ASCII} characters. @xref{Strings of Events}, for
+details about @key{META}-handling in strings.
The read syntax for meta characters uses @samp{\M-}. For example,
@samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with
@end ifnottex
bit to indicate that the shift key was used in typing a control
character. This distinction is possible only when you use X terminals
-or other special terminals; ordinary terminals do not report the
-distinction to the computer in any way. The Lisp syntax for
-the shift bit is @samp{\S-}; thus, @samp{?\C-\S-o} or @samp{?\C-\S-O}
-represents the shifted-control-o character.
+or other special terminals; ordinary text terminals do not report the
+distinction. The Lisp syntax for the shift bit is @samp{\S-}; thus,
+@samp{?\C-\S-o} or @samp{?\C-\S-O} represents the shifted-control-o
+character.
@cindex hyper characters
@cindex super characters
independently.
A symbol whose name starts with a colon (@samp{:}) is called a
-@dfn{keyword symbol}. These symbols automatically act as constants, and
-are normally used only by comparing an unknown symbol with a few
-specific alternatives.
+@dfn{keyword symbol}. These symbols automatically act as constants,
+and are normally used only by comparing an unknown symbol with a few
+specific alternatives. @xref{Constant Variables}.
@cindex @samp{\} in symbols
@cindex backslash in symbols
@group
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}.}
@end group
@group
1+ ; @r{A symbol named @samp{1+}}
@end group
@end example
+@cindex @samp{##} read syntax
@ifinfo
@c This uses ``colon'' instead of a literal `:' because Info cannot
@c cope with a `:' in a menu
@ifnotinfo
@cindex @samp{#:} read syntax
@end ifnotinfo
- Normally the Lisp reader interns all symbols (@pxref{Creating
-Symbols}). To prevent interning, you can write @samp{#:} before the
-name of the symbol.
+ As an exception to the rule that a symbol's name serves as its
+printed representation, @samp{##} is the printed representation for an
+interned symbol whose name is an empty string. Furthermore,
+@samp{#:@var{foo}} is the printed representation for an uninterned
+symbol whose name is @var{foo}. (Normally, the Lisp reader interns
+all symbols; @pxref{Creating Symbols}.)
@node Sequence Type
@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, vectors, char-tables and
-bool-vectors. Vectors can hold elements of any type, but string
-elements must be characters, and bool-vector elements must be @code{t}
-or @code{nil}. Char-tables are like vectors except that they are
-indexed by any valid character code. The characters in a string can
-have text properties like characters in a buffer (@pxref{Text
-Properties}), but vectors do not support text properties, even when
-their elements happen to be characters.
-
- Lists, strings and the other array types 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.
-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}.
+elements. There are two kinds of sequence in Emacs Lisp: @dfn{lists}
+and @dfn{arrays}.
+
+ Lists are the most commonly-used sequences. A list can hold
+elements of any type, and its length can be easily changed by adding
+or removing elements. See the next subsection for more about lists.
+
+ Arrays are fixed-length sequences. They are further subdivided into
+strings, vectors, char-tables and bool-vectors. Vectors can hold
+elements of any type, whereas string elements must be characters, and
+bool-vector elements must be @code{t} or @code{nil}. Char-tables are
+like vectors except that they are indexed by any valid character code.
+The characters in a string can have text properties like characters in
+a buffer (@pxref{Text Properties}), but vectors do not support text
+properties, even when their elements happen to be characters.
+
+ Lists, strings and the other array types also share 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. Several
+functions, called sequence functions, accept any kind of sequence.
+For example, the function @code{length} reports the length of any kind
+of sequence. @xref{Sequences Arrays Vectors}.
It is generally impossible to read the same sequence twice, since
sequences are always created anew upon reading. If you read the read
@cindex decrement field of register
@cindex pointers
- A @dfn{cons cell} is an object that consists of two slots, called the
-@sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} or
-@dfn{refer to} any Lisp object. We also say that ``the @sc{car} of
-this cons cell is'' whatever object its @sc{car} slot currently holds,
-and likewise for the @sc{cdr}.
-
-@quotation
-A note to C programmers: in Lisp, we do not distinguish between
-``holding'' a value and ``pointing to'' the value, because pointers in
-Lisp are implicit.
-@end quotation
+ A @dfn{cons cell} is an object that consists of two slots, called
+the @sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} any
+Lisp object. We also say that ``the @sc{car} of this cons cell is''
+whatever object its @sc{car} slot currently holds, and likewise for
+the @sc{cdr}.
+@cindex list structure
A @dfn{list} is a series of cons cells, linked together so that the
@sc{cdr} slot of each cons cell holds either the next cons cell or the
empty list. The empty list is actually the symbol @code{nil}.
-@xref{Lists}, for functions that work on lists. Because most cons
-cells are used as part of lists, the phrase @dfn{list structure} has
-come to refer to any structure made out of cons cells.
+@xref{Lists}, for details. Because most cons cells are used as part
+of lists, we refer to any structure made out of cons cells as a
+@dfn{list structure}.
+
+@cindex linked list
+@quotation
+A note to C programmers: a Lisp list thus works as a @dfn{linked list}
+built up of cons cells. Because pointers in Lisp are implicit, we do
+not distinguish between a cons cell slot ``holding'' a value versus
+``pointing to'' the value.
+@end quotation
@cindex atoms
Because cons cells are so central to Lisp, we also have a word for
@xref{Strings and Characters}, for functions that operate on strings.
@menu
-* Syntax for Strings::
-* Non-ASCII in Strings::
-* Nonprinting Characters::
-* Text Props and Strings::
+* Syntax for Strings:: How to specify Lisp strings.
+* Non-ASCII in Strings:: International characters in strings.
+* Nonprinting Characters:: Literal unprintable characters in strings.
+* Text Props and Strings:: Strings with text properties.
@end menu
@node Syntax for 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"}. To include a
-double-quote in a string, precede it with a backslash; thus, @code{"\""}
-is a string containing just a single double-quote character. Likewise,
-you can include a backslash by preceding it with another backslash, like
-this: @code{"this \\ is a single embedded backslash"}.
+ The read syntax for a string is a double-quote, an arbitrary number
+of characters, and another double-quote, @code{"like this"}. To
+include a double-quote in a string, precede it with a backslash; thus,
+@code{"\""} is a string containing just a single double-quote
+character. Likewise, you can include a backslash by preceding it with
+another backslash, like this: @code{"this \\ is a single embedded
+backslash"}.
@cindex newline in strings
The newline character is not special in the read syntax for strings;
@node Non-ASCII in Strings
@subsubsection Non-@acronym{ASCII} Characters in Strings
- You can include a non-@acronym{ASCII} international character in a string
-constant by writing it literally. There are two text representations
-for non-@acronym{ASCII} characters in Emacs strings (and in buffers): unibyte
-and multibyte. If the string constant is read from a multibyte source,
-such as a multibyte buffer or string, or a file that would be visited as
-multibyte, then the character is read as a multibyte character, and that
-makes the string multibyte. If the string constant is read from a
-unibyte source, then the character is read as unibyte and that makes the
-string unibyte.
-
- You can also represent a multibyte non-@acronym{ASCII} character with its
-character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many
-digits as necessary. (Multibyte non-@acronym{ASCII} character codes are all
-greater than 256.) Any character which is not a valid hex digit
-terminates this construct. If the next character in the string could be
-interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to
-terminate the hex escape---for example, @w{@samp{\x8e0\ }} represents
-one character, @samp{a} with grave accent. @w{@samp{\ }} in a string
-constant is just like backslash-newline; it does not contribute any
-character to the string, but it does terminate the preceding hex escape.
+ You can include a non-@acronym{ASCII} international character in a
+string constant by writing it literally. There are two text
+representations for non-@acronym{ASCII} characters in Emacs strings
+(and in buffers): unibyte and multibyte (@pxref{Text
+Representations}). If the string constant is read from a multibyte
+source, such as a multibyte buffer or string, or a file that would be
+visited as multibyte, then Emacs reads the non-@acronym{ASCII}
+character as a multibyte character and automatically makes the string
+a multibyte string. If the string constant is read from a unibyte
+source, then Emacs reads the non-@acronym{ASCII} character as unibyte,
+and makes the string unibyte.
+
+ Instead of writing a non-@acronym{ASCII} character literally into a
+multibyte string, you can write it as its character code using a hex
+escape, @samp{\x@var{nnnnnnn}}, with as many digits as necessary.
+(Multibyte non-@acronym{ASCII} character codes are all greater than
+256.) You can also specify a character in a multibyte string using
+the @samp{\u} or @samp{\U} Unicode escape syntax (@pxref{General
+Escape Syntax}). In either case, any character which is not a valid
+hex digit terminates the construct. If the next character in the
+string could be interpreted as a hex digit, write @w{@samp{\ }}
+(backslash and space) to terminate the hex escape---for example,
+@w{@samp{\xe0\ }} represents one character, @samp{a} with grave
+accent. @w{@samp{\ }} in a string constant is just like
+backslash-newline; it does not contribute any character to the string,
+but it does terminate the preceding hex escape. Using any hex escape
+in a string (even for an @acronym{ASCII} character) automatically
+forces the string to be multibyte.
You can represent a unibyte non-@acronym{ASCII} character with its
character code, which must be in the range from 128 (0200 octal) to
255 (0377 octal). If you write all such character codes in octal and
the string contains no other characters forcing it to be multibyte,
-this produces a unibyte string. However, using any hex escape in a
-string (even for an @acronym{ASCII} character) forces the string to be
-multibyte.
-
- You can also specify characters in a string by their numeric values
-in Unicode, using @samp{\u} and @samp{\U} (@pxref{Character Type}).
-
- @xref{Text Representations}, for more information about the two
-text representations.
+this produces a unibyte string.
@node Nonprinting Characters
@subsubsection Nonprinting Characters in Strings
@node Text Props and Strings
@subsubsection Text Properties in Strings
+@cindex @samp{#(} read syntax
+@cindex text properties, read syntax
A string can hold properties for the characters it contains, in
addition to the characters themselves. This enables programs that copy
text between strings and buffers to copy the text's properties with no
@node Bool-Vector Type
@subsection Bool-Vector Type
- A @dfn{bool-vector} is a one-dimensional array of elements that
-must be @code{t} or @code{nil}.
+ A @dfn{bool-vector} is a one-dimensional array whose elements must
+be @code{t} or @code{nil}.
The printed representation of a bool-vector is like a string, except
that it begins with @samp{#&} followed by the length. The string
A hash table is a very fast kind of lookup table, somewhat like an
alist in that it maps keys to corresponding values, but much faster.
-Hash tables have no read syntax, and print using hash notation.
-@xref{Hash Tables}, for functions that operate on hash tables.
+The printed representation of a hash table specifies its properties
+and contents, like this:
@example
(make-hash-table)
- @result{} #<hash-table 'eql nil 0/65 0x83af980>
+ @result{} #s(hash-table size 65 test eql rehash-size 1.5
+ rehash-threshold 0.8 data ())
@end example
+@noindent
+@xref{Hash Tables}, for more information about hash tables.
+
@node Function Type
@subsection Function Type
@node Primitive Function Type
@subsection Primitive Function Type
-@cindex special forms
+@cindex primitive function
A @dfn{primitive function} is a function callable from Lisp but
written in the C programming language. Primitive functions are also
@node Byte-Code Type
@subsection Byte-Code Function Type
-The byte compiler produces @dfn{byte-code function objects}.
-Internally, a byte-code function object is much like a vector; however,
-the evaluator handles this data type specially when it appears as a
-function to be called. @xref{Byte Compilation}, for information about
-the byte compiler.
+@dfn{Byte-code function objects} are produced by byte-compiling Lisp
+code (@pxref{Byte Compilation}). Internally, a byte-code function
+object is much like a vector; however, the evaluator handles this data
+type specially when it appears in a function call. @xref{Byte-Code
+Objects}.
The printed representation and read syntax for a byte-code function
object is like that for a vector, with an additional @samp{#} before the
* Buffer Type:: The basic object of editing.
* Marker Type:: A position in a buffer.
* Window Type:: Buffers are displayed in windows.
-* Frame Type:: Windows subdivide frames.
+* Frame Type:: Windows subdivide frames.
+* Terminal Type:: A terminal device displays frames.
* Window Configuration Type:: Recording the way a frame is subdivided.
* Frame Configuration Type:: Recording the status of all frames.
-* Process Type:: A process running on the underlying OS.
+* Process Type:: A subprocess of Emacs running on the underlying OS.
* Stream Type:: Receive or send characters.
* Keymap Type:: What function a keystroke invokes.
* Overlay Type:: How an overlay is represented.
+* Font Type:: Fonts for displaying text.
@end menu
@node Buffer Type
(@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 any window.
+therefore displayed, at some time, in a window (@pxref{Windows}). But
+a buffer need not be displayed in any window. Each buffer has a
+designated position called @dfn{point} (@pxref{Positions}); most
+editing commands act on the contents of the current buffer in the
+neighborhood of point. At any time, one buffer is the @dfn{current
+buffer}.
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, you can insert text efficiently into an
existing buffer, altering the buffer's contents, whereas ``inserting''
-text into a string requires concatenating substrings, and the result is
-an entirely new string object.
+text into a string requires concatenating substrings, and the result
+is an entirely new string object.
- Each buffer has a designated position called @dfn{point}
-(@pxref{Positions}). At any time, one buffer is the @dfn{current
-buffer}. Most editing commands act on the contents of the current
-buffer in the neighborhood of point. Many of the standard Emacs
-functions manipulate or test the characters in the current buffer; a
-whole chapter in this manual is devoted to describing these functions
-(@pxref{Text}).
+ Many of the standard Emacs functions manipulate or test the
+characters in the current buffer; a whole chapter in this manual is
+devoted to describing these functions (@pxref{Text}).
Several other data structures are associated with each buffer:
@xref{Frames}, for a description of the functions that work on frames.
+@node Terminal Type
+@subsection Terminal Type
+@cindex terminal type
+
+ A @dfn{terminal} is a device capable of displaying one or more
+Emacs frames (@pxref{Frame Type}).
+
+ Terminals have no read syntax. They print in hash notation giving
+the terminal's ordinal number and its TTY device file name.
+
+@example
+@group
+(get-device-terminal nil)
+ @result{} #<terminal 1 on /dev/tty>
+@end group
+@end example
+
+@c FIXME: add an xref to where terminal-related primitives are described.
+
@node Window Configuration Type
@subsection Window Configuration Type
@cindex window layout in a frame
@cindex window layout, all frames
A @dfn{frame configuration} stores information about the positions,
-sizes, and contents of the windows in all frames. It is actually
-a list whose @sc{car} is @code{frame-configuration} and whose
-@sc{cdr} is an alist. Each alist element describes one frame,
-which appears as the @sc{car} of that element.
+sizes, and contents of the windows in all frames. It is not a
+primitive type---it is actually a list whose @sc{car} is
+@code{frame-configuration} and whose @sc{cdr} is an alist. Each alist
+element describes one frame, which appears as the @sc{car} of that
+element.
@xref{Frame Configurations}, for a description of several functions
related to frame configurations.
@xref{Overlays}, for how to create and use overlays.
+@node Font Type
+@subsection Font Type
+
+ A @dfn{font} specifies how to display text on a graphical terminal.
+There are actually three separate font types---@dfn{font objects},
+@dfn{font specs}, and @dfn{font entities}---each of which has slightly
+different properties. None of them have a read syntax; their print
+syntax looks like @samp{#<font-object>}, @samp{#<font-spec>}, and
+@samp{#<font-entity>} respectively. @xref{Low-Level Font}, for a
+description of these Lisp objects.
+
@node Circular Objects
@section Read Syntax for Circular Objects
@cindex circular structure, read syntax
@item consp
@xref{List-related Predicates, consp}.
+@item custom-variable-p
+@xref{Variable Definitions, custom-variable-p}.
+
@item display-table-p
@xref{Display Tables, display-table-p}.
@item floatp
@xref{Predicates on Numbers, floatp}.
+@item fontp
+@xref{Low-Level Font}.
+
@item frame-configuration-p
@xref{Frame Configurations, frame-configuration-p}.
@item syntax-table-p
@xref{Syntax Tables, syntax-table-p}.
-@item user-variable-p
-@xref{Defining Variables, user-variable-p}.
-
@item vectorp
@xref{Vectors, vectorp}.
@defun type-of object
This function returns a symbol naming the primitive type of
-@var{object}. The value is one of the symbols @code{symbol},
-@code{integer}, @code{float}, @code{string}, @code{cons}, @code{vector},
-@code{char-table}, @code{bool-vector}, @code{hash-table}, @code{subr},
-@code{compiled-function}, @code{marker}, @code{overlay}, @code{window},
-@code{buffer}, @code{frame}, @code{process}, or
+@var{object}. The value is one of the symbols @code{bool-vector},
+@code{buffer}, @code{char-table}, @code{compiled-function},
+@code{cons}, @code{float}, @code{font-entity}, @code{font-object},
+@code{font-spec}, @code{frame}, @code{hash-table}, @code{integer},
+@code{marker}, @code{overlay}, @code{process}, @code{string},
+@code{subr}, @code{symbol}, @code{vector}, @code{window}, or
@code{window-configuration}.
@example
@section Equality Predicates
@cindex equality
- Here we describe two functions that test for equality between any two
-objects. Other functions test equality of contents between objects of specific
-types, e.g., strings. For these predicates, see the appropriate chapter
-describing the data type.
+ Here we describe functions that test for equality between two
+objects. Other functions test equality of contents between objects of
+specific types, e.g.@: strings. For these predicates, see the
+appropriate chapter describing the data type.
@defun eq object1 object2
This function returns @code{t} if @var{object1} and @var{object2} are
-the same object, @code{nil} otherwise.
-
-@code{eq} returns @code{t} if @var{object1} and @var{object2} are
-integers 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, meaning that a change in the contents of one will be reflected
-by the same change in the contents of the other.
+the same object, and @code{nil} otherwise.
+
+If @var{object1} and @var{object2} are integers with the same value,
+they are considered to be the same object (i.e.@: @code{eq} returns
+@code{t}). If @var{object1} and @var{object2} are symbols with the
+same name, they are normally the same object---but see @ref{Creating
+Symbols} for exceptions. 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, meaning that a change in the contents of one will
+be reflected by the same change in the contents of the other.
@example
@group
@end group
@end example
+@noindent
The @code{make-symbol} function returns an uninterned symbol, distinct
from the symbol that is used if you write the name in a Lisp expression.
Distinct symbols with the same name are not @code{eq}. @xref{Creating
@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 or contents are the same. So, if two
-objects are @code{eq}, they are @code{equal}, but the converse is not
-always true.
+equal components, and @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 or contents are the
+same. So, if two objects are @code{eq}, they are @code{equal}, but
+the converse is not always true.
@example
@group
@end example
Comparison of strings is case-sensitive, but does not take account of
-text properties---it compares only the characters in the strings. For
-technical reasons, a unibyte string and a multibyte string are
-@code{equal} if and only if they contain the same sequence of
-character codes and all these codes are either in the range 0 through
-127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}).
-(@pxref{Text Representations}).
+text properties---it compares only the characters in the strings.
+@xref{Text Properties}. Use @code{equal-including-properties} to also
+compare text properties. For technical reasons, a unibyte string and
+a multibyte string are @code{equal} if and only if they contain the
+same sequence of character codes and all these codes are either in the
+range 0 through 127 (@acronym{ASCII}) or 160 through 255
+(@code{eight-bit-graphic}). (@pxref{Text Representations}).
@example
@group
Because of this recursive method, circular lists may therefore cause
infinite recursion (leading to an error).
-@ignore
- arch-tag: 9711a66e-4749-4265-9e8c-972d55b67096
-@end ignore
+@defun equal-including-properties object1 object2
+This function behaves like @code{equal} in all cases but also requires
+that for two strings to be equal, they have the same text properties.
+
+@example
+@group
+(equal "asdf" (propertize "asdf" '(asdf t)))
+ @result{} t
+@end group
+@group
+(equal-including-properties "asdf"
+ (propertize "asdf" '(asdf t)))
+ @result{} nil
+@end group
+@end example
+@end defun