@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 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
+@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
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
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
@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 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
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
* 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 floatp
@xref{Predicates on Numbers, floatp}.
+@item fontp
+@xref{Low-Level Font}.
+
@item frame-configuration-p
@xref{Frame Configurations, frame-configuration-p}.
@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
+ Here we describe 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.
@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
+text properties---it compares only the characters in the strings. 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
Because of this recursive method, circular lists may therefore cause
infinite recursion (leading to an error).
+@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
+
@ignore
arch-tag: 9711a66e-4749-4265-9e8c-972d55b67096
@end ignore